[Python-checkins] r72735 - in python/branches/py3k/Doc/library: email.charset.rst email.generator.rst email.header.rst email.iterators.rst email.message.rst email.mime.rst email.parser.rst email.rst email.util.rst
georg.brandl
python-checkins at python.org
Sun May 17 13:28:33 CEST 2009
Author: georg.brandl
Date: Sun May 17 13:28:33 2009
New Revision: 72735
Log:
Use new optional argument style in email docs.
Modified:
python/branches/py3k/Doc/library/email.charset.rst
python/branches/py3k/Doc/library/email.generator.rst
python/branches/py3k/Doc/library/email.header.rst
python/branches/py3k/Doc/library/email.iterators.rst
python/branches/py3k/Doc/library/email.message.rst
python/branches/py3k/Doc/library/email.mime.rst
python/branches/py3k/Doc/library/email.parser.rst
python/branches/py3k/Doc/library/email.rst
python/branches/py3k/Doc/library/email.util.rst
Modified: python/branches/py3k/Doc/library/email.charset.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.charset.rst (original)
+++ python/branches/py3k/Doc/library/email.charset.rst Sun May 17 13:28:33 2009
@@ -14,7 +14,7 @@
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 @@
: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 @@
.. 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 @@
*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 @@
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 @@
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 @@
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 @@
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.
Modified: python/branches/py3k/Doc/library/email.generator.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.generator.rst (original)
+++ python/branches/py3k/Doc/library/email.generator.rst Sun May 17 13:28:33 2009
@@ -23,7 +23,7 @@
: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 @@
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 @@
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
Modified: python/branches/py3k/Doc/library/email.header.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.header.rst (original)
+++ python/branches/py3k/Doc/library/email.header.rst Sun May 17 13:28:33 2009
@@ -46,7 +46,7 @@
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 @@
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 @@
: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 @@
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 @@
[('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 @@
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.
Modified: python/branches/py3k/Doc/library/email.iterators.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.iterators.rst (original)
+++ python/branches/py3k/Doc/library/email.iterators.rst Sun May 17 13:28:33 2009
@@ -10,7 +10,7 @@
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 @@
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 @@
*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 @@
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.
Modified: python/branches/py3k/Doc/library/email.message.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.message.rst (original)
+++ python/branches/py3k/Doc/library/email.message.rst Sun May 17 13:28:33 2009
@@ -36,7 +36,7 @@
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 @@
: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 @@
*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 @@
.. 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 @@
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 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 @@
: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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
: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
Modified: python/branches/py3k/Doc/library/email.mime.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.mime.rst (original)
+++ python/branches/py3k/Doc/library/email.mime.rst Sun May 17 13:28:33 2009
@@ -57,7 +57,7 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. currentmodule:: email.mime.message
-.. class:: MIMEMessage(_msg[, _subtype])
+.. class:: MIMEMessage(_msg, _subtype='rfc822')
Module: :mod:`email.mime.message`
@@ -174,7 +174,7 @@
.. currentmodule:: email.mime.text
-.. class:: MIMEText(_text[, _subtype[, _charset]])
+.. class:: MIMEText(_text, _subtype='plain', _charset='us-ascii')
Module: :mod:`email.mime.text`
Modified: python/branches/py3k/Doc/library/email.parser.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.parser.rst (original)
+++ python/branches/py3k/Doc/library/email.parser.rst Sun May 17 13:28:33 2009
@@ -58,13 +58,12 @@
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 @@
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 @@
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 @@
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 @@
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 @@
.. 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*
Modified: python/branches/py3k/Doc/library/email.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.rst (original)
+++ python/branches/py3k/Doc/library/email.rst Sun May 17 13:28:33 2009
@@ -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 at python.org>
.. sectionauthor:: Barry A. Warsaw <barry at python.org>
.. Copyright (C) 2001-2007 Python Software Foundation
Modified: python/branches/py3k/Doc/library/email.util.rst
==============================================================================
--- python/branches/py3k/Doc/library/email.util.rst (original)
+++ python/branches/py3k/Doc/library/email.util.rst Sun May 17 13:28:33 2009
@@ -84,7 +84,7 @@
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 @@
``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 @@
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 @@
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,
More information about the Python-checkins
mailing list