Skip to content

C
cpython
Kaydet (Commit) 3f076d8b authored tarafından Georg Brandl's avatar Georg Brandl
Dosyalara gözat
Seçenekler

Use new optional argument style in email docs.

üst fe66fc12
Hide whitespace changes
Inline Side-by-side
Showing with 72 additions and 86 deletions
Doc/library/email.charset.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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.
......
Doc/library/email.generator.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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
......
Doc/library/email.header.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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.
Doc/library/email.iterators.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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.
Doc/library/email.message.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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
......
Doc/library/email.mime.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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`
......
Doc/library/email.parser.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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*
......
Doc/library/email.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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
......
Doc/library/email.util.rst
Dosyayı görüntüle @ 3f076d8b
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment