Switch more function arguments docs to new-style.

Doc/library/os.path.rst

@@ -218,7 +218,7 @@ applications should use string objects to access all files.
    links encountered in the path (if they are supported by the operating system).
 
 
-.. function:: relpath(path[, start])
+.. function:: relpath(path, start=None)
 
    Return a relative filepath to *path* either from the current directory or from
    an optional *start* point.

Doc/library/os.rst

@@ -204,18 +204,17 @@ process and user.
    Return the current process's user id. Availability: Unix.
 
 
-.. function:: getenv(varname[, value])
+.. function:: getenv(key, default=None)
 
-   Return the value of the environment variable *varname* if it exists, or *value*
+   Return the value of the environment variable *key* if it exists, or
-   if it doesn't.  *value* defaults to ``None``. Availability: most flavors of
+   *default* if it doesn't.  Availability: most flavors of Unix, Windows.
-   Unix, Windows.
 
 
-.. function:: putenv(varname, value)
+.. function:: putenv(key, value)
 
    .. index:: single: environment variables; setting
 
-   Set the environment variable named *varname* to the string *value*.  Such
+   Set the environment variable named *key* to the string *value*.  Such
    changes to the environment affect subprocesses started with :func:`os.system`,
    :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
    Unix, Windows.
@@ -326,11 +325,11 @@ process and user.
    Unix.
 
 
-.. function:: unsetenv(varname)
+.. function:: unsetenv(key)
 
    .. index:: single: environment variables; deleting
 
-   Unset (delete) the environment variable named *varname*. Such changes to the
+   Unset (delete) the environment variable named *key*. Such changes to the
    environment affect subprocesses started with :func:`os.system`, :func:`popen` or
    :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.
 
@@ -847,15 +846,14 @@ Files and Directories
    doesn't open the FIFO --- it just creates the rendezvous point.
 
 
-.. function:: mknod(filename[, mode=0o600, device])
+.. function:: mknod(filename[, mode=0o600[, device]])
 
    Create a filesystem node (file, device special file or named pipe) named
-   *filename*. *mode* specifies both the permissions to use and the type of node to
+   *filename*. *mode* specifies both the permissions to use and the type of node
-   be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
+   to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
-   ``stat.S_IFCHR``, ``stat.S_IFBLK``,
+   ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
-   and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
+   available in :mod:`stat`).  For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
-   For ``stat.S_IFCHR`` and
+   *device* defines the newly created device special file (probably using
-   ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
    :func:`os.makedev`), otherwise it is ignored.
 
 
@@ -1123,7 +1121,7 @@ Files and Directories
    Availability: Unix, Windows.
 
 
-.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])
+.. function:: walk(top, topdown=True, onerror=None, followlinks=False)
 
    .. index::
       single: directory; walking

Doc/library/ossaudiodev.rst

@@ -1,4 +1,3 @@
-
 :mod:`ossaudiodev` --- Access to OSS-compatible audio devices
 =============================================================
 

Doc/library/parser.rst

@@ -1,4 +1,3 @@
-
 :mod:`parser` --- Access Python parse trees
 ===========================================
 
@@ -165,7 +164,7 @@ executable code objects.  Parse trees may be extracted with or without line
 numbering information.
 
 
-.. function:: st2list(st[, line_info])
+.. function:: st2list(st, line_info=False, col_info=False)
 
    This function accepts an ST object from the caller in *st* and returns a
    Python list representing the equivalent parse tree.  The resulting list
@@ -183,7 +182,7 @@ numbering information.
    This information is omitted if the flag is false or omitted.
 
 
-.. function:: st2tuple(st[, line_info])
+.. function:: st2tuple(st, line_info=False, col_info=False)
 
    This function accepts an ST object from the caller in *st* and returns a
    Python tuple representing the equivalent parse tree.  Other than returning a
@@ -194,7 +193,7 @@ numbering information.
    information is omitted if the flag is false or omitted.
 
 
-.. function:: compilest(st[, filename='<syntax-tree>'])
+.. function:: compilest(st, filename='<syntax-tree>')
 
    .. index::
       builtin: exec
@@ -293,7 +292,7 @@ ST objects (using the :mod:`pickle` module) is also supported.
 ST objects have the following methods:
 
 
-.. method:: ST.compile([filename])
+.. method:: ST.compile(filename='<syntax-tree>')
 
    Same as ``compilest(st, filename)``.
 
@@ -308,14 +307,14 @@ ST objects have the following methods:
    Same as ``issuite(st)``.
 
 
-.. method:: ST.tolist([line_info])
+.. method:: ST.tolist(line_info=False, col_info=False)
 
-   Same as ``st2list(st, line_info)``.
+   Same as ``st2list(st, line_info, col_info)``.
 
 
-.. method:: ST.totuple([line_info])
+.. method:: ST.totuple(line_info=False, col_info=False)
 
-   Same as ``st2tuple(st, line_info)``.
+   Same as ``st2tuple(st, line_info, col_info)``.
 
 
 .. _st-examples:

Doc/library/pdb.rst

@@ -79,7 +79,7 @@ The typical usage to inspect a crashed program is::
 The module defines the following functions; each enters the debugger in a
 slightly different way:
 
