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

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

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

См. также

Module email: Представление и управление сообщениями.

`Mailbox` объекты

class mailbox.Mailbox

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

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

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

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

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

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

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

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

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

add(message)

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

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

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

remove(key)

__delitem__(key)

discard(key)

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

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

__setitem__(key, message)

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

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

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

keys(): То же, что и iterkeys(), за исключением того, что возвращается list, а не итератор.

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

Примечание

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

values(): То же, что и itervalues(), за исключением того, что возвращается list, а не итератор.

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

items(): То же, что и iteritems(), за исключением того, что возвращается list пар, а не итератор пар.

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, но не должна содержать другие папки. Вместо этого логическое вложение обозначается с помощью '.' для разграничения уровней, например, «Архив.2005.07».

colon

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

import mailbox
mailbox.Maildir.colon = '!'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также

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

`mbox` объекты

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

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

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

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

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

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

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

См. также

Страница справки mbox из tin: Спецификация формата с деталями блокировки.
Настройка Netscape Mail на Unix: Почему формат Content-Length плох: Аргумент в пользу использования оригинального формата mbox, а не вариаций.
Формат «mbox» — это семейство нескольких несовместимых форматов почтового ящика: История вариаций формата mbox.

`MH` объекты

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

См. также

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

`Babyl` объекты

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

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

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

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

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

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

Примечание

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

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

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

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

См. также

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

`MMDF` объекты

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

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

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

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

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

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

См. также

mmdf man page from tin: Спецификация формата MMDF из документации tin, программы-читателя новостей.
MMDF: Статья Википедии, описывающая Многоканальное средство распространения записок.

объекты `Message`

class mailbox.Message(message=None)

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

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

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

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

объекты `MaildirMessage`

class mailbox.MaildirMessage(message=None)

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`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 может быть строкой более чем из одного символа.

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

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

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

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

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

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

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

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

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

`MHMessage` объекты

class mailbox.MHMessage(message=None)

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

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

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

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

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

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

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

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

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

Результат	Состояние `MaildirMessage`
последовательность «непрочитанное»	флаг S отсутствует
последовательность «ответ отправлен»	флаг R
последовательность «помечено»	флаг F

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

Результат	Состояние `mboxMessage` или `MMDFMessage`
последовательность «непрочитанное»	флаг R отсутствует
последовательность «ответ отправлен»	флаг A
последовательность «помечено»	флаг F

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

Результат	Состояние `BabylMessage`
последовательность «непрочитанное»	метка «непрочитанное»
последовательность «ответ отправлен»	метка «ответ отправлен»

`BabylMessage` объекты

class mailbox.BabylMessage(message=None)

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

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

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

По умолчанию Rmail отображает только видимые заголовки. Однако класс BabylMessage использует исходные заголовки, поскольку они более полные. Видимые заголовки можно получить явно, если необходимо.

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

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

set_labels(labels): Устанавливает список меток сообщения на labels.

add_label(label): Добавляет label в список меток сообщения.

remove_label(label): Удаляет label из списка меток сообщения.

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

set_visible(visible): Устанавливает видимые заголовки сообщения такими же, как заголовки в message. Параметр visible должен быть экземпляром Message, экземпляром email.message.Message, строкой или объектом типа «подобный файлу» (который должен быть открыт в текстовом режиме).

update_visible(): Когда исходные заголовки экземпляра BabylMessage изменяются, видимые заголовки не автоматически изменяются соответственно. Этот метод обновляет видимые заголовки следующим образом: каждый видимый заголовок с соответствующим исходным заголовком устанавливается на значение исходного заголовка, каждый видимый заголовок без соответствующего исходного заголовка удаляется, и любые из Date, From, Reply-To, To, CC и Subject, присутствующие в исходных заголовках, но отсутствующие в видимых заголовках, добавляются в видимые заголовки.

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

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

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

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

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

Результат	Состояние `MHMessage`
метка «непрочитанное»	последовательность «непрочитанное»
метка «ответ отправлен»	последовательность «ответ отправлен»

`MMDFMessage` объекты

class mailbox.MMDFMessage(message=None)

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

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

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

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

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

Экземпляры MMDFMessage предлагают следующие методы, которые идентичны методам, предлагаемым mboxMessage:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Исключения

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

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

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

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

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

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

Примеры

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

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

Для копирования всей почты из папки Babyl в папку MH, преобразуя всю специфичную для формата информацию, которая может быть преобразована:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

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

import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

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

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

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

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

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

Mailbox объекты

Maildir объекты

mbox объекты

MH объекты

Babyl объекты

MMDF объекты

объекты Message

объекты MaildirMessage

mboxMessage объекты

MHMessage объекты

BabylMessage объекты

MMDFMessage объекты

Исключения

Примеры

`Mailbox` объекты

`Maildir` объекты

`mbox` объекты

`MH` объекты

`Babyl` объекты

`MMDF` объекты

объекты `Message`

объекты `MaildirMessage`

`mboxMessage` объекты

`MHMessage` объекты

`BabylMessage` объекты

`MMDFMessage` объекты