"mailbox" --- 다양한 형식의 사서함 조작하기
*******************************************

**소스 코드:** Lib/mailbox.py

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

이 모듈은 디스크 상의 사서함과 여기에 포함된 메시지에 액세스하고 조작
하기 위한 "Mailbox"와 "Message"라는 두 개의 클래스를 정의합니다.
"Mailbox"는 키에서 메시지로의 딕셔너리와 유사한 매핑을 제공합니다.
"Message"는 형식별 상태와 동작으로 "email.message" 모듈의 "Message" 클
래스를 확장합니다. 지원되는 사서함 형식은 Maildir, mbox, MH, Babyl 및
MMDF입니다.

더 보기:

  모듈 "email"
     메시지를 표현하고 조작합니다.


"Mailbox" 객체
==============

class mailbox.Mailbox

   검사하고 수정할 수 있는 사서함.

   "Mailbox" 클래스는 인터페이스를 정의하고 인스턴스 화하려는 것은 아
   닙니다. 대신 형식별 서브 클래스는 "Mailbox"를 상속해야 하며 코드는
   특정 서브 클래스를 인스턴스 화해야 합니다.

   "Mailbox" 인터페이스는 메시지에 해당하는 작은 키가 있는 딕셔너리와
   유사합니다. 키는 사용되는 "Mailbox" 인스턴스에 의해 발급되며 해당
   "Mailbox" 인스턴스에만 의미가 있습니다. 키는 메시지를 다른 메시지로
   바꾸는 등 해당 메시지가 수정되어도 메시지를 계속 식별합니다.

   집합과 유사한 메서드 "add()"를 사용하여 "Mailbox" 인스턴스에 메시지
   를 추가하고 "del" 문이나 집합과 유사한 메서드 "remove()"와
   "discard()"를 사용하여 제거할 수 있습니다.

   "Mailbox" 인터페이스의 의미는 몇 가지 주목할만한 면에서 딕셔너리와
   다릅니다. 메시지가 요청될 때마다, 새 표현(보통 "Message" 인스턴스)
   이 사서함의 현재 상태를 기반으로 생성됩니다. 마찬가지로, "Mailbox"
   인스턴스에 메시지가 추가되면, 제공된 메시지 표현의 내용이 복사됩니
   다. 두 경우 모두 메시지 표현의 참조는 "Mailbox" 인스턴스가 유지하는
   것이 아닙니다.

   기본 "Mailbox" *이터레이터*는 기본 "딕셔너리" 이터레이터가 수행하는
   것처럼 키가 아니라 메시지 표현을 이터레이트 합니다. 또한, 이터레이
   션 중 사서함 수정은 안전하고 잘 정의되어 있습니다. 이터레이터가 만
   들어진 후 사서함에 추가된 메시지는 이터레이터가 볼 수 없습니다. 이
   터레이터가 산출하기 전에 사서함에서 제거된 메시지는 자동으로 건너뛰
   지만, 이터레이터의 키를 사용하면 해당 메시지가 직후에 제거되는 경우
   "KeyError" 예외가 발생할 수 있습니다.

   경고:

     다른 프로세스에 의해 동시에 변경될 수 있는 사서함을 수정할 때는
     매우 주의하십시오. 이러한 작업에 사용할 가장 안전한 사서함 형식은
     "Maildir"입니다; 동시 쓰기를 위해서는 "mbox"와 같은 단일 파일 형
     식을 사용하지 마십시오. 사서함을 수정하는 경우, 파일의 메시지를
     읽거나 메시지를 추가하거나 삭제하여 변경하기 *전에* "lock()"과
     "unlock()" 메서드를 호출하여 사서함을 *반드시* 잠가야 합니다. 사
     서함을 잠그는 데 실패하면 메시지가 손실되거나 전체 사서함이 손상
     될 위험이 있습니다.

   "Mailbox" 인스턴스에는 다음 메서드가 있습니다:

   add(message)

      사서함에 *message*를 추가하고 할당된 키를 반환합니다.

      매개 변수 *message*는 "Message" 인스턴스,
      "email.message.Message" 인스턴스, 문자열, 바이트 문자열 또는 파
      일류 객체(바이너리 모드로 열어야 합니다)일 수 있습니다.
      *message*가 적절한 형식별 "Message" 서브 클래스의 인스턴스이면 (
      예를 들어, 이것이 "mbox" 인스턴스일 때 "mboxMessage" 인스턴스이
      면), 형식별 정보가 사용됩니다. 그렇지 않으면, 형식별 정보에 대한
      적절한 기본값이 사용됩니다.

      버전 3.2에서 변경: 바이너리 입력에 대한 지원이 추가되었습니다.

   remove(key)
   __delitem__(key)
   discard(key)

      사서함에서 *key*에 해당하는 메시지를 삭제합니다.

      그러한 메시지가 없으면, 메서드가 "remove()"나 "__delitem__()"으
      로 호출되면 "KeyError" 예외가 발생하지만, "discard()"로 호출되면
      예외가 발생하지 않습니다. 하부 사서함 형식이 다른 프로세스에 의
      한 동시 수정을 지원하면 "discard()"의 동작을 선호할 수 있습니다.

   __setitem__(key, message)

      *key*에 해당하는 메시지를 *message*로 바꿉니다. *key*에 해당하는
      메시지가 없으면 "KeyError" 예외를 발생시킵니다.

      "add()"와 마찬가지로, *message* 매개 변수는 "Message" 인스턴스,
      "email.message.Message" 인스턴스, 문자열, 바이트 문자열 또는 파
      일류 객체(바이너리 모드로 열어야 합니다)일 수 있습니다.
      *message*가 적절한 형식별 "Message" 서브 클래스의 인스턴스이면 (
      예를 들어, 이것이 "mbox" 인스턴스일 때 "mboxMessage" 인스턴스이
      면), 형식별 정보가 사용됩니다. 그렇지 않으면, 현재 *key*에 해당
      하는 메시지의 형식별 정보가 변경되지 않습니다.

   iterkeys()

      Return an *iterator* over all keys

   keys()

      The same as "iterkeys()", except that a "list" is returned
      rather than an *iterator*

   itervalues()
   __iter__()

      모든 메시지의 표현에 대한 *이터레이터*를 반환합니다. "Mailbox"
      인스턴스가 초기화될 때 사용자 정의 메시지 팩토리가 지정되지 않는
      한, 메시지는 적절한 형식별 "Message" 서브 클래스의 인스턴스로 표
      현됩니다.

      참고:

        "__iter__()"의 동작은 키를 이터레이트 하는 딕셔너리의 동작과
        다릅니다.

   values()

      The same as "itervalues()", except that a "list" is returned
      rather than an *iterator*

   iteritems()

      (*key*, *message*) 쌍에 대한 *이터레이터*를 반환합니다. 여기서
      *key*는 키이고 *message*는 메시지 표현입니다. "Mailbox" 인스턴스
      가 초기화될 때 사용자 정의 메시지 팩토리가 지정되지 않는 한 메시
      지는 적절한 형식별 "Message" 서브 클래스의 인스턴스로 표시됩니다
      .

   items()

      The same as "iteritems()", except that a "list" of pairs is
      returned rather than an *iterator* of pairs.

   get(key, default=None)
   __getitem__(key)

      *key*에 해당하는 메시지 표현을 반환합니다. 이러한 메시지가 없으
      면, 메서드가 "get()"으로 호출되면 *default*가 반환되고 메서드가
      "__getitem__()"으로 호출되면 "KeyError" 예외가 발생합니다.
      "Mailbox" 인스턴스가 초기화될 때 사용자 정의 메시지 팩토리가 지
      정되지 않는 한 메시지는 적절한 형식별 "Message" 서브 클래스의 인
      스턴스로 표시됩니다.

   get_message(key)

      *key*에 해당하는 메시지의 표현을 적절한 형식별 "Message" 서브 클
      래스의 인스턴스로 반환하거나, 그러한 메시지가 없으면 "KeyError"
      예외를 발생시킵니다.

   get_bytes(key)

      *key*에 해당하는 메시지의 바이트 표현을 반환하거나, 그러한 메시
      지가 없으면 "KeyError" 예외를 발생시킵니다.

      Added in version 3.2.

   get_string(key)

      *key*에 해당하는 메시지의 문자열 표현을 반환하거나 그러한 메시지
      가 없으면 "KeyError" 예외를 발생시킵니다. 메시지는
      "email.message.Message"를 통해 처리되어 7비트(7bit clean) 표현으
      로 변환됩니다.

   get_file(key)

      *key*에 해당하는 메시지의 *파일류* 표현을 반환하거나, 그러한 메
      시지가 없으면 "KeyError" 예외를 발생시킵니다. 파일류 객체는 바이
      너리 모드로 열린 것처럼 작동합니다. 이 파일이 더는 필요하지 않으
      면 닫아야 합니다.

      버전 3.2에서 변경: 파일 객체는 실제로 *바이너리 파일*입니다; 이
      전에는 텍스트 모드로 잘못 반환되었습니다. 또한, *파일류 객체*는
      이제 *컨텍스트 관리자* 프로토콜을 지원합니다: "with" 문을 사용하
      여 자동으로 닫을 수 있습니다.

      참고:

        메시지의 다른 표현과 달리, *파일류* 표현은 메시지를 만든
        "Mailbox" 인스턴스나 하부 사서함과 반드시 독립적인 것은 아닙니
        다. 더욱 자세한 설명서는 각 서브 클래스에서 제공합니다.

   __contains__(key)

      *key*가 메시지에 해당하면 "True"를 반환하고, 그렇지 않으면
      "False"를 반환합니다.

   __len__()

      사서함에 있는 메시지 수를 반환합니다.

   clear()

      사서함에서 모든 메시지를 삭제합니다.

   pop(key, default=None)

      *key*에 해당하는 메시지 표현을 반환하고 메시지를 삭제합니다. 이
      러한 메시지가 없으면, *default*를 반환합니다. "Mailbox" 인스턴스
      가 초기화될 때 사용자 정의 메시지 팩토리가 지정되지 않는 한 메시
      지는 적절한 형식별 "Message" 서브 클래스의 인스턴스로 표시됩니다
      .

   popitem()

      임의의 (*key*, *message*) 쌍을 반환하고, 여기서 *key*는 키이고
      *message*는 메시지 표현입니다, 해당 메시지를 삭제합니다. 사서함
      이 비어 있으면, "KeyError" 예외를 발생시킵니다. "Mailbox" 인스턴
      스가 초기화될 때 사용자 정의 메시지 팩토리가 지정되지 않는 한 메
      시지는 적절한 형식별 "Message" 서브 클래스의 인스턴스로 표시됩니
      다.

   update(arg)

      매개 변수 *arg*는 *key*에서 *message*로의 매핑이거나 (*key*,
      *message*) 쌍의 이터러블 이어야 합니다. 주어진 *key*와 *message*
      에 대해 "__setitem__()"을 사용하는 것처럼 *key*에 해당하는 메시
      지가 *message*로 설정되도록 사서함을 갱신합니다. "__setitem__()"
      과 마찬가지로, 각 *key*는 이미 사서함의 메시지에 해당해야 합니다
      , 그렇지 않으면 "KeyError" 예외가 발생하므로, 일반적으로 *arg*가
      "Mailbox" 인스턴스가 되는 것은 올바르지 않습니다.

      참고:

        딕셔너리와 달리 키워드 인자는 지원되지 않습니다.

   flush()

      계류 중인 변경 사항을 파일 시스템에 기록합니다. 일부 "Mailbox"
      서브 클래스의 경우, 변경 사항이 항상 즉시 기록되고 "flush()"는
      아무 작업도 하지 않지만, 이 메서드를 호출하는 습관을 만들어야 합
      니다.

   lock()

      다른 프로세스가 수정하지 않아야 한다는 것을 알 수 있도록 사서함
      에 대한 배타적 권고 잠금(exclusive advisory lock)을 획득합니다.
      잠금을 사용할 수 없으면 "ExternalClashError" 가 발생합니다. 사용
      되는 특정 잠금 메커니즘은 사서함 형식에 따라 다릅니다. 내용을 수
      정하기 전에 사서함을 *항상* 잠가야 합니다.

   unlock()

      사서함의 잠금을 해제합니다 (있다면).

   close()

      사서함을 플러시하고, 필요하면 잠금을 해제한 다음, 열려있는 모든
      파일을 닫습니다. 일부 "Mailbox" 서브 클래스의 경우, 이 메서드는
      아무 작업도 수행하지 않습니다.


