mailbox — Управление почтовыми ящиками в различных форматах

Исходный код: Lib/mailbox.py

Этот модуль определяет два класса, Mailbox и Message, для доступа и управления почтовыми ящиками на диске и сообщениями, которые они содержат. Mailbox предоставляет отображение, подобное словарю, из ключей в сообщения. Message расширяет класс email.message модуля Message с состоянием и поведением, специфичными для формата. Поддерживаемые форматы почтовых ящиков: Maildir, mbox, MH, Babyl и MMDF.

См. также

Module email: Представление и обработка сообщений.

Объекты почтового ящика

class mailbox.Mailbox

Почтовый ящик, который можно просматривать и изменять.

Класс Mailbox определяет интерфейс и не предназначен для создания экземпляров. Вместо этого, подклассы, специфичные для формата, должны наследоваться от Mailbox, а ваш код должен создавать экземпляры конкретного подкласса.

Интерфейс Mailbox подобен словарю, с небольшими ключами, соответствующими сообщениям. Ключи выдаются экземпляром Mailbox, с которым они будут использоваться, и имеют смысл только для этого экземпляра Mailbox. Ключ продолжает идентифицировать сообщение, даже если соответствующее сообщение изменено, например, заменено другим сообщением.

Сообщения могут быть добавлены к экземпляру Mailbox с помощью метода add(), похожего на добавление в множество, и удалены с помощью оператора del или методов, похожих на удаление из множества, remove() и discard().

Семантика интерфейса Mailbox отличается от семантики словаря несколькими важными аспектами. Каждый раз, когда запрашивается сообщение, генерируется новое представление (обычно экземпляр Message), основанное на текущем состоянии почтового ящика. Аналогично, при добавлении сообщения в экземпляр Mailbox содержимое предоставленного представления сообщения копируется. В обоих случаях экземпляр Mailbox не сохраняет ссылку на представление сообщения.

По умолчанию итератор Mailbox итерируется по представлениям сообщений, а не по ключам, как это делает итератор словаря по умолчанию. Кроме того, изменение почтового ящика во время итерации безопасно и корректно определено. Сообщения, добавленные в почтовый ящик после создания итератора, не будут видны итератору. Сообщения, удаленные из почтового ящика до того, как итератор их предоставит, будут пропущены, хотя использование ключа из итератора может привести к исключению KeyError, если соответствующее сообщение впоследствии будет удалено.

Предупреждение

Будьте очень осторожны при изменении почтовых ящиков, которые могут быть одновременно изменены другим процессом. Наиболее безопасный формат почтового ящика для таких задач — Maildir; старайтесь избегать использования форматов с одним файлом, таких как mbox, для одновременной записи. Если вы изменяете почтовый ящик, вы обязательно должны заблокировать его, вызвав методы lock() и unlock() перед чтением каких-либо сообщений в файле или внесением каких-либо изменений путем добавления или удаления сообщения. Отсутствие блокировки почтового ящика может привести к потере сообщений или повреждению всего почтового ящика.

Экземпляры Mailbox имеют следующие методы:

add(message)

Добавить message в почтовый ящик и вернуть ключ, который был ему назначен.

Параметр message может быть экземпляром Message, экземпляром email.message.Message, строкой, строкой байтов или объектом типа «подобный файлу» (который должен быть открыт в двоичном режиме). Если message является экземпляром соответствующего подкласса Message, специфичного для формата (например, если это экземпляр mboxMessage, а это экземпляр mbox), используется его информация, специфичная для формата. В противном случае используются разумные значения по умолчанию для информации, специфичной для формата.

Изменено в версии 3.2: Добавлена поддержка двоичного ввода.

remove(key)

__delitem__(key)

discard(key)

Удалить сообщение, соответствующее key, из почтового ящика.

Если такого сообщения не существует, генерируется исключение KeyError, если метод был вызван как remove() или __delitem__(), но исключение не генерируется, если метод был вызван как discard(). Поведение discard() может быть предпочтительным, если формат базового почтового ящика поддерживает одновременное изменение другими процессами.

__setitem__(key, message)

Заменить сообщение, соответствующее key, на message. Вызвать исключение KeyError, если сообщение, соответствующее key, не существует.

Как и в случае с add(), параметр message может быть экземпляром Message, экземпляром email.message.Message, строкой, строкой байтов или объектом типа «подобный файлу» (который должен быть открыт в двоичном режиме). Если message является экземпляром соответствующего подкласса Message, специфичного для формата (например, если это экземпляр mboxMessage, а это экземпляр mbox), используется его информация, специфичная для формата. В противном случае информация, специфичная для формата, сообщения, которое соответствует key, остается неизменной.

iterkeys()
keys(): Возвращает итератор по всем ключам, если вызвана как iterkeys(), или список ключей, если вызвана как keys().

