email — pakiet obsługi e-mail oraz MIME

kod źródłowy:. Lib/email/__init__.py

Pakiet email jest biblioteką do zarządzania wiadomościami e-mail. Nie jest on specjalnie zaprojektowany do wysyłania wiadomości e-mail do SMTP (RFC 2821), NNTP lub innych serwerów; służą do tego to funkcje modułów takich jak smtplib i nntplib. Pakiet email stara się być jak najbardziej zgodny z RFC, wspierając RFC 5322 i RFC 6532, a także takie RFC związane z MIME, jak RFC 2045, RFC 2046, RFC 2047, RFC 2183 i RFC 2231.

Ogólna struktura pakietu email może zostać podzielona na trzy główne komponenty, plus czwarty komponent, który kontroluje zachowanie pozostałych komponentów.

Centralnym komponentem pakietu jest „model obiektowy”, który reprezentuje wiadomości e-mail. Aplikacja wchodzi w interakcję z pakietem głównie poprzez model obiektowy interfejsu zdefiniowanego w pod-module message . Aplikacja może używać tego API do zadawania pytań dotyczących istniejącego e-mail, do konstruowania nowego e-mail lub do dodawania lub usuwania e-mail pod-komponentów, które same używają tego samego interfejsu modelu obiektowego. Oznacza to, że zgodnie z naturą wiadomości e-mail i ich podkomponentów MIME, model obiektowy e-mail jest strukturą drzewiastą obiektów, które wszystkie zapewniają EmailMessage API .

Pozostałe dwa główne komponenty pakietu to parser i generator. Analizator składni pobiera zserializowaną wersję komunikatu e-mail (strumień bajtów) i przekształca go w drzewo obiektów EmailMessage. Generator pobiera EmailMessage i zamienia ją z powrotem w serializowany strumień bajtów. (Analizator składni i generator obsługują również strumienie znaków tekstowych, ale to użycie jest odradzane, ponieważ zbyt łatwo jest skończyć z wiadomościami, które nie są poprawne w jeden ani drugi sposób.)

The control component is the policy module. Every EmailMessage, every generator, and every parser has an associated policy object that controls its behavior. Usually an application only needs to specify the policy when an EmailMessage is created, either by directly instantiating an EmailMessage to create a new email, or by parsing an input stream using a parser. But the policy can be changed when the message is serialized using a generator. This allows, for example, a generic email message to be parsed from disk, but to serialize it using standard SMTP settings when sending it to an email server.

The email package does its best to hide the details of the various governing RFCs from the application. Conceptually the application should be able to treat the email message as a structured tree of unicode text and binary attachments, without having to worry about how these are represented when serialized. In practice, however, it is often necessary to be aware of at least some of the rules governing MIME messages and their structure, specifically the names and nature of the MIME „content types” and how they identify multipart documents. For the most part this knowledge should only be required for more complex applications, and even then it should only be the high level structure in question, and not the details of how those structures are represented. Since MIME content types are used widely in modern internet software (not just email), this will be a familiar concept to many programmers.

The following sections describe the functionality of the email package. We start with the message object model, which is the primary interface an application will use, and follow that with the parser and generator components. Then we cover the policy controls, which completes the treatment of the main components of the library.

The next three sections cover the exceptions the package may raise and the defects (non-compliance with the RFCs) that the parser may detect. Then we cover the headerregistry and the contentmanager sub-components, which provide tools for doing more detailed manipulation of headers and payloads, respectively. Both of these components contain features relevant to consuming and producing non-trivial messages, but also document their extensibility APIs, which will be of interest to advanced applications.

Following those is a set of examples of using the fundamental parts of the APIs covered in the preceding sections.

The foregoing represent the modern (unicode friendly) API of the email package. The remaining sections, starting with the Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The compat32 API does not hide the details of the RFCs from the application, but for applications that need to operate at that level, they can be useful tools. This documentation is also relevant for applications that are still using the compat32 API for backward compatibility reasons.

Zmienione w wersji 3.6: Docs reorganized and rewritten to promote the new EmailMessage/EmailPolicy API.

Contents of the email package documentation:

Legacy API:

Zobacz także

Module smtplib

SMTP (Simple Mail Transport Protocol) client

Module poplib

POP (Post Office Protocol) client

Module imaplib

IMAP (Internet Message Access Protocol) client

Module nntplib

NNTP (Net News Transport Protocol) client

Module mailbox

Tools for creating, reading, and managing collections of messages on disk using a variety standard formats.