diff options
| author | Benjamin Peterson <benjamin@python.org> | 2012-09-29 18:14:19 (GMT) |
|---|---|---|
| committer | Benjamin Peterson <benjamin@python.org> | 2012-09-29 18:14:19 (GMT) |
| commit | 14fb44e1bab9db128770f1d91d244916a669e7c3 (patch) | |
| tree | 278d9ccc8f819b05f8114c3154087c70b88ed69c /Doc/library | |
| parent | 1764c80925795b6f059e961c5a352c5ece5a7fff (diff) | |
| parent | 99a247fd01c1cd780c0c3ee1116657627f1ee744 (diff) | |
| download | cpython-14fb44e1bab9db128770f1d91d244916a669e7c3.zip cpython-14fb44e1bab9db128770f1d91d244916a669e7c3.tar.gz cpython-14fb44e1bab9db128770f1d91d244916a669e7c3.tar.bz2 | |
merge mostly from default
Diffstat (limited to 'Doc/library')
36 files changed, 280 insertions, 157 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 4203e8b..9f6a1ea 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -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 diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 4c5b649..dc76ea5 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -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:: diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index afceb8d..c202cf2 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -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. diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst index 1ba2ed3..b4c90cd 100644 --- a/Doc/library/crypt.rst +++ b/Doc/library/crypt.rst @@ -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") diff --git a/Doc/library/crypto.rst b/Doc/library/crypto.rst index a233561..469ede49 100644 --- a/Doc/library/crypto.rst +++ b/Doc/library/crypto.rst @@ -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: diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 5d8368b..4f19cee 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -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: diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index c424148..9e5cb55 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -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*. diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index cdd6c26..ed53f06 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -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 diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 61e4932..c2b3b21 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -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]]) - - 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 +.. function:: int(x=0) + int(x, base=10) + + 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]) + + Return the smallest item in an iterable or the smallest of two or more + arguments. - 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. + 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 diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index efb4c41..5599dac 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -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 diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 83b7702..4050ab3 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -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 diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index da3e690..1eb554a 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -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. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 0229ab5..95f120c 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -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 diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index 402fae2..f09fa08 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -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") diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 8623630..0f6aba1 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -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). diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 33a3511..616b7cd 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -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)) diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst index 62da72c..87a50b0 100644 --- a/Doc/library/nntplib.rst +++ b/Doc/library/nntplib.rst @@ -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 diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index add582e..6a03edf 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -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`] diff --git a/Doc/library/os.rst b/Doc/library/os.rst index aec8073..5f149cb 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -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 diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst index 9e5bec9..3002700 100644 --- a/Doc/library/ossaudiodev.rst +++ b/Doc/library/ossaudiodev.rst @@ -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 diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index a648cfa..861546c 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -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() diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 23dbd1f..55c9d70 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -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 diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 3bf8a99..36b80c3 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -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. diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst index 6dd477a..2ca71ff 100644 --- a/Doc/library/smtpd.rst +++ b/Doc/library/smtpd.rst @@ -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. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 02af9ca..5737b40 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -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* diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 90f3e54..ed5b3ae 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -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. diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index c0fc4d7..042f8f4 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -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. diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst index aa0f5a1..6e90dc0 100644 --- a/Doc/library/syslog.rst +++ b/Doc/library/syslog.rst @@ -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 diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index 0ac1cc6..c625254 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -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) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 275a578..7ab739b 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -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. diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index c41e59d..6989b1c 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -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""" diff --git a/Doc/library/tkinter.tix.rst b/Doc/library/tkinter.tix.rst index 289bffd..9de73ad 100644 --- a/Doc/library/tkinter.tix.rst +++ b/Doc/library/tkinter.tix.rst @@ -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 diff --git a/Doc/library/types.rst b/Doc/library/types.rst index b60b195..695480f 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -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: diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index bed698a..3e50031 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -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 diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 0af9038..2657ebd 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -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 diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst index d56fe0e..208cb97 100644 --- a/Doc/library/urllib.parse.rst +++ b/Doc/library/urllib.parse.rst @@ -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 |