Switch more function arguments docs to new-style.

f3d51f74 · Georg Brandl · 08dbd3e2 · f3d51f74 · f3d51f74 · f3d51f74
Commit f3d51f74 authored Sep 02, 2009 by Georg Brandl
39 changed files
--- a/Doc/library/os.path.rst
+++ b/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.

--- a/Doc/library/os.rst
+++ b/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

--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
 :mod:`ossaudiodev` --- Access to OSS-compatible audio devices
 =============================================================

--- a/Doc/library/parser.rst
+++ b/Doc/library/parser.rst
 :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:

--- a/Doc/library/pdb.rst
+++ b/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.

--- a/Doc/library/persistence.rst
+++ b/Doc/library/persistence.rst
 .. _persistence:
 ****************

--- a/Doc/library/pickle.rst
+++ b/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.

--- a/Doc/library/pickletools.rst
+++ b/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.

--- a/Doc/library/pipes.rst
+++ b/Doc/library/pipes.rst
 :mod:`pipes` --- Interface to shell pipelines
 =============================================

--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
 :mod:`pkgutil` --- Package extension utility
 ============================================

--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
 :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

--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
 :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',

--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
 .. _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::
-   The :class:`Stats` class is defined in the :mod:`pstats` module.
+Analysis of the profiler data is done using the :class:`pstats.Stats` class.
 .. 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

--- a/Doc/library/pty.rst
+++ b/Doc/library/pty.rst
 :mod:`pty` --- Pseudo-terminal utilities
 ========================================

--- a/Doc/library/pwd.rst
+++ b/Doc/library/pwd.rst
 :mod:`pwd` --- The password database
 ====================================

--- a/Doc/library/py_compile.rst
+++ b/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.

--- a/Doc/library/pyclbr.rst
+++ b/Doc/library/pyclbr.rst
 :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

--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
 :mod:`pydoc` --- Documentation generator and online help system
 ===============================================================

--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
 :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

--- a/Doc/library/python.rst
+++ b/Doc/library/python.rst
 .. _python:
 ***********************

--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
 :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.

--- a/Doc/library/quopri.rst
+++ b/Doc/library/quopri.rst
 :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::

--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
 :mod:`random` --- Generate pseudo-random numbers
 ================================================

--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
 :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

--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
 :mod:`readline` --- GNU readline interface
 ==========================================

--- a/Doc/library/reprlib.rst
+++ b/Doc/library/reprlib.rst
 :mod:`reprlib` --- Alternate :func:`repr` implementation
 ========================================================
 .. module:: reprlib
   :synopsis: Alternate repr() implementation with size limits.
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
 :mod:`resource` --- Resource usage information
 ==============================================

--- a/Doc/library/rlcompleter.rst
+++ b/Doc/library/rlcompleter.rst
 :mod:`rlcompleter` --- Completion function for GNU readline
 ===========================================================

--- a/Doc/library/runpy.rst
+++ b/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

--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
 :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

--- a/Doc/library/shelve.rst
+++ b/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

--- a/Doc/library/shlex.rst
+++ b/Doc/library/shlex.rst
 :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

--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
 :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

--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
 :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)

--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
 :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
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
 :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

--- a/Doc/library/sndhdr.rst
+++ b/Doc/library/sndhdr.rst
 :mod:`sndhdr` --- Determine type of sound file
 ==============================================

--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
 :mod:`socket` --- Low-level networking interface
 ================================================

--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
 :mod:`socketserver` --- A framework for network servers
 =======================================================