Switch more function arguments docs to new-style.

Author: birkenfeld

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*
-   if it doesn't.  *value* defaults to ``None``. Availability: most flavors of
-   Unix, Windows.
+   Return the value of the environment variable *key* if it exists, or
+   *default* if it doesn't.  Availability: most flavors of 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
-   be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
-   ``stat.S_IFCHR``, ``stat.S_IFBLK``,
-   and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
-   For ``stat.S_IFCHR`` and
-   ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
+   *filename*. *mode* specifies both the permissions to use and the type of node
+   to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
+   ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
+   available in :mod:`stat`).  For ``stat.S_IFCHR`` and ``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]])
-               runeval(expression[, globals[, locals]])
-               runcall(function[, argument, ...])
+   .. method:: run(statement, globals=None, locals=None)
+               runeval(expression, globals=None, locals=None)
+               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:
+The :class:`PrettyPrinter` class supports several derivative functions:
 
-.. function:: pformat(object[, indent[, width[, depth]]])
+.. function:: pformat(object, indent=1, width=80, depth=None)
 
    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',