itervalues()
__iter__()
values(): Возвращает итератор по представлениям всех сообщений, если вызвана как itervalues() или __iter__(), или список таких представлений, если вызвана как values(). Сообщения представлены как экземпляры соответствующего подкласса Message, специфичного для формата, если не был указан пользовательский фабричный метод сообщений при инициализации экземпляра Mailbox.

Примечание

Поведение __iter__() отличается от поведения словарей, которые итерируются по ключам.

iteritems()
items(): Возвращает итератор по парам (key, message), где key — ключ, а message — представление сообщения, если вызвана как iteritems(), или список таких пар, если вызвана как items(). Сообщения представлены как экземпляры соответствующего подкласса Message, специфичного для формата, если не был указан пользовательский фабричный метод сообщений при инициализации экземпляра Mailbox.

get(key, default=None)
__getitem__(key): Возвращает представление сообщения, соответствующего ключу key. Если такого сообщения нет, возвращается default, если метод был вызван как get(), и возникает исключение KeyError, если метод был вызван как __getitem__(). Сообщение представляется как экземпляр соответствующего подкласса Message для конкретного формата, если при инициализации экземпляра Mailbox не был указан пользовательский фабричный метод для сообщений.

get_message(key): Возвращает представление сообщения, соответствующего ключу key, в виде экземпляра соответствующего подкласса Message для конкретного формата, или вызывает исключение KeyError, если такого сообщения нет.

get_bytes(key): Возвращает байтовое представление сообщения, соответствующего ключу key, или вызывает исключение KeyError, если такого сообщения нет.

Добавлена в версии 3.2.

get_string(key): Возвращает строковое представление сообщения, соответствующего ключу key, или вызывает исключение KeyError, если такого сообщения нет. Сообщение обрабатывается через email.message.Message для преобразования в представление, очищенное от символов с кодировкой 7 бит.

get_file(key): Возвращает файлоподобное представление сообщения, соответствующего ключу key, или вызывает исключение KeyError, если такого сообщения нет. Файлоподобный объект ведет себя так, как будто открыт в двоичном режиме. Этот файл должен быть закрыт, как только он больше не нужен.

Изменено в версии 3.2: Файловый объект действительно является двоичным файлом; ранее он неправильно возвращался в текстовом режиме. Также файлоподобный объект теперь поддерживает протокол управления контекстом: вы можете использовать оператор with для автоматического закрытия файла.

Примечание

В отличие от других представлений сообщений, файлоподобные представления не обязательно независимы от экземпляра Mailbox, который их создал, или от базового почтового ящика. Более подробные сведения приводятся в документации каждого подкласса.

__contains__(key): Возвращает True , если key соответствует сообщению, False в противном случае.

__len__(): Возвращает количество сообщений в почтовом ящике.

clear(): Удаляет все сообщения из почтового ящика.

pop(key, default=None): Возвращает представление сообщения, соответствующего key, и удаляет сообщение. Если такого сообщения нет, возвращает default. Сообщение представляется как экземпляр соответствующего подкласса Message для конкретного формата, если при инициализации экземпляра Mailbox не был указан пользовательский фабричный метод для сообщений.

popitem(): Возвращает произвольную пару (key, message), где key — ключ, а message — представление сообщения, и удаляет соответствующее сообщение. Если почтовый ящик пуст, возникает исключение KeyError. Сообщение представляется как экземпляр соответствующего подкласса Message для конкретного формата, если при инициализации экземпляра Mailbox не был указан пользовательский фабричный метод для сообщений.

update(arg): Параметр arg должен быть отображением key-to-message или итерируемым списком пар (key, message). Обновляет почтовый ящик так, что для каждого заданного key и message сообщение, соответствующее key, устанавливается в message так же, как если бы это было сделано с помощью __setitem__(). Как и в случае с __setitem__(), каждый key должен уже соответствовать сообщению в почтовом ящике, иначе будет вызвано исключение KeyError, поэтому в общем случае неверно, чтобы arg был экземпляром Mailbox.

Примечание

В отличие от словарей, ключевые аргументы не поддерживаются.

flush(): Записывает все ожидающие изменения в файловую систему. Для некоторых подклассов Mailbox изменения всегда записываются немедленно, и flush() ничего не делает, но вы должны все равно привыкнуть вызывать этот метод.

lock(): Приобретает эксклюзивную консультативную блокировку почтового ящика, чтобы другие процессы знали, что не должны его изменять. Если блокировка недоступна, возникает ExternalClashError. Конкретные механизмы блокировки зависят от формата почтового ящика. Вы всегда должны блокировать почтовый ящик перед внесением любых изменений в его содержимое.

unlock(): Освобождает блокировку почтового ящика, если она существует.

close(): Очищает почтовый ящик, разблокирует его при необходимости и закрывает все открытые файлы. Для некоторых подклассов Mailbox этот метод ничего не делает.

`Maildir`

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

