mailbox
— Манипулировать почтовыми ящиками в различных форматах¶
Источник: Lib/mailbox.py
Этот модуль определяет два класса, Mailbox
и Message
, для доступа и работы с почтовыми ящиками на диске и содержащимися в них сообщениями. Mailbox
предлагает словарно-подобное отображение ключей на сообщения. Message
расширяет класс email.message
модуля Message
с состоянием и поведением, специфичными для конкретного формата. Поддерживаются следующие форматы почтовых ящиков: Maildir, mbox, MH, Babyl и MMDF.
См.также
- Модуль
email
Представлять сообщения и манипулировать ими.
Mailbox
объектов¶
- class mailbox.Mailbox¶
Почтовый ящик, который можно осматривать и изменять.
Класс
Mailbox
определяет интерфейс и не предназначен для инстанцирования. Вместо этого подклассы, специфичные для конкретного формата, должны наследоваться отMailbox
, а ваш код должен инстанцировать конкретный подкласс.Интерфейс
Mailbox
похож на словарь, с небольшими ключами, соответствующими сообщениям. Ключи выдаются экземпляромMailbox
, с которым они будут использоваться, и имеют смысл только для этого экземпляраMailbox
. Ключ продолжает идентифицировать сообщение, даже если соответствующее сообщение было изменено, например, заменено другим сообщением.Сообщения могут быть добавлены в экземпляр
Mailbox
с помощью метода, подобного наборуadd()
, и удалены с помощью оператораdel
или методов, подобных наборуremove()
иdiscard()
.Семантика интерфейса
Mailbox
отличается от семантики словаря некоторыми примечательными особенностями. Каждый раз, когда запрашивается сообщение, генерируется новое представление (обычно экземплярMessage
), основанное на текущем состоянии почтового ящика. Аналогично, когда сообщение добавляется в экземплярMailbox
, содержимое предоставленного представления сообщения копируется. Ни в том, ни в другом случае ссылка на представление сообщения не сохраняется в экземпляреMailbox
.Итератор по умолчанию
Mailbox
iterator выполняет итерацию по представлениям сообщений, а не по ключам, как итератор по умолчаниюdictionary
. Кроме того, модификация почтового ящика во время итерации безопасна и хорошо определена. Сообщения, добавленные в почтовый ящик после создания итератора, не будут видны итератору. Сообщения, удаленные из почтового ящика до того, как итератор их выдаст, будут молча пропущены, хотя использование ключа из итератора может привести к исключениюKeyError
, если соответствующее сообщение будет впоследствии удалено.Предупреждение
Будьте очень осторожны при изменении почтовых ящиков, которые могут быть одновременно изменены каким-либо другим процессом. Самый безопасный формат почтового ящика для таких задач -
Maildir
; старайтесь избегать использования однофайловых форматов, таких какmbox
, для одновременной записи. Если вы изменяете почтовый ящик, вы должны заблокировать его, вызвав методыlock()
иunlock()
перед чтением сообщений из файла или внесением изменений путем добавления или удаления сообщения. Если не заблокировать почтовый ящик, есть риск потерять сообщения или повредить весь почтовый ящик.У экземпляров
Mailbox
есть следующие методы:- add(message)¶
Добавьте сообщение в почтовый ящик и верните назначенный ему ключ.
Параметр message может быть экземпляром
Message
, экземпляромemail.message.Message
, строкой, байтовой строкой или файлоподобным объектом (который должен быть открыт в двоичном режиме). Если message является экземпляром соответствующего подклассаMessage
, специфичного для формата (например, если это экземплярmboxMessage
, а это экземплярmbox
), используется его специфичная для формата информация. В противном случае используются разумные значения по умолчанию для информации, специфичной для формата.Изменено в версии 3.2: Добавлена поддержка двоичного ввода.
- remove(key)¶
- __delitem__(key)¶
- discard(key)¶
Удаление сообщения, соответствующего ключу, из почтового ящика.
Если такого сообщения не существует, возникает исключение
KeyError
, если метод был вызван какremove()
или__delitem__()
, но исключение не возникает, если метод был вызван какdiscard()
. Поведениеdiscard()
может быть предпочтительным, если основной формат почтового ящика поддерживает одновременную модификацию другими процессами.
- __setitem__(key, message)¶
Замените сообщение, соответствующее key, на message. Вызывает исключение
KeyError
, если ни одно сообщение уже не соответствует key.Как и в случае с
add()
, параметр message может быть экземпляромMessage
, экземпляромemail.message.Message
, строкой, байтовой строкой или файлоподобным объектом (который должен быть открыт в двоичном режиме). Если сообщение является экземпляром соответствующего подклассаMessage
(например, если это экземплярmboxMessage
, а это экземплярmbox
), то используется его информация, специфичная для формата. В противном случае форматно-специфическая информация сообщения, которое в данный момент соответствует key, остается без изменений.
- keys()¶
То же самое, что и
iterkeys()
, за исключением того, что возвращаетсяlist
, а не iterator.
- itervalues()¶
- __iter__()¶
Возвращает iterator над представлениями всех сообщений. Сообщения представляются как экземпляры соответствующего подкласса
Message
, специфичного для формата, если при инициализации экземпляраMailbox
не была указана фабрика сообщений.Примечание
Поведение
__iter__()
не похоже на поведение словарей, которые перебирают ключи.
- values()¶
То же самое, что и
itervalues()
, за исключением того, что возвращаетсяlist
, а не iterator.
- iteritems()¶
Возвращает iterator над парами (key, message), где key - ключ, а message - представление сообщения. Сообщения представляются как экземпляры соответствующего подкласса
Message
, специфичного для формата, если при инициализации экземпляраMailbox
не была указана пользовательская фабрика сообщений.
- items()¶
То же самое, что и
iteritems()
, за исключением того, что возвращаетсяlist
пар, а не iterator пар.
- get(key, default=None)¶
- __getitem__(key)¶
Возвращает представление сообщения, соответствующего key. Если такого сообщения не существует, возвращается default, если метод был вызван как
get()
, и исключениеKeyError
, если метод был вызван как__getitem__()
. Сообщение представляется как экземпляр соответствующего подклассаMessage
, специфичного для формата, если при инициализации экземпляраMailbox
не была указана пользовательская фабрика сообщений.
- get_message(key)¶
Возвращает представление сообщения, соответствующего key, в виде экземпляра соответствующего подкласса
Message
, специфичного для формата, или вызывает исключениеKeyError
, если такого сообщения не существует.
- get_bytes(key)¶
Возвращает байтовое представление сообщения, соответствующего key, или вызывает исключение
KeyError
, если такого сообщения не существует.Added in version 3.2.
- get_string(key)¶
Возвращает строковое представление сообщения, соответствующего key, или вызывает исключение
KeyError
, если такого сообщения не существует. Сообщение обрабатывается черезemail.message.Message
, чтобы преобразовать его в 7-битное чистое представление.
- get_file(key)¶
Возвращает file-like представление сообщения, соответствующего key, или вызывает исключение
KeyError
, если такого сообщения не существует. Файлоподобный объект ведет себя так же, как если бы он был открыт в двоичном режиме. Этот файл должен быть закрыт, если он больше не нужен.Изменено в версии 3.2: Объект файла действительно является binary file; ранее он некорректно возвращался в текстовом режиме. Кроме того, file-like object теперь поддерживает протокол context manager: вы можете использовать оператор
with
для его автоматического закрытия.Примечание
В отличие от других представлений сообщений, представления file-like не обязательно независимы от экземпляра
Mailbox
, который их создал, или от основного почтового ящика. Более подробная документация предоставляется каждым подклассом.
- __contains__(key)¶
Возвращает
True
, если ключ соответствует сообщению,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__()
почтового ящика.Added in version 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()
, потому что изменения, сделанные с помощью этого метода почтового ящика, не будут видны методу объекта message,get_flags()
.Added in version 3.13.
- add_flag(key, flag)¶
В сообщении, соответствующем key, установите флаги, указанные flag, не изменяя другие флаги. Чтобы добавить более одного флага за раз, flag может быть строкой из более чем одного символа.
Соображения по поводу использования этого метода в сравнении с методом
add_flag()
объекта сообщения аналогичны соображениям дляset_flags()
; см. обсуждение там.Added in version 3.13.
- remove_flag(key, flag)¶
В сообщении, соответствующем key, снимите флаги, указанные flag, не изменяя другие флаги. Чтобы удалить несколько флагов за один раз, flag может быть строкой из более чем одного символа.
Соображения по поводу использования этого метода в сравнении с методом
remove_flag()
объекта сообщения аналогичны соображениям дляset_flags()
; см. обсуждение там.Added in version 3.13.
- get_info(key)¶
Возвращает строку, содержащую информацию о сообщении, соответствующем key. Это то же самое, что и
get_message(key).get_info()
, но гораздо быстрее, поскольку не открывает файл сообщения. Используйте этот метод при итерации по ключам, чтобы определить, какие сообщения интересно получить.Если у вас есть объект
MaildirMessage
, используйте вместо него методget_info()
, потому что изменения, сделанные методомset_info()
сообщения, не отражаются здесь до вызова метода__setitem__()
почтового ящика.Added in version 3.13.
- set_info(key, info)¶
Установите значение info для сообщения, соответствующего key. Вызов
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()
, потому что изменения, сделанные с помощью этого метода почтового ящика, не будут видны методу объекта message,get_info()
.Added in version 3.13.
Некоторые методы
Mailbox
, реализованныеMaildir
, заслуживают особого внимания:- add(message)¶
- __setitem__(key, message)¶
- update(arg)¶
Предупреждение
Эти методы генерируют уникальные имена файлов на основе идентификатора текущего процесса. При использовании нескольких потоков могут возникнуть незамеченные столкновения имен, которые приведут к повреждению почтового ящика, если потоки не скоординированы, чтобы избежать одновременного использования этих методов для работы с одним и тем же почтовым ящиком.
- flush()¶
Все изменения в почтовых ящиках Maildir применяются немедленно, поэтому этот метод ничего не делает.
- lock()¶
- unlock()¶
Почтовые ящики Maildir не поддерживают (или не требуют) блокировки, поэтому эти методы ничего не делают.
- close()¶
Экземпляры
Maildir
не хранят никаких открытых файлов, а базовые почтовые ящики не поддерживают блокировку, поэтому этот метод ничего не делает.
- get_file(key)¶
В зависимости от платформы хоста может оказаться невозможным изменить или удалить основное сообщение, пока возвращаемый файл остается открытым.
См.также
- maildir man page from Courier
Спецификация формата. Описывает общее расширение для поддержки папок.
- Using maildir format
Заметки о 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
, заслуживают особого внимания:
См.также
- mbox man page from tin
Спецификация формата с подробным описанием блокировки.
- Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad
Аргумент в пользу использования оригинального формата mbox, а не его разновидности.
- «mbox» is a family of several mutually incompatible mailbox formats
История вариаций 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 (называемые folders). Папки могут быть вложены друг в друга неограниченно. Почтовые ящики MH также поддерживают sequences, которые представляют собой именованные списки, используемые для логической группировки сообщений без их перемещения во вложенные папки. Последовательности определяются в файле
.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 применяются немедленно, поэтому этот метод ничего не делает.
См.также
- nmh - Message Handling System
Главная страница nmh, обновленной версии оригинального mh.
- MH & nmh: Email for Users & Programmers
Книга под лицензией 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 также имеет сопровождающий список labels, или коротких строк, которые записывают дополнительную информацию о сообщении, а список всех пользовательских меток, найденных в почтовом ящике, хранится в разделе опций Babyl.
Экземпляры
Babyl
имеют все методыMailbox
в дополнение к следующим:- get_labels()¶
Возвращает список имен всех пользовательских меток, используемых в почтовом ящике.
Примечание
Чтобы определить, какие метки существуют в почтовом ящике, проверяются сами сообщения, а не список меток в разделе параметров Babyl, но раздел Babyl обновляется при каждом изменении почтового ящика.
Некоторые методы
Mailbox
, реализованныеBabyl
, заслуживают особого внимания:- get_file(key)¶
В почтовых ящиках Babyl заголовки сообщения не хранятся смежно с телом сообщения. Чтобы создать файлоподобное представление, заголовки и тело копируются в экземпляр
io.BytesIO
, который имеет API, идентичный файловому. В результате файлоподобный объект действительно независим от базового почтового ящика, но не экономит память по сравнению со строковым представлением.
См.также
- Format of Version 5 Babyl Files
Спецификация формата Babyl.
- Reading Mail with Rmail
Руководство по Rmail, содержащее некоторую информацию о семантике Babyl.
MMDF
объектов¶
- class mailbox.MMDF(path, factory=None, create=True)¶
Подкласс
Mailbox
для почтовых ящиков в формате MMDF. Параметр factory - это вызываемый объект, который принимает файлоподобное представление сообщения (которое ведет себя так же, как если бы было открыто в двоичном режиме) и возвращает пользовательское представление. Если factory имеет значениеNone
, то по умолчанию используется представление сообщенийMMDFMessage
. Если create имеет значениеTrue
, почтовый ящик создается, если он не существует.MMDF - это однофайловый формат почтового ящика, придуманный для Multichannel Memorandum Distribution Facility, агента по передаче почты. Каждое сообщение имеет ту же форму, что и сообщение mbox, но до и после него заключены в скобки строки, содержащие четыре символа Control-A (
'\001'
). Как и в формате mbox, начало каждого сообщения обозначается строкой, первые пять символов которой - «From „, но при сохранении сообщений дополнительные вхождения “From „ не преобразуются в “>From », поскольку дополнительные строки-разделители не позволяют принять такие вхождения за начало последующих сообщений.Некоторые методы
Mailbox
, реализованныеMMDF
, заслуживают особого внимания:
См.также
- mmdf man page from tin
Спецификация формата MMDF из документации tin, программы для чтения новостей.
- MMDF
Статья Википедии, описывающая Многоканальный механизм распределения меморандумов.
Message
объектов¶
- class mailbox.Message(message=None)¶
Подкласс
email.message
модуляMessage
. Подклассыmailbox.Message
добавляют состояние и поведение, специфичные для формата почтового ящика.Если message опущено, новый экземпляр создается в пустом состоянии по умолчанию. Если message является экземпляром
email.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
Trashed
Отмечено для последующего удаления
Экземпляры
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()¶
Возвращает строку, содержащую «информацию» для сообщения. Это полезно для доступа и изменения «информации», которая является экспериментальной (т. е. не является списком флагов).
- set_info(info)¶
Установите значение «info» в info, которое должно быть строкой.
Когда экземпляр MaildirMessage
создается на основе экземпляра mboxMessage
или MMDFMessage
, заголовки Status и X-Status опускаются, и выполняются следующие преобразования:
Результирующее состояние |
Состояние |
---|---|
Подкаталог «cur» |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг D |
Когда экземпляр MaildirMessage
создается на основе экземпляра MHMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Подкаталог «cur» |
«Невидимая» последовательность |
Подкаталог «cur» и флаг S |
нет «невидимой» последовательности |
Флаг |
последовательность «флажков» |
Флаг |
«Ответил» последовательность |
Когда экземпляр MaildirMessage
создается на основе экземпляра BabylMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Подкаталог «cur» |
«Невидимая» этикетка |
Подкаталог «cur» и флаг S |
нет «невидимой» этикетки |
Флаг |
метка «переслано» или «отправлено» |
Флаг |
ярлык «ответил» |
Флаг |
метка «удалено» |
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
, и происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг |
Флаг |
Флаг |
Подкаталог «cur» |
Флаг D |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Когда экземпляр mboxMessage
создается на основе экземпляра MHMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг R и флаг O |
нет «невидимой» последовательности |
Флаг |
«Невидимая» последовательность |
Флаг |
последовательность «флажков» |
Флаг |
«Ответил» последовательность |
Когда экземпляр mboxMessage
создается на основе экземпляра BabylMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг R и флаг O |
нет «невидимой» этикетки |
Флаг |
«Невидимая» этикетка |
Флаг D |
метка «удалено» |
Флаг |
ярлык «ответил» |
Когда экземпляр mboxMessage
создается на основе экземпляра MMDFMessage
, строка «From» копируется, и все флаги напрямую соответствуют друг другу:
Результирующее состояние |
|
---|---|
Флаг |
Флаг |
Флаг |
Флаг |
Флаг D |
Флаг D |
Флаг |
Флаг |
Флаг |
Флаг |
MHMessage
объектов¶
- class mailbox.MHMessage(message=None)¶
Сообщение со специфическим для MH поведением. Параметр message имеет то же значение, что и в конструкторе
Message
.Сообщения MH не поддерживают метки или флаги в традиционном смысле, но они поддерживают последовательности, которые представляют собой логические группы произвольных сообщений. Некоторые программы чтения почты (хотя и не стандартные mh и nmh) используют последовательности примерно так же, как флаги в других форматах, например, следующим образом:
Последовательность
Пояснение
невидимый
Не прочитано, но ранее обнаружено MUA
ответил
Ответил на
отмечено
Отмечено как важное
Экземпляры
MHMessage
предлагают следующие методы:- get_sequences()¶
Возвращает список имен последовательностей, включающих данное сообщение.
- set_sequences(sequences)¶
Установите список последовательностей, включающих это сообщение.
- add_sequence(sequence)¶
Добавьте последовательность в список последовательностей, содержащих это сообщение.
- remove_sequence(sequence)¶
Удалить последовательность из списка последовательностей, включающих это сообщение.
Когда экземпляр MHMessage
создается на основе экземпляра MaildirMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
«Невидимая» последовательность |
нет флага S |
«Ответил» последовательность |
Флаг |
последовательность «флажков» |
Флаг |
Когда экземпляр MHMessage
создается на основе экземпляра mboxMessage
или MMDFMessage
, заголовки Status и X-Status опускаются, и выполняются следующие преобразования:
Результирующее состояние |
Состояние |
---|---|
«Невидимая» последовательность |
нет флага R |
«Ответил» последовательность |
Флаг |
последовательность «флажков» |
Флаг |
Когда экземпляр MHMessage
создается на основе экземпляра BabylMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
«Невидимая» последовательность |
«Невидимая» этикетка |
«Ответил» последовательность |
ярлык «ответил» |
BabylMessage
объектов¶
- class mailbox.BabylMessage(message=None)¶
Сообщение с поведением, специфичным для Babyl. Параметр message имеет то же значение, что и в конструкторе
Message
.Некоторые метки сообщений, называемые attributes, по соглашению имеют особые значения. Они имеют следующие атрибуты:
Этикетка
Пояснение
невидимый
Не прочитано, но ранее обнаружено MUA
удалено
Отмечено для последующего удаления
подано
Копирование в другой файл или почтовый ящик
ответил
Ответил на
перенаправлено
Передано
отредактировано
Изменено пользователем
отправить
Отправить
По умолчанию Rmail отображает только видимые заголовки. Однако класс
BabylMessage
использует оригинальные заголовки, поскольку они более полные. При желании к видимым заголовкам можно обратиться явно.Экземпляры
BabylMessage
предлагают следующие методы:- get_labels()¶
Возвращает список меток на сообщении.
- set_labels(labels)¶
Установите список меток в сообщении на labels.
- add_label(label)¶
Добавьте label в список меток сообщения.
- remove_label(label)¶
Удалите label из списка меток сообщения.
- get_visible()¶
Возвращает экземпляр
Message
, заголовки которого являются видимыми заголовками сообщения, а тело пустое.
- set_visible(visible)¶
Устанавливает видимые заголовки сообщения такими же, как заголовки в message. Параметр visible должен быть экземпляром
Message
, экземпляромemail.message.Message
, строкой или файлоподобным объектом (который должен быть открыт в текстовом режиме).
- update_visible()¶
При изменении исходных заголовков экземпляра
BabylMessage
видимые заголовки автоматически не изменяются. Этот метод обновляет видимые заголовки следующим образом: каждый видимый заголовок с соответствующим оригинальным заголовком устанавливается в значение оригинального заголовка, каждый видимый заголовок без соответствующего оригинального заголовка удаляется, а любые из Date, From, Reply-To, To, CC и Subject, которые присутствуют в оригинальных, но не видимых заголовках, добавляются в видимые заголовки.
Когда экземпляр BabylMessage
создается на основе экземпляра MaildirMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
«Невидимая» этикетка |
нет флага S |
метка «удалено» |
Флаг |
ярлык «ответил» |
Флаг |
метка «forwarded» |
Флаг |
Когда экземпляр BabylMessage
создается на основе экземпляра mboxMessage
или MMDFMessage
, заголовки Status и X-Status опускаются, и выполняются следующие преобразования:
Результирующее состояние |
Состояние |
---|---|
«Невидимая» этикетка |
нет флага R |
метка «удалено» |
Флаг D |
ярлык «ответил» |
Флаг |
Когда экземпляр BabylMessage
создается на основе экземпляра MHMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
«Невидимая» этикетка |
«Невидимая» последовательность |
ярлык «ответил» |
«Ответил» последовательность |
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
, и происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг |
Флаг |
Флаг |
Подкаталог «cur» |
Флаг D |
Флаг |
Флаг |
Флаг |
Флаг |
Флаг |
Когда экземпляр MMDFMessage
создается на основе экземпляра MHMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг R и флаг O |
нет «невидимой» последовательности |
Флаг |
«Невидимая» последовательность |
Флаг |
последовательность «флажков» |
Флаг |
«Ответил» последовательность |
Когда экземпляр MMDFMessage
создается на основе экземпляра BabylMessage
, происходят следующие преобразования:
Результирующее состояние |
|
---|---|
Флаг R и флаг O |
нет «невидимой» этикетки |
Флаг |
«Невидимая» этикетка |
Флаг D |
метка «удалено» |
Флаг |
ярлык «ответил» |
Когда экземпляр MMDFMessage
создается на основе экземпляра mboxMessage
, строка «From» копируется, и все флаги напрямую соответствуют друг другу:
Результирующее состояние |
|
---|---|
Флаг |
Флаг |
Флаг |
Флаг |
Флаг D |
Флаг D |
Флаг |
Флаг |
Флаг |
Флаг |
Исключения¶
В модуле mailbox
определены следующие классы исключений:
- exception mailbox.Error¶
Базовый класс для всех остальных специфических для модуля исключений.
- exception mailbox.NoSuchMailboxError¶
Возникает, когда почтовый ящик ожидается, но не найден, например, при инстанцировании подкласса
Mailbox
с несуществующим путем (и с параметром create, установленным вFalse
) или при открытии несуществующей папки.
- exception mailbox.NotEmptyError¶
Возникает, когда почтовый ящик не пуст, но ожидается, что он будет пуст, например, при удалении папки, содержащей сообщения.
- exception mailbox.ExternalClashError¶
Возникает, когда некоторые условия, связанные с почтовым ящиком, не зависящие от программы, приводят к тому, что она не может продолжить работу, например, когда не удается получить блокировку, которая уже принадлежит другой программе, или когда уникальное имя файла уже существует.
Примеры¶
Простой пример печати тем всех сообщений в почтовом ящике, которые кажутся интересными:
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()