mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-15 21:44:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 12

Merge with main repo default branch.

Browse source
This commit is contained in:
Georg Brandl 2012-09-29 09:27:15 +02:00
commit 99a247fd01
150 changed files with 5492 additions and 4403 deletions
Download patch file Download diff file Expand all files Collapse all files

23
Doc/library/argparse.rst
View file

@ -130,9 +130,12 @@ command-line arguments from :data:`sys.argv`.
ArgumentParser objects
----------------------
.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], \
[argument_default], [parents], [prefix_chars], \
[conflict_handler], [formatter_class])
.. class:: ArgumentParser(prog=None, usage=None, description=None, \
epilog=None, parents=[], \
formatter_class=argparse.HelpFormatter, \
prefix_chars='-', fromfile_prefix_chars=None, \
argument_default=None, conflict_handler='error', \
add_help=True)
Create a new :class:`ArgumentParser` object. Each parameter has its own more
detailed description below, but in short they are:
@ -920,6 +923,17 @@ was not present at the command line::
>>> parser.parse_args(''.split())
Namespace(foo=42)
If the ``default`` value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type_
conversion argument, if provided, before setting the attribute on the
:class:`Namespace` return value. Otherwise, the parser uses the value as is::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
is used when no command-line argument was present::
@ -958,6 +972,9 @@ types and functions can be used directly as the value of the ``type`` argument::
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
See the section on the default_ keyword argument for information on when the
``type`` argument is applied to default arguments.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the
:func:`open` function. For example, ``FileType('w')`` can be used to create a

2
Doc/library/collections.rst
View file

@ -1012,7 +1012,7 @@ are deleted. But when new keys are added, the keys are appended
to the end and the sort is not maintained.
It is also straight-forward to create an ordered dictionary variant
that the remembers the order the keys were *last* inserted.
that remembers the order the keys were *last* inserted.
If a new entry overwrites an existing entry, the
original insertion position is changed and moved to the end::

19
Doc/library/configparser.rst
View file

@ -1007,7 +1007,7 @@ ConfigParser Objects
.. versionadded:: 3.2
.. method:: get(section, option, raw=False, [vars, fallback])
.. method:: get(section, option, *, raw=False, vars=None[, fallback])
Get an *option* value for the named *section*. If *vars* is provided, it
must be a dictionary. The *option* is looked up in *vars* (if provided),
@ -1025,21 +1025,21 @@ ConfigParser Objects
(especially when using the mapping protocol).
.. method:: getint(section, option, raw=False, [vars, fallback])
.. method:: getint(section, option, *, raw=False, vars=None[, fallback])
A convenience method which coerces the *option* in the specified *section*
to an integer. See :meth:`get` for explanation of *raw*, *vars* and
*fallback*.
.. method:: getfloat(section, option, raw=False, [vars, fallback])
.. method:: getfloat(section, option, *, raw=False, vars=None[, fallback])
A convenience method which coerces the *option* in the specified *section*
to a floating point number. See :meth:`get` for explanation of *raw*,
*vars* and *fallback*.
.. method:: getboolean(section, option, raw=False, [vars, fallback])
.. method:: getboolean(section, option, *, raw=False, vars=None[, fallback])
A convenience method which coerces the *option* in the specified *section*
to a Boolean value. Note that the accepted values for the option are
@ -1051,7 +1051,8 @@ ConfigParser Objects
*fallback*.
.. method:: items([section], raw=False, vars=None)
.. method:: items(raw=False, vars=None)
items(section, raw=False, vars=None)
When *section* is not given, return a list of *section_name*,
*section_proxy* pairs, including DEFAULTSECT.
@ -1149,7 +1150,13 @@ ConfigParser Objects
RawConfigParser Objects
-----------------------
.. class:: RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None)
.. class:: RawConfigParser(defaults=None, dict_type=collections.OrderedDict, \
allow_no_value=False, *, delimiters=('=', ':'), \
comment_prefixes=('#', ';'), \
inline_comment_prefixes=None, strict=True, \
empty_lines_in_values=True, \
default_section=configparser.DEFAULTSECT[, \
interpolation])
Legacy variant of the :class:`ConfigParser` with interpolation disabled
by default and unsafe ``add_section`` and ``set`` methods.

10
Doc/library/crypt.rst
View file

@ -121,11 +121,14 @@ The :mod:`crypt` module defines the following functions:
Examples
--------
A simple example illustrating typical use::
A simple example illustrating typical use (a constant-time comparison
operation is needed to limit exposure to timing attacks.
:func:`hmac.compare_digest` is suitable for this purpose)::
import pwd
import crypt
import getpass
from hmac import compare_digest as compare_hash
def login():
username = input('Python login: ')
@ -134,7 +137,7 @@ A simple example illustrating typical use::
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise ValueError('no support for shadow passwords')
cleartext = getpass.getpass()
return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
return compare_hash(crypt.crypt(cleartext, cryptedpasswd), cryptedpasswd)
else:
return True
@ -142,7 +145,8 @@ To generate a hash of a password using the strongest available method and
check it against the original::
import crypt
from hmac import compare_digest as compare_hash
hashed = crypt.crypt(plaintext)
if hashed != crypt.crypt(plaintext, hashed):
if not compare_hash(hashed, crypt.crypt(plaintext, hashed)):
raise ValueError("hashed version doesn't validate against original")

1
Doc/library/crypto.rst
View file