Подкласс Mailbox для почтовых ящиков в формате Maildir. Параметр factory — вызываемый объект, принимающий представление сообщения в виде файла (как если бы оно было открыто в двоичном режиме) и возвращающий пользовательское представление. Если factory — None, используется MaildirMessage в качестве стандартного представления сообщения. Если create — True, почтовый ящик создаётся, если он не существует.

Если create — True, и путь dirname существует, он будет обрабатываться как существующий Maildir без проверки структуры каталога.

Имя dirname так названо по историческим причинам, а не path.

Maildir — это основанный на каталогах формат почтовых ящиков, изобретённый для qmail mail transfer agent и сейчас широко поддерживается другими программами. Сообщения в почтовом ящике Maildir хранятся в отдельных файлах внутри общей структуры каталогов. Эта конструкция позволяет почтовым ящикам Maildir получать доступ и модифицировать их несколькими независимыми программами без повреждения данных, поэтому блокировка файлов не требуется.

Почтовые ящики Maildir содержат три подкаталога: tmp, new, и cur. Сообщения временно создаются в подкаталоге tmp, а затем перемещаются в подкаталог new для завершения доставки. После этого пользовательский агент может переместить сообщение в подкаталог cur и сохранить информацию о состоянии сообщения в специальном разделе «info», добавленном к имени файла.

Также поддерживаются папки в стиле, введённом Courier mail transfer agent. Любой подкаталог основного почтового ящика считается папкой, если '.' — это первый символ в его имени. Имена папок представляются Maildir без ведущего '.'. Каждая папка сама по себе является почтовым ящиком Maildir, но не должна содержать другие папки. Вместо этого логическое вложение указывается с помощью '.' для разделения уровней, например, «Archived.2005.07».

Примечание

Спецификация Maildir требует использования двоеточия (':') в некоторых именах файлов сообщений. Однако некоторые операционные системы не допускают этого символа в именах файлов. Если вы хотите использовать формат Maildir в такой операционной системе, вы должны указать другой символ для использования вместо него. Восклицательный знак ('!') — популярный выбор. Например:

import mailbox
mailbox.Maildir.colon = '!'

Атрибут colon также может быть установлен для каждого экземпляра.

Maildir экземпляры имеют все методы Mailbox в дополнение к следующим:

list_folders(): Возвращает список имён всех папок.

get_folder(folder): Возвращает экземпляр Maildir, представляющий папку с именем folder. Если папка не существует, генерируется исключение NoSuchMailboxError.

add_folder(folder): Создаёт папку с именем folder и возвращает экземпляр Maildir, представляющий её.

remove_folder(folder): Удаляет папку с именем folder. Если папка содержит сообщения, генерируется исключение NotEmptyError, и папка не удаляется.

clean(): Удаляет временные файлы из почтового ящика, к которым не было доступа в течение последних 36 часов. В спецификации Maildir указано, что программы чтения почты должны это периодически делать.

Некоторые методы Mailbox, реализованные в Maildir, заслуживают особого внимания:

add(message)
__setitem__(key, message)
update(arg): Предупреждение

Эти методы генерируют уникальные имена файлов, основанные на текущем идентификаторе процесса. При использовании нескольких потоков могут произойти незамеченные конфликты имён и привести к повреждению почтового ящика, если потоки не скоординированы, чтобы избежать использования этих методов для одновременной обработки одного и того же почтового ящика.

flush(): Все изменения в почтовых ящиках Maildir применяются немедленно, поэтому этот метод ничего не делает.

lock()
unlock(): Почтовые ящики Maildir не поддерживают (или не требуют) блокировки, поэтому эти методы ничего не делают.

close(): Экземпляры Maildir не сохраняют открытые файлы, а подлежащие почтовые ящики не поддерживают блокировку, поэтому этот метод ничего не делает.

get_file(key): В зависимости от платформы хоста, возможно, невозможно изменить или удалить базовое сообщение, пока возвращаемый файл остаётся открытым.

См. также

maildir man page from Courier: Спецификация формата. Описывает общее расширение для поддержки папок.
Использование формата maildir: Заметки о формате Maildir от его создателя. Включает обновлённую схему создания имён и подробности о семантике «info».

`mbox`

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

Подкласс Mailbox для почтовых ящиков в формате mbox. Параметр factory — вызываемый объект, принимающий представление сообщения в виде файла (как если бы оно было открыто в двоичном режиме) и возвращающий пользовательское представление. Если factory — None, используется mboxMessage в качестве стандартного представления сообщения. Если create — True, почтовый ящик создаётся, если он не существует.

Формат mbox — классический формат для хранения почты в системах Unix. Все сообщения в почтовом ящике mbox хранятся в одном файле, и начало каждого сообщения обозначается строкой, первые пять символов которой «From «.

