mailbox
— Manipulate mailboxes in various formats¶
Вихідний код: Lib/mailbox.py
This module defines two classes, Mailbox
and Message
, for
accessing and manipulating on-disk mailboxes and the messages they contain.
Mailbox
offers a dictionary-like mapping from keys to messages.
Message
extends the email.message
module’s
Message
class with format-specific state and behavior.
Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
Дивись також
- Модуль
email
Представляти та маніпулювати повідомленнями.
Mailbox
objects¶
-
class
mailbox.
Mailbox
¶ Поштова скринька, яку можна перевірити та змінити.
The
Mailbox
class defines an interface and is not intended to be instantiated. Instead, format-specific subclasses should inherit fromMailbox
and your code should instantiate a particular subclass.The
Mailbox
interface is dictionary-like, with small keys corresponding to messages. Keys are issued by theMailbox
instance with which they will be used and are only meaningful to thatMailbox
instance. A key continues to identify a message even if the corresponding message is modified, such as by replacing it with another message.Messages may be added to a
Mailbox
instance using the set-like methodadd()
and removed using adel
statement or the set-like methodsremove()
anddiscard()
.Mailbox
interface semantics differ from dictionary semantics in some noteworthy ways. Each time a message is requested, a new representation (typically aMessage
instance) is generated based upon the current state of the mailbox. Similarly, when a message is added to aMailbox
instance, the provided message representation’s contents are copied. In neither case is a reference to the message representation kept by theMailbox
instance.The default
Mailbox
iterator iterates over message representations, not keys as the default dictionary iterator does. Moreover, modification of a mailbox during iteration is safe and well-defined. Messages added to the mailbox after an iterator is created will not be seen by the iterator. Messages removed from the mailbox before the iterator yields them will be silently skipped, though using a key from an iterator may result in aKeyError
exception if the corresponding message is subsequently removed.Попередження
Be very cautious when modifying mailboxes that might be simultaneously changed by some other process. The safest mailbox format to use for such tasks is Maildir; try to avoid using single-file formats such as mbox for concurrent writing. If you’re modifying a mailbox, you must lock it by calling the
lock()
andunlock()
methods before reading any messages in the file or making any changes by adding or deleting a message. Failing to lock the mailbox runs the risk of losing messages or corrupting the entire mailbox.Mailbox
instances have the following methods:-
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)¶ Замініть повідомлення, що відповідає ключу на повідомлення. Викликати виняток
KeyError
, якщо жодне повідомлення вже не відповідає ключу.Як і
add()
, параметр message може бути екземпляромMessage
, екземпляромemail.message.Message
, рядком, рядком байтів або файлоподібним об’єктом (який має бути відкритий у двійковому режимі). Якщо message є екземпляром відповідного підкласуMessage
(наприклад, якщо це екземплярmboxMessage
, а це екземплярmbox
), його специфічний для формату використовується інформація. В іншому випадку інформація про формат повідомлення, яке наразі відповідає ключу, залишається без змін.
-
iterkeys
()¶ -
keys
()¶ Return an iterator over all keys if called as
iterkeys()
or return a list of keys if called askeys()
.
-
itervalues
()¶ -
__iter__
()¶ -
values
()¶ Return an iterator over representations of all messages if called as
itervalues()
or__iter__()
or return a list of such representations if called asvalues()
. The messages are represented as instances of the appropriate format-specificMessage
subclass unless a custom message factory was specified when theMailbox
instance was initialized.Примітка
Поведінка
__iter__()
відрізняється від поведінки словників, які перебирають ключі.
-
iteritems
()¶ -
items
()¶ Return an iterator over (key, message) pairs, where key is a key and message is a message representation, if called as
iteritems()
or return a list of such pairs if called asitems()
. The messages are represented as instances of the appropriate format-specificMessage
subclass unless a custom message factory was specified when theMailbox
instance was initialized.
-
get
(key, default=None)¶ -
__getitem__
(key)¶ Return a representation of the message corresponding to key. If no such message exists, default is returned if the method was called as
get()
and aKeyError
exception is raised if the method was called as__getitem__()
. The message is represented as an instance of the appropriate format-specificMessage
subclass unless a custom message factory was specified when theMailbox
instance was initialized.
-
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)¶ Return a file-like representation of the message corresponding to key, or raise a
KeyError
exception if no such message exists. The file-like object behaves as if open in binary mode. This file should be closed once it is no longer needed.Змінено в версії 3.2: The file object really is a binary file; previously it was incorrectly returned in text mode. Also, the file-like object now supports the context management protocol: you can use a
with
statement to automatically close it.Примітка
Unlike other representations of messages, file-like representations are not necessarily independent of the
Mailbox
instance that created them or of the underlying mailbox. More specific documentation is provided by each subclass.
-
__contains__
(key)¶ Повертає
True
, якщо ключ відповідає повідомленню,False
інакше.
-
__len__
()¶ Повернути кількість повідомлень у поштовій скриньці.
-
clear
()¶ Видалити всі повідомлення з поштової скриньки.
-
pop
(key, default=None)¶ Return a representation of the message corresponding to key and delete the message. If no such message exists, return default. The message is represented as an instance of the appropriate format-specific
Message
subclass unless a custom message factory was specified when theMailbox
instance was initialized.
-
popitem
()¶ Return an arbitrary (key, message) pair, where key is a key and message is a message representation, and delete the corresponding message. If the mailbox is empty, raise a
KeyError
exception. The message is represented as an instance of the appropriate format-specificMessage
subclass unless a custom message factory was specified when theMailbox
instance was initialized.
-
update
(arg)¶ Parameter arg should be a key-to-message mapping or an iterable of (key, message) pairs. Updates the mailbox so that, for each given key and message, the message corresponding to key is set to message as if by using
__setitem__()
. As with__setitem__()
, each key must already correspond to a message in the mailbox or else aKeyError
exception will be raised, so in general it is incorrect for arg to be aMailbox
instance.Примітка
На відміну від словників, аргументи ключових слів не підтримуються.
-
flush
()¶ Write any pending changes to the filesystem. For some
Mailbox
subclasses, changes are always written immediately andflush()
does nothing, but you should still make a habit of calling this method.
-
lock
()¶ Отримайте ексклюзивне консультаційне блокування поштової скриньки, щоб інші процеси знали, що не потрібно її змінювати. Якщо блокування недоступне, виникає
ExternalClashError
. Використовувані конкретні механізми блокування залежать від формату поштової скриньки. Ви повинні завжди блокувати поштову скриньку, перш ніж вносити будь-які зміни в її вміст.
-
unlock
()¶ Зніміть блокування поштової скриньки, якщо є.
-
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», доданому до імені файлу.Folders of the style introduced by the Courier mail transfer agent are also supported. Any subdirectory of the main mailbox is considered a folder if
'.'
is the first character in its name. Folder names are represented byMaildir
without the leading'.'
. Each folder is itself a Maildir mailbox but should not contain other folders. Instead, a logical nesting is indicated using'.'
to delimit levels, e.g., «Archived.2005.07».Примітка
Специфікація Maildir вимагає використання двокрапки (
':'
) у певних іменах файлів повідомлень. Однак деякі операційні системи не дозволяють використовувати цей символ у назвах файлів. Якщо ви бажаєте використовувати формат, подібний до Maildir, у такій операційній системі, вам слід указати інший символ для використання замість нього. Знак оклику ('!'
) є популярним вибором. Наприклад:import mailbox mailbox.Maildir.colon = '!'
The
colon
attribute may also be set on a per-instance basis.Maildir
instances have all of the methods ofMailbox
in addition to the following:-
list_folders
()¶ Повернути список імен усіх папок.
-
get_folder
(folder)¶ Return a
Maildir
instance representing the folder whose name is folder. ANoSuchMailboxError
exception is raised if the folder does not exist.
-
add_folder
(folder)¶ Create a folder whose name is folder and return a
Maildir
instance representing it.
-
remove_folder
(folder)¶ Видаліть папку з назвою папка. Якщо папка містить будь-які повідомлення, буде викликано виняток
NotEmptyError
і папку не буде видалено.
-
clean
()¶ Видаліть із поштової скриньки тимчасові файли, до яких не було доступу протягом останніх 36 годин. Специфікація Maildir говорить, що програми для читання пошти повинні робити це час від часу.
Some
Mailbox
methods implemented byMaildir
deserve special remarks:-
add
(message)¶ -
__setitem__
(key, message)¶ -
update
(arg)¶ Попередження
Ці методи генерують унікальні імена файлів на основі ідентифікатора поточного процесу. Під час використання кількох потоків можуть виникнути невиявлені конфлікти імен і спричинити пошкодження поштової скриньки, якщо потоки не координуються, щоб уникнути використання цих методів для одночасного маніпулювання тією самою поштовою скринькою.
-
flush
()¶ Усі зміни в поштових скриньках Maildir застосовуються негайно, тому цей метод нічого не робить.
-
lock
()¶ -
unlock
()¶ Поштові скриньки Maildir не підтримують (або вимагають) блокування, тому ці методи нічого не роблять.
-
close
()¶ Maildir
instances do not keep any open files and the underlying mailboxes do not support locking, so this method does nothing.
-
get_file
(key)¶ Залежно від хост-платформи може бути неможливо змінити або видалити базове повідомлення, поки повернутий файл залишається відкритим.
-
Дивись також
- maildir man page from Courier
Специфікація формату. Описує загальне розширення для підтримки папок.
- Використання формату maildir
Нотатки про Maildir від його винахідника. Включає оновлену схему створення імен і подробиці семантики «info».
mbox
¶
-
class
mailbox.
mbox
(path, factory=None, create=True)¶ Підклас
Mailbox
для поштових скриньок у форматі mbox. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значенняNone
,mboxMessage
використовується як типове представлення повідомлення. Якщо create має значенняTrue
, поштова скринька буде створена, якщо вона не існує.Формат mbox є класичним форматом для зберігання пошти в системах Unix. Усі повідомлення в поштовій скриньці mbox зберігаються в одному файлі, початок кожного повідомлення позначається рядком, перші п’ять символів якого є «Від».
Several variations of the mbox format exist to address perceived shortcomings in the original. In the interest of compatibility,
mbox
implements the original format, which is sometimes referred to as mboxo. This means that the Content-Length header, if present, is ignored and that any occurrences of «From » at the beginning of a line in a message body are transformed to «>From » when storing the message, although occurrences of «>From » are not transformed to «From » when reading the message.Some
Mailbox
methods implemented bymbox
deserve special remarks:
Дивись також
- сторінка довідки mbox з tin
Специфікація формату з деталями щодо блокування.
- Налаштування Netscape Mail в Unix: Чому формат довжини вмісту поганий
Аргумент для використання оригінального формату mbox, а не варіації.
- «mbox» - це сімейство з кількох взаємно несумісних форматів поштових скриньок
Історія різновидів mbox.
MH
¶
-
class
mailbox.
MH
(path, factory=None, create=True)¶ Підклас
Mailbox
для поштових скриньок у форматі MH. Параметр factory — це викликаючий об’єкт, який приймає файлоподібне представлення повідомлення (яке поводиться так, ніби відкрито в двійковому режимі) і повертає спеціальне представлення. Якщо factory має значенняNone
,MHMessage
використовується як типове представлення повідомлення. Якщо create має значенняTrue
, поштова скринька буде створена, якщо вона не існує.MH — це формат поштової скриньки на основі каталогу, створений для системи обробки повідомлень MH, агента користувача електронної пошти. Кожне повідомлення в поштовій скриньці MH зберігається в окремому файлі. Крім повідомлень, поштова скринька MH може містити інші поштові скриньки MH (так звані folders). Папки можуть бути вкладеними нескінченно довго. Поштові скриньки MH також підтримують sequences, які є іменованими списками, які використовуються для логічного групування повідомлень без їх переміщення до підпапок. Послідовності визначено у файлі під назвою
.mh_sequences
у кожній папці.The
MH
class manipulates MH mailboxes, but it does not attempt to emulate all of mh’s behaviors. In particular, it does not modify and is not affected by thecontext
or.mh_profile
files that are used by mh to store its state and configuration.MH
instances have all of the methods ofMailbox
in addition to the following:-
list_folders
()¶ Повернути список імен усіх папок.
-
get_folder
(folder)¶ Return an
MH
instance representing the folder whose name is folder. ANoSuchMailboxError
exception is raised if the folder does not exist.
-
remove_folder
(folder)¶ Видаліть папку з назвою папка. Якщо папка містить будь-які повідомлення, буде викликано виняток
NotEmptyError
і папку не буде видалено.
-
get_sequences
()¶ Повертає словник імен послідовностей, зіставлених зі списками ключів. Якщо послідовностей немає, повертається порожній словник.
-
set_sequences
(sequences)¶ Повторно визначте послідовності, які існують у поштовій скриньці, на основі sequences, словника імен, зіставлених зі списками ключів, як повертає
get_sequences()
.
-
pack
()¶ Перейменуйте повідомлення в поштовій скриньці за потреби, щоб усунути прогалини в нумерації. Записи в списку послідовностей оновлюються відповідно.
Примітка
Уже видані ключі стають недійсними під час цієї операції та не повинні використовуватися згодом.
Some
Mailbox
methods implemented byMH
deserve special remarks:-
remove
(key)¶ -
__delitem__
(key)¶ -
discard
(key)¶ Ці методи негайно видаляють повідомлення. Угода MH про позначення повідомлення для видалення шляхом додавання коми перед його назвою не використовується.
-
lock
()¶ -
unlock
()¶ Three locking mechanisms are used—dot locking and, if available, the
flock()
andlockf()
system calls. For MH mailboxes, locking the mailbox means locking the.mh_sequences
file and, only for the duration of any operations that affect them, locking individual message files.
-
get_file
(key)¶ Залежно від хост-платформи може бути неможливо видалити базове повідомлення, поки повернутий файл залишається відкритим.
-
flush
()¶ Усі зміни до поштових скриньок MH негайно застосовуються, тому цей метод нічого не робить.
-
Дивись також
- nmh - Message Handling System
Домашня сторінка 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 також має супровідний список labels або коротких рядків, які записують додаткову інформацію про повідомлення, а список усіх визначених користувачем міток, знайдених у поштовій скриньці, зберігається в розділі параметрів Babyl .
Babyl
instances have all of the methods ofMailbox
in addition to the following:-
get_labels
()¶ Повертає список імен усіх визначених користувачем міток, які використовуються в поштовій скриньці.
Примітка
Фактичні повідомлення перевіряються, щоб визначити, які мітки існують у поштовій скриньці, замість перегляду списку міток у розділі параметрів Babyl, але розділ Babyl оновлюється щоразу, коли поштова скринька змінюється.
Some
Mailbox
methods implemented byBabyl
deserve special remarks:-
get_file
(key)¶ У поштових скриньках Babyl заголовки повідомлення не зберігаються поруч із тілом повідомлення. Щоб створити файлоподібне представлення, заголовки та тіло копіюються разом у екземпляр
io.BytesIO
, який має API, ідентичний API файлу. Як наслідок, файлоподібний об’єкт справді не залежить від базової поштової скриньки, але не економить пам’ять у порівнянні з представленням рядків.
-
Дивись також
- Формат файлів 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, початок кожного повідомлення позначається рядком, перші п’ять символів якого є «Від», але додаткові входження «Від» не перетворюються на «>Від» під час зберігання повідомлень, оскільки додаткові рядки-роздільники повідомлень запобігають помилково приймаючи такі випадки за початок наступних повідомлень.Some
Mailbox
methods implemented byMMDF
deserve special remarks:
Дивись також
- сторінка довідки mmdf з tin
Специфікація формату MMDF із документації tin, читання новин.
- MMDF
Стаття у Вікіпедії, що описує багатоканальний засіб розповсюдження меморандумів.
Message
objects¶
-
class
mailbox.
Message
(message=None)¶ A subclass of the
email.message
module’sMessage
. Subclasses ofmailbox.Message
add mailbox-format-specific state and behavior.If message is omitted, the new instance is created in a default, empty state. If message is an
email.message.Message
instance, its contents are copied; furthermore, any format-specific information is converted insofar as possible if message is aMessage
instance. If message is a string, a byte string, or a file, it should contain an RFC 2822-compliant message, which is read and parsed. Files should be open in binary mode, but text mode files are accepted for backward compatibility.Специфічний для формату стан і поведінка, запропоновані підкласами, відрізняються, але загалом підтримуються лише ті властивості, які не є специфічними для конкретної поштової скриньки (хоча, імовірно, властивості є специфічними для певного формату поштової скриньки). Наприклад, зміщення файлів для однофайлових форматів поштової скриньки та імена файлів для форматів поштової скриньки на основі каталогу не зберігаються, оскільки вони застосовуються лише до оригінальної поштової скриньки. Але інформація про те, чи було повідомлення прочитано користувачем або позначено як важливе, зберігається, оскільки воно стосується самого повідомлення.
There is no requirement that
Message
instances be used to represent messages retrieved usingMailbox
instances. In some situations, the time and memory required to generateMessage
representations might not be acceptable. For such situations,Mailbox
instances also offer string and file-like representations, and a custom message factory may be specified when aMailbox
instance is initialized.
MaildirMessage
¶
-
class
mailbox.
MaildirMessage
(message=None)¶ Повідомлення зі специфічною поведінкою Maildir. Параметр message має те саме значення, що й у конструкторі
Message
.Як правило, програма поштового агента користувача переміщує всі повідомлення з підкаталогу
new
до підкаталогуcur
після того, як користувач вперше відкриває та закриває поштову скриньку, записуючи, що повідомлення є старими незалежно від того чи вони насправді не були прочитані. Кожне повідомлення вcur
має розділ «info», доданий до імені файлу для зберігання інформації про його стан. (Деякі програми для читання пошти також можуть додавати розділ «info» до повідомлень уnew
.) Розділ «info» може мати одну з двох форм: він може містити «2», після якого йде список стандартизованих позначок ( наприклад, «2,FR») або може містити «1», за яким слідує так звана експериментальна інформація. Стандартні позначки для повідомлень Maildir такі:Прапор
Значення
Пояснення
Д
Чернетка
Під композицією
Ф
Позначено
Позначено як важливе
П
Пройшов
Переслано, повторно надіслано або відхилено
Р
Відповів
Відповів
С
Бачив
Прочитайте
Т
У кошик
Позначено для подальшого видалення
MaildirMessage
instances offer the following methods:-
get_subdir
()¶ Повертає або «новий» (якщо повідомлення має зберігатися в підкаталозі
new
), або «cur» (якщо повідомлення має зберігатися в підкаталозіcur
).Примітка
A message is typically moved from
new
tocur
after its mailbox has been accessed, whether or not the message is has been read. A messagemsg
has been read if"S" in msg.get_flags()
isTrue
.
-
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 може бути рядком із кількох символів. Поточна «інформація» перезаписується незалежно від того, чи містить вона експериментальну інформацію, а не прапорці.
-
remove_flag
(flag)¶ Скасувати прапор(и), визначені flag, не змінюючи інші прапори. Щоб видалити кілька прапорців одночасно, flag може бути рядком із кількох символів. Якщо «info» містить експериментальну інформацію, а не прапорці, поточна «info» не змінюється.
-
get_date
()¶ Повертає дату доставки повідомлення як число з плаваючою комою, яке представляє секунди з епохи.
-
set_date
(date)¶ Встановіть дату доставки повідомлення на date, число з плаваючою комою, яке представляє секунди з епохи.
-
get_info
()¶ Повертає рядок, що містить «інформацію» про повідомлення. Це корисно для доступу та модифікації «інформації», яка є експериментальною (тобто не списку позначок).
-
set_info
(info)¶ Встановіть для «info» значення info, яке має бути рядком.
-
When a MaildirMessage
instance is created based upon an
mboxMessage
or MMDFMessage
instance, the Status
and X-Status headers are omitted and the following conversions
take place:
Результуючий стан |
стан |
---|---|
підкаталог «cur». |
О прапор |
Прапор F |
Прапор F |
Прапор R |
Прапор |
S прапор |
Прапор R |
Т прапор |
D прапор |
When a MaildirMessage
instance is created based upon an
MHMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
підкаталог «cur». |
«невидима» послідовність |
підкаталог «cur» і прапор S |
немає «невидимої» послідовності |
Прапор F |
«позначена» послідовність |
Прапор R |
послідовність «відповів». |
When a MaildirMessage
instance is created based upon a
BabylMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
підкаталог «cur». |
ярлик «невидимий». |
підкаталог «cur» і прапор S |
немає мітки «невидиме». |
P прапор |
мітка «переслано» або «повторно надіслано». |
Прапор R |
мітка «відповів». |
Т прапор |
ярлик «видалено». |
mboxMessage
¶
-
class
mailbox.
mboxMessage
(message=None)¶ Повідомлення зі специфічною поведінкою mbox. Параметр message має те саме значення, що й у конструкторі
Message
.Повідомлення в поштовій скриньці mbox зберігаються разом в одному файлі. Адреса конверта відправника та час доставки зазвичай зберігаються в рядку, що починається на «Від», який використовується для позначення початку повідомлення, хоча існують значні відмінності в точному форматі цих даних серед реалізацій mbox. Прапорці, які вказують на стан повідомлення, наприклад, чи було воно прочитано чи позначено як важливе, зазвичай зберігаються в заголовках Status і X-Status.
Звичайні позначки для повідомлень mbox такі:
Прапор
Значення
Пояснення
Р
Прочитайте
Прочитайте
О
Старий
Раніше виявлено MUA
Д
Видалено
Позначено для подальшого видалення
Ф
Позначено
Позначено як важливе
А
відповів
Відповів
Прапорці «R» і «O» зберігаються в заголовку Status, а прапорці «D», «F» і «A» зберігаються в заголовку X-Status. Прапорці та заголовки зазвичай з’являються у зазначеному порядку.
mboxMessage
instances offer the following methods:-
get_from
()¶ Повертає рядок, що представляє рядок «Від», який позначає початок повідомлення в поштовій скриньці mbox. Початковий «Від» і кінцевий символ нового рядка виключаються.
-
set_from
(from_, time_=None)¶ Set the «From » line to from_, which should be specified without a leading «From » or trailing newline. For convenience, time_ may be specified and will be formatted appropriately and appended to from_. If time_ is specified, it should be a
time.struct_time
instance, a tuple suitable for passing totime.strftime()
, orTrue
(to usetime.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 може бути рядком із кількох символів.
-
When an mboxMessage
instance is created based upon a
MaildirMessage
instance, a «From » line is generated based upon the
MaildirMessage
instance’s delivery date, and the following conversions
take place:
Результуючий стан |
|
---|---|
Прапор R |
S прапор |
О прапор |
підкаталог «cur». |
D прапор |
Т прапор |
Прапор F |
Прапор F |
Прапор |
Прапор R |
When an mboxMessage
instance is created based upon an
MHMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
Прапор R і прапор O |
немає «невидимої» послідовності |
О прапор |
«невидима» послідовність |
Прапор F |
«позначена» послідовність |
Прапор |
послідовність «відповів». |
When an mboxMessage
instance is created based upon a
BabylMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
Прапор R і прапор O |
немає мітки «невидиме». |
О прапор |
ярлик «невидимий». |
D прапор |
ярлик «видалено». |
Прапор |
мітка «відповів». |
When a Message
instance is created based upon an MMDFMessage
instance, the «From » line is copied and all flags directly correspond:
Результуючий стан |
|
---|---|
Прапор R |
Прапор R |
О прапор |
О прапор |
D прапор |
D прапор |
Прапор F |
Прапор F |
Прапор |
Прапор |
MHMessage
¶
-
class
mailbox.
MHMessage
(message=None)¶ Повідомлення зі специфічними для MH поведінками. Параметр message має те саме значення, що й у конструкторі
Message
.Повідомлення MH не підтримують позначки чи прапорці в традиційному розумінні, але вони підтримують послідовності, які є логічними групами довільних повідомлень. Деякі програми читання пошти (хоча не стандартні mh і nmh) використовують послідовності приблизно так само, як прапорці використовуються з іншими форматами, а саме:
Послідовність
Пояснення
невидимий
Не прочитано, але раніше виявлено MUA
відповів
Відповів
позначено
Позначено як важливе
MHMessage
instances offer the following methods:-
get_sequences
()¶ Повернути список імен послідовностей, які містять це повідомлення.
-
set_sequences
(sequences)¶ Встановіть список послідовностей, які включають це повідомлення.
-
add_sequence
(sequence)¶ Додайте послідовність до списку послідовностей, які містять це повідомлення.
-
remove_sequence
(sequence)¶ Видаліть послідовність зі списку послідовностей, які містять це повідомлення.
-
When an MHMessage
instance is created based upon a
MaildirMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
«невидима» послідовність |
немає прапора S |
послідовність «відповів». |
Прапор R |
«позначена» послідовність |
Прапор F |
When an MHMessage
instance is created based upon an
mboxMessage
or MMDFMessage
instance, the Status
and X-Status headers are omitted and the following conversions
take place:
Результуючий стан |
стан |
---|---|
«невидима» послідовність |
немає прапора R |
послідовність «відповів». |
Прапор |
«позначена» послідовність |
Прапор F |
When an MHMessage
instance is created based upon a
BabylMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
«невидима» послідовність |
ярлик «невидимий». |
послідовність «відповів». |
мітка «відповів». |
BabylMessage
¶
-
class
mailbox.
BabylMessage
(message=None)¶ Повідомлення з особливостями поведінки Babyl. Параметр message має те саме значення, що й у конструкторі
Message
.Певні мітки повідомлень, які називаються attributes, визначені угодою як такі, що мають спеціальні значення. Атрибути такі:
Мітка
Пояснення
невидимий
Не прочитано, але раніше виявлено MUA
видалено
Позначено для подальшого видалення
подано
Скопійовано в інший файл або поштову скриньку
відповів
Відповів
пересилається
Переслано
відредаговано
Змінено користувачем
обурюватися
Обурюватися
By default, Rmail displays only visible headers. The
BabylMessage
class, though, uses the original headers because they are more complete. Visible headers may be accessed explicitly if desired.BabylMessage
instances offer the following methods:-
get_labels
()¶ Повернути список міток у повідомленні.
-
set_labels
(labels)¶ Установіть список міток у повідомленні на мітки.
-
add_label
(label)¶ Додайте label до списку міток у повідомленні.
-
remove_label
(label)¶ Видаліть label зі списку міток у повідомленні.
-
get_visible
()¶ Return an
Message
instance whose headers are the message’s visible headers and whose body is empty.
-
set_visible
(visible)¶ Налаштуйте видимі заголовки повідомлення такими ж, як заголовки в повідомленні. Параметр visible має бути екземпляром
Message
, екземпляромemail.message.Message
, рядком або файлоподібним об’єктом (який має бути відкритий у текстовому режимі).
-
update_visible
()¶ When a
BabylMessage
instance’s original headers are modified, the visible headers are not automatically modified to correspond. This method updates the visible headers as follows: each visible header with a corresponding original header is set to the value of the original header, each visible header without a corresponding original header is removed, and any of Date, From, Reply-To, To, CC, and Subject that are present in the original headers but not the visible headers are added to the visible headers.
-
When a BabylMessage
instance is created based upon a
MaildirMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
ярлик «невидимий». |
немає прапора S |
ярлик «видалено». |
Т прапор |
мітка «відповів». |
Прапор R |
мітка «переслано». |
P прапор |
When a BabylMessage
instance is created based upon an
mboxMessage
or MMDFMessage
instance, the Status
and X-Status headers are omitted and the following conversions
take place:
Результуючий стан |
стан |
---|---|
ярлик «невидимий». |
немає прапора R |
ярлик «видалено». |
D прапор |
мітка «відповів». |
Прапор |
When a BabylMessage
instance is created based upon an
MHMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
ярлик «невидимий». |
«невидима» послідовність |
мітка «відповів». |
послідовність «відповів». |
MMDFMessage
¶
-
class
mailbox.
MMDFMessage
(message=None)¶ Повідомлення зі специфічною для MMDF поведінкою. Параметр message має те саме значення, що й у конструкторі
Message
.Як і повідомлення в поштовій скриньці mbox, повідомлення MMDF зберігаються з адресою відправника та датою доставки в початковому рядку, що починається з «Від». Подібним чином прапорці, які вказують на стан повідомлення, зазвичай зберігаються в заголовках Status і X-Status.
Звичайні позначки для повідомлень MMDF ідентичні прапорцям для повідомлень mbox і такі:
Прапор
Значення
Пояснення
Р
Прочитайте
Прочитайте
О
Старий
Раніше виявлено MUA
Д
Видалено
Позначено для подальшого видалення
Ф
Позначено
Позначено як важливе
А
відповів
Відповів
Прапорці «R» і «O» зберігаються в заголовку Status, а прапорці «D», «F» і «A» зберігаються в заголовку X-Status. Прапорці та заголовки зазвичай з’являються у зазначеному порядку.
MMDFMessage
instances offer the following methods, which are identical to those offered bymboxMessage
:-
get_from
()¶ Повертає рядок, що представляє рядок «Від», який позначає початок повідомлення в поштовій скриньці mbox. Початковий «Від» і кінцевий символ нового рядка виключаються.
-
set_from
(from_, time_=None)¶ Set the «From » line to from_, which should be specified without a leading «From » or trailing newline. For convenience, time_ may be specified and will be formatted appropriately and appended to from_. If time_ is specified, it should be a
time.struct_time
instance, a tuple suitable for passing totime.strftime()
, orTrue
(to usetime.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 може бути рядком із кількох символів.
-
When an MMDFMessage
instance is created based upon a
MaildirMessage
instance, a «From » line is generated based upon the
MaildirMessage
instance’s delivery date, and the following conversions
take place:
Результуючий стан |
|
---|---|
Прапор R |
S прапор |
О прапор |
підкаталог «cur». |
D прапор |
Т прапор |
Прапор F |
Прапор F |
Прапор |
Прапор R |
When an MMDFMessage
instance is created based upon an
MHMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
Прапор R і прапор O |
немає «невидимої» послідовності |
О прапор |
«невидима» послідовність |
Прапор F |
«позначена» послідовність |
Прапор |
послідовність «відповів». |
When an MMDFMessage
instance is created based upon a
BabylMessage
instance, the following conversions take place:
Результуючий стан |
|
---|---|
Прапор R і прапор O |
немає мітки «невидиме». |
О прапор |
ярлик «невидимий». |
D прапор |
ярлик «видалено». |
Прапор |
мітка «відповів». |
When an MMDFMessage
instance is created based upon an
mboxMessage
instance, the «From » line is copied and all flags directly
correspond:
Результуючий стан |
|
---|---|
Прапор R |
Прапор R |
О прапор |
О прапор |
D прапор |
D прапор |
Прапор F |
Прапор F |
Прапор |
Прапор |
Винятки¶
The following exception classes are defined in the mailbox
module:
-
exception
mailbox.
Error
¶ Основний клас для всіх інших винятків, специфічних для модуля.
-
exception
mailbox.
NoSuchMailboxError
¶ Викликається, коли поштова скринька очікується, але не знайдена, наприклад, під час створення екземпляра підкласу
Mailbox
із шляхом, якого не існує (і з параметром create, встановленим наFalse
), або під час відкриття папку, яка не існує.
-
exception
mailbox.
NotEmptyError
¶ Викликається, коли поштова скринька не порожня, але очікується, що вона буде порожньою, наприклад, під час видалення папки, яка містить повідомлення.
-
exception
mailbox.
ExternalClashError
¶ Raised when some mailbox-related condition beyond the control of the program causes it to be unable to proceed, such as when failing to acquire a lock that another program already holds a lock, or when a uniquely-generated file name already exists.
Приклади¶
Простий приклад друку тем усіх повідомлень у поштовій скриньці, які здаються цікавими:
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()