"email.parser": 전자 메일 메시지 구문 분석
******************************************

**소스 코드:** Lib/email/parser.py

======================================================================

메시지 객체 구조는 두 가지 방법으로 만들 수 있습니다: "EmailMessage"
객체를 만들고, 딕셔너리 인터페이스를 사용하여 헤더를 추가하고,
"set_content()"와 관련 메서드를 사용하여 페이 로드를 추가하여 아예 새
로 만들 수 있습니다. 또는 전자 메일 메시지의 직렬화된 표현을 구문 분석
해서 만들 수 있습니다.

"email" 패키지는 MIME 문서를 포함한 대부분의 전자 우편 문서 구조를 이
해하는 표준 구문 분석기를 제공합니다. 구문 분석기에 바이트열, 문자열
또는 파일 객체를 전달하면 구문 분석기가 객체 구조의 루트
"EmailMessage" 인스턴스를 반환합니다. MIME이 아닌 간단한 메시지의 경우
이 루트 객체의 페이 로드는 메시지의 텍스트를 포함하는 문자열일 수 있습
니다. MIME 메시지의 경우 루트 객체는 "is_multipart()" 메서드가 "True"
를 반환하고, "get_body()", "iter_parts()" 및 "walk()"와 같은 페이 로드
조작 메서드를 통해 서브 파트에 액세스 할 수 있습니다.

실제로 사용 가능한 두 가지 구문 분석기 인터페이스가 있습니다, "Parser"
API와 증분 "FeedParser" API. "Parser" API는 메시지의 전체 텍스트가 메
모리에 있거나 전체 메시지가 파일 시스템의 파일에 있을 때 가장 유용합니
다. 더 많은 입력을 기다리기 위해 블록할 수 있는 스트림에서 메시지를 읽
을 때는 "FeedParser"가 더 적합합니다 (가령 소켓에서 전자 메일 메시지를
읽을 때). "FeedParser"는 메시지를 증분 적으로 소비하고 구문 분석 할 수
있으며, 구문 분석기를 닫을 때만 루트 객체를 반환합니다.

구문 분석기는 제한적인 방식으로 확장될 수 있음에 유의하십시오. 물론 구
문 분석기는 처음부터 새로 구현할 수 있습니다. "email" 패키지에 포함된
구문 분석기와 "EmailMessage" 클래스를 연결하는 모든 로직은 "policy" 클
래스에 내장되므로, 사용자 정의 구문 분석기는 적절한 "policy" 메서드의
사용자 정의 버전을 구현하여 필요한 방식으로 메시지 객체 트리를 만들 수
있습니다.


FeedParser API
==============

"email.feedparser" 모듈에서 임포트 한 "BytesFeedParser"는 전자 메일 메
시지의 증분 구문 분석에 도움이 되는 API를 제공합니다. 블록할 수 있는
소스(가령 소켓)에서 전자 메일 메시지의 텍스트를 읽을 때 필요합니다. 물
론 "BytesFeedParser"는 *바이트열류 객체*, 문자열 또는 파일에 완전히 포
함된 전자 메일 메시지를 구문 분석하는 데 사용될 수 있지만,
"BytesParser" API가 이러한 사용 사례에서는 더 편리 할 수 있습니다. 두
구문 분석기 API의 의미와 결과는 같습니다.

"BytesFeedParser"의 API는 간단합니다; 인스턴스를 만들고, 더는 공급할
것이 없을 때까지 바이트열을 공급한 다음 구문 분석기를 닫아 루트 메시지
객체를 얻습니다. "BytesFeedParser"는 표준 호환 메시지를 구문 분석할 때
매우 정확하고, 미준수 메시지를 구문 분석하는 데 매우 효과적이며 메시지
를 어떻게 손상되었다고 간주하는지에 대한 정보를 제공합니다. 메시지에서
발견된 문제점 리스트로 메시지 객체의 "defects" 어트리뷰트를 채웁니다.
찾을 수 있는 결함 목록은 "email.errors" 모듈을 참조하십시오.

