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

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

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

См. также

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

`Mailbox` объекты

class mailbox.Mailbox

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

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

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

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

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

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

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

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

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

add(message)

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

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

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

remove(key)

__delitem__(key)

discard(key)

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

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

__setitem__(key, message)

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

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

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

keys(): То же, что и iterkeys(), но возвращается list, а не итератор.

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

Примечание

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

values(): То же, что и itervalues(), но возвращается list, а не итератор.

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

`Maildir` объекты

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

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

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

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

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

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

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

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

См. также

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

`mbox` объекты

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

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

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

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

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

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

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

См. также

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

`MH` объекты

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

Ключи, выданные ранее, становятся недействительными после выполнения этой операции, поэтому впоследствии их не следует использовать.

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

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

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

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

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

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

См. также

nmh - Message Handling System: Домашняя страница nmh — обновлённой версии оригинальной программы mh.
MH & nmh: Email for Users & Programmers: Книга о mh и nmh, распространяемая по лицензии GPL; содержит некоторые сведения о формате почтового ящика.

`Babyl` объекты

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

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

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

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

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

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

Примечание

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

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

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

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

См. также

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

`MMDF` объекты

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

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

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

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

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

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

См. также

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

`Message` объекты

class mailbox.Message(message=None)

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

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

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

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

`MaildirMessage` объекты

class mailbox.MaildirMessage(message=None)

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

set_info(info): Задает для раздела «info» значение info, которое должно быть строкой.

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

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Подкаталог «cur»	Флаг O
Флаг F	Флаг F
Флаг R	Флаг A
Флаг S	Флаг R
Флаг T	Флаг D

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

Итоговое состояние	Состояние `MHMessage`
Подкаталог «cur»	Последовательность «unseen»
Подкаталог «cur» и флаг S	Нет последовательности «unseen»
Флаг F	Последовательность «flagged»
Флаг R	Последовательность «replied»

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

Итоговое состояние	Состояние `BabylMessage`
Подкаталог «cur»	Метка «unseen»
Подкаталог «cur» и флаг S	Нет метки «unseen»
Флаг P	Метка «forwarded» или «resent»
Флаг R	Метка «answered»
Флаг T	Метка «deleted»

`mboxMessage` объекты

class mailbox.mboxMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

Итоговое состояние	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог «cur»
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

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

Итоговое состояние	Состояние `MHMessage`
Флаг R и флаг O	Нет последовательности «unseen»
Флаг O	Последовательность «unseen»
Флаг F	Последовательность «flagged»
Флаг A	Последовательность «replied»

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

Итоговое состояние	Состояние `BabylMessage`
Флаг R и флаг O	Нет метки «unseen»
Флаг O	Метка «unseen»
Флаг D	Метка «deleted»
Флаг A	Метка «answered»

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

Итоговое состояние	Состояние `MMDFMessage`
Флаг R	Флаг R
Флаг O	Флаг O
Флаг D	Флаг D
Флаг F	Флаг F
Флаг A	Флаг A

`MHMessage` объекты

class mailbox.MHMessage(message=None)

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

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

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

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

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

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

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

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

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

Итоговое состояние	Состояние `MaildirMessage`
Последовательность «unseen»	Нет флага S
Последовательность «replied»	Флаг R
Последовательность «flagged»	Флаг F

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

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Последовательность «unseen»	Нет флага R
Последовательность «replied»	Флаг A
Последовательность «flagged»	Флаг F

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

Итоговое состояние	Состояние `BabylMessage`
Последовательность «unseen»	Метка «unseen»
Последовательность «replied»	Метка «answered»

`BabylMessage` объекты

class mailbox.BabylMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

Итоговое состояние	Состояние `MaildirMessage`
Метка «unseen»	Нет флага S
Метка «deleted»	Флаг T
Метка «answered»	Флаг R
Метка «forwarded»	Флаг P

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

Итоговое состояние	Состояние `mboxMessage` или `MMDFMessage`
Метка «unseen»	Нет флага R
Метка «deleted»	Флаг D
Метка «answered»	Флаг A

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

Итоговое состояние	Состояние `MHMessage`
Метка «unseen»	Последовательность «unseen»
Метка «answered»	Последовательность «replied»

`MMDFMessage` объекты

class mailbox.MMDFMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

Итоговое состояние	Состояние `MaildirMessage`
Флаг R	Флаг S
Флаг O	Подкаталог “cur”
Флаг D	Флаг T
Флаг F	Флаг F
Флаг A	Флаг R

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

Итоговое состояние	Состояние `MHMessage`
Флаги R и O	Нет последовательности “unseen”
Флаг O	Последовательность “unseen”
Флаг F	Последовательность “flagged”
Флаг A	Последовательность “replied”

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

Итоговое состояние	Состояние `BabylMessage`
Флаги R и O	Нет метки “unseen”
Флаг O	Метка “unseen”
Флаг D	Метка “deleted”
Флаг A	Метка “answered”

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

Итоговое состояние	Состояние `mboxMessage`
Флаг R	Флаг R
Флаг O	Флаг O
Флаг D	Флаг D
Флаг F	Флаг F
Флаг A	Флаг A

Исключения

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

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

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

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

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

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

Примеры

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

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

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

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

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

import mailbox
import email.errors

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

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

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

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

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

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

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

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

Mailbox объекты

Maildir объекты

mbox объекты

MH объекты

Babyl объекты

MMDF объекты

Message объекты

MaildirMessage объекты

mboxMessage объекты

MHMessage объекты

BabylMessage объекты

MMDFMessage объекты

Исключения

Примеры

`Mailbox` объекты

`Maildir` объекты

`mbox` объекты

`MH` объекты

`Babyl` объекты

`MMDF` объекты

`Message` объекты

`MaildirMessage` объекты

`mboxMessage` объекты

`MHMessage` объекты

`BabylMessage` объекты

`MMDFMessage` объекты