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

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

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

19.4.1. Объекты Mailbox

class mailbox.Mailbox

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

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

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

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

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

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

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

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

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

add(message)

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

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

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

remove(key)

__delitem__(key)

discard(key)

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

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

__setitem__(key, message)

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

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

iterkeys()

keys()

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

itervalues()

__iter__()

values()

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

Примечание

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

iteritems()

items()

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

get(key, default=None)

__getitem__(key)

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

get_message(key)

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

get_bytes(key)

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

Новое в версии 3.2.

get_string(key)

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

get_file(key)

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

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

Примечание

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

__contains__(key)

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

__len__()

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

clear()

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

pop(key, default=None)

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

popitem()

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

update(arg)

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

Примечание

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

flush()

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

lock()

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

unlock()

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

close()

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

19.4.1.1. Maildir

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

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

Имя dirname используется по историческим причинам, а не path.

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

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

Также поддерживаются папки в стиле, введённом агентом пересылки почты Courier. Любой подкаталог основного почтового ящика считается папкой, если первый символ его имени — '.'. Имена папок представлены как Maildir без ведущего '.'. Каждая папка сама является почтовым ящиком Maildir, но не должна содержать другие папки. Вместо этого логическое вложение указывается с помощью '.', разделяя уровни, например, «Archived.2005.07».

Примечание

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

import mailbox
mailbox.Maildir.colon = '!'

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

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

list_folders()

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

get_folder(folder)

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

add_folder(folder)

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

remove_folder(folder)

Удаляет папку с именем folder. Если папка содержит сообщения, будет выброшено исключение NotEmptyError, и папка не будет удалена.

clean()

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

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

add(message)

__setitem__(key, message)

update(arg)

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

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

flush()

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

lock()

unlock()

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

close()

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

get_file(key)

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

19.4.1.2. mbox

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

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

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

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

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

get_file(key)

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

lock()

unlock()

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

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

19.4.1.4. Babyl

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

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

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

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

Объекты Babyl имеют все методы Mailbox, а также следующие:

get_labels()

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

Примечание

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

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

get_file(key)

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

lock()

unlock()

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

19.4.1.5. MMDF

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

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

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

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

get_file(key)

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

lock()

unlock()

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

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

class mailbox.Message(message=None)

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

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

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

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

19.4.2.1. MaildirMessage

class mailbox.MaildirMessage(message=None)

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

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

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

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

get_subdir()

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

Примечание

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

set_subdir(subdir)

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

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

get_date()

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

set_date(date)

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

get_info()

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

set_info(info)

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

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

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

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

19.4.2.2. mboxMessage

class mailbox.mboxMessage(message=None)

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

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

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

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

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

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

get_from()

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

set_from(from_, time_=None)

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

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

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

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

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

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

19.4.2.3. MHMessage

class mailbox.MHMessage(message=None)

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

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

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

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

get_sequences()

Возвращает список имён последовательностей, которые включают это сообщение.

set_sequences(sequences)

Устанавливает список последовательностей, которые включают это сообщение.

add_sequence(sequence)

Добавляет sequence в список последовательностей, которые включают это сообщение.

remove_sequence(sequence)

Удаляет sequence из списка последовательностей, которые включают это сообщение.

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

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

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

19.4.2.4. BabylMessage

class mailbox.BabylMessage(message=None)

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

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

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

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

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

get_labels()

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

set_labels(labels)

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

add_label(label)

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

remove_label(label)

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

get_visible()

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

set_visible(visible)

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

update_visible()

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

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

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

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

19.4.2.5. MMDFMessage

class mailbox.MMDFMessage(message=None)

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

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

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

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

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

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

get_from()

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

set_from(from_, time_=None)

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

get_flags()

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

set_flags(flags)

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

add_flag(flag)

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

remove_flag(flag)

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

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

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

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

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

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

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

exception mailbox.Error

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

exception mailbox.NoSuchMailboxError

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

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

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

exception mailbox.FormatError

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

19.4.4. Примеры

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

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

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

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

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

import mailbox
import email.errors

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

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

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

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

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

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

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