"BytesFeedParser" API는 다음과 같습니다:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

   "BytesFeedParser" 인스턴스를 만듭니다. 선택적 *_factory*는 인자 없
   는 콜러블입니다; 지정되지 않으면 *policy*의 "message_factory"를 사
   용합니다. 새로운 메시지 객체가 필요할 때마다 *_factory*를 호출합니
   다.

   *policy*가 지정되면, 그것이 지정하는 규칙을 사용하여 메시지 표시를
   갱신합니다. *policy*가 설정되지 않으면, "compat32" 정책을 사용합니
   다. 이 정책은 파이썬 3.2 버전의 email 패키지와의 호환성을 유지하고
   "Message"를 기본 팩토리로 제공합니다. 다른 모든 정책은
   "EmailMessage"를 기본 *_factory*로 제공합니다. *policy*가 제어하는
   다른 기능에 대한 자세한 내용은 "policy" 설명서를 참조하십시오.

   참고: **policy 키워드는 항상 지정해야 합니다**; 이후 버전의 파이썬
   에서는 기본값이 "email.policy.default"로 변경됩니다.

   버전 3.2에 추가.

   버전 3.3에서 변경: *policy* 키워드를 추가했습니다.

   버전 3.6에서 변경: *_factory*는 기본적으로 정책 "message_factory"입
   니다.

   feed(data)

      구문 분석기에 데이터를 더 공급합니다. *data*는 하나 이상의 줄을
      포함하는 *바이트열류 객체*여야 합니다. 줄은 부분적일 수 있고 구
      문 분석기는 그러한 부분적인 줄을 올바르게 이어붙입니다. 줄은 세
      가지 일반 줄 종료 중 어느 것이라도 될 수 있습니다: 캐리지 리턴
      (carriage return), 줄 바꿈(newline) 또는 캐리지 리턴과 줄 바꿈 (
      이것들을 혼합할 수도 있습니다).

   close()

      이전에 제공된 모든 데이터의 구문 분석을 완료하고 루트 메시지 객
      체를 반환합니다. 이 메서드가 호출된 후 "feed()"가 호출되면 어떻
      게 되는지는 정의되지 않습니다.

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

   "feed()" 메서드에 대한 입력이 문자열이어야 한다는 점을 제외하고는
   "BytesFeedParser"와 같게 작동합니다. 이러한 메시지가 유효할 수 있는
   유일한 방법은 ASCII 텍스트만 포함하거나 "utf8"가 "True"일 때 바이너
   리 첨부 파일을 포함하지 않는 것이라서, 이것의 용도는 제한적입니다.

   버전 3.3에서 변경: *policy* 키워드를 추가했습니다.


Parser API
==========

"email.parser" 모듈에서 임포트 한 "BytesParser" 클래스는 메시지의 전체
내용이 *바이트열류 객체*나 파일로 있을 때 메시지를 구문 분석하는 데 사
용할 수 있는 API를 제공합니다. "email.parser" 모듈은 또한 문자열 구문
분석을 위한 "Parser"와 메시지 헤더에만 관심이 있을 때 사용할 수 있는
헤더 전용 구문 분석기인 "BytesHeaderParser"와 "HeaderParser"를 제공합
니다. "BytesHeaderParser"와 "HeaderParser"는 메시지 본문을 구문 분석하
지 않고 페이 로드를 원시 본문으로 설정하기 때문에 이러한 상황에서 훨씬
더 빠를 수 있습니다.

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

   "BytesParser" 인스턴스를 만듭니다. *_class*와 *policy* 인자는
   "BytesFeedParser" 의 *_factory*와 *policy* 인자와 같은 의미입니다.

   참고: **policy 키워드는 항상 지정해야 합니다**; 이후 버전의 파이썬
   에서는 기본값이 "email.policy.default"로 변경됩니다.

   버전 3.3에서 변경: 2.4에서 폐지된 *strict* 인자를 제거했습니다.
   *policy* 키워드를 추가했습니다.

   버전 3.6에서 변경: *_class*는 기본적으로 정책 "message_factory"입니
   다.

   parse(fp, headersonly=False)

      바이너리 파일류 객체 *fp*에서 모든 데이터를 읽고, 결과 바이트열
      을 구문 분석한 후, 메시지 객체를 반환합니다. *fp*는 "readline()"
      과 "read()" 메서드를 모두 지원해야 합니다.

      *fp*에 포함된 바이트열은 **RFC 5322**(또는 "utf8"가 "True"이면,
      **RFC 6532**) 블록 스타일 헤더와 헤더 연장 줄들로 포맷되어야 하
      며, 선택적으로 봉투 헤더가 앞에 올 수 있습니다. 헤더 블록은 데이
      터 끝이나 빈 줄로 종료됩니다. 헤더 블록 다음에는 메시지 본문이
      있습니다 (*Content-Transfer-Encoding*이 "8bit"인 서브 파트를 포
      함하여 MIME 인코딩된 서브 파트를 포함할 수 있습니다).

      선택적 *headersonly*는 헤더를 읽은 후에 구문 분석을 중지할지를
      지정하는 플래그입니다. 기본값은 "False"이며 파일의 전체 내용을
      구문 분석합니다.

   parsebytes(bytes, headersonly=False)

      파일류 객체 대신 *바이트열류 객체*를 취한다는 점을 제외하고는
      "parse()" 메서드와 유사합니다. *바이트열류 객체*로 이 메서드를
      호출하는 것은 "BytesIO" 인스턴스로 *bytes*를 먼저 감싸고
      "parse()"를 호출하는 것과 동등합니다.

      선택적 *headersonly*는 "parse()" 메서드와 같습니다.

   버전 3.2에 추가.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

   *headersonly*의 기본값이 "True"라는 점을 제외하고는 "BytesParser"와
   정확히 같습니다.

   버전 3.3에 추가.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

   이 클래스는 "BytesParser"와 유사하지만, 문자열 입력을 처리합니다.

   버전 3.3에서 변경: *strict* 인자를 제거했습니다. *policy* 키워드를
   추가했습니다.

   버전 3.6에서 변경: *_class*는 기본적으로 정책 "message_factory"입니
   다.

   parse(fp, headersonly=False)

      텍스트 모드 파일류 객체 *fp*에서 모든 데이터를 읽고, 결과 텍스트
      를 구문 분석한 후, 루트 메시지 객체를 반환합니다. *fp*는 파일류
      객체의 "readline()"과 "read()" 메서드를 모두 지원해야 합니다.

      텍스트 모드 요구 사항 외에, 이 메서드는 "BytesParser.parse()"처
      럼 작동합니다.

   parsestr(text, headersonly=False)

      파일류 객체 대신 문자열 객체를 취한다는 점을 제외하고는
      "parse()" 메서드와 유사합니다. 문자열로 이 메서드를 호출하는 것
      은 "StringIO" 인스턴스로 *text*를 먼저 감싸고 "parse()"를 호출하
      는 것과 동등합니다.

      선택적 *headersonly*는 "parse()" 메서드와 같습니다.

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

   *headersonly*의 기본값이 "True"라는 점을 제외하고는 "Parser"와 정확
   히 같습니다.

