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(): Возвращает итератор по парам (ключ, сообщение), где ключ — ключ, а сообщение — представление сообщения, если вызвано как 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 должен быть сопоставлением «ключ-значение» или итерируемым набором пар «ключ-значение». Обновляет почтовый ящик так, что для каждого заданного ключа и значения сообщение, соответствующее ключу, устанавливается в значение, как если бы использовалось __setitem__(). Как и с __setitem__(), каждый ключ должен уже соответствовать сообщению в почтовом ящике, иначе будет генерироваться исключение 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.

`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 от 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	Старое	Ранее обнаружено MUA
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) используют последовательности аналогично тому, как флаги используются в других форматах, как показано ниже:

Последовательность	Описание
непрочитанное	Не прочитано, но ранее обнаружено MUA
отвечено	На него ответили
отмечено	Отмечено как важное

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

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

set_sequences(sequences): Устанавливает список последовательностей, включающих это сообщение.

add_sequence(sequence): Добавляет sequence в список последовательностей, включающих это сообщение.

remove_sequence(sequence): Удаляет sequence из списка последовательностей, включающих это сообщение.

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

Результирующее состояние	состояние `MaildirMessage`
Последовательность “непрочитанное”	нет флага S
Последовательность “отвечено”	флаг R
Последовательность “отмечено”	флаг F

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

Результирующее состояние	состояние `mboxMessage` или `MMDFMessage`
Последовательность “непрочитанное”	нет флага R
Последовательность “отвечено”	флаг A
Последовательность “отмечено”	флаг F

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

Результирующее состояние	состояние `BabylMessage`
Последовательность “непрочитанное”	метка “непрочитанное”
Последовательность “отвечено”	метка “ответ”

`BabylMessage`

class mailbox.BabylMessage(message=None)

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

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

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

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

Результат	Состояние `MaildirMessage`
Метка “unseen”	Флаг S отсутствует
Метка “deleted”	Флаг T присутствует
Метка “answered”	Флаг R присутствует
Метка “forwarded”	Флаг P присутствует

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

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

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

Результат	Состояние `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	Ответ	На него ответили

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()