-.. function:: run(statement[, globals[, locals]])
+.. function:: run(statement, globals=None, locals=None)
 
    Execute the *statement* (given as a string) under debugger control.  The
    debugger prompt appears before any code is executed; you can set breakpoints and
@@ -90,14 +90,14 @@ slightly different way:
    explanation of the built-in :func:`exec` or :func:`eval` functions.)
 
 
-.. function:: runeval(expression[, globals[, locals]])
+.. function:: runeval(expression, globals=None, locals=None)
 
    Evaluate the *expression* (given as a string) under debugger control.  When
    :func:`runeval` returns, it returns the value of the expression.  Otherwise this
    function is similar to :func:`run`.
 
 
-.. function:: runcall(function[, argument, ...])
+.. function:: runcall(function, *args, **kwds)
 
    Call the *function* (a function or method object, not a string) with the given
    arguments.  When :func:`runcall` returns, it returns whatever the function call
@@ -111,7 +111,7 @@ slightly different way:
    being debugged (e.g. when an assertion fails).
 
 
-.. function:: post_mortem([traceback])
+.. function:: post_mortem(traceback=None)
 
    Enter post-mortem debugging of the given *traceback* object.  If no
    *traceback* is given, it uses the one of the exception that is currently
@@ -147,9 +147,9 @@ access further features, you have to do this yourself:
    .. versionadded:: 3.1
       The *skip* argument.
 
-   .. method:: run(statement[, globals[, locals]])
+   .. method:: run(statement, globals=None, locals=None)
-               runeval(expression[, globals[, locals]])
+               runeval(expression, globals=None, locals=None)
-               runcall(function[, argument, ...])
+               runcall(function, *args, **kwds)
                set_trace()
 
       See the documentation for the functions explained above.

Doc/library/persistence.rst

@@ -1,4 +1,3 @@
-
 .. _persistence:
 
 ****************

Doc/library/pickle.rst

@@ -141,7 +141,7 @@ an unpickler, then you call the unpickler's :meth:`load` method.  The
 The :mod:`pickle` module provides the following functions to make the pickling
 process more convenient:
 
-.. function:: dump(obj, file[, protocol, \*, fix_imports=True])
+.. function:: dump(obj, file, protocol=None, \*, fix_imports=True)
 
    Write a pickled representation of *obj* to the open file object *file*.  This
    is equivalent to ``Pickler(file, protocol).dump(obj)``.
@@ -162,7 +162,7 @@ process more convenient:
    map the new Python 3.x names to the old module names used in Python 2.x,
    so that the pickle data stream is readable with Python 2.x.
 
-.. function:: dumps(obj[, protocol, \*, fix_imports=True])
+.. function:: dumps(obj, protocol=None, \*, fix_imports=True)
 
    Return the pickled representation of the object as a :class:`bytes`
    object, instead of writing it to a file.
@@ -179,7 +179,7 @@ process more convenient:
    map the new Python 3.x names to the old module names used in Python 2.x,
    so that the pickle data stream is readable with Python 2.x.
 
-.. function:: load(file, [\*, fix_imports=True, encoding="ASCII", errors="strict"])
+.. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict")
 
    Read a pickled object representation from the open file object *file* and
    return the reconstituted object hierarchy specified therein.  This is
@@ -202,7 +202,7 @@ process more convenient:
    *errors* tell pickle how to decode 8-bit string instances pickled by Python
    2.x; these default to 'ASCII' and 'strict', respectively.
 
-.. function:: loads(bytes_object, [\*, fix_imports=True, encoding="ASCII", errors="strict"])
+.. function:: loads(bytes_object, \*, fix_imports=True, encoding="ASCII", errors="strict")
 
    Read a pickled object hierarchy from a :class:`bytes` object and return the
    reconstituted object hierarchy specified therein
@@ -247,7 +247,7 @@ The :mod:`pickle` module defines three exceptions:
 The :mod:`pickle` module exports two classes, :class:`Pickler` and
 :class:`Unpickler`:
 
-.. class:: Pickler(file[, protocol, \*, fix_imports=True])
+.. class:: Pickler(file, protocol=None, \*, fix_imports=True)
 
    This takes a binary file for writing a pickle data stream.
 
@@ -295,7 +295,7 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and
       Use :func:`pickletools.optimize` if you need more compact pickles.
 
 
-.. class:: Unpickler(file, [\*, fix_imports=True, encoding="ASCII", errors="strict"])
+.. class:: Unpickler(file, \*, fix_imports=True, encoding="ASCII", errors="strict")
 
    This takes a binary file for reading a pickle data stream.
 

Doc/library/pickletools.rst

@@ -2,7 +2,8 @@
 ==================================================
 
 .. module:: pickletools
-   :synopsis: Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.
+   :synopsis: Contains extensive comments about the pickle protocols and
+              pickle-machine opcodes, as well as some useful functions.
 
 This module contains various constants relating to the intimate details of the
 :mod:`pickle` module, some lengthy comments about the implementation, and a
@@ -12,7 +13,7 @@ ordinary users of the :mod:`pickle` module probably won't find the
 :mod:`pickletools` module relevant.
 
 
-.. function:: dis(pickle[, out=None, memo=None, indentlevel=4])
+.. function:: dis(pickle, out=None, memo=None, indentlevel=4)
 
    Outputs a symbolic disassembly of the pickle to the file-like object *out*,
    defaulting to ``sys.stdout``.  *pickle* can be a string or a file-like object.

