Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3f076d8

Browse files
birkenfeldbirkenfeld
committed
Use new optional argument style in email docs.
1 parent fe66fc1 commit 3f076d8

9 files changed

Lines changed: 72 additions & 86 deletions

‎Doc/library/email.charset.rst‎

Lines changed: 14 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Instances of :class:`Charset` are used in several other modules within the
1414
Import this class from the :mod:`email.charset` module.
1515

1616

17-
.. class:: Charset([input_charset])
17+
.. class:: Charset(input_charset=DEFAULT_CHARSET)
1818

1919
Map character sets to their email properties.
2020

@@ -40,7 +40,6 @@ Import this class from the :mod:`email.charset` module.
4040

4141
:class:`Charset` instances have the following data attributes:
4242

43-
4443
.. attribute:: input_charset
4544

4645
The initial character set specified. Common aliases are converted to
@@ -66,10 +65,10 @@ Import this class from the :mod:`email.charset` module.
6665

6766
.. attribute:: output_charset
6867

69-
Some character sets must be converted before they can be used in email headers
70-
or bodies. If the *input_charset* is one of them, this attribute will
71-
contain the name of the character set output will be converted to. Otherwise, it will
72-
be ``None``.
68+
Some character sets must be converted before they can be used in email
69+
headers or bodies. If the *input_charset* is one of them, this attribute
70+
will contain the name of the character set output will be converted to.
71+
Otherwise, it will be ``None``.
7372

7473

7574
.. attribute:: input_codec
@@ -85,8 +84,8 @@ Import this class from the :mod:`email.charset` module.
8584
*output_charset*. If no conversion codec is necessary, this attribute
8685
will have the same value as the *input_codec*.
8786

88-
:class:`Charset` instances also have the following methods:
8987

88+
:class:`Charset` instances also have the following methods:
9089

9190
.. method:: get_body_encoding()
9291

@@ -102,13 +101,9 @@ Import this class from the :mod:`email.charset` module.
102101
returns the string ``base64`` if *body_encoding* is ``BASE64``, and
103102
returns the string ``7bit`` otherwise.
104103

104+
.. XXX to_splittable and from_splittable are not there anymore!
105105
106-
.. method:: convert(s)
107-
108-
Convert the string *s* from the *input_codec* to the *output_codec*.
109-
110-
111-
.. method:: to_splittable(s)
106+
.. method to_splittable(s)
112107
113108
Convert a possibly multibyte string to a safely splittable format. *s* is
114109
the string to split.
@@ -123,7 +118,7 @@ Import this class from the :mod:`email.charset` module.
123118
the Unicode replacement character ``'U+FFFD'``.
124119
125120
126-
.. method:: from_splittable(ustr[, to_output])
121+
.. method from_splittable(ustr[, to_output])
127122
128123
Convert a splittable string back into an encoded string. *ustr* is a
129124
Unicode string to "unsplit".
@@ -153,29 +148,17 @@ Import this class from the :mod:`email.charset` module.
153148
quoted-printable or base64 encoding.
154149

155150

156-
.. method:: header_encode(s[, convert])
151+
.. method:: header_encode(string)
157152

158-
Header-encode the string *s*.
159-
160-
If *convert* is ``True``, the string will be converted from the input
161-
charset to the output charset automatically. This is not useful for
162-
multibyte character sets, which have line length issues (multibyte
163-
characters must be split on a character, not a byte boundary); use the
164-
higher-level :class:`~email.header.Header` class to deal with these issues
165-
(see :mod:`email.header`). *convert* defaults to ``False``.
153+
Header-encode the string *string*.
166154

167155
The type of encoding (base64 or quoted-printable) will be based on the
168156
*header_encoding* attribute.
169157

170158

171-
.. method:: body_encode(s[, convert])
172-
173-
Body-encode the string *s*.
159+
.. method:: body_encode(string)
174160

175-
If *convert* is ``True`` (the default), the string will be converted from
176-
the input charset to output charset automatically. Unlike
177-
:meth:`header_encode`, there are no issues with byte boundaries and
178-
multibyte charsets in email bodies, so this is usually pretty safe.
161+
Body-encode the string *string*.
179162

180163
The type of encoding (base64 or quoted-printable) will be based on the
181164
*body_encoding* attribute.
@@ -205,7 +188,7 @@ The :mod:`email.charset` module also provides the following functions for adding
205188
new entries to the global character set, alias, and codec registries:
206189

207190

208-
.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
191+
.. function:: add_charset(charset, header_enc=None, body_enc=None, output_charset=None)
209192

210193
Add character properties to the global registry.
211194

‎Doc/library/email.generator.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Here are the public methods of the :class:`Generator` class, imported from the
2323
:mod:`email.generator` module:
2424

2525