"Maildir" 객체
--------------

class mailbox.Maildir(dirname, factory=None, create=True)

   Maildir 형식의 사서함에 대한 "Mailbox"의 서브 클래스. 매개 변수
   *factory*는 파일류 메시지 표현(바이너리 모드에서 열린 것처럼 동작합
   니다)을 받아들이고 사용자 정의 표현을 반환하는 콜러블 객체입니다.
   *factory*가 "None"이면, "MaildirMessage" 가 기본 메시지 표현으로 사
   용됩니다. *create*가 "True"이면, 사서함이 없으면 만들어집니다.

   *create*가 "True"이고 *dirname* 경로가 존재하면, 디렉터리 레이아웃
   을 확인하지 않고 기존 maildir로 처리됩니다.

   역사적인 이유로 *path*가 아니라 *dirname*이라고 이름 붙였습니다.

   Maildir은 qmail 메일 전송 에이전트를 위해 고안된 디렉터리 기반 사서
   함 형식이며 현재 다른 프로그램에서 널리 지원됩니다. Maildir 사서함
   의 메시지는 공통 디렉터리 구조 내에서 별도의 파일에 저장됩니다. 이
   설계를 사용하면 데이터 손상 없이 여러 관련 없는 프로그램에서
   Maildir 사서함에 액세스하고 수정할 수 있어서 파일 잠금이 필요하지
   않습니다.

   Maildir 사서함에는 세 개의 하위 디렉터리가 있습니다, 이름하여
   "tmp", "new" 및 "cur". 메시지는 일시적으로 "tmp" 하위 디렉터리에 만
   들어진 다음 "new" 하위 디렉터리로 이동하여 전달을 완료합니다. 메일
   사용자 에이전트는 이후에 메시지를 "cur" 하위 디렉터리로 이동하고 파
   일 이름에 추가된 특수 "info" 섹션에 메시지 상태에 대한 정보를 저장
   할 수 있습니다.

   Courier 메일 전송 에이전트가 도입한 스타일의 폴더도 지원됩니다.
   "'.'"가 이름의 첫 번째 문자인 경우 주 사서함의 모든 하위 디렉터리는
   폴더로 간주합니다. 폴더 이름은 앞의 "'.'"없이 "Maildir"로 표시됩니
   다. 각 폴더는 그 자체가 Maildir 사서함이지만 다른 폴더를 포함해서는
   안 됩니다. 대신, 수준을 구분하기 위해 "'.'"을 사용하여 논리적 중첩
   이 표시됩니다, 예를 들어, "Archived.2005.07".

   colon

      Maildir 명세에서는 특정 메시지 파일 이름에 콜론("':'")을 사용하
      도록 요구합니다. 그러나 일부 운영 체제에서는 파일 이름에 이 문자
      를 허용하지 않습니다. 이러한 운영 체제에서 Maildir과 유사한 형식
      을 사용하려면, 대신 사용할 다른 문자를 지정해야 합니다. 느낌표
      ("'!'")는 인기 있는 선택입니다. 예를 들면:

         import mailbox
         mailbox.Maildir.colon = '!'

      "colon" 어트리뷰트는 인스턴스별로 설정할 수도 있습니다.

   버전 3.13에서 변경: "Maildir" now ignores files with a leading dot.

   "Maildir" 인스턴스에는 "Mailbox"의 모든 메서드 외에도 다름과 같은
   메서드가 있습니다:

   list_folders()

      모든 폴더의 이름 리스트를 반환합니다.

   get_folder(folder)

      이름이 *folder*인 폴더를 나타내는 "Maildir" 인스턴스를 반환합니
      다. 폴더가 없으면 "NoSuchMailboxError" 예외가 발생합니다.

   add_folder(folder)

      이름이 *folder*인 폴더를 만들고 이를 나타내는 "Maildir" 인스턴스
      를 반환합니다.

   remove_folder(folder)

      이름이 *folder*인 폴더를 삭제합니다. 폴더에 메시지가 포함되었으
      면, "NotEmptyError" 예외가 발생하고 폴더가 삭제되지 않습니다.

   clean()

      지난 36시간 동안 액세스하지 않은 사서함에서 임시 파일을 삭제합니
      다. Maildir 명세는 메일을 읽는 프로그램이 이 작업을 가끔 수행해
      야 한다고 말합니다.

   get_flags(key)

      Return as a string the flags that are set on the message
      corresponding to *key*. This is the same as
      "get_message(key).get_flags()" but much faster, because it does
      not open the message file. Use this method when iterating over
      the keys to determine which messages are interesting to get.

      If you do have a "MaildirMessage" object, use its "get_flags()"
      method instead, because changes made by the message's
      "set_flags()", "add_flag()" and "remove_flag()" methods are not
      reflected here until the mailbox's "__setitem__()" method is
      called.

      Added in version 3.13.

   set_flags(key, flags)

      On the message corresponding to *key*, set the flags specified
      by *flags* and unset all others. Calling
      "some_mailbox.set_flags(key, flags)" is similar to

         one_message = some_mailbox.get_message(key)
         one_message.set_flags(flags)
         some_mailbox[key] = one_message

      but faster, because it does not open the message file.

      If you do have a "MaildirMessage" object, use its "set_flags()"
      method instead, because changes made with this mailbox method
      will not be visible to the message object's method,
      "get_flags()".

      Added in version 3.13.

   add_flag(key, flag)

      *key*에 해당하는 메시지에 대해, 다른 플래그를 변경하지 않고
      *flag*로 지정된 플래그를 설정합니다. 한 번에 둘 이상의 플래그를
      추가하기 위해, *flag*가 둘 이상의 문자로 구성된 문자열일 수 있습
      니다.

      Considerations for using this method versus the message object's
      "add_flag()" method are similar to those for "set_flags()"; see
      the discussion there.

      Added in version 3.13.

   remove_flag(key, flag)

      *key*에 해당하는 메시지에 대해, 다른 플래그를 변경하지 않고
      *flag*에 의해 지정된 플래그를 설정 해제합니다. 한 번에 둘 이상의
      플래그를 제거하기 위해, *flag*는 둘 이상의 문자로 구성된 문자열
      일 수 있습니다.

      Considerations for using this method versus the message object's
      "remove_flag()" method are similar to those for "set_flags()";
      see the discussion there.

      Added in version 3.13.

   get_info(key)

      Return a string containing the info for the message
      corresponding to *key*. This is the same as
      "get_message(key).get_info()" but much faster, because it does
      not open the message file. Use this method when iterating over
      the keys to determine which messages are interesting to get.

      If you do have a "MaildirMessage" object, use its "get_info()"
      method instead, because changes made by the message's
      "set_info()" method are not reflected here until the mailbox's
      "__setitem__()" method is called.

      Added in version 3.13.

   set_info(key, info)

      Set the info of the message corresponding to *key* to *info*.
      Calling "some_mailbox.set_info(key, flags)" is similar to

         one_message = some_mailbox.get_message(key)
         one_message.set_info(info)
         some_mailbox[key] = one_message

      but faster, because it does not open the message file.

      If you do have a "MaildirMessage" object, use its "set_info()"
      method instead, because changes made with this mailbox method
      will not be visible to the message object's method,
      "get_info()".

      Added in version 3.13.

   "Maildir"에 의해 구현된 일부 "Mailbox" 메서드는 특별한 주의가 필요
   합니다:

   add(message)
   __setitem__(key, message)
   update(arg)

      경고:

        이 메서드들은 현재 프로세스 ID를 기반으로 고유한 파일 이름을
        생성합니다. 다중 스레드를 사용할 때, 이러한 메서드를 사용하여
        같은 사서함을 동시에 조작하지 않도록 스레드를 조정하지 않으면
        감지되지 않은 이름 충돌이 발생하여 사서함이 손상될 수 있습니다
        .

   flush()

      Maildir 사서함에 대한 모든 변경 사항은 즉시 적용되므로, 이 메서
      드는 아무 작업도 수행하지 않습니다.

   lock()
   unlock()

      Maildir 사서함은 잠금을 지원(또는 필요로)하지 않아서, 이 메서드
      들은 아무 작업도 수행하지 않습니다.

   close()

      "Maildir" 인스턴스는 아무런 열린 파일도 유지하지 않으며 하부 사
      서함은 잠금을 지원하지 않아서, 이 메서드는 아무 작업도 수행하지
      않습니다.

   get_file(key)

      호스트 플랫폼에 따라, 반환된 파일이 열려있는 동안 하부 메시지를
      수정하거나 제거하지 못할 수 있습니다.