Doc/library/pipes.rst

@@ -1,4 +1,3 @@
-
 :mod:`pipes` --- Interface to shell pipelines
 =============================================
 

Doc/library/pkgutil.rst

@@ -1,4 +1,3 @@
-
 :mod:`pkgutil` --- Package extension utility
 ============================================
 

Doc/library/poplib.rst

@@ -1,4 +1,3 @@
-
 :mod:`poplib` --- POP3 protocol client
 ======================================
 
@@ -24,7 +23,7 @@ mailserver supports IMAP, you would be better off using the
 A single class is provided by the :mod:`poplib` module:
 
 
-.. class:: POP3(host[, port[, timeout]])
+.. class:: POP3(host, port=POP3_PORT[, timeout])
 
    This class implements the actual POP3 protocol.  The connection is created when
    the instance is initialized. If *port* is omitted, the standard POP3 port (110)
@@ -33,12 +32,13 @@ A single class is provided by the :mod:`poplib` module:
    be used).
 
 
-.. class:: POP3_SSL(host[, port[, keyfile[, certfile]]])
+.. class:: POP3_SSL(host, port=POP3_SSL_PORT, keyfile=None, certfile=None[, timeout])
 
    This is a subclass of :class:`POP3` that connects to the server over an SSL
    encrypted socket.  If *port* is not specified, 995, the standard POP3-over-SSL
    port is used.  *keyfile* and *certfile* are also optional - they can contain a
    PEM formatted private key and certificate chain file for the SSL connection.
+   *timeout* works as in the :class:`POP3` constructor.
 
 
 One exception is defined as an attribute of the :mod:`poplib` module:
@@ -160,7 +160,7 @@ An :class:`POP3` instance has the following methods:
    POP3 servers you will use before trusting it.
 
 
-.. method:: POP3.uidl([which])
+.. method:: POP3.uidl(which=None)
 
    Return message digest (unique id) list. If *which* is specified, result contains
    the unique id for that message in the form ``'response mesgnum uid``, otherwise

Doc/library/pprint.rst

@@ -1,4 +1,3 @@
-
 :mod:`pprint` --- Data pretty printer
 =====================================
 
@@ -27,7 +26,7 @@ The :mod:`pprint` module defines one class:
 .. First the implementation class:
 
 
-.. class:: PrettyPrinter(...)
+.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None)
 
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
    several keyword parameters.  An output stream may be set using the *stream*
@@ -62,21 +61,20 @@ The :mod:`pprint` module defines one class:
       >>> pp.pprint(tup)
       ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
 
+
 The :class:`PrettyPrinter` class supports several derivative functions:
 
-.. Now the derivative functions:
+.. function:: pformat(object, indent=1, width=80, depth=None)
-
-.. function:: pformat(object[, indent[, width[, depth]]])
 
    Return the formatted representation of *object* as a string.  *indent*, *width*
    and *depth* will be passed to the :class:`PrettyPrinter` constructor as
    formatting parameters.
 
 
-.. function:: pprint(object[, stream[, indent[, width[, depth]]]])
+.. function:: pprint(object, stream=None, indent=1, width=80, depth=None)
 
    Prints the formatted representation of *object* on *stream*, followed by a
-   newline.  If *stream* is omitted, ``sys.stdout`` is used.  This may be used
+   newline.  If *stream* is ``None``, ``sys.stdout`` is used.  This may be used
    in the interactive interpreter instead of the :func:`print` function for
    inspecting values (you can even reassign ``print = pprint.pprint`` for use
    within a scope).  *indent*, *width* and *depth* will be passed to the
@@ -191,7 +189,8 @@ are converted to strings.  The default implementation uses the internals of the
 pprint Example
 --------------
 
-This example demonstrates several uses of the :func:`pprint` function and its parameters.
+This example demonstrates several uses of the :func:`pprint` function and its
+parameters.
 
    >>> import pprint
    >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',

Doc/library/profile.rst

@@ -1,4 +1,3 @@
-
 .. _profile:
 
 ********************
@@ -235,7 +234,7 @@ discussion of how to derive "better" profilers from the classes presented, or
 reading the source code for these modules.
 
 
-.. function:: run(command[, filename])
+.. function:: run(command, filename=None, sort=-1)
 
    This function takes a single argument that can be passed to the :func:`exec`
    function, and an optional file name.  In all cases this routine attempts to
@@ -264,8 +263,8 @@ reading the source code for these modules.
       for the number of calls,
 
    tottime
-      for the total time spent in the given function (and excluding time made in calls
+      for the total time spent in the given function (and excluding time made in
-      to sub-functions),
+      calls to sub-functions),
 
    percall
       is the quotient of ``tottime`` divided by ``ncalls``
@@ -285,24 +284,25 @@ reading the source code for these modules.
    calls.  Note that when the function does not recurse, these two values are the
    same, and only the single figure is printed.
 
+   If *sort* is given, it can be one of ``'stdname'`` (sort by filename:lineno),
+   ``'calls'`` (sort by number of calls), ``'time'`` (sort by total time) or
+   ``'cumulative'`` (sort by cumulative time).  The default is ``'stdname'``.
 