@ -8,6 +8,7 @@ Cryptographic Services
The modules described in this chapter implement various algorithms of a
cryptographic nature. They are available at the discretion of the installation.
On Unix systems, the :mod:`crypt` module may also be available.
Here's an overview:

28
Doc/library/csv.rst
View file

@ -71,9 +71,10 @@ The :mod:`csv` module defines the following functions:
A short usage example::
>>> import csv
>>> spamReader = csv.reader(open('eggs.csv', newline=''), delimiter=' ', quotechar='|')
>>> for row in spamReader:
... print(', '.join(row))
>>> with open('eggs.csv', newline='') as csvfile:
... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
... for row in spamreader:
... print(', '.join(row))
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam
@ -99,11 +100,12 @@ The :mod:`csv` module defines the following functions:
A short usage example::
>>> import csv
>>> spamWriter = csv.writer(open('eggs.csv', 'w', newline=''), delimiter=' ',
... quotechar='|', quoting=csv.QUOTE_MINIMAL)
>>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])
>>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
import csv
with open('eggs.csv', 'w', newline='') as csvfile:
spamwriter = csv.writer(csvfile, delimiter=' ',
quotechar='|', quoting=csv.QUOTE_MINIMAL)
spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
.. function:: register_dialect(name[, dialect], **fmtparams)
@ -221,11 +223,11 @@ The :mod:`csv` module defines the following classes:
An example for :class:`Sniffer` use::
csvfile = open("example.csv")
dialect = csv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = csv.reader(csvfile, dialect)
# ... process CSV file contents here ...
with open('example.csv') as csvfile:
dialect = csv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = csv.reader(csvfile, dialect)
# ... process CSV file contents here ...
The :mod:`csv` module defines the following constants:

46
Doc/library/curses.rst
View file

