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

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

1. Объекты почтовых ящиков

class mailbox.Mailbox

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

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

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

Сообщения могут быть добавлены в экземпляр Mailbox с помощью метода set-like add() и удалены с помощью оператора del или методов set-like 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), используется его информация, специфичная для формата. В противном случае используются разумные значения по умолчанию для информации, специфичной для формата.

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)

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

get_message(key)

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

get_string(key)

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

get_file(key)

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

Примечание

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

has_key(key)

__contains__(key)

Возвращает True , если ключ соответствует сообщению, False в противном случае.

__len__()

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

clear()

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

pop(key[, default])

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

popitem()

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

update(arg)

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

Примечание

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

flush()

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

lock()

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

unlock()

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

close()

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

1.1. Maildir

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

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

По историческим причинам factory по умолчанию равен rfc822.Message, а dirname называется так, а не path. Для экземпляра Maildir, который ведёт себя как экземпляры других подклассов Mailbox, установите factory в None.

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

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

Также поддерживаются папки, введенные агентом передачи почты Courier. Любой подкаталог основного почтового ящика считается папкой, если первый символ его имени — '.'. Имена папок представлены как 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)

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

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

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

1.4. 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 заголовки сообщения не хранятся непрерывно с телом сообщения. Для создания представления в виде файла заголовки и тело копируются вместе в экземпляр StringIO (из модуля StringIO), который имеет идентичный API файлу. В результате, объекту в виде файла действительно не зависит от базового почтового ящика, но не экономит память по сравнению с строковым представлением.

lock()

unlock()

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

1.5. MMDF

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

Подкласс Mailbox для почтовых ящиков в формате MMDF. Параметр factory — вызываемый объект, который принимает представление сообщения в виде объекта file-like (как если бы он был открыт в двоичном режиме) и возвращает пользовательское представление. Если 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().

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

class mailbox.Message([message])

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

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

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

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

2.1. MaildirMessage

class mailbox.MaildirMessage([message])

Сообщение со специфичным для 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 опушены, и происходят следующие преобразования:

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

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

2.2. mboxMessage

class mailbox.mboxMessage([message])

Сообщение с поведением, специфичным для 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, и происходят следующие преобразования:

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

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

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

2.3. MHMessage

class mailbox.MHMessage([message])

Сообщение с поведением, специфичным для 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, происходят следующие преобразования:

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

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

2.4. BabylMessage

class mailbox.BabylMessage([message])

Сообщение со специфичным для 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, происходят следующие преобразования:

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

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

2.5. MMDFMessage

class mailbox.MMDFMessage([message])

Сообщение со специфичным для 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, и происходят следующие преобразования:

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

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

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

3. Исключения

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

exception mailbox.Error

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

exception mailbox.NoSuchMailboxError

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

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

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

exception mailbox.FormatError

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

4. Устаревшие классы и методы

Более ранние версии модуля mailbox не поддерживают модификацию почтовых ящиков, например, добавление или удаление сообщений, и не предоставляют классы для представления свойств сообщений, специфичных для формата. Для обеспечения обратной совместимости устаревшие классы почтовых ящиков по-прежнему доступны, но следует использовать новые классы вместо них. Старые классы были удалены в Python 3.

Более старые объекты почтового ящика поддерживают только итерацию и предоставляют один общедоступный метод:

oldmailbox.next()

Возвращает следующее сообщение в почтовом ящике, созданное с необязательным аргументом factory, переданным в конструктор объекта почтового ящика. По умолчанию это объект rfc822.Message (см. модуль rfc822). В зависимости от реализации почтового ящика атрибут fp этого объекта может быть истинным объектом файла или экземпляром класса, имитирующим объект файла, заботясь о таких вещах, как границы сообщений, если несколько сообщений почты содержатся в одном файле и т. д. Если больше сообщений недоступно, этот метод возвращает None.

Большинство старых классов почтовых ящиков имеют имена, отличающиеся от текущих имён классов почтовых ящиков, за исключением Maildir. По этой причине новый класс Maildir определяет метод next(), а его конструктор немного отличается от конструкторов других новых классов почтовых ящиков.