-.. function:: runctx(command, globals, locals[, filename])
+
+.. function:: runctx(command, globals, locals, filename=None)
 
    This function is similar to :func:`run`, with added arguments to supply the
    globals and locals dictionaries for the *command* string.
 
-Analysis of the profiler data is done using the :class:`Stats` class.
 
-.. note::
+Analysis of the profiler data is done using the :class:`pstats.Stats` class.
-
-   The :class:`Stats` class is defined in the :mod:`pstats` module.
 
 
 .. module:: pstats
    :synopsis: Statistics object for use with the profiler.
 
 
-.. class:: Stats(filename[, stream=sys.stdout[, ...]])
+.. class:: Stats(*filenames, stream=sys.stdout)
 
    This class constructor creates an instance of a "statistics object" from a
    *filename* (or set of filenames).  :class:`Stats` objects are manipulated by
@@ -342,7 +342,7 @@ The :class:`Stats` Class
    accumulated into a single entry.
 
 
-.. method:: Stats.add(filename[, ...])
+.. method:: Stats.add(*filenames)
 
    This method of the :class:`Stats` class accumulates additional profiling
    information into the current profiling object.  Its arguments should refer to
@@ -359,7 +359,7 @@ The :class:`Stats` Class
    :class:`profile.Profile` and :class:`cProfile.Profile` classes.
 
 
-.. method:: Stats.sort_stats(key[, ...])
+.. method:: Stats.sort_stats(*keys)
 
    This method modifies the :class:`Stats` object by sorting it according to the
    supplied criteria.  The argument is typically a string identifying the basis of
@@ -426,7 +426,7 @@ The :class:`Stats` Class
    .. This method is provided primarily for compatibility with the old profiler.
 
 
-.. method:: Stats.print_stats([restriction, ...])
+.. method:: Stats.print_stats(*restrictions)
 
    This method for the :class:`Stats` class prints out a report as described in the
    :func:`profile.run` definition.
@@ -455,7 +455,7 @@ The :class:`Stats` Class
    then proceed to only print the first 10% of them.
 
 
-.. method:: Stats.print_callers([restriction, ...])
+.. method:: Stats.print_callers(*restrictions)
 
    This method for the :class:`Stats` class prints a list of all functions that
    called each function in the profiled database.  The ordering is identical to
@@ -473,7 +473,7 @@ The :class:`Stats` Class
      the current function while it was invoked by this specific caller.
 
 
-.. method:: Stats.print_callees([restriction, ...])
+.. method:: Stats.print_callees(*restrictions)
 
    This method for the :class:`Stats` class prints a list of all function that were
    called by the indicated function.  Aside from this reversal of direction of

Doc/library/pty.rst

@@ -1,4 +1,3 @@
-
 :mod:`pty` --- Pseudo-terminal utilities
 ========================================
 

Doc/library/pwd.rst

@@ -1,4 +1,3 @@
-
 :mod:`pwd` --- The password database
 ====================================
 

Doc/library/py_compile.rst

@@ -22,7 +22,7 @@ byte-code cache files in the directory containing the source code.
    Exception raised when an error occurs while attempting to compile the file.
 
 
-.. function:: compile(file[, cfile[, dfile[, doraise]]])
+.. function:: compile(file, cfile=None, dfile=None, doraise=False)
 
    Compile a source file to byte-code and write out the byte-code cache  file.  The
    source code is loaded from the file name *file*.  The  byte-code is written to
@@ -34,10 +34,10 @@ byte-code cache files in the directory containing the source code.
    written to ``sys.stderr``, but no exception is raised.
 
 
-.. function:: main([args])
+.. function:: main(args=None)
 
    Compile several source files.  The files named in *args* (or on the command
-   line, if *args* is not specified) are compiled and the resulting bytecode is
+   line, if *args* is ``None``) are compiled and the resulting bytecode is
    cached in the normal manner.  This function does not search a directory
    structure to locate source files; it only compiles files named explicitly.
 

Doc/library/pyclbr.rst

@@ -1,4 +1,3 @@
-
 :mod:`pyclbr` --- Python class browser support
 ==============================================
 
@@ -17,7 +16,7 @@ not implemented in Python, including all standard and optional extension
 modules.
 
 
-.. function:: readmodule(module[, path=None])
+.. function:: readmodule(module, path=None)
 
    Read a module and return a dictionary mapping class names to class
    descriptor objects.  The parameter *module* should be the name of a
@@ -26,7 +25,7 @@ modules.
    of ``sys.path``, which is used to locate module source code.
 
 
-.. function:: readmodule_ex(module[, path=None])
+.. function:: readmodule_ex(module, path=None)
 
    Like :func:`readmodule`, but the returned dictionary, in addition to
    mapping class names to class descriptor objects, also maps top-level

Doc/library/pydoc.rst

@@ -1,4 +1,3 @@
-
 :mod:`pydoc` --- Documentation generator and online help system
 ===============================================================
 

Doc/library/pyexpat.rst

@@ -1,4 +1,3 @@
-
 :mod:`xml.parsers.expat` --- Fast XML parsing using Expat
 =========================================================
 
@@ -56,7 +55,7 @@ The :mod:`xml.parsers.expat` module contains two functions:
    Returns an explanatory string for a given error number *errno*.
 
 