Существуют несколько вариантов формата mbox, направленных на устранение предполагаемых недостатков оригинала. В интересах совместимости mbox реализует оригинальный формат, иногда называемый mboxo. Это означает, что заголовок Content-Length, если он присутствует, игнорируется, и все вхождения «From » в начале строки в теле сообщения преобразуются в «>From » при сохранении сообщения, хотя вхождения «>From » не преобразуются в «From » при чтении сообщения.

Некоторые методы Mailbox, реализованные в mbox, заслуживают особого внимания:

get_file(key): Использование файла после вызова flush() или close() в экземпляре mbox может привести к непредсказуемым результатам или выбросу исключения.

lock()
unlock(): Используются три механизма блокировки: точечная блокировка и, если доступны, системные вызовы flock() и lockf().

См. также

mbox man page from tin: Спецификация формата с подробными сведениями о блокировке.
Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad: Аргументы в пользу использования оригинального формата mbox вместо вариаций.
“mbox” is a family of several mutually incompatible mailbox formats: История вариаций формата mbox.

`MH`

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

Подкласс Mailbox для почтовых ящиков в формате MH. Параметр factory — вызываемый объект, принимающий представление сообщения в виде файла (как если бы он был открыт в двоичном режиме) и возвращающий настраиваемое представление. Если factory равен None, по умолчанию используется MHMessage для представления сообщения. Если create равно True, почтовый ящик создается, если он не существует.

MH — это основанный на каталогах формат почтовых ящиков, созданный для системы обработки почты MH, почтового агента пользователя. Каждое сообщение в почтовом ящике MH хранится в отдельном файле. Почтовый ящик MH может содержать другие почтовые ящики MH (называемые папками) помимо сообщений. Папки могут быть вложены неограниченно. Почтовые ящики MH также поддерживают последовательности, которые представляют собой именованные списки, используемые для логической группировки сообщений без перемещения их в подпапки. Последовательности определяются в файле, называемом .mh_sequences в каждой папке.

Класс MH обрабатывает почтовые ящики MH, но не пытается эмулировать все поведения mh. В частности, он не изменяет и не зависит от файлов context и .mh_profile, которые используются mh для хранения состояния и конфигурации.

Объекты MH имеют все методы Mailbox плюс следующие:

list_folders(): Возвращает список имён всех папок.

get_folder(folder): Возвращает экземпляр MH, представляющий папку с именем folder. Если папки не существует, возбуждается исключение NoSuchMailboxError.

add_folder(folder): Создаёт папку с именем folder и возвращает экземпляр MH, представляющий её.

remove_folder(folder): Удаляет папку с именем folder. Если папка содержит сообщения, возбуждается исключение NotEmptyError, и папка не удаляется.

get_sequences(): Возвращает словарь имён последовательностей, сопоставленных со списками ключей. Если последовательностей нет, возвращается пустой словарь.

set_sequences(sequences): Переопределяет существующие в почтовом ящике последовательности на основе sequences, словаря имён, сопоставленных со списками ключей, подобно тому, что возвращает get_sequences().

pack(): Переименовывает сообщения в почтовом ящике по мере необходимости, чтобы устранить пробелы в нумерации. Записи в списке последовательностей обновляются соответствующим образом.

Примечание

Ключи, уже выданные, аннулируются этой операцией и не должны использоваться впоследствии.

Некоторые методы Mailbox, реализованные в MH, заслуживают особого упоминания:

remove(key)
__delitem__(key)
discard(key): Эти методы немедленно удаляют сообщение. Конвенция MH помечать сообщение для удаления путём добавления запятой в начало имени не используется.

lock()
unlock(): Используются три механизма блокировки — точечная блокировка и, если доступны, системные вызовы flock() и lockf(). Для почтовых ящиков MH блокировка ящика означает блокировку файла .mh_sequences и, только на время любых операций, влияющих на них, блокировку отдельных файлов сообщений.

get_file(key): В зависимости от платформы может не быть возможности удалить базовое сообщение, пока возвращаемый файл остаётся открытым.

flush(): Все изменения в почтовых ящиках MH применяются немедленно, поэтому этот метод ничего не делает.

close(): Экземпляры MH не хранят открытых файлов, поэтому этот метод эквивалентен unlock().

См. также

nmh - Система обработки сообщений: Главная страница nmh, обновленной версии исходного mh.
MH & nmh: Электронная почта для пользователей и программистов: Книга с открытым кодом GPL о mh и nmh, с некоторыми сведениями о формате почтового ящика.

`Babyl`

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

Подкласс Mailbox для почтовых ящиков в формате Babyl. Параметр factory — вызываемый объект, принимающий представление сообщения в виде файла (как если бы он был открыт в двоичном режиме) и возвращающий настраиваемое представление. Если factory равен None, по умолчанию используется BabylMessage для представления сообщения. Если create равно True, почтовый ящик создаётся, если он не существует.

