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

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

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

См.также

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

`Mailbox` объекты¶

class mailbox.Mailbox¶

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

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

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

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

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

По умолчанию Mailbox iterator выполняется итерация по представлениям сообщений, а не по ключам, как это делает итератор по умолчанию dictionary. Кроме того, модификация почтового ящика во время итерации безопасна и четко определена. Сообщения, добавленные в почтовый ящик после создания итератора, не будут отображаться итератором. Сообщения, удаленные из почтового ящика до того, как их выдаст итератор, будут автоматически пропущены, хотя использование ключа из итератора может привести к исключению 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)¶

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

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

__setitem__(key, message)¶

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

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

iterkeys()¶: Возвращает iterator по всем клавишам

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.2: Файловым объектом действительно является binary file; ранее он был неправильно возвращен в текстовом режиме. Кроме того, file-like object теперь поддерживает протокол context manager: вы можете использовать инструкцию with, чтобы автоматически закрыть его.

Примечание

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

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

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

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

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

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

update(arg)¶: Параметр arg должен быть сопоставлением ключа с сообщением или итерацией пар (ключ, сообщение). Обновляет почтовый ящик таким образом, чтобы для каждого заданного ключа и сообщения сообщение, соответствующее ключу, было установлено в сообщение, как если бы использовалось __setitem__(). Как и в случае с __setitem__(), каждый ключ должен уже соответствовать сообщению в почтовом ящике, иначе будет вызвано исключение 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 существует, он будет рассматриваться как существующий почтовый каталог без попытки проверки его расположения в каталоге.

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

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

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

Также поддерживаются папки в стиле, представленном курьерским агентом по передаче почты. Любой подкаталог основного почтового ящика считается папкой, если в его названии первым символом является '.'. Имена папок обозначаются символом 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 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 хранятся в одном файле, начало каждого сообщения обозначается строкой, первые пять символов которой - «От «.

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

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

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

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

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

Примечание

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

Некоторые 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, почтовый ящик создается, даже если он не существует.

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

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

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

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

См.также

mmdf man page from tin: Спецификация формата MDF из документации 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.

Как правило, приложение mail user agent перемещает все сообщения из подкаталога new в подкаталог cur после того, как пользователь впервые открывает и закрывает почтовый ящик, записывая, что сообщения устарели, независимо от того, были ли они прочитаны на самом деле. К каждому сообщению в cur к имени файла добавлен раздел «информация» для хранения информации о его состоянии. (Некоторые читатели почты могут также добавлять раздел «информация» к сообщениям в new.) Раздел «информация» может иметь одну из двух форм: он может содержать «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 должен быть либо «новый», либо «текущий».

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

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

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

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»	O флаг
Флаг F	Флаг F
Флаг R	Флаг
Флаг S	Флаг R
Т-образный флаг	Флаг D

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

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

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

Результирующее состояние	`BabylMessage` состояние
подкаталог «cur»	«невидимый» ярлык
подкаталог «cur» и флаг S	нет «невидимого» ярлыка
Флаг P	надпись «переслано» или «повторно отправлено»
Флаг R	надпись «ответил»
Т-образный флаг	метка «удалено»

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

Результирующее состояние	`MaildirMessage` состояние
Флаг R	Флаг S
O флаг	подкаталог «cur»
Флаг D	Т-образный флаг
Флаг F	Флаг F
Флаг	Флаг R

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

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

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

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

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

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

`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
«помеченная» последовательность	Флаг F

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

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

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

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

`BabylMessage` объекты¶

class mailbox.BabylMessage(message=None)¶

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

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

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

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

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

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

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

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

remove_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
метка «удалено»	Т-образный флаг
надпись «ответил»	Флаг R
надпись «переслано»	Флаг P

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

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

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

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

`MMDFMessage` объекты¶

class mailbox.MMDFMessage(message=None)¶

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

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

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

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

MMDFMessage`Обычные :class:`mboxMessage флаги для сообщений MMDF идентичны флагам для сообщений mbox и являются следующими:

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, строка «От» создается на основе даты поставки экземпляров MaildirMessage и выполняются следующие преобразования:

Результирующее состояние	`MaildirMessage` состояние
Флаг R	Флаг S
O флаг	подкаталог «cur»
Флаг D	Т-образный флаг
Флаг F	Флаг F
Флаг	Флаг R

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

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

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

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

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

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

Исключения¶

В модуле 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.11

Содержание

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

Вы здесь:

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

Mailbox объекты¶

Maildir объекты¶

mbox объекты¶

MH объекты¶

Babyl объекты¶

MMDF объекты¶

Message объекты¶

MaildirMessage объекты¶

mboxMessage объекты¶

MHMessage объекты¶

BabylMessage объекты¶

MMDFMessage объекты¶

Исключения¶

Примеры¶

Python 3.11

Содержание

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

Вы здесь:

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

`Mailbox` объекты¶

`Maildir` объекты¶

`mbox` объекты¶

`MH` объекты¶

`Babyl` объекты¶

`MMDF` объекты¶

`Message` объекты¶

`MaildirMessage` объекты¶

`mboxMessage` объекты¶

`MHMessage` объекты¶

`BabylMessage` объекты¶

`MMDFMessage` объекты¶