-.. function:: ParserCreate([encoding[, namespace_separator]])
+.. function:: ParserCreate(encoding=None, namespace_separator=None)
 
    Creates and returns a new :class:`xmlparser` object.   *encoding*, if specified,
    must be a string naming the encoding  used by the XML data.  Expat doesn't

Doc/library/python.rst

@@ -1,4 +1,3 @@
-
 .. _python:
 
 ***********************

Doc/library/queue.rst

@@ -1,4 +1,3 @@
-
 :mod:`queue` --- A synchronized queue class
 ===========================================
 
@@ -100,7 +99,7 @@ provide the public methods described below.
    guarantee that a subsequent call to put() will not block.
 
 
-.. method:: Queue.put(item[, block[, timeout]])
+.. method:: Queue.put(item, block=True, timeout=None)
 
    Put *item* into the queue. If optional args *block* is true and *timeout* is
    None (the default), block if necessary until a free slot is available. If
@@ -116,7 +115,7 @@ provide the public methods described below.
    Equivalent to ``put(item, False)``.
 
 
-.. method:: Queue.get([block[, timeout]])
+.. method:: Queue.get(block=True, timeout=None)
 
    Remove and return an item from the queue. If optional args *block* is true and
    *timeout* is None (the default), block if necessary until an item is available.

Doc/library/quopri.rst

@@ -1,4 +1,3 @@
-
 :mod:`quopri` --- Encode and decode MIME quoted-printable data
 ==============================================================
 
@@ -19,7 +18,7 @@ few nonprintable characters; the base64 encoding scheme available via the
 sending a graphics file.
 
 
-.. function:: decode(input, output[,header])
+.. function:: decode(input, output, header=False)
 
    Decode the contents of the *input* file and write the resulting decoded binary
    data to the *output* file. *input* and *output* must either be file objects or
@@ -30,7 +29,7 @@ sending a graphics file.
    Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text".
 
 
-.. function:: encode(input, output, quotetabs)
+.. function:: encode(input, output, quotetabs, header=False)
 
    Encode the contents of the *input* file and write the resulting quoted-printable
    data to the *output* file. *input* and *output* must either be file objects or
@@ -38,20 +37,22 @@ sending a graphics file.
    ``input.readline()`` returns an empty string. *quotetabs* is a flag which
    controls whether to encode embedded spaces and tabs; when true it encodes such
    embedded whitespace, and when false it leaves them unencoded.  Note that spaces
-   and tabs appearing at the end of lines are always encoded, as per :rfc:`1521`.
+   and tabs appearing at the end of lines are always encoded, as per
+   :rfc:`1521`.  *header* is a flag which controls if spaces are encoded as
+   underscores as per :rfc:`1522`.
 
 
-.. function:: decodestring(s[,header])
+.. function:: decodestring(s, header=False)
 
    Like :func:`decode`, except that it accepts a source string and returns the
    corresponding decoded string.
 
 
-.. function:: encodestring(s[, quotetabs])
+.. function:: encodestring(s, quotetabs=False, header=False)
 
    Like :func:`encode`, except that it accepts a source string and returns the
-   corresponding encoded string.  *quotetabs* is optional (defaulting to 0), and is
+   corresponding encoded string.  *quotetabs* and *header* are optional
-   passed straight through to :func:`encode`.
+   (defaulting to ``False``), and are passed straight through to :func:`encode`.
 
 
 .. seealso::

Doc/library/random.rst

@@ -1,4 +1,3 @@
-
 :mod:`random` --- Generate pseudo-random numbers
 ================================================
 

Doc/library/re.rst

@@ -1,4 +1,3 @@
-
 :mod:`re` --- Regular expression operations
 ===========================================
 
@@ -446,7 +445,7 @@ regular expressions.  Most non-trivial applications always use the compiled
 form.
 
 
-.. function:: compile(pattern[, flags])
+.. function:: compile(pattern, flags=0)
 
    Compile a regular expression pattern into a regular expression object, which
    can be used for matching using its :func:`match` and :func:`search` methods,
@@ -556,7 +555,7 @@ form.
    string.
 
 
-.. function:: match(pattern, string[, flags])
+.. function:: match(pattern, string, flags=0)
 
    If zero or more characters at the beginning of *string* match the regular
    expression *pattern*, return a corresponding :class:`MatchObject` instance.
@@ -569,7 +568,7 @@ form.
       instead.
 
 
-.. function:: split(pattern, string[, maxsplit=0, flags=0])
+.. function:: split(pattern, string, maxsplit=0, flags=0)
 
    Split *string* by the occurrences of *pattern*.  If capturing parentheses are
    used in *pattern*, then the text of all groups in the pattern are also returned
@@ -609,7 +608,7 @@ form.
       Added the optional flags argument.
 
 
-.. function:: findall(pattern, string[, flags])
+.. function:: findall(pattern, string, flags=0)
 
    Return all non-overlapping matches of *pattern* in *string*, as a list of
    strings.  The *string* is scanned left-to-right, and matches are returned in
@@ -619,7 +618,7 @@ form.
    beginning of another match.
 
 
-.. function:: finditer(pattern, string[, flags])
+.. function:: finditer(pattern, string, flags=0)
 
    Return an :term:`iterator` yielding :class:`MatchObject` instances over all
    non-overlapping matches for the RE *pattern* in *string*.  The *string* is