Babyl — это формат почтового ящика из одного файла, используемый почтовым агентом Rmail, включённым в Emacs. Начало сообщения обозначается строкой, содержащей два символа Control-Underscore ('\037') и Control-L ('\014'). Конец сообщения обозначается началом следующего сообщения или, в случае последнего сообщения, строкой, содержащей символ Control-Underscore ('\037').

Сообщения в почтовом ящике Babyl имеют два набора заголовков: исходные заголовки и так называемые видимые заголовки. Видимые заголовки обычно представляют собой подмножество исходных заголовков, которые были переформатированы или сокращены для большей привлекательности. Каждое сообщение в почтовом ящике Babyl также имеет связанный список меток или коротких строк, которые записывают дополнительную информацию о сообщении, и список всех пользовательских меток, найденных в почтовом ящике, сохраняется в разделе опций Babyl.

Объекты Babyl имеют все методы Mailbox плюс следующие:

get_labels(): Возвращает список имён всех пользовательских меток, используемых в почтовом ящике.

Примечание

Фактические сообщения проверяются, чтобы определить, какие метки существуют в почтовом ящике, а не консультируется список меток в разделе опций Babyl, но раздел Babyl обновляется всякий раз, когда почтовый ящик изменяется.

Некоторые методы Mailbox, реализованные в Babyl, заслуживают особого упоминания:

get_file(key): В почтовых ящиках Babyl заголовки сообщения не хранятся непрерывно с телом сообщения. Для создания представления в виде файла заголовки и тело копируются вместе в объект io.BytesIO, который имеет API, идентичный API файла. В результате, объекту в виде файла не требуется доступ к базовому почтовому ящику, но он не экономит память по сравнению с строковым представлением.

lock()
unlock(): Используются три механизма блокировки — точечная блокировка и, если доступны, системные вызовы flock() и lockf().

См. также

Формат файлов Babyl версии 5: Спецификация формата Babyl.
Чтение почты с помощью Rmail: Справочник по Rmail, с некоторыми сведениями о семантике Babyl.

END_OF_DOCUMENT_MARKER

`MMDF`

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

Подкласс Mailbox для почтовых ящиков в формате MMDF. Параметр factory — вызываемый объект, принимающий представление сообщения в формате файла (как если бы оно было открыто в двоичном режиме) и возвращающий пользовательское представление. Если factory — None, по умолчанию используется MMDFMessage для представления сообщений. Если create — True, почтовый ящик создаётся, если он не существует.

MMDF — формат почтового ящика в одном файле, разработанный для Multichannel Memorandum Distribution Facility, агента передачи почты. Каждое сообщение имеет тот же формат, что и сообщение mbox, но заключено в строки, содержащие четыре символа Control-A ('\001') перед и после. Как и в формате mbox, начало каждого сообщения обозначается строкой, первые пять символов которой — «From », но дополнительные вхождения «From » не преобразуются в «>From » при сохранении сообщений, потому что дополнительные разделительные строки сообщений предотвращают ошибочное восприятие таких вхождений как начала последующих сообщений.

Некоторые методы Mailbox, реализованные в MMDF, заслуживают особого упоминания:

get_file(key): Использование файла после вызова flush() или close() на экземпляре MMDF может привести к непредсказуемым результатам или исключению.

lock()
unlock(): Используются три механизма блокировки: точечная блокировка и, если доступны, системные вызовы flock() и lockf().

См. также

mmdf man page от tin: Спецификация формата MMDF из документации tin, программы просмотра новостей.
MMDF: Статья Википедии, описывающая Multichannel Memorandum Distribution Facility.

Объекты сообщений

class mailbox.Message(message=None)

Подкласс класса email.message модуля Message. Подклассы mailbox.Message добавляют состояние и поведение, специфичные для формата почтового ящика.

Если message опущено, новый экземпляр создается в стандартном пустом состоянии. Если message является экземпляром email.message.Message, его содержимое копируется; кроме того, любая информация, специфичная для формата, преобразуется, насколько это возможно, если message является экземпляром Message. Если message является строкой, байтовой строкой или файлом, он должен содержать сообщение, соответствующее RFC 2822, которое будет прочитано и обработано. Файлы должны быть открыты в двоичном режиме, но текстовые файлы принимаются для обратной совместимости.

Состояние и поведение, специфичные для формата, предлагаемые подклассами, варьируются, но в целом поддерживаются только свойства, не специфичные для конкретного почтового ящика (хотя, предположительно, свойства специфичны для конкретного формата почтового ящика). Например, смещения файлов для почтовых ящиков с одним файлом и имена файлов для почтовых ящиков на основе каталогов не сохраняются, потому что они применимы только к исходному почтовому ящику. Но состояние, такое как прочитано ли сообщение пользователем или помечено как важное, сохраняется, потому что оно относится к самому сообщению.

Не требуется, чтобы экземпляры Message использовались для представления сообщений, извлечённых с помощью экземпляров Mailbox. В некоторых ситуациях время и память, необходимые для создания представлений Message, могут быть неприемлемы. В таких ситуациях экземпляры Mailbox также предлагают строковые и файловые представления, и при инициализации экземпляра Mailbox может быть указана пользовательская фабрика сообщений.

