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

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

Этот модуль определяет два класса: Mailbox и Message, предназначенные для доступа к почтовым ящикам, хранящимся на диске, и содержащимся в них сообщениям, а также для работы с ними. Mailbox предоставляет отображение ключей на сообщения, подобное словарю. Message расширяет класс Message модуля email.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, если такого сообщения нет. Сообщение обрабатывается с помощью email.message.Message, чтобы преобразовать его в 7-битное представление без посторонних символов.

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

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

Примечание

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

`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 также можно задать отдельно для каждого экземпляра.

Изменено в версии 3.13: Maildir теперь игнорирует файлы, имя которых начинается с точки.

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

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

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

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

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

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

get_flags(key)

Возвращает в виде строки флаги, установленные для сообщения, соответствующего key. Это то же самое, что get_message(key).get_flags(), но намного быстрее, поскольку файл сообщения не открывается. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения стоит получить.

Если у вас есть объект MaildirMessage, вместо этого используйте его метод get_flags(), поскольку изменения, внесённые методами объекта сообщения set_flags(), add_flag() и remove_flag(), не будут здесь отражены до вызова метода почтового ящика __setitem__().

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

set_flags(key, flags)

Для сообщения, соответствующего key, устанавливает флаги, указанные в flags, и снимает все остальные. Вызов some_mailbox.set_flags(key, flags) аналогичен

one_message = some_mailbox.get_message(key)
one_message.set_flags(flags)
some_mailbox[key] = one_message

но выполняется быстрее, поскольку файл сообщения не открывается.

Если у вас есть объект MaildirMessage, вместо этого используйте его метод set_flags(), поскольку изменения, внесённые этим методом почтового ящика, не будут видны методу объекта сообщения get_flags().

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

add_flag(key, flag)

Для сообщения, соответствующего key, устанавливает флаги, указанные в flag, не изменяя остальные флаги. Чтобы добавить несколько флагов одновременно, flag может быть строкой из нескольких символов.

Рекомендации по использованию этого метода вместо метода объекта сообщения add_flag() аналогичны рекомендациям для set_flags(); см. соответствующее описание.

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

remove_flag(key, flag)

Для сообщения, соответствующего key, снимает флаги, указанные в flag, не изменяя остальные флаги. Чтобы снять несколько флагов одновременно, flag может быть строкой из нескольких символов.

Рекомендации по использованию этого метода вместо метода объекта сообщения remove_flag() аналогичны рекомендациям для set_flags(); см. соответствующее описание.

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

get_info(key)

Возвращает строку со сведениями для сообщения, соответствующего key. Это то же самое, что get_message(key).get_info(), но намного быстрее, поскольку файл сообщения не открывается. Используйте этот метод при переборе ключей, чтобы определить, какие сообщения стоит получить.

Если у вас есть объект MaildirMessage, вместо этого используйте его метод get_info(), поскольку изменения, внесённые методом объекта сообщения set_info(), не будут здесь отражены до вызова метода почтового ящика __setitem__().

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

set_info(key, info)

Задаёт для сообщения, соответствующего key, сведения info. Вызов some_mailbox.set_info(key, flags) аналогичен

one_message = some_mailbox.get_message(key)
one_message.set_info(info)
some_mailbox[key] = one_message

но выполняется быстрее, поскольку файл сообщения не открывается.

Если у вас есть объект MaildirMessage, вместо этого используйте его метод set_info(), поскольку изменения, внесённые этим методом почтового ящика, не будут видны методу объекта сообщения get_info().

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

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

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

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

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

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

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

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

См. также

Справочная страница maildir от Courier: Спецификация формата. Описывает распространённое расширение для поддержки папок.
Использование формата 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_bytes(key, from_=False): Примечание. У этого метода есть дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи в файле mbox — это строка Unix «From ». Если from_ имеет значение False, первая строка файла отбрасывается.

get_file(key, from_=False)

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

Примечание. У этого метода есть дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи в файле mbox — это строка Unix «From ». Если from_ имеет значение False, первая строка файла отбрасывается.

get_string(key, from_=False): Примечание. У этого метода есть дополнительный параметр (from_) по сравнению с другими классами. Первая строка записи в файле mbox — это строка Unix «From ». Если from_ имеет значение False, первая строка файла отбрасывается.

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

См. также

Справочная страница mbox от tin: Спецификация формата со сведениями о блокировке.
Настройка 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, а также следующие методы:

Изменено в версии 3.13: Добавлена поддержка папок, не содержащих файл .mh_sequences.

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: электронная почта для пользователей и программистов: Книга о 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().

См. также

Формат файлов Babyl версии 5: Спецификация формата Babyl.
Чтение почты с помощью 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_bytes(key, from_=False): Примечание: по сравнению с другими классами этот метод имеет дополнительный параметр (from_). Первая строка записи в файле mbox — это строка Unix «From ». Если from_ имеет значение False, первая строка файла отбрасывается.

get_file(key, from_=False)

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

Примечание: по сравнению с другими классами этот метод имеет дополнительный параметр (from_). Первая строка записи в файле mbox — это строка Unix «From ». Если from_ имеет значение False, первая строка файла отбрасывается.

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

См. также

страница руководства mmdf из 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` объекты