@@ -628,7 +627,7 @@ form.
    match.
 
 
-.. function:: sub(pattern, repl, string[, count, flags])
+.. function:: sub(pattern, repl, string, count=0, flags=0)
 
    Return the string obtained by replacing the leftmost non-overlapping occurrences
    of *pattern* in *string* by the replacement *repl*.  If the pattern isn't found,
@@ -677,7 +676,7 @@ form.
       Added the optional flags argument.
 
 
-.. function:: subn(pattern, repl, string[, count, flags])
+.. function:: subn(pattern, repl, string, count=0, flags=0)
 
    Perform the same operation as :func:`sub`, but return a tuple ``(new_string,
    number_of_subs_made)``.
@@ -752,7 +751,7 @@ attributes:
    :meth:`~RegexObject.match` method.
 
 
-.. method:: RegexObject.split(string[, maxsplit=0])
+.. method:: RegexObject.split(string, maxsplit=0)
 
    Identical to the :func:`split` function, using the compiled pattern.
 
@@ -767,12 +766,12 @@ attributes:
    Identical to the :func:`finditer` function, using the compiled pattern.
 
 
-.. method:: RegexObject.sub(repl, string[, count=0])
+.. method:: RegexObject.sub(repl, string, count=0)
 
    Identical to the :func:`sub` function, using the compiled pattern.
 
 
-.. method:: RegexObject.subn(repl, string[, count=0])
+.. method:: RegexObject.subn(repl, string, count=0)
 
    Identical to the :func:`subn` function, using the compiled pattern.
 
@@ -870,7 +869,7 @@ support the following methods and attributes:
       'c3'
 
 
-.. method:: MatchObject.groups([default])
+.. method:: MatchObject.groups(default=None)
 
    Return a tuple containing all the subgroups of the match, from 1 up to however
    many groups are in the pattern.  The *default* argument is used for groups that
@@ -893,7 +892,7 @@ support the following methods and attributes:
       ('24', '0')
 
 
-.. method:: MatchObject.groupdict([default])
+.. method:: MatchObject.groupdict(default=None)
 
    Return a dictionary containing all the *named* subgroups of the match, keyed by
    the subgroup name.  The *default* argument is used for groups that did not
@@ -904,8 +903,8 @@ support the following methods and attributes:
       {'first_name': 'Malcom', 'last_name': 'Reynolds'}
 
 
-.. method:: MatchObject.start([group])
+.. method:: MatchObject.start(group=0)
-            MatchObject.end([group])
+            MatchObject.end(group=0)
 
    Return the indices of the start and end of the substring matched by *group*;
    *group* defaults to zero (meaning the whole matched substring). Return ``-1`` if
@@ -928,7 +927,7 @@ support the following methods and attributes:
       'tony@tiger.net'
 
 
-.. method:: MatchObject.span([group])
+.. method:: MatchObject.span(group=0)
 
    For :class:`MatchObject` *m*, return the 2-tuple ``(m.start(group),
    m.end(group))``. Note that if *group* did not contribute to the match, this is

Doc/library/readline.rst

@@ -1,4 +1,3 @@
-
 :mod:`readline` --- GNU readline interface
 ==========================================
 

Doc/library/reprlib.rst

@@ -1,7 +1,6 @@
 :mod:`reprlib` --- Alternate :func:`repr` implementation
 ========================================================
 
-
 .. module:: reprlib
    :synopsis: Alternate repr() implementation with size limits.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

Doc/library/resource.rst

@@ -1,4 +1,3 @@
-
 :mod:`resource` --- Resource usage information
 ==============================================
 

Doc/library/rlcompleter.rst

@@ -1,4 +1,3 @@
-
 :mod:`rlcompleter` --- Completion function for GNU readline
 ===========================================================
 

Doc/library/runpy.rst

@@ -19,7 +19,7 @@ When executed as a script, the module effectively operates as follows::
 The :mod:`runpy` module provides a single function:
 
 
-.. function:: run_module(mod_name[, init_globals] [, run_name][, alter_sys])
+.. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)
 
    Execute the code of the specified module and return the resulting module globals
    dictionary. The module's code is first located using the standard import

Doc/library/select.rst

@@ -1,4 +1,3 @@
-
 :mod:`select` --- Waiting for I/O completion
 ============================================
 
@@ -24,7 +23,7 @@ The module defines the following:
    string, as would be printed by the C function :cfunc:`perror`.
 
 
-.. function:: epoll([sizehint=-1])
+.. function:: epoll(sizehint=-1)
 
    (Only supported on Linux 2.5.44 and newer.)  Returns an edge polling object,
    which can be used as Edge or Level Triggered interface for I/O events; see

Doc/library/shelve.rst

@@ -14,7 +14,7 @@ This includes most class instances, recursive data types, and objects containing
 lots of shared  sub-objects.  The keys are ordinary strings.
 
 
-.. function:: open(filename[, flag='c'[, protocol=None[, writeback=False]]])
+.. function:: open(filename, flag='c', protocol=None, writeback=False)
 
    Open a persistent dictionary.  The filename specified is the base filename for
    the underlying database.  As a side-effect, an extension may be added to the