`MaildirMessage`

class mailbox.MaildirMessage(message=None)

Сообщение со специфичным для Maildir поведением. Параметр message имеет то же значение, что и для конструктора Message.

Обычно приложение почтового клиента перемещает все сообщения в подкаталоге new в подкаталог cur после первого открытия и закрытия почтового ящика, записывая, что сообщения являются старыми, независимо от того, были ли они прочитаны на самом деле. Каждое сообщение в подкаталоге cur имеет добавленный в имя файла раздел «info», чтобы хранить информацию о его состоянии. (Некоторые почтовые клиенты также могут добавлять раздел «info» к сообщениям в подкаталоге new.) Раздел «info» может иметь одну из двух форм: он может содержать «2», за которым следует список стандартных флагов (например, «2,FR»), или он может содержать «1», за которым следует так называемая экспериментальная информация. Стандартные флаги для сообщений Maildir следующие:

Флаг	Значение	Описание
D	Черновик	В процессе составления
F	Помечено	Отмечено как важное
P	Прошло	Переслано, переотправлено или возвращено
R	Ответ	Отвечено
S	Просмотрено	Прочитано
T	Удалено	Помечено для последующего удаления

Экземпляры MaildirMessage предлагают следующие методы:

get_subdir(): Возвращает «new» (если сообщение должно храниться в подкаталоге new) или «cur» (если сообщение должно храниться в подкаталоге cur).

Примечание

Сообщение обычно перемещается из new в cur после доступа к почтовому ящику, независимо от того, было ли сообщение прочитано. Сообщение msg считается прочитанным, если "S" in msg.get_flags() равно True.

set_subdir(subdir): Устанавливает подкаталог, в котором должно храниться сообщение. Параметр subdir должен быть либо «new», либо «cur».

get_flags(): Возвращает строку, определяющую текущие флаги. Если сообщение соответствует стандартному формату Maildir, результатом является конкатенация в алфавитном порядке нуля или одного вхождения каждого из 'D', 'F', 'P', 'R', 'S', и 'T'. Возвращается пустая строка, если флаги не установлены или «info» содержит экспериментальную семантику.

set_flags(flags): Устанавливает флаги, указанные в flags, и сбрасывает все остальные.

add_flag(flag): Устанавливает флаги, указанные в flag, без изменения других флагов. Для добавления нескольких флагов одновременно flag может быть строкой длиной более одного символа. Текущее значение «info» перезаписывается, независимо от того, содержит ли оно экспериментальную информацию или флаги.

remove_flag(flag): Сбрасывает флаги, указанные в flag, без изменения других флагов. Для удаления нескольких флагов одновременно flag может быть строкой длиной более одного символа. Если «info» содержит экспериментальную информацию вместо флагов, текущее значение «info» не изменяется.

get_date(): Возвращает дату доставки сообщения в виде числа с плавающей точкой, представляющего секунды с начала эпохи.

set_date(date): Устанавливает дату доставки сообщения на date, число с плавающей точкой, представляющее секунды с начала эпохи.

get_info(): Возвращает строку, содержащую «info» для сообщения. Это полезно для доступа к и изменения экспериментальной «info» (т.е., не являющейся списком флагов).

set_info(info): Устанавливает «info» на info, которое должно быть строкой.

При создании экземпляра MaildirMessage на основе экземпляра mboxMessage или MMDFMessage заголовки Status и X-Status опускаются, и происходят следующие преобразования:

Результирующее состояние	Состояние `mboxMessage` или `MMDFMessage`
Подкаталог «cur»	Флаг O
Флаг F	Флаг F
Флаг R	Флаг A
Флаг S	Флаг R
Флаг T	Флаг D

При создании экземпляра MaildirMessage на основе экземпляра MHMessage происходят следующие преобразования:

Результирующее состояние	Состояние `MHMessage`
Подкаталог «cur»	Последовательность «unseen»
Подкаталог «cur» и флаг S	Нет последовательности «unseen»
Флаг F	Последовательность «flagged»
Флаг R	Последовательность «replied»

При создании экземпляра MaildirMessage на основе экземпляра BabylMessage происходят следующие преобразования:

Результирующее состояние	Состояние `BabylMessage`
Подкаталог «cur»	Метка «unseen»
Подкаталог «cur» и флаг S	Нет метки «unseen»
Флаг P	Метка «forwarded» или «resent»
Флаг R	Метка «answered»
Флаг T	Метка «deleted»

END_OF_DOCUMENT_MARKER

`mboxMessage`

class mailbox.mboxMessage(message=None)

Сообщение со специфичным поведением для mbox. Параметр message имеет то же значение, что и в конструкторе Message.

