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

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

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

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

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)

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

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

__setitem__(key, message)

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

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

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 должен быть отображением 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 и теперь широко поддерживается другими программами. Сообщения в почтовом ящике 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)

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

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

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

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

MMDF

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

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

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

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

get_file(key)

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

lock()

unlock()

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

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

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

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

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

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

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

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

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

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

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

При создании экземпляра MHMessage на основе экземпляра 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 происходят следующие преобразования:

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

При создании экземпляра BabylMessage на основе экземпляра 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, и происходят следующие преобразования:

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

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

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

Исключения

В модуле 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()