@@ -84,7 +84,7 @@ Restrictions
   implementation used.
 
 
-.. class:: Shelf(dict[, protocol=None[, writeback=False]])
+.. class:: Shelf(dict, protocol=None, writeback=False)
 
    A subclass of :class:`collections.MutableMapping` which stores pickled values
    in the *dict* object.
@@ -99,7 +99,7 @@ Restrictions
    memory and make sync and close take a long time.
 
 
-.. class:: BsdDbShelf(dict[, protocol=None[, writeback=False]])
+.. class:: BsdDbShelf(dict, protocol=None, writeback=False)
 
    A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`!next`,
    :meth:`previous`, :meth:`last` and :meth:`set_location` which are available
@@ -112,7 +112,7 @@ Restrictions
    as for the :class:`Shelf` class.
 
 
-.. class:: DbfilenameShelf(filename[, flag='c'[, protocol=None[, writeback=False]]])
+.. class:: DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)
 
    A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like
    object.  The underlying file will be opened using :func:`dbm.open`.  By

Doc/library/shlex.rst

@@ -1,4 +1,3 @@
-
 :mod:`shlex` --- Simple lexical analysis
 ========================================
 
@@ -18,7 +17,7 @@ applications) or for parsing quoted strings.
 The :mod:`shlex` module defines the following functions:
 
 
-.. function:: split(s[, comments[, posix]])
+.. function:: split(s, comments=False, posix=True)
 
    Split the string *s* using shell-like syntax. If *comments* is :const:`False`
    (the default), the parsing of comments in the given string will be disabled
@@ -28,13 +27,14 @@ The :mod:`shlex` module defines the following functions:
 
    .. note::
 
-      Since the :func:`split` function instantiates a :class:`shlex` instance, passing
+      Since the :func:`split` function instantiates a :class:`shlex` instance,
-      ``None`` for *s* will read the string to split from standard input.
+      passing ``None`` for *s* will read the string to split from standard
+      input.
 
 The :mod:`shlex` module defines the following class:
 
 
-.. class:: shlex([instream[, infile[, posix]]])
+.. class:: shlex(instream=None, infile=None, posix=False)
 
    A :class:`shlex` instance or subclass instance is a lexical analyzer object.
    The initialization argument, if present, specifies where to read characters
@@ -111,7 +111,7 @@ A :class:`shlex` instance has the following methods:
    :meth:`pop_source` methods.
 
 
-.. method:: shlex.push_source(stream[, filename])
+.. method:: shlex.push_source(newstream, newfile=None)
 
    Push an input source stream onto the input stack.  If the filename argument is
    specified it will later be available for use in error messages.  This is the
@@ -124,7 +124,7 @@ A :class:`shlex` instance has the following methods:
    used internally when the lexer reaches EOF on a stacked input stream.
 
 
-.. method:: shlex.error_leader([file[, line]])
+.. method:: shlex.error_leader(infile=None, lineno=None)
 
    This method generates an error message leader in the format of a Unix C compiler
    error label; the format is ``'"%s", line %d: '``, where the ``%s`` is replaced

Doc/library/shutil.rst

@@ -1,4 +1,3 @@
-
 :mod:`shutil` --- High-level file operations
 ============================================
 
@@ -86,7 +85,7 @@ copying and removal. For operations on individual files, see also the
    match one of the glob-style *patterns* provided.  See the example below.
 
 
-.. function:: copytree(src, dst[, symlinks=False[, ignore=None]])
+.. function:: copytree(src, dst, symlinks=False, ignore=None)
 
    Recursively copy an entire directory tree rooted at *src*.  The destination
    directory, named by *dst*, must not already exist; it will be created as well
@@ -114,7 +113,7 @@ copying and removal. For operations on individual files, see also the
    ultimate tool.
 
 
-.. function:: rmtree(path[, ignore_errors[, onerror]])
+.. function:: rmtree(path, ignore_errors=False, onerror=None)
 
    .. index:: single: directory; deleting
 

Doc/library/signal.rst

@@ -1,4 +1,3 @@
-
 :mod:`signal` --- Set handlers for asynchronous events
 ======================================================
 
@@ -82,7 +81,8 @@ The variables defined in the :mod:`signal` module are:
 
 .. data:: ITIMER_REAL
 
-   Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration.
+   Decrements interval timer in real time, and delivers :const:`SIGALRM` upon
+   expiration.
 
 
 .. data:: ITIMER_VIRTUAL
@@ -182,14 +182,14 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: siginterrupt(signalnum, flag)
 
-   Change system call restart behaviour: if *flag* is :const:`False`, system calls
+   Change system call restart behaviour: if *flag* is :const:`False`, system
-   will be restarted when interrupted by signal *signalnum*, otherwise system calls will
+   calls will be restarted when interrupted by signal *signalnum*, otherwise
-   be interrupted. Returns nothing. Availability: Unix (see the man page
+   system calls will be interrupted. Returns nothing. Availability: Unix (see
-   :manpage:`siginterrupt(3)` for further information).
+   the man page :manpage:`siginterrupt(3)` for further information).
 
-   Note that installing a signal handler with :func:`signal` will reset the restart
+   Note that installing a signal handler with :func:`signal` will reset the
-   behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
+   restart behaviour to interruptible by implicitly calling
-   value for the given signal.
+   :cfunc:`siginterrupt` with a true *flag* value for the given signal.
 
 
 .. function:: signal(signalnum, handler)