Сообщения в почтовом ящике mbox хранятся вместе в одном файле. Адрес отправителя и время доставки обычно хранятся в строке, начинающейся с «From », которая используется для указания начала сообщения, хотя точный формат этих данных сильно варьируется в разных реализациях mbox. Флаги, указывающие состояние сообщения, такие как прочитан ли оно или помечено как важное, обычно хранятся в заголовках Status и X-Status.

Стандартные флаги для сообщений mbox:

Флаг	Значение	Описание
R	Прочитан	Прочитан
O	Старый	Ранее обнаружено почтовым клиентом
D	Удалено	Помечено для последующего удаления
F	Помечен	Помечено как важное
A	Ответ	На него был ответ

Флаги «R» и «O» хранятся в заголовке Status, а флаги «D», «F» и «A» — в заголовке X-Status. Флаги и заголовки, как правило, появляются в упомянутом порядке.

mboxMessage экземпляры предлагают следующие методы:

get_from(): Возвращает строку, представляющую строку «From », которая отмечает начало сообщения в почтовом ящике mbox. Ведущий «From » и завершающая новая строка исключаются.

set_from(from_, time_=None): Устанавливает строку «From » в from_, которая должна быть указана без ведущего «From » или завершающей новой строки. Для удобства можно указать time_, который будет отформатирован соответствующим образом и добавлен к from_. Если time_ указан, он должен быть экземпляром time.struct_time, кортежем, подходящим для передачи в time.strftime(), или True, (чтобы использовать time.gmtime()).

get_flags(): Возвращает строку, определяющую установленные флаги. Если сообщение соответствует стандартному формату, результат представляет собой конкатенацию в указанном ниже порядке нулевого или одного вхождения каждого из 'R', 'O', 'D', 'F', и 'A'.

set_flags(flags): Устанавливает флаги, указанные в flags, и сбрасывает все остальные. Параметр flags должен представлять собой конкатенацию в любом порядке нуля или более вхождений каждого из 'R', 'O', 'D', 'F', и 'A'.

add_flag(flag): Устанавливает флаги, указанные в flag, без изменения других флагов. Для добавления более одного флага одновременно, flag может быть строкой более чем из одного символа.

remove_flag(flag): Сбрасывает флаги, указанные в flag, без изменения других флагов. Для удаления более одного флага одновременно, flag может быть строкой более чем из одного символа.

При создании экземпляра mboxMessage на основе экземпляра MaildirMessage строка «From » генерируется на основе даты доставки экземпляра MaildirMessage, и выполняются следующие преобразования:

Результат	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог «cur»
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

При создании экземпляра mboxMessage на основе экземпляра MHMessage выполняются следующие преобразования:

Результат	Состояние `MHMessage`
Флаги R и O	Нет последовательности «unseen»
Флаг O	Последовательность «unseen»
Флаг F	Последовательность «flagged»
Флаг A	Последовательность «replied»

При создании экземпляра mboxMessage на основе экземпляра BabylMessage выполняются следующие преобразования:

Результат	Состояние `BabylMessage`
Флаги R и O	Нет метки «unseen»
Флаг O	Метка «unseen»
Флаг D	Метка «deleted»
Флаг A	Метка «answered»

При создании экземпляра Message на основе экземпляра MMDFMessage строка «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 из списка последовательностей, которые включают это сообщение.

При создании экземпляра MHMessage на основе экземпляра MaildirMessage, происходят следующие преобразования:

Результат	Состояние `MaildirMessage`
Последовательность “unseen”	отсутствует флаг S
Последовательность “replied”	флаг R
Последовательность “flagged”	флаг F

При создании экземпляра MHMessage на основе экземпляра mboxMessage или MMDFMessage, заголовки Status и X-Status пропускаются, а происходят следующие преобразования:

Результат	Состояние `mboxMessage` или `MMDFMessage`
Последовательность “unseen”	отсутствует флаг R
Последовательность “replied”	флаг A
Последовательность “flagged”	флаг F

При создании экземпляра MHMessage на основе экземпляра BabylMessage, происходят следующие преобразования:

Результат	Состояние `BabylMessage`
Последовательность “unseen”	метка “unseen”
Последовательность “replied”	метка “answered”

`BabylMessage`

class mailbox.BabylMessage(message=None)

Сообщение с поведением, специфичным для Babyl. Параметр message имеет то же значение, что и в конструкторе Message.

Некоторые метки сообщений, называемые атрибутами, определены по умолчанию и имеют специальное значение. Эти атрибуты следующие:

Метка	Описание
непрочитанное	Не прочитанное, но ранее обнаруженное MUA
удаленное	Отмеченное для последующего удаления
архивированное	Скопированное в другой файл или почтовый ящик
ответ отправлен	На него был отправлен ответ
переслано	Переслано
отредактированное	Изменено пользователем
повторно отправленное	Повторно отправлено

