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

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

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

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

class mailbox.Mailbox

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

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

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

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

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

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

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

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

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

add(message)

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

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

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

remove(key)

__delitem__(key)

discard(key)

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

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

__setitem__(key, message)

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

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

iterkeys()

keys()

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

itervalues()

__iter__()

values()

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

Примечание

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

iteritems()

items()

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

get(key, default=None)

__getitem__(key)

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

get_message(key)

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

get_bytes(key)

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

Введено в версии 3.2.

get_string(key)

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

get_file(key)

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

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

Примечание

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

__contains__(key)

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

__len__()

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

clear()

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

pop(key, default=None)

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

popitem()

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

update(arg)

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

Примечание

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

flush()

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

lock()

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

unlock()

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

close()

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

1.1. Maildir

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

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

Наименование dirname вместо path сохранено по историческим причинам.

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

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

Также поддерживаются папки в стиле, введённом агентом пересылки почты Courier. Любой подкаталог основного почтового ящика считается папкой, если первый символ его имени — '.'. Имена папок представлены объектом Maildir без ведущего символа '.'. Каждая папка сама по себе является почтовым ящиком Maildir, но не должна содержать другие папки. Вместо этого логическое вложение обозначается с помощью '.', разделяя уровни, например, «Архив.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 заголовки сообщения не хранятся непрерывно с телом сообщения. Для создания представления в виде файла заголовки и тело копируются вместе в экземпляр io.BytesIO, который имеет API, идентичный API файла. В результате, объекту в виде файла не требуется дополнительная память по сравнению со строковым представлением.

lock()

unlock()

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

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

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

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.

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

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

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

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

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

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

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

2.5. 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 » копируется, и все флаги соответствуют напрямую:

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

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

exception mailbox.Error

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

exception mailbox.NoSuchMailboxError

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

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

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

exception mailbox.FormatError

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

4. Примеры

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

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