Старые классы почтовых ящиков, имена которых не совпадают с именами их новых аналогов, перечислены ниже:

class mailbox.UnixMailbox(fp[, factory])

Доступ к почтовому ящику в стиле классической Unix-системы, где все сообщения содержатся в одном файле и разделены строками From (также известными как From_). Объект файла fp указывает на файл почтового ящика. Необязательный параметр factory — это вызываемый объект, который должен создавать новые объекты сообщений. Метод next() объекта почтового ящика вызывает factory с одним аргументом — fp. По умолчанию используется класс rfc822.Message (см. модуль rfc822 — и примечание ниже).

Примечание

По соображениям внутренней реализации этого модуля, вы, скорее всего, захотите открыть объект fp в двоичном режиме. Это особенно важно в Windows.

Для максимальной переносимости сообщения в почтовом ящике в стиле Unix разделяются любой строкой, которая начинается ровно со строки 'From ' (обратите внимание на trailing-пробел), если ей предшествуют ровно две строки перевода. Из-за большого разнообразия практических вариантов, ничего другого в строке From_ рассматриваться не должно. Однако текущая реализация не проверяет наличия двух лидирующих строк перевода. Это обычно хорошо подходит для большинства приложений.

Класс UnixMailbox реализует более строгую версию проверки строки From_, используя регулярное выражение, которое обычно правильно соответствует разделителям From_. Оно рассматривает разделительную строку как разделенную строками From name time. Для максимальной переносимости используйте класс PortableUnixMailbox вместо этого. Этот класс идентичен UnixMailbox, за исключением того, что отдельные сообщения разделяются только строками From.

class mailbox.PortableUnixMailbox(fp[, factory])

Менее строгая версия UnixMailbox, которая учитывает только From в начале строки для разделения сообщений. Часть строки "имя время" в строке From игнорируется, чтобы защититься от некоторых вариаций, наблюдаемых на практике. Это работает, так как строки в сообщении, которые начинаются со 'From ', цитируются программным обеспечением для обработки почты во время доставки.

class mailbox.MmdfMailbox(fp[, factory])

Доступ к почтовому ящику в формате MMDF, где все сообщения содержатся в одном файле и разделяются строками, состоящими из 4 символов control-A. Объект файла fp указывает на файл почтового ящика. Необязательный параметр factory — такой же, как у класса UnixMailbox.

class mailbox.MHMailbox(dirname[, factory])

Доступ к почтовому ящику MH, представляющему собой директорию, где каждое сообщение находится в отдельном файле с числовым именем. Имя каталога почтового ящика передаётся в dirname. Параметр factory такой же, как у класса UnixMailbox.

class mailbox.BabylMailbox(fp[, factory])

Доступ к почтовому ящику Babyl, который похож на почтовый ящик MMDF. В формате Babyl каждое сообщение имеет два набора заголовков: исходные заголовки и видимые заголовки. Исходные заголовки появляются перед строкой, содержащей только '*** EOOH ***' (конец исходных заголовков), а видимые заголовки появляются после строки EOOH. Читатели почты, совместимые с Babyl, будут отображать только видимые заголовки, и объекты BabylMailbox будут возвращать сообщения, содержащие только видимые заголовки. Вам придётся самостоятельно анализировать файл почтового ящика, чтобы получить исходные заголовки. Сообщения электронной почты начинаются со строки EOOH и заканчиваются строкой, содержащей только '\037\014'. Параметр factory такой же, как у класса UnixMailbox.

Если вы хотите использовать старые классы почтовых ящиков с модулем email вместо устаревшего модуля rfc822, вы можете сделать это следующим образом:

import email
import email.Errors
import mailbox

def msgfactory(fp):
    try:
        return email.message_from_file(fp)
    except email.Errors.MessageParseError:
        # Don't return None since that will
        # stop the mailbox iterator
        return ''

mbox = mailbox.UnixMailbox(fp, msgfactory)

В качестве альтернативы, если вы знаете, что ваш почтовый ящик содержит только правильно сформированные сообщения MIME, вы можете упростить это до:

import email
import mailbox

mbox = mailbox.UnixMailbox(fp, email.message_from_file)

5. Примеры

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

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