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 в почтовый ящик и вернуть присвоенный ему ключ.

Параметр 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(), за исключением того, что возвращается list, а не итератор

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

Примечание

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

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

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

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

END_OF_DOCUMENT_MARKER

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

`mbox` объекты

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

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

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

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

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

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

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

См. также

mbox man page из 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 - Message Handling System: Главная страница nmh, обновленной версии исходного mh.
MH & nmh: Email for Users & Programmers: Книгу с открытым исходным кодом (GPL) о mh и nmh с некоторыми сведениями о формате почтового ящика.

`Babyl` объекты

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

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

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

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

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

get_labels()

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

Примечание

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

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

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

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

См. также

Format of Version 5 Babyl Files: Спецификация формата Babyl.
Reading Mail with Rmail: Справочная информация по Rmail, с некоторыми сведениями о семантике Babyl.

`MMDF` объекты

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

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

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

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

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

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

См. также

страница справки mmdf из tin: Спецификация формата MMDF из документации tin, программы-чтения новостей.
MMDF: Статья Википедии, описывающая Multichannel Memorandum Distribution Facility.

`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»	Последовательность «непрочитанных»
Подкаталог «cur» и флаг S	Нет последовательности «непрочитанных»
Флаг F	Последовательность «помеченных»
Флаг R	Последовательность «отвеченных»

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

Результат	Состояние `BabylMessage`
Подкаталог «cur»	Метка «непрочитанных»
Подкаталог «cur» и флаг S	Нет метки «непрочитанных»
Флаг P	Метка «перенаправленного» или «переотправленного»
Флаг R	Метка «отвеченного»
Флаг T	Метка «удаленного»

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

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

END_OF_DOCUMENT_MARKER

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

Результат	Состояние `MaildirMessage`
Последовательность “unseen”	Флаг S отсутствует
Последовательность “replied”	Флаг R присутствует
Последовательность “flagged”	Флаг F присутствует

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

Результат	Состояние `mboxMessage` или `MMDFMessage`
Последовательность “unseen”	Флаг R отсутствует
Последовательность “replied”	Флаг A присутствует
Последовательность “flagged”	Флаг F присутствует

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

Результат	Состояние `BabylMessage`
Последовательность “unseen”	Метка “unseen”
Последовательность “replied”	Метка “answered”

`BabylMessage` объекты

class mailbox.BabylMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Результат	Состояние `MHMessage`
Метка “unseen”	Последовательность “unseen”
Метка “answered”	Последовательность “replied”

`MMDFMessage` объекты

class mailbox.MMDFMessage(message=None)

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

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

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

Флаг	Значение	Описание
R	Прочитан	Прочитан
O	Старый	Ранее обнаружено почтовым клиентом
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	Отсутствует последовательность «непрочитанное»
Флаг O	Последовательность «непрочитанное»
Флаг F	Последовательность «отмеченный»
Флаг A	Последовательность «ответ»

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

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

При создании экземпляра 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` объекты