diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/email.charset.rst | 45 | ||||
| -rw-r--r-- | Doc/library/email.generator.rst | 6 | ||||
| -rw-r--r-- | Doc/library/email.header.rst | 26 | ||||
| -rw-r--r-- | Doc/library/email.iterators.rst | 8 | ||||
| -rw-r--r-- | Doc/library/email.message.rst | 31 | ||||
| -rw-r--r-- | Doc/library/email.mime.rst | 12 | ||||
| -rw-r--r-- | Doc/library/email.parser.rst | 14 | ||||
| -rw-r--r-- | Doc/library/email.rst | 4 | ||||
| -rw-r--r-- | Doc/library/email.util.rst | 12 |
9 files changed, 72 insertions, 86 deletions
diff --git a/Doc/library/email.charset.rst b/Doc/library/email.charset.rst index 1244615..d4b06fb 100644 --- a/Doc/library/email.charset.rst +++ b/Doc/library/email.charset.rst @@ -14,7 +14,7 @@ Instances of :class:`Charset` are used in several other modules within the Import this class from the :mod:`email.charset` module. -.. class:: Charset([input_charset]) +.. class:: Charset(input_charset=DEFAULT_CHARSET) Map character sets to their email properties. @@ -40,7 +40,6 @@ Import this class from the :mod:`email.charset` module. :class:`Charset` instances have the following data attributes: - .. attribute:: input_charset The initial character set specified. Common aliases are converted to @@ -66,10 +65,10 @@ Import this class from the :mod:`email.charset` module. .. attribute:: output_charset - Some character sets must be converted before they can be used in email headers - or bodies. If the *input_charset* is one of them, this attribute will - contain the name of the character set output will be converted to. Otherwise, it will - be ``None``. + Some character sets must be converted before they can be used in email + headers or bodies. If the *input_charset* is one of them, this attribute + will contain the name of the character set output will be converted to. + Otherwise, it will be ``None``. .. attribute:: input_codec @@ -85,8 +84,8 @@ Import this class from the :mod:`email.charset` module. *output_charset*. If no conversion codec is necessary, this attribute will have the same value as the *input_codec*. - :class:`Charset` instances also have the following methods: + :class:`Charset` instances also have the following methods: .. method:: get_body_encoding() @@ -102,13 +101,9 @@ Import this class from the :mod:`email.charset` module. returns the string ``base64`` if *body_encoding* is ``BASE64``, and returns the string ``7bit`` otherwise. + .. XXX to_splittable and from_splittable are not there anymore! - .. method:: convert(s) - - Convert the string *s* from the *input_codec* to the *output_codec*. - - - .. method:: to_splittable(s) + .. method to_splittable(s) Convert a possibly multibyte string to a safely splittable format. *s* is the string to split. @@ -123,7 +118,7 @@ Import this class from the :mod:`email.charset` module. the Unicode replacement character ``'U+FFFD'``. - .. method:: from_splittable(ustr[, to_output]) + .. method from_splittable(ustr[, to_output]) Convert a splittable string back into an encoded string. *ustr* is a Unicode string to "unsplit". @@ -153,29 +148,17 @@ Import this class from the :mod:`email.charset` module. quoted-printable or base64 encoding. - .. method:: header_encode(s[, convert]) + .. method:: header_encode(string) - Header-encode the string *s*. - - If *convert* is ``True``, the string will be converted from the input - charset to the output charset automatically. This is not useful for - multibyte character sets, which have line length issues (multibyte - characters must be split on a character, not a byte boundary); use the - higher-level :class:`~email.header.Header` class to deal with these issues - (see :mod:`email.header`). *convert* defaults to ``False``. + Header-encode the string *string*. The type of encoding (base64 or quoted-printable) will be based on the *header_encoding* attribute. - .. method:: body_encode(s[, convert]) - - Body-encode the string *s*. + .. method:: body_encode(string) - If *convert* is ``True`` (the default), the string will be converted from - the input charset to output charset automatically. Unlike - :meth:`header_encode`, there are no issues with byte boundaries and - multibyte charsets in email bodies, so this is usually pretty safe. + Body-encode the string *string*. The type of encoding (base64 or quoted-printable) will be based on the *body_encoding* attribute. @@ -205,7 +188,7 @@ The :mod:`email.charset` module also provides the following functions for adding new entries to the global character set, alias, and codec registries: -.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]]) +.. function:: add_charset(charset, header_enc=None, body_enc=None, output_charset=None) Add character properties to the global registry. diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst index 0f5788a..2061f76 100644 --- a/Doc/library/email.generator.rst +++ b/Doc/library/email.generator.rst @@ -23,7 +23,7 @@ Here are the public methods of the :class:`Generator` class, imported from the :mod:`email.generator` module: -.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]]) +.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78) The constructor for the :class:`Generator` class takes a file-like object called *outfp* for an argument. *outfp* must support the :meth:`write` method and be @@ -47,7 +47,7 @@ Here are the public methods of the :class:`Generator` class, imported from the The other public :class:`Generator` methods are: - .. method:: flatten(msg[, unixfrom]) + .. method:: flatten(msg, unixfrom=False) Print the textual representation of the message object structure rooted at *msg* to the output file specified when the :class:`Generator` instance @@ -84,7 +84,7 @@ except that non-\ :mimetype:`text` parts are substituted with a format string representing the part. -.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]]) +.. class:: DecodedGenerator(outfp[, mangle_from_=True, maxheaderlen=78, fmt=None) This class, derived from :class:`Generator` walks through all the subparts of a message. If the subpart is of main type :mimetype:`text`, then it prints the diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 5da1d95..1d530b2 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -46,7 +46,7 @@ header using the embedded ISO-8859-1 character. Here is the :class:`Header` class description: -.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]]) +.. class:: Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict') Create a MIME-compliant header that can contain strings in different character sets. @@ -70,14 +70,15 @@ Here is the :class:`Header` class description: for *header_name* is ``None``, meaning it is not taken into account for the first line of a long, split header. - Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace, - and is usually either a space or a hard tab character. This character will be - prepended to continuation lines. *continuation_ws* defaults to a single space character (" "). + Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding + whitespace, and is usually either a space or a hard tab character. This + character will be prepended to continuation lines. *continuation_ws* + defaults to a single space character. Optional *errors* is passed straight through to the :meth:`append` method. - .. method:: append(s[, charset[, errors]]) + .. method:: append(s, charset=None, errors='strict') Append the string *s* to the MIME header. @@ -103,7 +104,7 @@ Here is the :class:`Header` class description: :func:`ustr.encode` call, and defaults to "strict". - .. method:: encode([splitchars]) + .. method:: encode(splitchars=';, \\t', maxlinelen=None) Encode a message header into an RFC-compliant format, possibly wrapping long lines and encapsulating non-ASCII parts in base64 or quoted-printable @@ -111,10 +112,13 @@ Here is the :class:`Header` class description: split long ASCII lines on, in rough support of :rfc:`2822`'s *highest level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines. + *maxlinelen*, if given, overrides the instance's value for the maximum + line length. + + The :class:`Header` class also provides a number of methods to support standard operators and built-in functions. - .. method:: __str__() A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``. @@ -156,7 +160,7 @@ The :mod:`email.header` module also provides the following convenient functions. [('p\xf6stal', 'iso-8859-1')] -.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]]) +.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ') Create a :class:`Header` instance from a sequence of pairs as returned by :func:`decode_header`. @@ -165,7 +169,7 @@ The :mod:`email.header` module also provides the following convenient functions. pairs of the format ``(decoded_string, charset)`` where *charset* is the name of the character set. - This function takes one of those sequence of pairs and returns a :class:`Header` - instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in - the :class:`Header` constructor. + This function takes one of those sequence of pairs and returns a + :class:`Header` instance. Optional *maxlinelen*, *header_name*, and + *continuation_ws* are as in the :class:`Header` constructor. diff --git a/Doc/library/email.iterators.rst b/Doc/library/email.iterators.rst index f7ca9e4..6c35b79 100644 --- a/Doc/library/email.iterators.rst +++ b/Doc/library/email.iterators.rst @@ -10,7 +10,7 @@ Iterating over a message object tree is fairly easy with the useful higher level iterations over message object trees. -.. function:: body_line_iterator(msg[, decode]) +.. function:: body_line_iterator(msg, decode=False) This iterates over all the payloads in all the subparts of *msg*, returning the string payloads line-by-line. It skips over all the subpart headers, and it @@ -21,7 +21,7 @@ useful higher level iterations over message object trees. Optional *decode* is passed through to :meth:`Message.get_payload`. -.. function:: typed_subpart_iterator(msg[, maintype[, subtype]]) +.. function:: typed_subpart_iterator(msg, maintype='text', subtype=None) This iterates over all the subparts of *msg*, returning only those subparts that match the MIME type specified by *maintype* and *subtype*. @@ -37,7 +37,7 @@ The following function has been added as a useful debugging tool. It should *not* be considered part of the supported public interface for the package. -.. function:: _structure(msg[, fp[, level]]) +.. function:: _structure(msg, fp=None, level=0, include_default=False) Prints an indented representation of the content types of the message object structure. For example:: @@ -62,4 +62,4 @@ The following function has been added as a useful debugging tool. It should Optional *fp* is a file-like object to print the output to. It must be suitable for Python's :func:`print` function. *level* is used internally. - + *include_default*, if true, prints the default type as well. diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index 7f70898..93dda69 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -36,7 +36,7 @@ Here are the methods of the :class:`Message` class: The constructor takes no arguments. - .. method:: as_string([unixfrom]) + .. method:: as_string(unixfrom=False, maxheaderlen=0) Return the entire message flattened as a string. When optional *unixfrom* is ``True``, the envelope header is included in the returned string. @@ -88,7 +88,7 @@ Here are the methods of the :class:`Message` class: :meth:`set_payload` instead. - .. method:: get_payload([i[, decode]]) + .. method:: get_payload(i=None, decode=False) Return the current payload, which will be a list of :class:`Message` objects when :meth:`is_multipart` is ``True``, or a @@ -113,7 +113,7 @@ Here are the methods of the :class:`Message` class: *decode* is ``False``. - .. method:: set_payload(payload[, charset]) + .. method:: set_payload(payload, charset=None) Set the entire message object's payload to *payload*. It is the client's responsibility to ensure the payload invariants. Optional *charset* sets @@ -201,7 +201,8 @@ Here are the methods of the :class:`Message` class: .. method:: __delitem__(name) Delete all occurrences of the field with name *name* from the message's - headers. No exception is raised if the named field isn't present in the headers. + headers. No exception is raised if the named field isn't present in the + headers. .. method:: Message.__contains__(name) @@ -226,7 +227,7 @@ Here are the methods of the :class:`Message` class: values. - .. method:: get(name[, failobj]) + .. method:: get(name, failobj=None) Return the value of the named header field. This is identical to :meth:`__getitem__` except that optional *failobj* is returned if the @@ -235,7 +236,7 @@ Here are the methods of the :class:`Message` class: Here are some additional useful methods: - .. method:: get_all(name[, failobj]) + .. method:: get_all(name, failobj=None) Return a list of all the values for the field named *name*. If there are no such named headers in the message, *failobj* is returned (defaults to @@ -315,7 +316,7 @@ Here are the methods of the :class:`Message` class: :mailheader:`Content-Type` header. - .. method:: get_params([failobj[, header[, unquote]]]) + .. method:: get_params(failobj=None, header='content-type', unquote=True) Return the message's :mailheader:`Content-Type` parameters, as a list. The elements of the returned list are 2-tuples of key/value pairs, as @@ -330,7 +331,7 @@ Here are the methods of the :class:`Message` class: search instead of :mailheader:`Content-Type`. - .. method:: get_param(param[, failobj[, header[, unquote]]]) + .. method:: get_param(param, failobj=None, header='content-type', unquote=True) Return the value of the :mailheader:`Content-Type` header's parameter *param* as a string. If the message has no :mailheader:`Content-Type` @@ -363,7 +364,7 @@ Here are the methods of the :class:`Message` class: to ``False``. - .. method:: set_param(param, value[, header[, requote[, charset[, language]]]]) + .. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='') Set a parameter in the :mailheader:`Content-Type` header. If the parameter already exists in the header, its value will be replaced with @@ -381,7 +382,7 @@ Here are the methods of the :class:`Message` class: should be strings. - .. method:: del_param(param[, header[, requote]]) + .. method:: del_param(param, header='content-type', requote=True) Remove the given parameter completely from the :mailheader:`Content-Type` header. The header will be re-written in place without the parameter or @@ -390,7 +391,7 @@ Here are the methods of the :class:`Message` class: alternative to :mailheader:`Content-Type`. - .. method:: set_type(type[, header][, requote]) + .. method:: set_type(type, header='Content-Type', requote=True) Set the main type and subtype for the :mailheader:`Content-Type` header. *type* must be a string in the form :mimetype:`maintype/subtype`, @@ -406,7 +407,7 @@ Here are the methods of the :class:`Message` class: header is also added. - .. method:: get_filename([failobj]) + .. method:: get_filename(failobj=None) Return the value of the ``filename`` parameter of the :mailheader:`Content-Disposition` header of the message. If the header @@ -416,7 +417,7 @@ Here are the methods of the :class:`Message` class: unquoted as per :func:`email.utils.unquote`. - .. method:: get_boundary([failobj]) + .. method:: get_boundary(failobj=None) Return the value of the ``boundary`` parameter of the :mailheader:`Content-Type` header of the message, or *failobj* if either @@ -439,7 +440,7 @@ Here are the methods of the :class:`Message` class: have been present in the original :mailheader:`Content-Type` header. - .. method:: get_content_charset([failobj]) + .. method:: get_content_charset(failobj=None) Return the ``charset`` parameter of the :mailheader:`Content-Type` header, coerced to lower case. If there is no :mailheader:`Content-Type` header, or if @@ -449,7 +450,7 @@ Here are the methods of the :class:`Message` class: :class:`~email.charset.Charset` instance for the default encoding of the message body. - .. method:: get_charsets([failobj]) + .. method:: get_charsets(failobj=None) Return a list containing the character set names in the message. If the message is a :mimetype:`multipart`, then the list will contain one element diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst index 0214d56..703110a 100644 --- a/Doc/library/email.mime.rst +++ b/Doc/library/email.mime.rst @@ -57,7 +57,7 @@ Here are the classes: .. currentmodule:: email.mime.multipart -.. class:: MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]]) +.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_params) Module: :mod:`email.mime.multipart` @@ -82,7 +82,7 @@ Here are the classes: .. currentmodule:: email.mime.application -.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]]) +.. class:: MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, **_params) Module: :mod:`email.mime.application` @@ -105,7 +105,7 @@ Here are the classes: .. currentmodule:: email.mime.audio -.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]]) +.. class:: MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, **_params) Module: :mod:`email.mime.audio` @@ -131,7 +131,7 @@ Here are the classes: .. currentmodule:: email.mime.image -.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]]) +.. class:: MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, **_params) Module: :mod:`email.mime.image` @@ -158,7 +158,7 @@ Here are the classes: .. currentmodule:: email.mime.message -.. class:: MIMEMessage(_msg[, _subtype]) +.. class:: MIMEMessage(_msg, _subtype='rfc822') Module: :mod:`email.mime.message` @@ -174,7 +174,7 @@ Here are the classes: .. currentmodule:: email.mime.text -.. class:: MIMEText(_text[, _subtype[, _charset]]) +.. class:: MIMEText(_text, _subtype='plain', _charset='us-ascii') Module: :mod:`email.mime.text` diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst index ec2e71b..3de5c31 100644 --- a/Doc/library/email.parser.rst +++ b/Doc/library/email.parser.rst @@ -58,13 +58,12 @@ list of defects that it can find. Here is the API for the :class:`FeedParser`: -.. class:: FeedParser([_factory]) +.. class:: FeedParser(_factory=email.message.Message) Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument callable that will be called whenever a new message object is needed. It defaults to the :class:`email.message.Message` class. - .. method:: feed(data) Feed the :class:`FeedParser` some more data. *data* should be a string @@ -74,7 +73,6 @@ Here is the API for the :class:`FeedParser`: carriage return, newline, or carriage return and newline (they can even be mixed). - .. method:: close() Closing a :class:`FeedParser` completes the parsing of all previously fed @@ -96,7 +94,7 @@ as a string. :class:`HeaderParser` has the same API as the :class:`Parser` class. -.. class:: Parser([_class]) +.. class:: Parser(_class=email.message.Message, strict=None) The constructor for the :class:`Parser` class takes an optional argument *_class*. This must be a callable factory (such as a function or a class), and @@ -115,7 +113,7 @@ class. The other public :class:`Parser` methods are: - .. method:: parse(fp[, headersonly]) + .. method:: parse(fp, headersonly=False) Read all the data from the file-like object *fp*, parse the resulting text, and return the root message object. *fp* must support both the @@ -129,7 +127,7 @@ class. Optional *headersonly* is as with the :meth:`parse` method. - .. method:: parsestr(text[, headersonly]) + .. method:: parsestr(text, headersonly=False) Similar to the :meth:`parse` method, except it takes a string object instead of a file-like object. Calling this method on a string is exactly @@ -147,14 +145,14 @@ in the top-level :mod:`email` package namespace. .. currentmodule:: email -.. function:: message_from_string(s[, _class[, strict]]) +.. function:: message_from_string(s[, _class][, strict]) Return a message object structure from a string. This is exactly equivalent to ``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as with the :class:`Parser` class constructor. -.. function:: message_from_file(fp[, _class[, strict]]) +.. function:: message_from_file(fp[, _class][, strict]) Return a message object structure tree from an open file object. This is exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict* diff --git a/Doc/library/email.rst b/Doc/library/email.rst index a8cb8d7..d3f1908 100644 --- a/Doc/library/email.rst +++ b/Doc/library/email.rst @@ -2,8 +2,8 @@ =================================================== .. module:: email - :synopsis: Package supporting the parsing, manipulating, and generating email messages, - including MIME documents. + :synopsis: Package supporting the parsing, manipulating, and generating + email messages, including MIME documents. .. moduleauthor:: Barry A. Warsaw <barry@python.org> .. sectionauthor:: Barry A. Warsaw <barry@python.org> .. Copyright (C) 2001-2007 Python Software Foundation diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst index 49428f4..b02f4cd 100644 --- a/Doc/library/email.util.rst +++ b/Doc/library/email.util.rst @@ -84,7 +84,7 @@ There are several useful utilities provided in the :mod:`email.utils` module: about for common use. -.. function:: formatdate([timeval[, localtime][, usegmt]]) +.. function:: formatdate(timeval=None, localtime=False, usegmt=False) Returns a date string as per :rfc:`2822`, e.g.:: @@ -105,11 +105,11 @@ There are several useful utilities provided in the :mod:`email.utils` module: ``False``. -.. function:: make_msgid([idstring]) +.. function:: make_msgid(idstring=None) Returns a string suitable for an :rfc:`2822`\ -compliant - :mailheader:`Message-ID` header. Optional *idstring* if given, is a string used - to strengthen the uniqueness of the message id. + :mailheader:`Message-ID` header. Optional *idstring* if given, is a string + used to strengthen the uniqueness of the message id. .. function:: decode_rfc2231(s) @@ -117,7 +117,7 @@ There are several useful utilities provided in the :mod:`email.utils` module: Decode the string *s* according to :rfc:`2231`. -.. function:: encode_rfc2231(s[, charset[, language]]) +.. function:: encode_rfc2231(s, charset=None, language=None) Encode the string *s* according to :rfc:`2231`. Optional *charset* and *language*, if given is the character set name and language name to use. If @@ -125,7 +125,7 @@ There are several useful utilities provided in the :mod:`email.utils` module: is not, the string is encoded using the empty string for *language*. -.. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]]) +.. function:: collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii') When a header parameter is encoded in :rfc:`2231` format, :meth:`Message.get_param` may return a 3-tuple containing the character set, |