26-
.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
26+
.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78)
2727

2828
The constructor for the :class:`Generator` class takes a file-like object called
2929
*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
4747
The other public :class:`Generator` methods are:
4848

4949

50-
.. method:: flatten(msg[, unixfrom])
50+
.. method:: flatten(msg, unixfrom=False)
5151

5252
Print the textual representation of the message object structure rooted at
5353
*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
8484
representing the part.
8585

8686

87-
.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
87+
.. class:: DecodedGenerator(outfp[, mangle_from_=True, maxheaderlen=78, fmt=None)
8888

8989
This class, derived from :class:`Generator` walks through all the subparts of a
9090
message. If the subpart is of main type :mimetype:`text`, then it prints the

‎Doc/library/email.header.rst‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ header using the embedded ISO-8859-1 character.
4646
Here is the :class:`Header` class description:
4747

4848

49-
.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
49+
.. class:: Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')
5050

5151
Create a MIME-compliant header that can contain strings in different character
5252
sets.
@@ -70,14 +70,15 @@ Here is the :class:`Header` class description:
7070
for *header_name* is ``None``, meaning it is not taken into account for the
7171
first line of a long, split header.
7272

73-
Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
74-
and is usually either a space or a hard tab character. This character will be
75-
prepended to continuation lines. *continuation_ws* defaults to a single space character (" ").
73+
Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding
74+
whitespace, and is usually either a space or a hard tab character. This
75+
character will be prepended to continuation lines. *continuation_ws*
76+
defaults to a single space character.
7677

7778
Optional *errors* is passed straight through to the :meth:`append` method.
7879

7980

80-
.. method:: append(s[, charset[, errors]])
81+
.. method:: append(s, charset=None, errors='strict')
8182

8283
Append the string *s* to the MIME header.
8384

@@ -103,18 +104,21 @@ Here is the :class:`Header` class description:
103104
:func:`ustr.encode` call, and defaults to "strict".
104105

105106

106-
.. method:: encode([splitchars])
107+
.. method:: encode(splitchars=';, \\t', maxlinelen=None)
107108

108109
Encode a message header into an RFC-compliant format, possibly wrapping
109110
long lines and encapsulating non-ASCII parts in base64 or quoted-printable
110111
encodings. Optional *splitchars* is a string containing characters to
111112
split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
112113
level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines.
113114

115+
*maxlinelen*, if given, overrides the instance's value for the maximum
116+
line length.
117+
118+
114119
The :class:`Header` class also provides a number of methods to support
115120
standard operators and built-in functions.
116121

117-
118122
.. method:: __str__()
119123

120124
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.
156160
[('p\xf6stal', 'iso-8859-1')]
157161

158162

159-
.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
163+
.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
160164

161165
Create a :class:`Header` instance from a sequence of pairs as returned by
162166
:func:`decode_header`.
@@ -165,7 +169,7 @@ The :mod:`email.header` module also provides the following convenient functions.
165169
pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
166170
the character set.
167171

168-
This function takes one of those sequence of pairs and returns a :class:`Header`
169-
instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
170-
the :class:`Header` constructor.
172+
This function takes one of those sequence of pairs and returns a
173+
:class:`Header` instance. Optional *maxlinelen*, *header_name*, and
174+
*continuation_ws* are as in the :class:`Header` constructor.
171175

‎Doc/library/email.iterators.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Iterating over a message object tree is fairly easy with the
1010
useful higher level iterations over message object trees.
1111

1212

13-
.. function:: body_line_iterator(msg[, decode])
13+
.. function:: body_line_iterator(msg, decode=False)
1414

1515
This iterates over all the payloads in all the subparts of *msg*, returning the
1616
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.
2121
Optional *decode* is passed through to :meth:`Message.get_payload`.
2222

2323

24-
.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
24+
.. function:: typed_subpart_iterator(msg, maintype='text', subtype=None)
2525

2626
This iterates over all the subparts of *msg*, returning only those subparts that
2727
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
3737
*not* be considered part of the supported public interface for the package.
3838

3939

40-
.. function:: _structure(msg[, fp[, level]])
40+
.. function:: _structure(msg, fp=None, level=0, include_default=False)
4141

4242
Prints an indented representation of the content types of the message object
4343
structure. For example::
@@ -62,4 +62,4 @@ The following function has been added as a useful debugging tool. It should
6262

6363
Optional *fp* is a file-like object to print the output to. It must be
6464
suitable for Python's :func:`print` function. *level* is used internally.
65-
65+
*include_default*, if true, prints the default type as well.

‎Doc/library/email.message.rst‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Here are the methods of the :class:`Message` class:
3636
The constructor takes no arguments.
3737

3838

39-
.. method:: as_string([unixfrom])
39+
.. method:: as_string(unixfrom=False, maxheaderlen=0)
4040

4141
Return the entire message flattened as a string. When optional *unixfrom*
4242
is ``True``, the envelope header is included in the returned string.
@@ -88,7 +88,7 @@ Here are the methods of the :class:`Message` class:
8888
:meth:`set_payload` instead.
8989

9090

91-
.. method:: get_payload([i[, decode]])
91+
.. method:: get_payload(i=None, decode=False)
9292

9393
Return the current payload, which will be a list of
9494
:class:`Message` objects when :meth:`is_multipart` is ``True``, or a
@@ -113,7 +113,7 @@ Here are the methods of the :class:`Message` class:
113113
*decode* is ``False``.
114114

115115

116-
.. method:: set_payload(payload[, charset])
116+
.. method:: set_payload(payload, charset=None)
117117

118118
Set the entire message object's payload to *payload*. It is the client's
119119
responsibility to ensure the payload invariants. Optional *charset* sets
@@ -201,7 +201,8 @@ Here are the methods of the :class:`Message` class:
201201
.. method:: __delitem__(name)
202202

203203
Delete all occurrences of the field with name *name* from the message's
204-
headers. No exception is raised if the named field isn't present in the headers.
204+
headers. No exception is raised if the named field isn't present in the
205+
headers.
205206

206207

207208
.. method:: Message.__contains__(name)
@@ -226,7 +227,7 @@ Here are the methods of the :class:`Message` class:
226227
values.
227228

228229

229-
.. method:: get(name[, failobj])
230+
.. method:: get(name, failobj=None)
230231

231232
Return the value of the named header field. This is identical to
232233
:meth:`__getitem__` except that optional *failobj* is returned if the
@@ -235,7 +236,7 @@ Here are the methods of the :class:`Message` class:
235236
Here are some additional useful methods:
236237

237238

238-
.. method:: get_all(name[, failobj])
239+
.. method:: get_all(name, failobj=None)
239240

240241
Return a list of all the values for the field named *name*. If there are
241242
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:
315316
:mailheader:`Content-Type` header.
316317

317318

318-
.. method:: get_params([failobj[, header[, unquote]]])
319+
.. method:: get_params(failobj=None, header='content-type', unquote=True)
319320

320321
Return the message's :mailheader:`Content-Type` parameters, as a list.
321322
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:
330331
search instead of :mailheader:`Content-Type`.
331332

332333

333-
.. method:: get_param(param[, failobj[, header[, unquote]]])
334+
.. method:: get_param(param, failobj=None, header='content-type', unquote=True)
334335

335336
Return the value of the :mailheader:`Content-Type` header's parameter
336337
*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:
363364
to ``False``.
364365

365366

366-
.. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
367+
.. method:: set_param(param, value, header='Content-Type', requote=True, charset=None, language='')
367368

368369
Set a parameter in the :mailheader:`Content-Type` header. If the
369370
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:
381382
should be strings.
382383

383384

384-
.. method:: del_param(param[, header[, requote]])
385+
.. method:: del_param(param, header='content-type', requote=True)
385386

386387
Remove the given parameter completely from the :mailheader:`Content-Type`
387388
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:
390391
alternative to :mailheader:`Content-Type`.
391392

392393

393-
.. method:: set_type(type[, header][, requote])
394+
.. method:: set_type(type, header='Content-Type', requote=True)
394395

395396
Set the main type and subtype for the :mailheader:`Content-Type`
396397
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:
406407
header is also added.
407408

408409

409-
.. method:: get_filename([failobj])
410+
.. method:: get_filename(failobj=None)
410411

411412
Return the value of the ``filename`` parameter of the
412413
:mailheader:`Content-Disposition` header of the message. If the header
@@ -416,7 +417,7 @@ Here are the methods of the :class:`Message` class:
416417
unquoted as per :func:`email.utils.unquote`.
417418

418419

419-
.. method:: get_boundary([failobj])
420+
.. method:: get_boundary(failobj=None)
420421

421422
Return the value of the ``boundary`` parameter of the
422423
:mailheader:`Content-Type` header of the message, or *failobj* if either
@@ -439,7 +440,7 @@ Here are the methods of the :class:`Message` class:
439440
have been present in the original :mailheader:`Content-Type` header.
440441

441442

442-
.. method:: get_content_charset([failobj])
443+
.. method:: get_content_charset(failobj=None)
443444

444445
Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
445446
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:
449450
:class:`~email.charset.Charset` instance for the default encoding of the message body.
450451

451452

452-
.. method:: get_charsets([failobj])
453+
.. method:: get_charsets(failobj=None)
453454

454455
Return a list containing the character set names in the message. If the
455456
message is a :mimetype:`multipart`, then the list will contain one element

0 commit comments

Comments
 (0)