@ -377,7 +377,8 @@ The module :mod:`curses` defines the following functions:
is to be displayed.
.. function:: newwin([nlines, ncols,] begin_y, begin_x)
.. function:: newwin(begin_y, begin_x)
newwin(nlines, ncols, begin_y, begin_x)
Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, and
whose height/width is *nlines*/*ncols*.
@ -656,7 +657,8 @@ Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
the following methods and attributes:
.. method:: window.addch([y, x,] ch[, attr])
.. method:: window.addch(ch[, attr])
window.addch(y, x, ch[, attr])
.. note::
@ -670,13 +672,15 @@ the following methods and attributes:
position and attributes are the current settings for the window object.
.. method:: window.addnstr([y, x,] str, n[, attr])
.. method:: window.addnstr(str, n[, attr])
window.addnstr(y, x, str, n[, attr])
Paint at most *n* characters of the string *str* at ``(y, x)`` with attributes
*attr*, overwriting anything previously on the display.
.. method:: window.addstr([y, x,] str[, attr])
.. method:: window.addstr(str[, attr])
window.addstr(y, x, str[, attr])
Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
anything previously on the display.
@ -763,7 +767,10 @@ the following methods and attributes:
*bs* are *horch*. The default corner characters are always used by this function.
.. method:: window.chgat([y, x, ] [num,] attr)
.. method:: window.chgat(attr)
window.chgat(num, attr)
window.chgat(y, x, attr)
window.chgat(y, x, num, attr)
Set the attributes of *num* characters at the current cursor position, or at
position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
@ -812,7 +819,8 @@ the following methods and attributes:
Delete the line under the cursor. All following lines are moved up by one line.
.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
.. method:: window.derwin(begin_y, begin_x)
window.derwin(nlines, ncols, begin_y, begin_x)
An abbreviation for "derive window", :meth:`derwin` is the same as calling
:meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
@ -837,7 +845,7 @@ the following methods and attributes:
.. attribute:: window.encoding
Encoding used to encode method arguments (Unicode strings and characters).
The encoding attribute is inherited from by parent window when a subwindow
The encoding attribute is inherited from the parent window when a subwindow
is created, for example with :meth:`window.subwin`. By default, the locale
encoding is used (see :func:`locale.getpreferredencoding`).
@ -906,7 +914,8 @@ the following methods and attributes:
upper-left corner.
.. method:: window.hline([y, x,] ch, n)
.. method:: window.hline(ch, n)
window.hline(y, x, ch, n)
Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
the character *ch*.
@ -940,7 +949,8 @@ the following methods and attributes:
the character proper, and upper bits are the attributes.
.. method:: window.insch([y, x,] ch[, attr])
.. method:: window.insch(ch[, attr])
window.insch(y, x, ch[, attr])
Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
position *x* right by one character.
@ -961,7 +971,8 @@ the following methods and attributes:
line.
.. method:: window.insnstr([y, x,] str, n [, attr])
.. method:: window.insnstr(str, n[, attr])
window.insnstr(y, x, str, n[, attr])
Insert a character string (as many characters as will fit on the line) before
the character under the cursor, up to *n* characters. If *n* is zero or
@ -970,7 +981,8 @@ the following methods and attributes:
The cursor position does not change (after moving to *y*, *x*, if specified).
.. method:: window.insstr([y, x, ] str [, attr])
.. method:: window.insstr(str[, attr])
window.insstr(y, x, str[, attr])
Insert a character string (as many characters as will fit on the line) before
the character under the cursor. All characters to the right of the cursor are
@ -978,7 +990,8 @@ the following methods and attributes:
position does not change (after moving to *y*, *x*, if specified).
.. method:: window.instr([y, x] [, n])
.. method:: window.instr([n])
window.instr(y, x[, n])
Return a string of characters, extracted from the window starting at the
current cursor position, or at *y*, *x* if specified. Attributes are stripped
@ -1153,13 +1166,15 @@ the following methods and attributes:
Turn on attribute *A_STANDOUT*.
.. method:: window.subpad([nlines, ncols,] begin_y, begin_x)
.. method:: window.subpad(begin_y, begin_x)
window.subpad(nlines, ncols, begin_y, begin_x)
Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
whose width/height is *ncols*/*nlines*.
.. method:: window.subwin([nlines, ncols,] begin_y, begin_x)
.. method:: window.subwin(begin_y, begin_x)
window.subwin(nlines, ncols, begin_y, begin_x)
Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
whose width/height is *ncols*/*nlines*.
@ -1216,7 +1231,8 @@ the following methods and attributes:
:meth:`refresh`.
.. method:: window.vline([y, x,] ch, n)
.. method:: window.vline(ch, n)
window.vline(y, x, ch, n)
Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
character *ch*.

12
Doc/library/doctest.rst
View file

@ -338,7 +338,7 @@ The fine print:
Backslashes in a raw docstring: m\n
Otherwise, the backslash will be interpreted as part of the string. For example,
the "\\" above would be interpreted as a newline character. Alternatively, you
the ``\n`` above would be interpreted as a newline character. Alternatively, you
can double each backslash in the doctest version (and not use a raw string)::
>>> def f(x):
@ -1024,6 +1024,16 @@ from text files and modules with doctests:
This function uses the same search technique as :func:`testmod`.
.. note::
Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises
a :exc:`ValueError` if *module* contains no docstrings. You can prevent
this error by passing a :class:`DocTestFinder` instance as the
*test_finder* argument with its *exclude_empty* keyword argument set
to ``False``::
>>> finder = doctest.DocTestFinder(exclude_empty=False)
>>> suite = doctest.DocTestSuite(test_finder=finder)
Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a

75
Doc/library/functions.rst
View file

@ -629,14 +629,19 @@ are always available. They are listed here in alphabetical order.
to provide elaborate line editing and history features.
.. function:: int([number | string[, base]])
.. function:: int(x=0)
int(x, base=10)
Convert a number or string to an integer. If no arguments are given, return
``0``. If a number is given, return ``number.__int__()``. Conversion of
floating point numbers to integers truncates towards zero. A string must be
a base-radix integer literal optionally preceded by '+' or '-' (with no space
in between) and optionally surrounded by whitespace. A base-n literal
consists of the digits 0 to n-1, with 'a' to 'z' (or 'A' to 'Z') having
Convert a number or string *x* to an integer, or return ``0`` if no
arguments are given. If *x* is a number, return :meth:`x.__int__()
<object.__int__>`. For floating point numbers, this truncates towards zero.
If *x* is not a number or if *base* is given, then *x* must be a string,
:class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
literal <integers>` in radix *base*. Optionally, the literal can be
preceded by ``+`` or ``-`` (with no space in between) and surrounded by
whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
to ``z`` (or ``A`` to ``Z``) having
values 10 to 35. The default *base* is 10. The allowed values are 0 and 2-36.
Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code. Base 0
@ -725,11 +730,16 @@ are always available. They are listed here in alphabetical order.
already arranged into argument tuples, see :func:`itertools.starmap`\.
.. function:: max(iterable[, args...], *[, key])
.. function:: max(iterable, *[, key])
max(arg1, arg2, *args[, key])
With a single argument *iterable*, return the largest item of a non-empty
iterable (such as a string, tuple or list). With more than one argument, return
the largest of the arguments.
Return the largest item in an iterable or the largest of two or more
arguments.
If one positional argument is provided, *iterable* must be a non-empty
iterable (such as a non-empty string, tuple or list). The largest item
in the iterable is returned. If two or more positional arguments are
provided, the largest of the positional arguments is returned.
The optional keyword-only *key* argument specifies a one-argument ordering
function like that used for :meth:`list.sort`.
@ -748,11 +758,16 @@ are always available. They are listed here in alphabetical order.
:ref:`typememoryview` for more information.
.. function:: min(iterable[, args...], *[, key])
.. function:: min(iterable, *[, key])
min(arg1, arg2, *args[, key])
With a single argument *iterable*, return the smallest item of a non-empty
iterable (such as a string, tuple or list). With more than one argument, return
the smallest of the arguments.
Return the smallest item in an iterable or the smallest of two or more
arguments.
If one positional argument is provided, *iterable* must be a non-empty
iterable (such as a non-empty string, tuple or list). The smallest item
in the iterable is returned. If two or more positional arguments are
provided, the smallest of the positional arguments is returned.
The optional keyword-only *key* argument specifies a one-argument ordering
function like that used for :meth:`list.sort`.
@ -970,16 +985,16 @@ are always available. They are listed here in alphabetical order.
must be of integer types, and *y* must be non-negative.
.. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout, flush=False)
.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
Print *object*\(s) to the stream *file*, separated by *sep* and followed by
Print *objects* to the stream *file*, separated by *sep* and followed by
*end*. *sep*, *end* and *file*, if present, must be given as keyword
arguments.
All non-keyword arguments are converted to strings like :func:`str` does and
written to the stream, separated by *sep* and followed by *end*. Both *sep*
and *end* must be strings; they can also be ``None``, which means to use the
default values. If no *object* is given, :func:`print` will just write
default values. If no *objects* are given, :func:`print` will just write
*end*.
The *file* argument must be an object with a ``write(string)`` method; if it
@ -1061,7 +1076,8 @@ are always available. They are listed here in alphabetical order.
.. _func-range:
.. function:: range([start,] stop[, step])
.. function:: range(stop)
range(start, stop[, step])
:noindex:
Rather than being a function, :class:`range` is actually an immutable
@ -1087,18 +1103,18 @@ are always available. They are listed here in alphabetical order.
arguments starting at ``0``).
.. function:: round(x[, n])
.. function:: round(number[, ndigits])
Return the floating point value *x* rounded to *n* digits after the decimal
point. If *n* is omitted, it defaults to zero. Delegates to
``x.__round__(n)``.
Return the floating point value *number* rounded to *ndigits* digits after
the decimal point. If *ndigits* is omitted, it defaults to zero. Delegates
to ``number.__round__(ndigits)``.
For the built-in types supporting :func:`round`, values are rounded to the
closest multiple of 10 to the power minus *n*; if two multiples are equally
close, rounding is done toward the even choice (so, for example, both
``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is ``2``).
The return value is an integer if called with one argument, otherwise of the
same type as *x*.
closest multiple of 10 to the power minus *ndigits*; if two multiples are
equally close, rounding is done toward the even choice (so, for example,
both ``round(0.5)`` and ``round(-0.5)`` are ``0``, and ``round(1.5)`` is
``2``). The return value is an integer if called with one argument,
otherwise of the same type as *number*.
.. note::
@ -1126,7 +1142,8 @@ are always available. They are listed here in alphabetical order.
``x.foobar = 123``.
.. function:: slice([start,] stop[, step])
.. function:: slice(stop)
slice(start, stop[, step])
.. index:: single: Numerical Python

8
Doc/library/http.client.rst
View file

@ -27,7 +27,8 @@ HTTPS protocols. It is normally not used directly --- the module
The module provides the following classes:
.. class:: HTTPConnection(host, port=None[, strict[, timeout[, source_address]]])
.. class:: HTTPConnection(host, port=None[, strict][, timeout], \
source_address=None)
An :class:`HTTPConnection` instance represents one transaction with an HTTP
server. It should be instantiated passing it a host and optional port
@ -55,7 +56,10 @@ The module provides the following classes:
are not supported anymore.
.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None[, strict[, timeout[, source_address]]], *, context=None, check_hostname=None)
.. class:: HTTPSConnection(host, port=None, key_file=None, \
cert_file=None[, strict][, timeout], \
source_address=None, *, context=None, \
check_hostname=None)
A subclass of :class:`HTTPConnection` that uses SSL for communication with
secure servers. Default port is ``443``. If *context* is specified, it

4
Doc/library/inspect.rst
View file

@ -471,7 +471,7 @@ function.
Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the
passed arguments do not match the signature.
.. method:: Signature.replace([parameters], *, [return_annotation])
.. method:: Signature.replace(*[, parameters][, return_annotation])
Create a new Signature instance based on the instance replace was invoked
on. It is possible to pass different ``parameters`` and/or
@ -565,7 +565,7 @@ function.
... print('Parameter:', param)
Parameter: c
.. method:: Parameter.replace(*, [name], [kind], [default], [annotation])
.. method:: Parameter.replace(*[, name][, kind][, default][, annotation])
Create a new Parameter instance based on the instance replaced was invoked
on. To override a :class:`Parameter` attribute, pass the corresponding

3
Doc/library/itertools.rst
View file

@ -401,7 +401,8 @@ loops that truncate the stream.
self.currkey = self.keyfunc(self.currvalue)
.. function:: islice(iterable, [start,] stop [, step])
.. function:: islice(iterable, stop)
islice(iterable, start, stop[, step])
Make an iterator that returns selected elements from the iterable. If *start* is
non-zero, then elements from the iterable are skipped until start is reached.

18
Doc/library/json.rst
View file

@ -146,9 +146,12 @@ Basic Usage
object members will be pretty-printed with that indent level. An indent level
of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
selects the most compact representation. Using a positive integer indent
indents that many spaces per level. If *indent* is a string (such at '\t'),
indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
that string is used to indent each level.
.. versionchanged:: 3.2
Allow strings for *indent* in addition to integers.
If *separators* is an ``(item_separator, dict_separator)`` tuple, then it
will be used instead of the default ``(', ', ': ')`` separators. ``(',',
':')`` is the most compact JSON representation.
@ -371,10 +374,15 @@ Encoders and Decoders
will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis.
If *indent* is a non-negative integer (it is ``None`` by default), then JSON
array elements and object members will be pretty-printed with that indent
level. An indent level of 0 will only insert newlines. ``None`` is the most
compact representation.
If *indent* is a non-negative integer or string, then JSON array elements and
object members will be pretty-printed with that indent level. An indent level
of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
selects the most compact representation. Using a positive integer indent
indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
that string is used to indent each level.
.. versionchanged:: 3.2
Allow strings for *indent* in addition to integers.
If specified, *separators* should be an ``(item_separator, key_separator)``
tuple. The default is ``(', ', ': ')``. To get the most compact JSON

12
Doc/library/lzma.rst
View file

@ -335,15 +335,15 @@ Examples
Reading in a compressed file::
import lzma
with lzma.LZMAFile("file.xz") as f:
file_content = f.read()
with lzma.open("file.xz") as f:
file_content = f.read()
Creating a compressed file::
import lzma
data = b"Insert Data Here"
with lzma.LZMAFile("file.xz", "w") as f:
f.write(data)
with lzma.open("file.xz", "w") as f:
f.write(data)
Compressing data in memory::
@ -367,7 +367,7 @@ Writing compressed data to an already-open file::
import lzma
with open("file.xz", "wb") as f:
f.write(b"This data will not be compressed\n")
with lzma.LZMAFile(f, "w") as lzf:
with lzma.open(f, "w") as lzf:
lzf.write(b"This *will* be compressed\n")
f.write(b"Not compressed\n")
@ -378,5 +378,5 @@ Creating a compressed file using a custom filter chain::
{"id": lzma.FILTER_DELTA, "dist": 5},
{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.LZMAFile("file.xz", "w", filters=my_filters) as f:
with lzma.open("file.xz", "w", filters=my_filters) as f:
f.write(b"blah blah blah")

19
Doc/library/mailbox.rst
View file

@ -10,9 +10,9 @@
This module defines two classes, :class:`Mailbox` and :class:`Message`, for
accessing and manipulating on-disk mailboxes and the messages they contain.
:class:`Mailbox` offers a dictionary-like mapping from keys to messages.
:class:`Message` extends the :mod:`email.Message` module's :class:`Message`
class with format-specific state and behavior. Supported mailbox formats are
Maildir, mbox, MH, Babyl, and MMDF.
:class:`Message` extends the :mod:`email.message` module's
:class:`~email.message.Message` class with format-specific state and behavior.
Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
.. seealso::
@ -81,7 +81,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
it.
Parameter *message* may be a :class:`Message` instance, an
:class:`email.Message.Message` instance, a string, a byte string, or a
:class:`email.message.Message` instance, a string, a byte string, or a
file-like object (which should be open in binary mode). If *message* is
an instance of the
appropriate format-specific :class:`Message` subclass (e.g., if it's an
@ -112,7 +112,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
:exc:`KeyError` exception if no message already corresponds to *key*.
As with :meth:`add`, parameter *message* may be a :class:`Message`
instance, an :class:`email.Message.Message` instance, a string, a byte
instance, an :class:`email.message.Message` instance, a string, a byte
string, or a file-like object (which should be open in binary mode). If
*message* is an
instance of the appropriate format-specific :class:`Message` subclass
@ -757,11 +757,12 @@ Maildir, mbox, MH, Babyl, and MMDF.
.. class:: Message(message=None)
A subclass of the :mod:`email.Message` module's :class:`Message`. Subclasses of
:class:`mailbox.Message` add mailbox-format-specific state and behavior.
A subclass of the :mod:`email.message` module's
:class:`~email.message.Message`. Subclasses of :class:`mailbox.Message` add
mailbox-format-specific state and behavior.
If *message* is omitted, the new instance is created in a default, empty state.
If *message* is an :class:`email.Message.Message` instance, its contents are
If *message* is an :class:`email.message.Message` instance, its contents are
copied; furthermore, any format-specific information is converted insofar as
possible if *message* is a :class:`Message` instance. If *message* is a string,
a byte string,
@ -1267,7 +1268,7 @@ When an :class:`MHMessage` instance is created based upon a
Set the message's visible headers to be the same as the headers in
*message*. Parameter *visible* should be a :class:`Message` instance, an
:class:`email.Message.Message` instance, a string, or a file-like object
:class:`email.message.Message` instance, a string, or a file-like object
(which should be open in text mode).

5
Doc/library/multiprocessing.rst
View file

@ -295,7 +295,8 @@ The :mod:`multiprocessing` package mostly replicates the API of the
:class:`Process` and exceptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. class:: Process([group[, target[, name[, args[, kwargs]]]]], *, daemon=None)
.. class:: Process(group=None, target=None, name=None, args=(), kwargs={}, \
*, daemon=None)
Process objects represent activity that is run in a separate process. The
:class:`Process` class has equivalents of all the methods of
@ -1147,7 +1148,7 @@ process::
n = Value('i', 7)
x = Value(c_double, 1.0/3.0, lock=False)
s = Array('c', 'hello world', lock=lock)
s = Array('c', b'hello world', lock=lock)
A = Array(Point, [(1.875,-6.25), (-5.75,2.0), (2.375,9.5)], lock=lock)
p = Process(target=modify, args=(n, x, s, A))

6
Doc/library/nntplib.rst
View file

@ -487,10 +487,10 @@ The following are optional NNTP extensions defined in :rfc:`2980`. Some of
them have been superseded by newer commands in :rfc:`3977`.
.. method:: NNTP.xhdr(header, string, *, file=None)
.. method:: NNTP.xhdr(hdr, str, *, file=None)
Send an ``XHDR`` command. The *header* argument is a header keyword, e.g.
``'subject'``. The *string* argument should have the form ``'first-last'``
Send an ``XHDR`` command. The *hdr* argument is a header keyword, e.g.
``'subject'``. The *str* argument should have the form ``'first-last'``
where *first* and *last* are the first and last article numbers to search.
Return a pair ``(response, list)``, where *list* is a list of pairs ``(id,
text)``, where *id* is an article number (as a string) and *text* is the text of

17
Doc/library/optparse.rst
View file

@ -273,7 +273,8 @@ You're free to define as many short option strings and as many long option
strings as you like (including zero), as long as there is at least one option
string overall.
The option strings passed to :meth:`add_option` are effectively labels for the
The option strings passed to :meth:`OptionParser.add_option` are effectively
labels for the
option defined by that call. For brevity, we will frequently refer to
*encountering an option* on the command line; in reality, :mod:`optparse`
encounters *option strings* and looks up options from them.
@ -892,7 +893,8 @@ long option strings, but you must specify at least one overall option string.
The canonical way to create an :class:`Option` instance is with the
:meth:`add_option` method of :class:`OptionParser`.
.. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
.. method:: OptionParser.add_option(option)
OptionParser.add_option(*opt_str, attr=value, ...)
To define an option with only a short option string::
@ -1165,6 +1167,17 @@ must specify for any option using that action.
options.tracks.append(int("4"))
The ``append`` action calls the ``append`` method on the current value of the
option. This means that any default value specified must have an ``append``
method. It also means that if the default value is non-empty, the default
elements will be present in the parsed value for the option, with any values
from the command line appended after those default values::
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']
* ``"append_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]

5
Doc/library/os.rst
View file

@ -1855,9 +1855,8 @@ features:
:attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
some implementations.
This function can support :ref:`specifying a file descriptor
<path_fd>`, :ref:`specifying a file descriptor <path_fd>` and :ref:`not
following symlinks <follow_symlinks>`.
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
.. index:: module: stat

3
Doc/library/ossaudiodev.rst
View file

@ -67,7 +67,8 @@ the standard audio interface for Linux and recent versions of FreeBSD.
``ossaudiodev.error``.)
.. function:: open([device, ]mode)
.. function:: open(mode)
open(device, mode)
Open an audio device and return an OSS audio device object. This object
supports many file-like methods, such as :meth:`read`, :meth:`write`, and

2
Doc/library/pyexpat.rst
View file

@ -402,7 +402,7 @@ otherwise stated.
.. method:: xmlparser.CommentHandler(data)
Called for comments. *data* is the text of the comment, excluding the leading
'``<!-``\ ``-``' and trailing '``-``\ ``->``'.
``'<!-``\ ``-'`` and trailing ``'-``\ ``->'``.
.. method:: xmlparser.StartCdataSectionHandler()

11
Doc/library/random.rst
View file

@ -52,20 +52,20 @@ from sources provided by the operating system.
Bookkeeping functions:
.. function:: seed([x], version=2)
.. function:: seed(a=None, version=2)
Initialize the random number generator.
If *x* is omitted or ``None``, the current system time is used. If
If *a* is omitted or ``None``, the current system time is used. If
randomness sources are provided by the operating system, they are used
instead of the system time (see the :func:`os.urandom` function for details
on availability).
If *x* is an int, it is used directly.
If *a* is an int, it is used directly.
With version 2 (the default), a :class:`str`, :class:`bytes`, or :class:`bytearray`
object gets converted to an :class:`int` and all of its bits are used. With version 1,
the :func:`hash` of *x* is used instead.
the :func:`hash` of *a* is used instead.
.. versionchanged:: 3.2
Moved to the version 2 scheme which uses all of the bits in a string seed.
@ -93,7 +93,8 @@ Bookkeeping functions:
Functions for integers:
.. function:: randrange([start,] stop[, step])
.. function:: randrange(stop)
randrange(start, stop[, step])
Return a randomly selected element from ``range(start, stop, step)``. This is
equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a

2
Doc/library/site.rst
View file

@ -33,7 +33,7 @@ It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
are skipped. For the tail part, it uses the empty string and then
:file:`lib/site-packages` (on Windows) or
:file:`lib/python|version|/site-packages` and then :file:`lib/site-python` (on
:file:`lib/python{X.Y}/site-packages` and then :file:`lib/site-python` (on
Unix and Macintosh). For each of the distinct head-tail combinations, it sees
if it refers to an existing directory, and if so, adds it to ``sys.path`` and
also inspects the newly added path for configuration files.

13
Doc/library/smtpd.rst
View file

@ -111,12 +111,13 @@ SMTPChannel Objects
.. attribute:: addr
Holds the address of the client, the second value returned by
socket.accept()
:func:`socket.accept <socket.socket.accept>`
.. attribute:: received_lines
Holds a list of the line strings (decoded using UTF-8) received from
the client. The lines have their "\\r\\n" line ending translated to "\\n".
the client. The lines have their ``"\r\n"`` line ending translated to
``"\n"``.
.. attribute:: smtp_state
@ -141,12 +142,12 @@ SMTPChannel Objects
.. attribute:: received_data
Holds a string containing all of the data sent by the client during the
DATA state, up to but not including the terminating "\r\n.\r\n".
DATA state, up to but not including the terminating ``"\r\n.\r\n"``.
.. attribute:: fqdn
Holds the fully-qualified domain name of the server as returned by
``socket.getfqdn()``.
:func:`socket.getfqdn`.
.. attribute:: peer
@ -170,14 +171,14 @@ SMTPChannel Objects
MAIL Accepts the "MAIL FROM:" syntax and stores the supplied address as
:attr:`mailfrom`. In extended command mode, accepts the
:rfc:`1870` SIZE attribute and responds appropriately based on the
value of ``data_size_limit``.
value of *data_size_limit*.
RCPT Accepts the "RCPT TO:" syntax and stores the supplied addresses in
the :attr:`rcpttos` list.
RSET Resets the :attr:`mailfrom`, :attr:`rcpttos`, and
:attr:`received_data`, but not the greeting.
DATA Sets the internal state to :attr:`DATA` and stores remaining lines
from the client in :attr:`received_data` until the terminator
"\r\n.\r\n" is received.
``"\r\n.\r\n"`` is received.
HELP Returns minimal information on command syntax
VRFY Returns code 252 (the server doesn't know if the address is valid)
EXPN Reports that the command is not implemented.

3
Doc/library/socket.rst
View file

@ -1005,7 +1005,8 @@ correspond to Unix system calls applicable to sockets.
much data, if any, was successfully sent.
.. method:: socket.sendto(bytes[, flags], address)
.. method:: socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)
Send data to the socket. The socket should not be connected to a remote socket,
since the destination socket is specified by *address*. The optional *flags*

11
Doc/library/stdtypes.rst
View file

@ -1235,7 +1235,8 @@ The :class:`range` type represents an immutable sequence of numbers and is
commonly used for looping a specific number of times in :keyword:`for`
loops.
.. class:: range([start, ]stop[, step])
.. class:: range(stop)
range(start, stop[, step])
The arguments to the range constructor must be integers (either built-in
:class:`int` or any object that implements the ``__index__`` special
@ -2687,13 +2688,19 @@ copying.
.. attribute:: shape
A tuple of integers the length of :attr:`ndim` giving the shape of the
memory as a N-dimensional array.
memory as an N-dimensional array.
.. versionchanged:: 3.3
An empty tuple instead of None when ndim = 0.
.. attribute:: strides
A tuple of integers the length of :attr:`ndim` giving the size in bytes to
access each element for each dimension of the array.
.. versionchanged:: 3.3
An empty tuple instead of None when ndim = 0.
.. attribute:: suboffsets
Used internally for PIL-style arrays. The value is informational only.

14
Doc/library/subprocess.rst
View file

@ -307,10 +307,14 @@ default values. The arguments that are most commonly needed are:
:meth:`Popen.communicate` method.
If *shell* is ``True``, the specified command will be executed through
the shell. This can be useful if you are using Python primarily for the
the shell. This can be useful if you are using Python primarily for the
enhanced control flow it offers over most system shells and still want
access to other shell features such as filename wildcards, shell pipes and
environment variable expansion.
convenient access to other shell features such as shell pipes, filename
wildcards, environment variable expansion, and expansion of ``~`` to a
user's home directory. However, note that Python itself offers
implementations of many shell-like features (in particular, :mod:`glob`,
:mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,
:func:`os.path.expanduser`, and :mod:`shutil`).
.. versionchanged:: 3.3
When *universal_newlines* is ``True``, the class uses the encoding
@ -669,8 +673,8 @@ The following attributes are also available:
.. warning::
Use :meth:`communicate` rather than :attr:`.stdin.write <stdin>`,
:attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` to avoid
Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
:attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
deadlocks due to any of the other OS pipe buffers filling up and blocking the
child process.

3
Doc/library/syslog.rst
View file

@ -17,7 +17,8 @@ library that can speak to a syslog server is available in the
The module defines the following functions:
.. function:: syslog([priority,] message)
.. function:: syslog(message)
syslog(priority, message)
Send the string *message* to the system logger. A trailing newline is added
if necessary. Each message is tagged with a priority composed of a

19
Doc/library/textwrap.rst
View file

@ -25,6 +25,9 @@ otherwise, you should use an instance of :class:`TextWrapper` for efficiency.
Optional keyword arguments correspond to the instance attributes of
:class:`TextWrapper`, documented below. *width* defaults to ``70``.
See the :meth:`TextWrapper.wrap` method for additional details on how
:func:`wrap` behaves.
.. function:: fill(text, width=70, **kwargs)
@ -167,15 +170,18 @@ in a block of text.
.. attribute:: drop_whitespace
(default: ``True``) If true, whitespace that, after wrapping, happens to
end up at the beginning or end of a line is dropped (leading whitespace in
the first line is always preserved, though).
(default: ``True``) If true, whitespace at the beginning and ending of
every line (after wrapping but before indenting) is dropped.
Whitespace at the beginning of the paragraph, however, is not dropped
if non-whitespace follows it. If whitespace being dropped takes up an
entire line, the whole line is dropped.
.. attribute:: initial_indent
(default: ``''``) String that will be prepended to the first line of
wrapped output. Counts towards the length of the first line.
wrapped output. Counts towards the length of the first line. The empty
string is not indented.
.. attribute:: subsequent_indent
@ -236,8 +242,9 @@ in a block of text.
Wraps the single paragraph in *text* (a string) so every line is at most
:attr:`width` characters long. All wrapping options are taken from
instance attributes of the :class:`TextWrapper` instance. Returns a list
of output lines, without final newlines.
instance attributes of the :class:`TextWrapper` instance. Returns a list
of output lines, without final newlines. If the wrapped output has no
content, the returned list is empty.
.. method:: fill(text)

6
Doc/library/threading.rst
View file

@ -255,8 +255,8 @@ daemonic, and cannot be :meth:`~Thread.join`\ ed. They are never deleted,
since it is impossible to detect the termination of alien threads.
.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
verbose=None, *, daemon=None)
.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, *, \
daemon=None)
This constructor should always be called with keyword arguments. Arguments
are:
@ -275,8 +275,6 @@ since it is impossible to detect the termination of alien threads.
*kwargs* is a dictionary of keyword arguments for the target invocation.
Defaults to ``{}``.
*verbose* is a flag used for debugging messages.
If not ``None``, *daemon* explicitly sets whether the thread is daemonic.
If ``None`` (the default), the daemonic property is inherited from the
current thread.

20
Doc/library/timeit.rst
View file

@ -31,13 +31,13 @@ The module defines the following public class:
may also contain multiple statements separated by ``;`` or newlines, as long as
they don't contain multi-line string literals.
To measure the execution time of the first statement, use the :meth:`timeit`
method. The :meth:`repeat` method is a convenience to call :meth:`timeit`
To measure the execution time of the first statement, use the :meth:`Timer.timeit`
method. The :meth:`repeat` method is a convenience to call :meth:`.timeit`
multiple times and return a list of results.
The *stmt* and *setup* parameters can also take objects that are callable
without arguments. This will embed calls to them in a timer function that
will then be executed by :meth:`timeit`. Note that the timing overhead is a
will then be executed by :meth:`.timeit`. Note that the timing overhead is a
little larger in this case because of the extra function calls.
@ -60,12 +60,12 @@ The module defines the following public class:
.. method:: Timer.repeat(repeat=3, number=1000000)
Call :meth:`timeit` a few times.
Call :meth:`.timeit` a few times.
This is a convenience function that calls the :meth:`timeit` repeatedly,
This is a convenience function that calls the :meth:`.timeit` repeatedly,
returning a list of results. The first argument specifies how many times to
call :meth:`timeit`. The second argument specifies the *number* argument for
:func:`timeit`.
call :meth:`.timeit`. The second argument specifies the *number* argument for
:meth:`.timeit`.
.. note::
@ -89,7 +89,7 @@ The module defines the following public class:
.. note::
By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
By default, :meth:`.timeit` temporarily turns off :term:`garbage collection`
during the timing. The advantage of this approach is that it makes
independent timings more comparable. This disadvantage is that GC may be
an important component of the performance of the function being measured.
@ -117,7 +117,7 @@ The module also defines three convenience functions:
.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000)
Create a :class:`Timer` instance with the given statement, setup code and timer
function and run its :meth:`timeit` method with *number* executions.
function and run its :meth:`.timeit` method with *number* executions.
Command Line Interface
@ -243,7 +243,7 @@ attributes. ::
3.15 usec/pass
To give the :mod:`timeit` module access to functions you define, you can pass a
``setup`` parameter which contains an import statement::
*setup* parameter which contains an import statement::
def test():
"""Stupid test function"""

2
Doc/library/tkinter.tix.rst
View file

@ -504,7 +504,7 @@ Tix Commands
print(root.tix_configure())
.. method:: tixCommand.tix_configure([cnf,] **kw)
.. method:: tixCommand.tix_configure(cnf=None, **kw)
Query or modify the configuration options of the Tix application context. If no
option is specified, returns a dictionary all of the available options. If

2
Doc/library/types.rst
View file

@ -69,7 +69,7 @@ implement a Python interpreter. It deliberately avoids including some of
the types that arise only incidentally during processing such as the
``listiterator`` type.
Typical use is of these names is for :func:`isinstance` or
Typical use of these names is for :func:`isinstance` or
:func:`issubclass` checks.
Standard names are defined for the following types:

4
Doc/library/unittest.mock.rst
View file

@ -276,7 +276,7 @@ the `new_callable` argument to `patch`.
>>> mock.assert_called_once_with('foo', bar='baz')
Traceback (most recent call last):
...
AssertionError: Expected to be called once. Called 2 times.
AssertionError: Expected 'mock' to be called once. Called 2 times.
.. method:: assert_any_call(*args, **kwargs)
@ -2020,7 +2020,7 @@ extremely handy: :meth:`~Mock.assert_called_with` and
>>> mock.assert_called_once_with(1, 2, 3)
Traceback (most recent call last):
...
AssertionError: Expected to be called once. Called 2 times.
AssertionError: Expected 'mock' to be called once. Called 2 times.
Because mocks auto-create attributes on demand, and allow you to call them
with arbitrary arguments, if you misspell one of these assert methods then

2
Doc/library/unittest.rst
View file

@ -1265,7 +1265,7 @@ Test cases
.. method:: assertListEqual(first, second, msg=None)
assertTupleEqual(first, second, msg=None)
Tests that two lists or tuples are equal. If not an error message is
Tests that two lists or tuples are equal. If not, an error message is
constructed that shows only the differences between the two. An error
is also raised if either of the parameters are of the wrong type.
These methods are used by default when comparing lists or tuples with

5
Doc/library/urllib.parse.rst
View file

@ -145,8 +145,9 @@ or on combining URL components into a URL string.
percent-encoded sequences into Unicode characters, as accepted by the
:meth:`bytes.decode` method.
Use the :func:`urllib.parse.urlencode` function to convert such
dictionaries into query strings.
Use the :func:`urllib.parse.urlencode` function (with the ``doseq``
parameter set to ``True``) to convert such dictionaries into query
strings.
.. versionchanged:: 3.2