По умолчанию 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, которые присутствуют в исходных заголовках, но отсутствуют в видимых заголовках, добавляются к видимым заголовкам.

При создании экземпляра BabylMessage на основе экземпляра MaildirMessage происходят следующие преобразования:

Результат	Состояние `MaildirMessage`
Метка “непрочитанное”	нет флага S
Метка “удаленное”	флаг T
Метка “ответ отправлен”	флаг R
Метка “переслано”	флаг P

При создании экземпляра BabylMessage на основе экземпляра mboxMessage или MMDFMessage заголовки Status и X-Status пропускаются, и происходят следующие преобразования:

Результат	Состояние `mboxMessage` или `MMDFMessage`
Метка “непрочитанное”	нет флага R
Метка “удаленное”	флаг D
Метка “ответ отправлен”	флаг A

При создании экземпляра BabylMessage на основе экземпляра MHMessage происходят следующие преобразования:

Результат	Состояние `MHMessage`
Метка “непрочитанное”	последовательность “непрочитанное”
Метка “ответ отправлен”	последовательность “ответ отправлен”

`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(): Возвращает строку, представляющую строку «From », которая отмечает начало сообщения в почтовом ящике mbox. Ведущие «From » и хвостовая новая строка исключаются.

set_from(from_, time_=None): Устанавливает строку «From » в from_, которая должна быть указана без ведущих «From » или хвостовой новой строки. Для удобства можно указать time_, который будет отформатирован соответствующим образом и добавлен к from_. Если time_ указан, он должен быть экземпляром time.struct_time, кортежем, подходящим для передачи в time.strftime(), или True, (чтобы использовать time.gmtime()).

get_flags(): Возвращает строку, определяющую установленные в настоящее время флаги. Если сообщение соответствует стандартному формату, результат представляет собой конкатенацию в следующем порядке нуля или одного вхождения каждого из 'R', 'O', 'D', 'F', и 'A'.

set_flags(flags): Устанавливает флаги, указанные в flags, и сбрасывает все остальные. Параметр flags должен представлять собой конкатенацию в любом порядке нуля или более вхождений каждого из 'R', 'O', 'D', 'F', и 'A'.

add_flag(flag): Устанавливает флаг(и), указанный(е) в flag, без изменения других флагов. Чтобы добавить несколько флагов одновременно, flag может быть строкой, содержащей более одного символа.

remove_flag(flag): Сбрасывает флаг(и), указанный(е) в flag, без изменения других флагов. Чтобы удалить несколько флагов одновременно, flag может быть строкой, содержащей более одного символа.

При создании экземпляра MMDFMessage на основе экземпляра MaildirMessage, строка «From » генерируется на основе даты доставки экземпляра MaildirMessage, и происходят следующие преобразования:

Результат	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог “cur”
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

При создании экземпляра MMDFMessage на основе экземпляра MHMessage, происходят следующие преобразования:

Результат	Состояние `MHMessage`
Флаги R и O	Нет последовательности «unseen»
Флаг O	Последовательность «unseen»
Флаг F	Последовательность «flagged»
Флаг A	Последовательность «replied»

При создании экземпляра MMDFMessage на основе экземпляра BabylMessage, происходят следующие преобразования:

Результат	Состояние `BabylMessage`
Флаги R и O	Нет метки «unseen»
Флаг O	Метка «unseen»
Флаг D	Метка «deleted»
Флаг A	Метка «answered»

При создании экземпляра MMDFMessage на основе экземпляра mboxMessage, строка «From » копируется, а все флаги соответствуют напрямую:

Результат	Состояние `mboxMessage`
Флаг R	Флаг R
Флаг O	Флаг O
Флаг D	Флаг D
Флаг F	Флаг F
Флаг A	Флаг A

Исключения

В модуле mailbox определены следующие классы исключений:

exception mailbox.Error: Базовый класс для всех других модульных исключений.

exception mailbox.NoSuchMailboxError: Выбрасывается, когда ожидается почтовый ящик, но он не найден, например, при создании экземпляра Mailbox подкласса с путем, который не существует (и с параметром create установленным в False), или при открытии папки, которая не существует.

exception mailbox.NotEmptyError: Выбрасывается, когда почтовый ящик не пуст, но ожидается, что он будет пустым, например, при удалении папки, содержащей сообщения.

exception mailbox.ExternalClashError: Выбрасывается, когда какое-либо условие, связанное с почтовым ящиком и выходящее за рамки контроля программы, приводит к невозможности её продолжения, например, при неудачной попытке получить блокировку, которую уже держит другая программа, или когда уникальное имя файла, сгенерированное ранее, уже существует.

exception mailbox.FormatError: Выбрасывается, когда данные в файле не могут быть обработаны, например, когда экземпляр MH пытается прочитать поврежденный .mh_sequences файл.

Примеры

Простой пример вывода тем всех сообщений в почтовом ящике, которые кажутся интересными:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be 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                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

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