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, если такого сообщения нет. Сообщение обрабатывается классом 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, почтового клиента. Каждое сообщение в почтовом ящике 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(): Используются три механизма блокировки: блокировка с помощью файла-точки и, если доступны, системные вызовы 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 5322, которое считывается и разбирается. Файлы следует открывать в двоичном режиме, однако для обратной совместимости допускаются файлы, открытые в текстовом режиме.

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

Не требуется использовать экземпляры 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	Отвечено	На сообщение дан ответ

Экземпляры 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` объекты