Use new optional argument style in email docs.

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,