Doc/library/site.rst

@@ -1,4 +1,3 @@
-
 :mod:`site` --- Site-specific configuration hook
 ================================================
 
@@ -142,6 +141,6 @@ empty, and the path manipulations are skipped; however the import of
 
    .. versionadded:: 2.7
 
-XXX Update documentation
+.. XXX Update documentation
-XXX document python -m site --user-base --user-site
+.. XXX document python -m site --user-base --user-site
 

Doc/library/smtplib.rst

@@ -1,4 +1,3 @@
-
 :mod:`smtplib` --- SMTP protocol client
 =======================================
 
@@ -17,7 +16,7 @@ details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer
 Protocol) and :rfc:`1869` (SMTP Service Extensions).
 
 
-.. class:: SMTP([host[, port[, local_hostname[, timeout]]]])
+.. class:: SMTP(host='', port=0, local_hostname=None[, timeout])
 
    A :class:`SMTP` instance encapsulates an SMTP connection.  It has methods
    that support a full repertoire of SMTP and ESMTP operations. If the optional
@@ -32,13 +31,13 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    :meth:`sendmail`, and :meth:`quit` methods.  An example is included below.
 
 
-.. class:: SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])
+.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout])
 
    A :class:`SMTP_SSL` instance behaves exactly the same as instances of
    :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
    required from the beginning of the connection and using :meth:`starttls` is
    not appropriate. If *host* is not specified, the local host is used. If
-   *port* is omitted, the standard SMTP-over-SSL port (465) is used. *keyfile*
+   *port* is zero, the standard SMTP-over-SSL port (465) is used. *keyfile*
    and *certfile* are also optional, and can contain a PEM formatted private key
    and certificate chain file for the SSL connection. The optional *timeout*
    parameter specifies a timeout in seconds for blocking operations like the
@@ -46,7 +45,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    will be used).
 
 
-.. class:: LMTP([host[, port[, local_hostname]]])
+.. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None)
 
    The LMTP protocol, which is very similar to ESMTP, is heavily based on the
    standard SMTP client. It's common to use Unix sockets for LMTP, so our :meth:`connect`
@@ -142,7 +141,7 @@ An :class:`SMTP` instance has the following methods:
    for connection and for all messages sent to and received from the server.
 
 
-.. method:: SMTP.connect([host[, port]])
+.. method:: SMTP.connect(host='localhost', port=0)
 
    Connect to a host on a given port.  The defaults are to connect to the local
    host at the standard SMTP port (25). If the hostname ends with a colon (``':'``)
@@ -151,9 +150,9 @@ An :class:`SMTP` instance has the following methods:
    the constructor if a host is specified during instantiation.
 
 
-.. method:: SMTP.docmd(cmd, [, argstring])
+.. method:: SMTP.docmd(cmd, args='')
 
-   Send a command *cmd* to the server.  The optional argument *argstring* is simply
+   Send a command *cmd* to the server.  The optional argument *args* is simply
    concatenated to the command, separated by a space.
 
    This returns a 2-tuple composed of a numeric response code and the actual
@@ -167,7 +166,7 @@ An :class:`SMTP` instance has the following methods:
    :exc:`SMTPServerDisconnected` will be raised.
 
 
-.. method:: SMTP.helo([hostname])
+.. method:: SMTP.helo(name='')
 
    Identify yourself to the SMTP server using ``HELO``.  The hostname argument
    defaults to the fully qualified domain name of the local host.
@@ -178,7 +177,7 @@ An :class:`SMTP` instance has the following methods:
    It will be implicitly called by the :meth:`sendmail` when necessary.
 
 
-.. method:: SMTP.ehlo([hostname])
+.. method:: SMTP.ehlo(name='')
 
    Identify yourself to an ESMTP server using ``EHLO``.  The hostname argument
    defaults to the fully qualified domain name of the local host.  Examine the
@@ -239,7 +238,7 @@ An :class:`SMTP` instance has the following methods:
       No suitable authentication method was found.
 
 
-.. method:: SMTP.starttls([keyfile[, certfile]])
+.. method:: SMTP.starttls(keyfile=None, certfile=None)
 
    Put the SMTP connection in TLS (Transport Layer Security) mode.  All SMTP
    commands that follow will be encrypted.  You should then call :meth:`ehlo`
@@ -261,7 +260,7 @@ An :class:`SMTP` instance has the following methods:
      SSL/TLS support is not available to your python interpreter.
 
 
-.. method:: SMTP.sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])
+.. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_options=[])
 
    Send mail.  The required arguments are an :rfc:`822` from-address string, a list
    of :rfc:`822` to-address strings (a bare string will be treated as a list with 1

Doc/library/sndhdr.rst

@@ -1,4 +1,3 @@
-
 :mod:`sndhdr` --- Determine type of sound file
 ==============================================
 

Doc/library/socket.rst

@@ -1,4 +1,3 @@
-
 :mod:`socket` --- Low-level networking interface
 ================================================
 

Doc/library/socketserver.rst

@@ -1,4 +1,3 @@
-
 :mod:`socketserver` --- A framework for network servers
 =======================================================