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

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

remove(key)

__delitem__(key)

discard(key)

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

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

__setitem__(key, message)

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

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

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

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

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

Примечание

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

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

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

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

get(key, default=None)
__getitem__(key): Возвращает представление сообщения, соответствующего ключу 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-to-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 man page от Courier: Спецификация формата. Описывает общее расширение для поддержки папок.
Использование формата maildir: Заметки об авторе формата Maildir. Включает обновлённую схему создания имён и детали «информационных» семантик.

`mbox` объекты

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

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

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

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

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

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

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

См. также

mbox man page от 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: Электронная почта для пользователей и программистов: Книжка с открытым исходным кодом (GPL) о mh и nmh, с некоторыми сведениями о формате почтового ящика.

`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_file(key): Использование файла после вызова flush() или close() для экземпляра MMDF может привести к непредсказуемым результатам или выбросу исключения.

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

См. также

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

`Message` объекты

class mailbox.Message(message=None)

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

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

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

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

`MaildirMessage` объекты

class mailbox.MaildirMessage(message=None)

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`mboxMessage` объекты

class mailbox.mboxMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

При создании экземпляра mboxMessage на основе экземпляра MaildirMessage, строка «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) используют последовательности примерно так же, как флаги используются с другими форматами, как показано ниже:

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

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

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

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

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

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

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

Результат	Состояние `MaildirMessage`
Последовательность “непрочитанное”	нет флага S
Последовательность “ответ”	флаг R
Последовательность “отмечено”	флаг F

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

Результат	Состояние `mboxMessage` или `MMDFMessage`
Последовательность “непрочитанное”	нет флага R
Последовательность “ответ”	флаг A
Последовательность “отмечено”	флаг F

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

Результат	Состояние `BabylMessage`
Последовательность “непрочитанное”	метка “непрочитанное”
Последовательность “ответ”	метка “ответ”

`BabylMessage` объекты

class mailbox.BabylMessage(message=None)

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

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

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

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

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

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

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

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

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

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

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

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

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

Результат	Состояние `MaildirMessage`
метка “непрочитанное”	нет флага S
метка “удалено”	флаг T
метка “ответ”	флаг R
метка “переслано”	флаг P

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

Результат	Состояние `mboxMessage` или `MMDFMessage`
метка “непрочитанное”	нет флага R
метка “удалено”	флаг D
метка “ответ”	флаг A

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

Результат	Состояние `MHMessage`
метка “непрочитанное”	последовательность “непрочитанное”
метка “ответ”	последовательность “ответ”

END_OF_DOCUMENT_MARKER

`MMDFMessage` объекты

class mailbox.MMDFMessage(message=None)

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

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

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

Флаг	Значение	Описание
R	Прочитано	Прочитано
O	Старое	Ранее обнаружено MUA
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` объекты