더 보기:

  Courier의 maildir 매뉴얼 페이지
     형식의 명세. 지원 폴더에 대한 공통 확장을 설명합니다.

  Using maildir format
     발명가의 Maildir에 대한 노트. 개정된 이름 생성 체계와 "info" 의미
     론에 대한 세부 정보를 포함합니다.


"mbox" 객체
-----------

class mailbox.mbox(path, factory=None, create=True)

   mbox 형식의 사서함에 대한 "Mailbox"의 서브 클래스. 매개 변수
   *factory*는 파일류 메시지 표현(바이너리 모드에서 열린 것처럼 동작합
   니다)을 받아들이고 사용자 정의 표현을 반환하는 콜러블 객체입니다.
   *factory*가 "None"이면, "mboxMessage"가 기본 메시지 표현으로 사용됩
   니다. *create*가 "True"이면, 사서함이 없으면 만들어집니다.

   mbox 형식은 유닉스 시스템에서 메일을 저장하기 위한 고전적인 형식입
   니다. mbox 사서함의 모든 메시지는 처음 5개의 문자가 "From "인 줄로
   표시되는 각 메시지의 시작 부분과 함께 단일 파일에 저장됩니다.

   원래 형식에서 인식된 단점을 해결하기 위해 mbox 형식의 여러 변형이
   존재합니다. 호환성을 위해, "mbox"는 *mboxo*라고도 하는 원래 형식을
   구현합니다. 즉, *Content-Length* 헤더(있다면)는 무시되고 메시지 본
   문의 줄 시작 부분에 있는 "From "은 메시지를 저장할 때 ">From "으로
   변환됩니다, 하지만 메시지를 읽을 때 ">From "은 "From "으로 변환되지
   않습니다.

   "mbox"에 의해 구현된 일부 "Mailbox" 메서드는 특별한 주의가 필요합니
   다:

   get_bytes(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_file(key, from_=False)

      "mbox" 인스턴스에서 "flush()"나 "close()"를 호출한 후 파일을 사
      용하면 예기치 않은 결과가 발생하거나 예외가 발생할 수 있습니다.

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_string(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   lock()
   unlock()

      세 가지 잠금 메커니즘이 사용됩니다---점 잠금(dot locking)과, 사
      용할 수 있다면, "flock()"과 "lockf()" 시스템 호출.

더 보기:

  tin의 mbox 매뉴얼 페이지
     형식의 명세, 잠금에 대한 세부 정보가 있습니다.

  유닉스에서 Netscape Mail 구성하기: 왜 Content-Length 형식이 나쁜가
     변형이 아닌 원래 mbox 형식을 사용하는 것에 대한 논의.

  "mbox"는 서로 호환되지 않는 여러 사서함 형식의 집합입니다
     mbox 변형의 역사.


"MH" 객체
---------

class mailbox.MH(path, factory=None, create=True)

   MH 형식의 사서함에 대한 "Mailbox"의 서브 클래스. 매개 변수
   *factory*는 파일류 메시지 표현(바이너리 모드에서 열린 것처럼 동작합
   니다)을 받아들이고 사용자 정의 표현을 반환하는 콜러블 객체입니다.
   *factory*가 "None"이면, "MHMessage"가 기본 메시지 표현으로 사용됩니
   다. *create*가 "True"이면, 사서함이 없으면 만들어집니다.

   MH는 메일 사용자 에이전트인 MH 메시지 처리 시스템(MH Message
   Handling System)을 위해 개발된 디렉터리 기반 사서함 형식입니다. MH
   사서함의 각 메시지는 각자의 파일에 있습니다. MH 사서함에는 메시지
   외에 다른 MH 사서함(*폴더(folders)*라고 합니다)이 포함될 수 있습니
   다. 폴더는 무제한 중첩될 수 있습니다. MH 사서함은 또한 메시지를 서
   브 폴더로 이동하지 않고 논리적으로 그룹화하는 데 사용되는 명명된 목
   록인 *시퀀스(sequences)*를 지원합니다. 시퀀스는 각 폴더의
   ".mh_sequences"라는 파일에 정의됩니다.

   "MH" 클래스는 MH 사서함을 조작하지만, **mh**의 모든 동작을 모사하려
   고 시도하지는 않습니다. 특히, **mh**가 상태와 구성을 저장하는 데 사
   용하는 "context"나 ".mh_profile" 파일을 수정하지 않고 영향받지 않습
   니다.

   "MH" 인스턴스에는 "Mailbox"의 모든 메서드 외에도 다음 메서드가 있습
   니다:

   버전 3.13에서 변경: Supported folders that don't contain a
   ".mh_sequences" file.

   list_folders()

      모든 폴더의 이름 리스트를 반환합니다.

   get_folder(folder)

      이름이 *folder*인 폴더를 나타내는 "MH" 인스턴스를 반환합니다. 폴
      더가 없으면 "NoSuchMailboxError" 예외가 발생합니다.

   add_folder(folder)

      이름이 *folder*인 폴더를 만들고 이를 나타내는 "MH" 인스턴스를 반
      환합니다.

   remove_folder(folder)

      이름이 *folder*인 폴더를 삭제합니다. 폴더에 메시지가 포함되었으
      면, "NotEmptyError" 예외가 발생하고 폴더가 삭제되지 않습니다.

   get_sequences()

      키 리스트에 매핑된 시퀀스 이름의 딕셔너리를 반환합니다. 시퀀스가
      없으면, 빈 딕셔너리가 반환됩니다.

   set_sequences(sequences)

      "get_sequences()"에서 반환하는 것과 같이, 키 리스트에 매핑된 이
      름의 딕셔너리인, *sequences*를 기반으로 사서함에 존재하는 시퀀스
      를 다시 정의합니다.

   pack()

      번호 매기기의 간격을 없애기 위해 필요에 따라 사서함의 메시지 이
      름을 변경합니다. 시퀀스 리스트의 항목이 그에 따라 갱신됩니다.

      참고:

        이미 발급된 키는 이 작업에 의해 무효가 되며 이후에 사용해서는
        안 됩니다.

   "MH"에 의해 구현된 일부 "Mailbox" 메서드는 특별한 주의가 필요합니다
   :

   remove(key)
   __delitem__(key)
   discard(key)

      이 메서드들은 메시지를 즉시 삭제합니다. 이름 앞에 쉼표를 추가하
      여 메시지를 삭제하도록 표시하는 MH 규칙은 사용되지 않습니다.

   lock()
   unlock()

      세 가지 잠금 메커니즘이 사용됩니다---점 잠금(dot locking)과, 사
      용할 수 있다면, "flock()"과 "lockf()" 시스템 호출. MH 사서함의
      경우, 사서함을 잠그는 것은 ".mh_sequences" 파일을 잠그는 것을 의
      미하며, 해당 파일에 영향을 주는 작업 기간에만 개별 메시지 파일을
      잠급니다.

   get_file(key)

      호스트 플랫폼에 따라, 반환된 파일이 열려있는 동안 하부 메시지를
      제거하지 못할 수도 있습니다.

   flush()

      MH 사서함에 대한 모든 변경 사항이 즉시 적용되므로, 이 메서드는
      아무 작업도 수행하지 않습니다.

   close()

      "MH" 인스턴스는 열린 파일을 유지하지 않아서, 이 메서드는
      "unlock()"과 동등합니다.

더 보기:

  nmh - 메시지 처리 시스템
     **nmh**의 홈페이지, 원래 **mh**의 갱신된 버전.

  MH & nmh: 사용자와 프로그래머를 위한 이메일
     **mh**와 **nmh**에 대한 GPL 라이선스 책, 사서함 형식에 대한 정보
     가 있습니다.


"Babyl" 객체
------------

class mailbox.Babyl(path, factory=None, create=True)

   Babyl 형식의 사서함에 대한 "Mailbox"의 서브 클래스. 매개 변수
   *factory*는 파일류 메시지 표현(바이너리 모드에서 열린 것처럼 동작합
   니다)을 받아들이고 사용자 정의 표현을 반환하는 콜러블 객체입니다.
   *factory*가 "None"이면, "BabylMessage"가 기본 메시지 표현으로 사용
   됩니다. *create*가 "True"이면, 사서함이 없으면 만들어집니다.

   Babyl은 Emacs에 포함된 Rmail 메일 사용자 에이전트에서 사용하는 단일
   파일 사서함 형식입니다. 메시지의 시작 부분은 Control-
   Underscore("'\037'")와 Control-L("'\014'") 두 문자가 포함된 줄로 표
   시됩니다. 메시지의 끝은 다음 메시지의 시작이나, 마지막 메시지의 경
   우 Control-Underscore("'\037'") 문자가 포함된 줄로 표시됩니다.

   Babyl 사서함의 메시지는 두 집합의 헤더가 있습니다, 원래 헤더와 소위
   가시적(visible) 헤더가 있습니다. 가시적 헤더는 일반적으로 더 매력적
   으로 다시 포맷되거나 요약된 원래 헤더의 부분 집합입니다. Babyl 사서
   함의 각 메시지에는 *레이블(labels)* 리스트, 또는 메시지에 대한 추가
   정보를 기록하는 짧은 문자열이 있으며, 사서함에 있는 모든 사용자 정
   의 레이블 목록은 Babyl 옵션 섹션에 보관됩니다.

   "Babyl" 인스턴스에는 "Mailbox"의 모든 메서드 외에도 다음과 같은 메
   서드가 있습니다:

   get_labels()

      사서함에 사용된 모든 사용자 정의 레이블의 이름 리스트를 반환합니
      다.

      참고:

        Babyl 옵션 섹션의 레이블 목록을 참조하지 않고 사서함에 있는 레
        이블을 확인하기 위해 실제 메시지를 검사하지만, 사서함이 수정될
        때마다 Babyl 섹션이 갱신됩니다.

   "Babyl"에 의해 구현된 일부 "Mailbox" 메서드는 특별한 주의가 필요합
   니다:

   get_file(key)

      Babyl 사서함에서, 메시지 헤더는 메시지 본문과 연속적으로 저장되
      지 않습니다. 파일류 표현을 생성하기 위해, 헤더와 본문이 파일과
      동일한 API를 가진 "io.BytesIO" 인스턴스에 함께 복사됩니다. 결과
      적으로, 파일류 객체는 하부 사서함과는 진짜로 독립적이지만 문자열
      표현보다 메모리를 절약하지 않습니다.

   lock()
   unlock()

      세 가지 잠금 메커니즘이 사용됩니다---점 잠금(dot locking)과, 사
      용할 수 있다면, "flock()"과 "lockf()" 시스템 호출.

더 보기:

  Format of Version 5 Babyl Files
     Babyl 형식의 명세.

  Rmail로 메일 읽기
     Rmail 매뉴얼, Babyl 의미론에 대한 정보가 있습니다.


"MMDF" 객체
-----------

class mailbox.MMDF(path, factory=None, create=True)

   MMDF 형식의 사서함에 대한 "Mailbox"의 서브 클래스. 매개 변수
   *factory*는 파일류 메시지 표현(바이너리 모드에서 열린 것처럼 동작합
   니다)을 받아들이고 사용자 정의 표현을 반환하는 콜러블 객체입니다.
   *factory*가 "None"이면, "MMDFMessage"가 기본 메시지 표현으로 사용됩
   니다. *create*가 "True"이면, 사서함이 없으면 만들어집니다.

   MMDF는 메일 전송 에이전트인 Multichannel Memorandum Distribution
   Facility를 위해 개발된 단일 파일 사서함 형식입니다. 각 메시지는
   mbox 메시지와 같은 형식이지만 4개의 Control-A ("'\001'") 문자를 포
   함하는 줄로 앞뒤로 둘러쌉니다. mbox 형식과 마찬가지로, 각 메시지의
   시작 부분은 처음 5개의 문자가 "From "인 줄로 표시되지만, 메시지를
   저장할 때 추가로 등장하는 "From "을 ">From "으로 변환하지 않습니다,
   메시지를 구분하는 추가적인 줄로 인해 후속 메시지의 시작으로 착각할
   우려가 없기 때문입니다.

   "MMDF"에 의해 구현된 일부 "Mailbox" 메서드는 특별한 주의가 필요합니
   다:

   get_bytes(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_file(key, from_=False)

      "MMDF" 인스턴스에서 "flush()"나 "close()"를 호출한 후 파일을 사
      용하면 예기치 않은 결과가 발생하거나 예외가 발생할 수 있습니다.

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   lock()
   unlock()

      세 가지 잠금 메커니즘이 사용됩니다---점 잠금(dot locking)과, 사
      용할 수 있다면, "flock()"과 "lockf()" 시스템 호출.

더 보기:

  tin의 mmdf 매뉴얼 페이지
     뉴스 리더인 tin의 설명서에 있는 MMDF 형식의 명세.

  MMDF
     Multichannel Memorandum Distribution Facility를 설명하는 위키피디
     아 기사.


"Message" 객체
==============

class mailbox.Message(message=None)

   "email.message" 모듈 "Message"의 서브 클래스. "mailbox.Message"의
   서브 클래스는 사서함 형식별 상태와 동작을 추가합니다.

   If *message* is omitted, the new instance is created in a default,
   empty state. If *message* is an "email.message.Message" instance,
   its contents are copied; furthermore, any format-specific
   information is converted insofar as possible if *message* is a
   "Message" instance. If *message* is a string, a byte string, or a
   file, it should contain an **RFC 5322**-compliant message, which is
   read and parsed.  Files should be open in binary mode, but text
   mode files are accepted for backward compatibility.

   서브 클래스에서 제공하는 형식별 상태와 동작은 다양하지만, 일반적으
   로 지원되는 특정 사서함에만 고유하지는 않은 속성입니다 (아마도 속성
   은 특정 사서함 형식에 고유합니다). 예를 들어, 단일 파일 사서함 형식
   에 대한 파일 오프셋과 디렉터리 기반 사서함 형식에 대한 파일 이름은
   유지되지 않는데, 원래 사서함에만 적용되기 때문입니다. 그러나 사용자
   가 메시지를 읽었는지나 중요하다고 표시되었는지와 같은 상태는 메시지
   자체에 적용되므로 유지됩니다.

   "Mailbox" 인스턴스를 사용하여 꺼낸 메시지를 나타내는 데 "Message"
   인스턴스를 사용할 필요는 없습니다. 때에 따라, "Message" 표현을 생성
   하는 데 필요한 시간과 메모리가 허용되지 않을 수 있습니다. 이러한 상
   황에서, "Mailbox" 인스턴스는 문자열과 파일류 표현도 제공하며,
   "Mailbox" 인스턴스가 초기화될 때 사용자 정의 메시지 팩토리를 지정할
   수 있습니다.


"MaildirMessage" 객체
---------------------

class mailbox.MaildirMessage(message=None)

   Maildir 특정 동작을 갖는 메시지. 매개 변수 *message*는 "Message" 생
   성자와 같은 의미입니다.

   일반적으로, 메일 사용자 에이전트 응용 프로그램은 사용자가 사서함을
   처음 열고 닫은 후 "new" 하위 디렉터리의 모든 메시지를 "cur" 하위 디
   렉터리로 이동하여, 메시지가 실제로 읽혔는지에 관계없이 오래되었음을
   기록합니다. "cur"의 각 메시지에는 상태에 대한 정보를 저장하기 위해
   파일 이름에 추가된 "info" 섹션이 있습니다. (일부 메일 리더는 "new"
   의 메시지에 "info" 섹션을 추가할 수도 있습니다.) "info" 섹션은 두
   가지 형식 중 하나를 취할 수 있습니다: "2,"와 그 뒤로 표준화된 플래
   그 목록이 오거나 (예를 들어, "2,FR"), "1,"과 그 뒤로 소위 실험적 정
   보를 포함할 수 있습니다. Maildir 메시지의 표준 플래그는 다음과 같습
   니다:

   +--------+-----------+----------------------------------+
   | 플래그 | 의미      | 설명                             |
   |========|===========|==================================|
   | D      | 초안      | 작성 중                          |
   +--------+-----------+----------------------------------+
   | F      | 깃발 표시 | 중요하다고 표시됨                |
   +--------+-----------+----------------------------------+
   | P      | 전달됨    | 전달, 재전송 또는 반송됨         |
   +--------+-----------+----------------------------------+
   | R      | 답장함    | 답장함                           |
   +--------+-----------+----------------------------------+
   | S      | 보았음    | 읽었음                           |
   +--------+-----------+----------------------------------+
   | T      | 휴지통    | 후에 삭제하기 위해 표시함        |
   +--------+-----------+----------------------------------+

   "MaildirMessage" 인스턴스는 다음 메서드를 제공합니다:

   get_subdir()

      "new"(메시지가 "new" 하위 디렉터리에 저장되어야 하면)나 "cur"(메
      시지가 "cur" 하위 디렉터리에 저장되어야 하면)를 반환합니다.

      참고:

        메시지를 읽었는지에 관계없이, 일반적으로 사서함에 액세스한 후
        메시지는 "new"에서 "cur"로 이동됩니다. ""S" in
        msg.get_flags()"가 "True"이면 메시지 "msg"를 읽은 것입니다.

   set_subdir(subdir)

      메시지를 저장할 하위 디렉터리를 설정합니다. 매개 변수 *subdir*은
      "new"나 "cur"여야 합니다.

   get_flags()

      현재 설정된 플래그를 지정하는 문자열을 반환합니다. 메시지가 표준
      Maildir 형식을 준수하면, 결과는 "'D'", "'F'", "'P'", "'R'",
      "'S'" 및 "'T'"의 각 항목이  알파벳 순서로 0이나 1개 등장하는 이
      어붙이기입니다. 플래그가 설정되지 않았거나 "info"에 실험적 의미
      가 포함되어 있으면 빈 문자열이 반환됩니다.

   set_flags(flags)

      *flags*로 지정된 플래그를 설정하고 다른 모든 플래그를 설정 해제
      합니다.

   add_flag(flag)

      다른 플래그를 변경하지 않고 *flag*로 지정된 플래그를 설정합니다.
      한 번에 둘 이상의 플래그를 추가하기 위해, *flag*가 둘 이상의 문
      자로 구성된 문자열일 수 있습니다. 플래그 대신 실험적 정보를 포함
      하는지와 관계없이 현재 "info"를 덮어씁니다.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* may be a
      string of more than one character.  If "info" contains
      experimental information rather than flags, the current "info"
      is not modified.

   get_date()

      메시지의 배달 날짜를 에포크(Epoch) 이후 초를 나타내는 부동 소수
      점 숫자로 반환합니다.

   set_date(date)

      메시지의 배달 날짜를 *date*로 설정합니다. 이는 에포크(Epoch) 이
      후 초를 나타내는 부동 소수점 숫자입니다.

   get_info()

      메시지에 대한 "info"를 포함하는 문자열을 반환합니다. 이것은 실험
      적인 (즉, 플래그 목록이 아닌) "info"를 액세스하고 수정하는 데 유
      용합니다.

   set_info(info)

      "info"를 문자열이어야 하는 *info*로 설정합니다.

"mboxMessage"나 "MMDFMessage" 인스턴스를 기반으로 "MaildirMessage" 인
스턴스가 만들어질 때, *Status*와 *X-Status* 헤더가 생략되고 다음 변환
이 발생합니다:

+----------------------+------------------------------------------------+
| 결과 상태            | "mboxMessage"나 "MMDFMessage" 상태             |
|======================|================================================|
| "cur" 하위 디렉터리  | O 플래그                                       |
+----------------------+------------------------------------------------+
| F 플래그             | F 플래그                                       |
+----------------------+------------------------------------------------+
| R 플래그             | A 플래그                                       |
+----------------------+------------------------------------------------+
| S 플래그             | R 플래그                                       |
+----------------------+------------------------------------------------+
| T 플래그             | D 플래그                                       |
+----------------------+------------------------------------------------+

"MHMessage" 인스턴스를 기반으로 "MaildirMessage" 인스턴스가 만들어지면
, 다음 변환이 발생합니다:

+---------------------------------+----------------------------+
| 결과 상태                       | "MHMessage" 상태           |
|=================================|============================|
| "cur" 하위 디렉터리             | "unseen" 시퀀스            |
+---------------------------------+----------------------------+
| "cur" 하위 디렉터리와 S 플래그  | "unseen" 시퀀스 없음       |
+---------------------------------+----------------------------+
| F 플래그                        | "flagged" 시퀀스           |
+---------------------------------+----------------------------+
| R 플래그                        | "replied" 시퀀스           |
+---------------------------------+----------------------------+

"BabylMessage" 인스턴스를 기반으로 "MaildirMessage" 인스턴스가 만들어
지면 다음 변환이 발생합니다:

+---------------------------------+---------------------------------+
| 결과 상태                       | "BabylMessage" 상태             |
|=================================|=================================|
| "cur" 하위 디렉터리             | "unseen" 레이블                 |
+---------------------------------+---------------------------------+
| "cur" 하위 디렉터리와 S 플래그  | "unseen" 레이블 없음            |
+---------------------------------+---------------------------------+
| P 플래그                        | "forwarded"나 "resent" 레이블   |
+---------------------------------+---------------------------------+
| R 플래그                        | "answered" 레이블               |
+---------------------------------+---------------------------------+
| T 플래그                        | "deleted" 레이블                |
+---------------------------------+---------------------------------+


"mboxMessage" 객체
------------------

class mailbox.mboxMessage(message=None)

   mbox 특정 동작을 갖는 메시지. 매개 변수 *message*는 "Message" 생성
   자와 같은 의미입니다.

   mbox 사서함의 메시지는 단일 파일에 함께 저장됩니다. 보낸 사람의 봉
   투 주소(envelope address)와 배달 시간은 일반적으로 메시지의 시작을
   나타내는 데 사용되는 "From "으로 시작하는 줄에 저장되지만, mbox 구
   현 간에 이 데이터의 정확한 형식에는 상당한 차이가 있습니다. 읽었는
   지나 중요하다고 표시되었는지와 같은 메시지 상태를 나타내는 플래그는
   일반적으로 *Status*와 *X-Status* 헤더에 저장됩니다.

   mbox 메시지의 전통적인 플래그는 다음과 같습니다:

   +--------+------------+----------------------------------+
   | 플래그 | 의미       | 설명                             |
   |========|============|==================================|
   | R      | 읽었음     | 읽었음                           |
   +--------+------------+----------------------------------+
   | O      | 오래되었음 | 전에 MUA에서 감지됨              |
   +--------+------------+----------------------------------+
   | D      | 삭제됨     | 후에 삭제하기 위해 표시함        |
   +--------+------------+----------------------------------+
   | F      | 깃발 표시  | 중요하다고 표시됨                |
   +--------+------------+----------------------------------+
   | A      | 답변함     | 답장함                           |
   +--------+------------+----------------------------------+

   "R"과 "O" 플래그는 *Status* 헤더에 저장되고, "D", "F" 및 "A" 플래그
   는 *X-Status* 헤더에 저장됩니다. 플래그와 헤더는 일반적으로 언급된
   순서대로 나타납니다.

   "mboxMessage" 인스턴스는 다음 메서드를 제공합니다:

   get_from()

      mbox 사서함에서 메시지의 시작을 표시하는 "From " 줄을 나타내는
      문자열을 반환합니다. 선행 "From "과 후행 줄넘김은 제외됩니다.

   set_from(from_, time_=None)

      "From " 줄을 *from_*으로 설정합니다. *from_*은 선행 "From "이나
      후행 줄넘김 없이 지정되어야 합니다. 편의를 위해, *time_*을 지정
      할 수 있으며 적절하게 포맷해서 *from_*에 추가합니다. *time_*이
      지정되면, "time.struct_time" 인스턴스, "time.strftime()"로 전달
      하기에 적합한 튜플 또는 "True"("time.gmtime()" 사용)여야 합니다.

   get_flags()

      현재 설정된 플래그를 지정하는 문자열을 반환합니다. 메시지가 전통
      적인 형식을 준수하면, 결과는 "'R'", "'O'", "'D'", "'F'" 및 "'A'"
      각각이 이 순서로 0이나 1회 등장하도록 이어붙인 것입니다.

   set_flags(flags)

      *flags*에서 지정한 플래그를 설정하고 다른 모든 플래그를 설정 해
      제합니다. 매개 변수 *flags*는 "'R'", "'O'", "'D'", "'F'" 및
      "'A'" 각각이 0개 이상 등장하도록 임의의 순서로 이어붙인 것이어야
      합니다.

   add_flag(flag)

      다른 플래그를 변경하지 않고 *flag*로 지정된 플래그를 설정합니다.
      한 번에 둘 이상의 플래그를 추가하기 위해, *flag*가 둘 이상의 문
      자로 구성된 문자열일 수 있습니다.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* may be a
      string of more than one character.

"MaildirMessage" 인스턴스를 기반으로 "mboxMessage" 인스턴스가 만들어지
면, "MaildirMessage" 인스턴스의 배달 날짜를 기반으로 "From " 줄이 생성
되고, 다음과 같은 변환이 발생합니다:

+-------------------+---------------------------------+
| 결과 상태         | "MaildirMessage" 상태           |
|===================|=================================|
| R 플래그          | S 플래그                        |
+-------------------+---------------------------------+
| O 플래그          | "cur" 하위 디렉터리             |
+-------------------+---------------------------------+
| D 플래그          | T 플래그                        |
+-------------------+---------------------------------+
| F 플래그          | F 플래그                        |
+-------------------+---------------------------------+
| A 플래그          | R 플래그                        |
+-------------------+---------------------------------+

"MHMessage" 인스턴스를 기반으로 "mboxMessage" 인스턴스가 만들어지면,
다음과 같은 변환이 발생합니다:

+---------------------+----------------------------+
| 결과 상태           | "MHMessage" 상태           |
|=====================|============================|
| R 플래그와 O 플래그 | "unseen" 시퀀스 없음       |
+---------------------+----------------------------+
| O 플래그            | "unseen" 시퀀스            |
+---------------------+----------------------------+
| F 플래그            | "flagged" 시퀀스           |
+---------------------+----------------------------+
| A 플래그            | "replied" 시퀀스           |
+---------------------+----------------------------+

"BabylMessage" 인스턴스를 기반으로 "mboxMessage" 인스턴스가 만들어지면
, 다음과 같은 변환이 발생합니다:

+---------------------+-------------------------------+
| 결과 상태           | "BabylMessage" 상태           |
|=====================|===============================|
| R 플래그와 O 플래그 | "unseen" 레이블 없음          |
+---------------------+-------------------------------+
| O 플래그            | "unseen" 레이블               |
+---------------------+-------------------------------+
| D 플래그            | "deleted" 레이블              |
+---------------------+-------------------------------+
| A 플래그            | "answered" 레이블             |
+---------------------+-------------------------------+

"MMDFMessage" 인스턴스를 기반으로 "mboxMessage" 인스턴스가 만들어지면,
"From " 줄이 복사되고 모든 플래그가 직접 대응됩니다:

+-------------------+------------------------------+
| 결과 상태         | "MMDFMessage" 상태           |
|===================|==============================|
| R 플래그          | R 플래그                     |
+-------------------+------------------------------+
| O 플래그          | O 플래그                     |
+-------------------+------------------------------+
| D 플래그          | D 플래그                     |
+-------------------+------------------------------+
| F 플래그          | F 플래그                     |
+-------------------+------------------------------+
| A 플래그          | A 플래그                     |
+-------------------+------------------------------+


"MHMessage" 객체
----------------

class mailbox.MHMessage(message=None)

   MH 특정 동작을 갖는 메시지. 매개 변수 *message*는 "Message" 생성자
   와 같은 의미입니다.

   MH 메시지는 전통적인 의미에서 마크나 플래그를 지원하지 않지만, 임의
   메시지의 논리적 그룹인 시퀀스를 지원합니다. 일부 메일 읽기 프로그램
   (표준 **mh**와 **nmh**는 아니지만)은 다음과 같이 다른 형식에서 플래
   그를 사용하는 것과 거의 같은 방식으로 시퀀스를 사용합니다:

   +------------+--------------------------------------------+
   | 시퀀스     | 설명                                       |
   |============|============================================|
   | unseen     | 읽지 않았지만, 이전에 MUA에서 감지했습니다 |
   |            | .                                          |
   +------------+--------------------------------------------+
   | replied    | 답장함                                     |
   +------------+--------------------------------------------+
   | flagged    | 중요하다고 표시됨                          |
   +------------+--------------------------------------------+

   "MHMessage" 인스턴스는 다음 메서드를 제공합니다:

   get_sequences()

      이 메시지를 포함하는 시퀀스의 이름 리스트를 반환합니다.

   set_sequences(sequences)

      이 메시지를 포함하는 시퀀스의 리스트를 설정합니다.

   add_sequence(sequence)

      이 메시지를 포함하는 시퀀스의 리스트에 *sequence*를 추가합니다.

   remove_sequence(sequence)

      이 메시지를 포함하는 시퀀스의 리스트에서 *sequence*를 제거합니다
      .

"MaildirMessage" 인스턴스를 기반으로 "MHMessage" 인스턴스가 만들어지면
, 다음과 같은 변환이 발생합니다:

+----------------------+---------------------------------+
| 결과 상태            | "MaildirMessage" 상태           |
|======================|=================================|
| "unseen" 시퀀스      | S 플래그 없음                   |
+----------------------+---------------------------------+
| "replied" 시퀀스     | R 플래그                        |
+----------------------+---------------------------------+
| "flagged" 시퀀스     | F 플래그                        |
+----------------------+---------------------------------+

"mboxMessage"나 "MMDFMessage" 인스턴스를 기반으로 "MHMessage" 인스턴스
가 만들어지면, *Status*와 *X-Status* 헤더가 생략되고 다음과 같은 변환
이 발생합니다:

+----------------------+------------------------------------------------+
| 결과 상태            | "mboxMessage"나 "MMDFMessage" 상태             |
|======================|================================================|
| "unseen" 시퀀스      | R 플래그 없음                                  |
+----------------------+------------------------------------------------+
| "replied" 시퀀스     | A 플래그                                       |
+----------------------+------------------------------------------------+
| "flagged" 시퀀스     | F 플래그                                       |
+----------------------+------------------------------------------------+

"BabylMessage" 인스턴스를 기반으로 "MHMessage" 인스턴스가 만들어지면,
다음과 같은 변환이 발생합니다:

+----------------------+-------------------------------+
| 결과 상태            | "BabylMessage" 상태           |
|======================|===============================|
| "unseen" 시퀀스      | "unseen" 레이블               |
+----------------------+-------------------------------+
| "replied" 시퀀스     | "answered" 레이블             |
+----------------------+-------------------------------+


"BabylMessage" 객체
-------------------

class mailbox.BabylMessage(message=None)

   Babyl 특정 동작을 갖는 메시지. 매개 변수 *message*는 "Message" 생성
   자와 같은 의미입니다.

   *어트리뷰트(attributes)*라고 부르는 특정 메시지 레이블은 관례에 따
   라 특별한 의미를 갖도록 정의됩니다. 어트리뷰트는 다음과 같습니다:

   +-------------+--------------------------------------------+
   | 레이블      | 설명                                       |
   |=============|============================================|
   | unseen      | 읽지 않았지만, 이전에 MUA에서 감지했습니다 |
   |             | .                                          |
   +-------------+--------------------------------------------+
   | deleted     | 후에 삭제하기 위해 표시함                  |
   +-------------+--------------------------------------------+
   | filed       | 다른 파일이나 사서함에 복사됨              |
   +-------------+--------------------------------------------+
   | answered    | 답장함                                     |
   +-------------+--------------------------------------------+
   | forwarded   | 전달됨                                     |
   +-------------+--------------------------------------------+
   | edited      | 사용자가 수정했음                          |
   +-------------+--------------------------------------------+
   | resent      | 다시 보냈음                                |
   +-------------+--------------------------------------------+

   기본적으로, Rmail은 가시적 헤더만 표시합니다. 그러나 "BabylMessage"
   클래스는 더 완전하기 때문에 원래 헤더를 사용합니다. 원하면 가시적
   헤더에 명시적으로 액세스 할 수 있습니다.

   "BabylMessage" 인스턴스는 다음 메서드를 제공합니다:

   get_labels()

      메시지의 레이블 리스트를 반환합니다.

   set_labels(labels)

      메시지의 레이블 리스트를 *labels*로 설정합니다.

   add_label(label)

      메시지의 레이블 리스트에 *label*을 추가합니다.

   remove_label(label)

      메시지의 레이블 리스트에서 *label*을 제거합니다.

   get_visible()

      헤더가 메시지의 가시적 헤더이고 본문이 비어있는 "Message" 인스턴
      스를 반환합니다.

   set_visible(visible)

      메시지의 가시적 헤더를 *message*의 헤더와 같게 설정합니다. 매개
      변수 *visible*은 "Message" 인스턴스, "email.message.Message" 인
      스턴스, 문자열 또는 파일류 객체(텍스트 모드로 열어야 합니다)여야
      합니다.

   update_visible()

      "BabylMessage" 인스턴스의 원래 헤더가 수정될 때, 가시적 헤더는
      일치하도록 자동으로 수정되지 않습니다. 이 메서드는 다음과 같이
      가시적 헤더를 갱신합니다: 해당 원본 헤더가 있는 각 가시적 헤더는
      원래 헤더의 값으로 설정되고, 해당 원본 헤더가 없는 각 가시적 헤
      더는 제거되며 원래 헤더에는 있지만, 가시적 헤더에는 없는 *Date*,
      *From*, *Reply-To*, *To*, *CC* 및 *Subject*는 모두 가시적 헤더에
      추가됩니다.

"MaildirMessage" 인스턴스를 기반으로 "BabylMessage" 인스턴스가 만들어
지면, 다음과 같은 변환이 발생합니다:

+---------------------+---------------------------------+
| 결과 상태           | "MaildirMessage" 상태           |
|=====================|=================================|
| "unseen" 레이블     | S 플래그 없음                   |
+---------------------+---------------------------------+
| "deleted" 레이블    | T 플래그                        |
+---------------------+---------------------------------+
| "answered" 레이블   | R 플래그                        |
+---------------------+---------------------------------+
| "forwarded" 레이블  | P 플래그                        |
+---------------------+---------------------------------+

"mboxMessage"나 "MMDFMessage" 인스턴스를 기반으로 "BabylMessage" 인스
턴스가 만들어지면, *Status*와 *X-Status* 헤더가 생략되고 다음과 같은
변환이 발생합니다:

+--------------------+------------------------------------------------+
| 결과 상태          | "mboxMessage"나 "MMDFMessage" 상태             |
|====================|================================================|
| "unseen" 레이블    | R 플래그 없음                                  |
+--------------------+------------------------------------------------+
| "deleted" 레이블   | D 플래그                                       |
+--------------------+------------------------------------------------+
| "answered" 레이블  | A 플래그                                       |
+--------------------+------------------------------------------------+

"MHMessage" 인스턴스를 기반으로 "BabylMessage" 인스턴스가 만들어지면,
다음과 같은 변환이 발생합니다:

+--------------------+----------------------------+
| 결과 상태          | "MHMessage" 상태           |
|====================|============================|
| "unseen" 레이블    | "unseen" 시퀀스            |
+--------------------+----------------------------+
| "answered" 레이블  | "replied" 시퀀스           |
+--------------------+----------------------------+


"MMDFMessage" 객체
------------------

class mailbox.MMDFMessage(message=None)

   MMDF 특정 동작을 갖는 메시지. 매개 변수 *message*는 "Message" 생성
   자와 같은 의미입니다.

   mbox 사서함의 메시지와 마찬가지로, MMDF 메시지는 보낸 사람의 주소와
   배달 날짜가 "From "으로 시작하는 첫 줄에 저장됩니다. 마찬가지로, 메
   시지의 상태를 나타내는 플래그는 일반적으로 *Status*와 *X-Status* 헤
   더에 저장됩니다.

   MMDF 메시지의 전통적인 플래그는 mbox 메시지의 플래그와 동일하며 다
   음과 같습니다:

   +--------+------------+----------------------------------+
   | 플래그 | 의미       | 설명                             |
   |========|============|==================================|
   | R      | 읽었음     | 읽었음                           |
   +--------+------------+----------------------------------+
   | O      | 오래되었음 | 전에 MUA에서 감지됨              |
   +--------+------------+----------------------------------+
   | D      | 삭제됨     | 후에 삭제하기 위해 표시함        |
   +--------+------------+----------------------------------+
   | F      | 깃발 표시  | 중요하다고 표시됨                |
   +--------+------------+----------------------------------+
   | A      | 답변함     | 답장함                           |
   +--------+------------+----------------------------------+

   "R"과 "O" 플래그는 *Status* 헤더에 저장되고, "D", "F" 및 "A" 플래그
   는 *X-Status* 헤더에 저장됩니다. 플래그와 헤더는 일반적으로 언급된
   순서대로 나타납니다.

   "MMDFMessage" 인스턴스는 "mboxMessage"에서 제공하는 것과 동일한 다
   음 메서드를 제공합니다:

   get_from()

      mbox 사서함에서 메시지의 시작을 표시하는 "From " 줄을 나타내는
      문자열을 반환합니다. 선행 "From "과 후행 줄넘김은 제외됩니다.

   set_from(from_, time_=None)

      "From " 줄을 *from_*으로 설정합니다. *from_*은 선행 "From "이나
      후행 줄넘김 없이 지정되어야 합니다. 편의를 위해, *time_*을 지정
      할 수 있으며 적절하게 포맷해서 *from_*에 추가합니다. *time_*이
      지정되면, "time.struct_time" 인스턴스, "time.strftime()"로 전달
      하기에 적합한 튜플 또는 "True"("time.gmtime()" 사용)여야 합니다.

   get_flags()

      현재 설정된 플래그를 지정하는 문자열을 반환합니다. 메시지가 전통
      적인 형식을 준수하면, 결과는 "'R'", "'O'", "'D'", "'F'" 및 "'A'"
      각각이 이 순서로 0이나 1회 등장하도록 이어붙인 것입니다.

   set_flags(flags)

      *flags*에서 지정한 플래그를 설정하고 다른 모든 플래그를 설정 해
      제합니다. 매개 변수 *flags*는 "'R'", "'O'", "'D'", "'F'" 및
      "'A'" 각각이 0개 이상 등장하도록 임의의 순서로 이어붙인 것이어야
      합니다.

   add_flag(flag)

      다른 플래그를 변경하지 않고 *flag*로 지정된 플래그를 설정합니다.
      한 번에 둘 이상의 플래그를 추가하기 위해, *flag*가 둘 이상의 문
      자로 구성된 문자열일 수 있습니다.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* may be a
      string of more than one character.

"MaildirMessage" 인스턴스를 기반으로 "MMDFMessage" 인스턴스가 만들어지
면, "MaildirMessage" 인스턴스의 배달 날짜를 기반으로 "From " 줄이 생성
되고, 다음과 같은 변환이 발생합니다:

+-------------------+---------------------------------+
| 결과 상태         | "MaildirMessage" 상태           |
|===================|=================================|
| R 플래그          | S 플래그                        |
+-------------------+---------------------------------+
| O 플래그          | "cur" 하위 디렉터리             |
+-------------------+---------------------------------+
| D 플래그          | T 플래그                        |
+-------------------+---------------------------------+
| F 플래그          | F 플래그                        |
+-------------------+---------------------------------+
| A 플래그          | R 플래그                        |
+-------------------+---------------------------------+

"MHMessage" 인스턴스를 기반으로 "MMDFMessage" 인스턴스가 만들어지면,
다음과 같은 변환이 발생합니다:

+---------------------+----------------------------+
| 결과 상태           | "MHMessage" 상태           |
|=====================|============================|
| R 플래그와 O 플래그 | "unseen" 시퀀스 없음       |
+---------------------+----------------------------+
| O 플래그            | "unseen" 시퀀스            |
+---------------------+----------------------------+
| F 플래그            | "flagged" 시퀀스           |
+---------------------+----------------------------+
| A 플래그            | "replied" 시퀀스           |
+---------------------+----------------------------+

"BabylMessage" 인스턴스를 기반으로 "MMDFMessage" 인스턴스가 만들어지면
, 다음과 같은 변환이 발생합니다:

+---------------------+-------------------------------+
| 결과 상태           | "BabylMessage" 상태           |
|=====================|===============================|
| R 플래그와 O 플래그 | "unseen" 레이블 없음          |
+---------------------+-------------------------------+
| O 플래그            | "unseen" 레이블               |
+---------------------+-------------------------------+
| D 플래그            | "deleted" 레이블              |
+---------------------+-------------------------------+
| A 플래그            | "answered" 레이블             |
+---------------------+-------------------------------+

"mboxMessage" 인스턴스를 기반으로 "MMDFMessage" 인스턴스가 만들어지면,
"From " 줄이 복사되고 모든 플래그가 직접 대응됩니다:

+-------------------+------------------------------+
| 결과 상태         | "mboxMessage" 상태           |
|===================|==============================|
| R 플래그          | R 플래그                     |
+-------------------+------------------------------+
| O 플래그          | O 플래그                     |
+-------------------+------------------------------+
| D 플래그          | D 플래그                     |
+-------------------+------------------------------+
| F 플래그          | F 플래그                     |
+-------------------+------------------------------+
| A 플래그          | A 플래그                     |
+-------------------+------------------------------+


예외
====

다음 예외 클래스가 "mailbox" 모듈에 정의되어 있습니다:

exception mailbox.Error

   The base class for all other module-specific exceptions.

exception mailbox.NoSuchMailboxError

   사서함이 기대되지만 찾을 수 없을 때 발생합니다, 가령 존재하지 않는
   경로로 (그리고 "False"로 설정된 *create* 매개 변수를 사용하여)
   "Mailbox" 서브 클래스를 인스턴스 화하거나, 존재하지 않는 폴더를 열
   때.

exception mailbox.NotEmptyError

   사서함이 비어 있지 않지만 비어있을 것으로 기대될 때 발생합니다, 가
   령 메시지가 포함된 폴더를 삭제할 때.

exception mailbox.ExternalClashError

   Raised when some mailbox-related condition beyond the control of
   the program causes it to be unable to proceed, such as when failing
   to acquire a lock that another program already holds, or when a
   uniquely generated file name already exists.

exception mailbox.FormatError

   파일의 데이터를 구문 분석할 수 없을 때 발생합니다, 가령 "MH" 인스턴
   스가 손상된 ".mh_sequences" 파일을 읽으려고 할 때.


예
==

사서함에 있는 모든 흥미롭게 보이는 메시지의 제목을 인쇄하는 간단한 예:

   import mailbox
   for message in mailbox.mbox('~/mbox'):
       subject = message['subject']       # None일 수 있습니다.
       if subject and 'python' in subject.lower():
           print(subject)

변환할 수 있는 모든 형식별 정보를 변환하면서, Babyl 사서함에서 MH 사서
함으로 모든 메일을 복사하려면:

   import mailbox
   destination = mailbox.MH('~/Mail')
   destination.lock()
   for message in mailbox.Babyl('~/RMAIL'):
       destination.add(mailbox.MHMessage(message))
   destination.flush()
   destination.unlock()

이 예에서는 여러 메일링 리스트로부터의 메일을 다른 사서함으로 정렬하여
넣고, 다른 프로그램에 의한 동시 수정으로 인한 메일 손상, 프로그램 중단
으로 인한 메일 손실 또는 사서함에 있는 잘못된 메시지로 인한 조기 종료
를 방지하도록 주의합니다:

   import mailbox
   import email.errors

   list_names = ('python-list', 'python-dev', 'python-bugs')

   boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
   inbox = mailbox.Maildir('~/Maildir', factory=None)

   for key in inbox.iterkeys():
       try:
           message = inbox[key]
       except email.errors.MessageParseError:
           continue                # 메시지가 잘못되었습니다. 그냥 둡니다.

       for name in list_names:
           list_id = message['list-id']
           if list_id and name in list_id:
               # 사용할 사서함을 얻습니다
               box = boxes[name]

               # 원본을 제거하기 전에 사본을 디스크에 기록합니다.
               # 충돌이 있으면, 메시지가 중복될 수 있지만, 메시지를 완전히 잃어버리는
               # 것보다는 낫습니다.
               box.lock()
               box.add(message)
               box.flush()
               box.unlock()

               # 원본 메시지 제거
               inbox.lock()
               inbox.discard(key)
               inbox.flush()
               inbox.unlock()
               break               # 목적지를 찾았으니, 그만 찾습니다.

   for box in boxes.itervalues():
       box.close()