문자열이나 파일 객체로부터 메시지 객체 구조를 만드는 것이 일반적인 작
업이기 때문에, 편의상 4가지 함수가 제공됩니다. 최상위 "email" 패키지
이름 공간에 있습니다.

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

   *바이트열류 객체*로부터 메시지 객체 구조를 반환합니다. 이것은
   "BytesParser().parsebytes(s)"와 동등합니다. 선택적 *_class*와
   *policy*는 "BytesParser" 클래스 생성자에서처럼 해석됩니다.

   버전 3.2에 추가.

   버전 3.3에서 변경: *strict* 인자를 제거했습니다. *policy* 키워드를
   추가했습니다.

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

   열린 바이너리 *파일 객체*로부터 메시지 객체 구조 트리를 반환합니다.
   이것은 "BytesParser().parse(fp)"와 동등합니다. *_class*와 *policy*
   는 "BytesParser" 클래스 생성자에서처럼 해석됩니다.

   버전 3.2에 추가.

   버전 3.3에서 변경: *strict* 인자를 제거했습니다. *policy* 키워드를
   추가했습니다.

email.message_from_string(s, _class=None, *, policy=policy.compat32)

   문자열로부터 메시지 객체 구조 트리를 반환합니다. 이것은
   "Parser().parsestr(s)"와 동등합니다. *_class*와 *policy*는 "Parser"
   클래스 생성자에서처럼 해석됩니다.

   버전 3.3에서 변경: *strict* 인자를 제거했습니다. *policy* 키워드를
   추가했습니다.

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

   열린 *파일 객체*로부터 메시지 객체 구조 트리를 반환합니다. 이것은
   "Parser().parse(fp)"와 동등합니다. *_class*와 *policy*는 "Parser"
   클래스 생성자에서처럼 해석됩니다.

   버전 3.3에서 변경: *strict* 인자를 제거했습니다. *policy* 키워드를
   추가했습니다.

   버전 3.6에서 변경: *_class*는 기본적으로 정책 "message_factory"입니
   다.

대화식 파이썬 프롬프트에서 "message_from_bytes()"를 사용하는 방법의 예
는 다음과 같습니다:

   >>> import email
   >>> msg = email.message_from_bytes(myBytes)  


추가 사항
=========

구문 분석 의미에 대한 참고 사항은 다음과 같습니다:

* 대부분의 *multipart*가 아닌 유형의 메시지는 문자열 페이 로드가 있는
  단일 메시지 객체로 구문 분석됩니다. 이 객체는 "is_multipart()"가
  "False"를 반환하고 "iter_parts()"는 빈 목록을 산출합니다.

* 모든 *multipart* 유형 메시지는 서브 메시지 객체 리스트 페이 로드가
  있는 컨테이너 메시지 객체로 구문 분석됩니다. 바깥 컨테이너 메시지는
  "is_multipart()"가 "True"를 반환하고 "iter_parts()"는 서브 파트 목록
  을 산출합니다.

* 콘텐츠 유형이 *message/**(가령 *message/delivery-status*와
  *message/rfc822*)인 대부분의 메시지는 길이가 1인 리스트 페이 로드를
  포함하는 컨테이너 객체로 구문 분석됩니다. "is_multipart()" 메서드는
  "True"를 반환합니다. "iter_parts()"가 산출하는 단일 요소가 서브 메시
  지 객체입니다.

* 일부 표준을 준수하지 않는 메시지는 *multipart* 처리에 대해 내부적으
  로 일관성이 없을 수 있습니다. 이러한 메시지는 *multipart* 유형의
  *Content-Type* 헤더를 가지면서도 "is_multipart()" 메서드가 "False"를
  반환할 수 있습니다. 이러한 메시지가 "FeedParser"로 구문 분석되었다면
  , *defects* 어트리뷰트 리스트에 "MultipartInvariantViolationDefect"
  클래스의 인스턴스가 있습니다. 자세한 내용은 "email.errors"를 참조하
  십시오.
