Содержание страницы

`mailbox` – Управление почтовыми ящиками в различных форматах¶mailbox – Manipulate mailboxes in various formats

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

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

См. также

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

`Mailbox` объекты¶Mailbox objects

class mailbox.Mailbox¶

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

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

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

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

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

По умолчанию Mailbox итератор выполняет итерацию по представлениям сообщений, а не по ключам, как это делает итератор 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)¶

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

`Maildir` объекты¶Maildir objects

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».

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

См. также

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

`mbox` объекты¶mbox objects

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 » обратно не преобразуются.

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

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

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

См. также

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

`MH` объекты¶MH objects

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

См. также

nmh – система обработки сообщений: Домашняя страница nmh, обновлённой версии исходного mh.
MH и nmh: электронная почта для пользователей и программистов: Книга, лицензированная под GPL, о mh и nmh, с некоторой информацией о формате почтового ящика.

`Babyl` объекты¶Babyl objects

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

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

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

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

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

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

Примечание

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

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

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

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

См. также

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

`MMDF` объекты¶MMDF objects

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()¶: Используются три механизма блокировки: точечная блокировка (dot locking) и, если доступны, системные вызовы flock() и lockf().

См. также

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

`Message` объекты¶Message objects

class mailbox.Message(message=None)¶

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

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

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

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

`MaildirMessage` объекты¶MaildirMessage objects

class mailbox.MaildirMessage(message=None)¶

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Результирующее состояние	Состояние `BabylMessage`
Подкаталог «cur»	метка «unseen»
подкаталог «cur» и флаг S	нет метки «unseen»
Флаг P	метка «forwarded» или «resent»
Флаг R	метка «отвечено»
Флаг T	метка «удалено»

`mboxMessage` объекты¶mboxMessage objects

class mailbox.mboxMessage(message=None)¶

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

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

Обычные флаги для сообщений mbox:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`MHMessage` объекты¶MHMessage objects

class mailbox.MHMessage(message=None)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`BabylMessage` объекты¶BabylMessage objects

class mailbox.BabylMessage(message=None)¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`MMDFMessage` объекты¶MMDFMessage objects

class mailbox.MMDFMessage(message=None)¶

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

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

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

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

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

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

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

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

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

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

Исключения¶Exceptions

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

exception mailbox.Error¶: Базовый класс для всех остальных исключений, специфичных для модуля.

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

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

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

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

Примеры¶Examples

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

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Может быть 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                # Сообщение повреждено. Просто оставьте его.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Получить почтовый ящик для использования.
            box = boxes[name]

            # Записать копию на диск перед удалением оригинала.
            # Если произошёл сбой, возможно дублирование сообщения, но
            # это лучше, чем полная потеря сообщения.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Удалить исходное сообщение
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Целевой получатель найден, поиск прекращён.

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

mailbox – Управление почтовыми ящиками в различных форматах¶mailbox – Manipulate mailboxes in various formats

Mailbox объекты¶Mailbox objects

Maildir объекты¶Maildir objects

mbox объекты¶mbox objects

MH объекты¶MH objects

Babyl объекты¶Babyl objects

MMDF объекты¶MMDF objects

Message объекты¶Message objects

MaildirMessage объекты¶MaildirMessage objects

mboxMessage объекты¶mboxMessage objects

MHMessage объекты¶MHMessage objects

BabylMessage объекты¶BabylMessage objects

MMDFMessage объекты¶MMDFMessage objects

Исключения¶Exceptions

Примеры¶Examples

`mailbox` – Управление почтовыми ящиками в различных форматах¶mailbox – Manipulate mailboxes in various formats

`Mailbox` объекты¶Mailbox objects

`Maildir` объекты¶Maildir objects

`mbox` объекты¶mbox objects

`MH` объекты¶MH objects

`Babyl` объекты¶Babyl objects

`MMDF` объекты¶MMDF objects

`Message` объекты¶Message objects

`MaildirMessage` объекты¶MaildirMessage objects

`mboxMessage` объекты¶mboxMessage objects

`MHMessage` объекты¶MHMessage objects

`BabylMessage` объекты¶BabylMessage objects

`MMDFMessage` объекты¶MMDFMessage objects