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

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

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

См.также

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

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

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

remove(key)¶

__delitem__(key)¶

discard(key)¶

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

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

__setitem__(key, message)¶

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

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

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

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

Примечание

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

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

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

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

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

Добавлено в версии 3.2.

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

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

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

Примечание

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

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

__len__()¶: Возвращает подсчет количества сообщений в почтовом ящике.

clear()¶: Удаление всех сообщений из почтового ящика.

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

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

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

Примечание

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

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

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

unlock()¶: Освободите замок почтового ящика, если таковой имеется.

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

`Maildir`¶

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

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

Если create имеет значение True и путь dirname существует, он будет рассматриваться как существующий maildir без попытки проверить расположение каталогов.

По историческим причинам dirname называется именно так, а не path.

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

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

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

Примечание

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

import mailbox
mailbox.Maildir.colon = '!'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См.также

maildir man page from Courier: Спецификация формата. Описывает общее расширение для поддержки папок.
Using maildir format: Заметки о 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 from tin: Спецификация формата с подробным описанием блокировки.
Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad: Аргумент в пользу использования оригинального формата mbox, а не его разновидности.
«mbox» is a family of several mutually incompatible mailbox formats: История вариаций 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 (называемые folders) в дополнение к сообщениям. Папки могут быть вложены неограниченно. Почтовые ящики MH также поддерживают sequences, которые представляют собой именованные списки, используемые для логической группировки сообщений без перемещения их во вложенные папки. Последовательности определяются в файле под названием .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 также имеет сопровождающий список labels, или коротких строк, которые записывают дополнительную информацию о сообщении, а список всех определяемых пользователем меток, найденных в почтовом ящике, хранится в разделе опций 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 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. Если сообщение является строкой, байтовой строкой или файлом, оно должно содержать 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	Trashed	Помечены для последующего удаления

Экземпляры 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()¶: Возвращает строку, содержащую «информацию» для сообщения. Это полезно для доступа и изменения «информации», которая является экспериментальной (т.е. не является списком флагов).

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

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

Результирующее состояние	<<<Состояние `mboxMessage` или `MMDFMessage`
подкаталог «cur»	Флаг
флаг	флаг
R флаг	Флаг
флаг S	R флаг
флаг T	Флаг D

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

Результирующее состояние	`MHMessage` состояние
подкаталог «cur»	«невидимая» последовательность
подкаталог «cur» и флаг S	нет «невидимой» последовательности
флаг	последовательность «флагов»
R флаг	последовательность «ответил»

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

Результирующее состояние	`BabylMessage` состояние
подкаталог «cur»	«невидимая» метка
подкаталог «cur» и флаг S	нет «невидимой» этикетки
флаг	метка «переслано» или «повторно отправлено».
R флаг	метка «ответил»
флаг T	метка «удалено»

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

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

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

Результирующее состояние	`MHMessage` состояние
Флаг R и флаг O	нет «невидимой» последовательности
Флаг	«невидимая» последовательность
флаг	последовательность «флагов»
Флаг	последовательность «ответил»

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

Результирующее состояние	`BabylMessage` состояние
Флаг R и флаг O	нет «невидимой» этикетки
Флаг	«невидимая» метка
Флаг D	метка «удалено»
Флаг	метка «ответил»

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

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

`MHMessage`¶

class mailbox.MHMessage(message=None)¶

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

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

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

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

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

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

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

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

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

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

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

Результирующее состояние	<<<Состояние `mboxMessage` или `MMDFMessage`
«невидимая» последовательность	нет флага R
последовательность «ответил»	Флаг
последовательность «флагов»	флаг

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

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

`BabylMessage`¶

class mailbox.BabylMessage(message=None)¶

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

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

Этикетка	Пояснение
невидимый	Не прочитано, но ранее обнаружено MUA
удалено	Помечены для последующего удаления
подано	Копирование в другой файл или почтовый ящик
ответил	Ответил на
перенаправлено	Переадресованный
отредактировано	Изменено пользователем
отправить	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` состояние
«невидимая» метка	нет флага S
метка «удалено»	флаг T
метка «ответил»	R флаг
метка «перенаправлено»	флаг

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

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

Когда экземпляр 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	Ответил	Ответил на

Экземпляры 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
Флаг	подкаталог «cur»
Флаг D	флаг T
флаг	флаг
Флаг	R флаг

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

Результирующее состояние	`MHMessage` состояние
Флаг R и флаг O	нет «невидимой» последовательности
Флаг	«невидимая» последовательность
флаг	последовательность «флагов»
Флаг	последовательность «ответил»

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

Результирующее состояние	`BabylMessage` состояние
Флаг R и флаг O	нет «невидимой» этикетки
Флаг	«невидимая» метка
Флаг D	метка «удалено»
Флаг	метка «ответил»

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

Результирующее состояние	`mboxMessage` состояние
R флаг	R флаг
Флаг	Флаг
Флаг D	Флаг D
флаг	флаг
Флаг	Флаг

Исключения¶

Следующие классы исключений определены в модуле 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()

json — Кодировщик и декодировщик JSON

mimetypes — Сопоставление имен файлов с типами MIME

Вернуться на верх

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

`Mailbox` объекты¶

`Maildir`¶

`mbox`¶

`MH`¶

`Babyl`¶

`MMDF`¶

`Message` объекты¶

`MaildirMessage`¶

`mboxMessage`¶

`MHMessage`¶

`BabylMessage`¶

`MMDFMessage`¶

Исключения¶

Примеры¶

Python 3.10

Содержание

Дополнительно

Вы здесь:

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

Mailbox объекты¶

Message объекты¶

Исключения¶

Примеры¶

Содержание

Дополнительно

Вы здесь:

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

`Mailbox` объекты¶

`Message` объекты¶