Switch more function arguments docs to new-style.
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 6d177f8..8f82963 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -218,7 +218,7 @@
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.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9bed1ce..aa95d1d 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -204,18 +204,17 @@
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 @@
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 @@
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 @@
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
diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst
index 3972f14..82a263f 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -1,4 +1,3 @@
-
:mod:`ossaudiodev` --- Access to OSS-compatible audio devices
=============================================================
diff --git a/Doc/library/parser.rst b/Doc/library/parser.rst
index 5aad938..df3a31c 100644
--- a/Doc/library/parser.rst
+++ b/Doc/library/parser.rst
@@ -1,4 +1,3 @@
-
:mod:`parser` --- Access Python parse trees
===========================================
@@ -165,7 +164,7 @@
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 @@
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 @@
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 have the following methods:
-.. method:: ST.compile([filename])
+.. method:: ST.compile(filename='<syntax-tree>')
Same as ``compilest(st, filename)``.
@@ -308,14 +307,14 @@
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:
diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index 678ae28..f4d0dd6 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -79,7 +79,7 @@
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 @@
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 @@
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 @@
.. 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.
diff --git a/Doc/library/persistence.rst b/Doc/library/persistence.rst
index b90b2e1..d5bb193 100644
--- a/Doc/library/persistence.rst
+++ b/Doc/library/persistence.rst
@@ -1,4 +1,3 @@
-
.. _persistence:
****************
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 21e4001..99e30c6 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -141,7 +141,7 @@
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 @@
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 @@
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 @@
*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 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 @@
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.
diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst
index 88ecbab..0f6933b 100644
--- 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 @@
: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.
diff --git a/Doc/library/pipes.rst b/Doc/library/pipes.rst
index 1f2b2ff..7e1ff9e 100644
--- a/Doc/library/pipes.rst
+++ b/Doc/library/pipes.rst
@@ -1,4 +1,3 @@
-
:mod:`pipes` --- Interface to shell pipelines
=============================================
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst
index 48d53e3..c097749 100644
--- a/Doc/library/pkgutil.rst
+++ b/Doc/library/pkgutil.rst
@@ -1,4 +1,3 @@
-
:mod:`pkgutil` --- Package extension utility
============================================
diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index 0b2c033..b397b4b 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -1,4 +1,3 @@
-
:mod:`poplib` --- POP3 protocol client
======================================
@@ -24,7 +23,7 @@
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 @@
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 @@
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
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index d1d1bae..932be75 100644
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -1,4 +1,3 @@
-
:mod:`pprint` --- Data pretty printer
=====================================
@@ -27,7 +26,7 @@
.. 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 @@
>>> 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[, 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 @@
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',
diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst
index 132365a..e465b56 100644
--- a/Doc/library/profile.rst
+++ b/Doc/library/profile.rst
@@ -1,4 +1,3 @@
-
.. _profile:
********************
@@ -235,7 +234,7 @@
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 @@
for the number of calls,
tottime
- for the total time spent in the given function (and excluding time made in calls
- to sub-functions),
+ for the total time spent in the given function (and excluding time made in
+ calls to sub-functions),
percall
is the quotient of ``tottime`` divided by ``ncalls``
@@ -285,24 +284,25 @@
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 @@
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 @@
: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 @@
.. 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 @@
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 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
diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst
index 6579ef0..ac965ff 100644
--- a/Doc/library/pty.rst
+++ b/Doc/library/pty.rst
@@ -1,4 +1,3 @@
-
:mod:`pty` --- Pseudo-terminal utilities
========================================
diff --git a/Doc/library/pwd.rst b/Doc/library/pwd.rst
index 562afd9..2c17d9e 100644
--- a/Doc/library/pwd.rst
+++ b/Doc/library/pwd.rst
@@ -1,4 +1,3 @@
-
:mod:`pwd` --- The password database
====================================
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst
index 0891862..c4f7229 100644
--- a/Doc/library/py_compile.rst
+++ b/Doc/library/py_compile.rst
@@ -22,7 +22,7 @@
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 @@
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.
diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst
index 36b46f4..11a0b6d 100644
--- a/Doc/library/pyclbr.rst
+++ b/Doc/library/pyclbr.rst
@@ -1,4 +1,3 @@
-
:mod:`pyclbr` --- Python class browser support
==============================================
@@ -17,7 +16,7 @@
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 @@
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
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index 1701662..b43f84d 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -1,4 +1,3 @@
-
:mod:`pydoc` --- Documentation generator and online help system
===============================================================
diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst
index 6fe60ad..aaa389a 100644
--- a/Doc/library/pyexpat.rst
+++ b/Doc/library/pyexpat.rst
@@ -1,4 +1,3 @@
-
:mod:`xml.parsers.expat` --- Fast XML parsing using Expat
=========================================================
@@ -56,7 +55,7 @@
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
diff --git a/Doc/library/python.rst b/Doc/library/python.rst
index 7d4d827..7888dd0 100644
--- a/Doc/library/python.rst
+++ b/Doc/library/python.rst
@@ -1,4 +1,3 @@
-
.. _python:
***********************
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index e16d6e9..63ef1ec 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -1,4 +1,3 @@
-
:mod:`queue` --- A synchronized queue class
===========================================
@@ -100,7 +99,7 @@
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 @@
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.
diff --git a/Doc/library/quopri.rst b/Doc/library/quopri.rst
index 8f525ef..7ceb661 100644
--- a/Doc/library/quopri.rst
+++ b/Doc/library/quopri.rst
@@ -1,4 +1,3 @@
-
:mod:`quopri` --- Encode and decode MIME quoted-printable data
==============================================================
@@ -19,7 +18,7 @@
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 @@
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 @@
``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
- passed straight through to :func:`encode`.
+ corresponding encoded string. *quotetabs* and *header* are optional
+ (defaulting to ``False``), and are passed straight through to :func:`encode`.
.. seealso::
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 6c7a04d..2ce2c85 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -1,4 +1,3 @@
-
:mod:`random` --- Generate pseudo-random numbers
================================================
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index ea6563b..e7ba899 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -1,4 +1,3 @@
-
:mod:`re` --- Regular expression operations
===========================================
@@ -446,7 +445,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
: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 @@
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 @@
'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 @@
('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 @@
{'first_name': 'Malcom', 'last_name': 'Reynolds'}
-.. method:: MatchObject.start([group])
- MatchObject.end([group])
+.. method:: MatchObject.start(group=0)
+ 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 @@
'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
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 5399d3e..6cc69a1 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -1,4 +1,3 @@
-
:mod:`readline` --- GNU readline interface
==========================================
diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst
index 17a6ac4..b529aca 100644
--- a/Doc/library/reprlib.rst
+++ b/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>
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index fbd7204..602bd44 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -1,4 +1,3 @@
-
:mod:`resource` --- Resource usage information
==============================================
diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst
index 6b3befc..48ca50e 100644
--- a/Doc/library/rlcompleter.rst
+++ b/Doc/library/rlcompleter.rst
@@ -1,4 +1,3 @@
-
:mod:`rlcompleter` --- Completion function for GNU readline
===========================================================
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
index 6feb4b1..a5bfb8d 100644
--- a/Doc/library/runpy.rst
+++ b/Doc/library/runpy.rst
@@ -19,7 +19,7 @@
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
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 2b2c890..e0e9299 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -1,4 +1,3 @@
-
:mod:`select` --- Waiting for I/O completion
============================================
@@ -24,7 +23,7 @@
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
diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst
index 35ed84c..aa402c4 100644
--- a/Doc/library/shelve.rst
+++ b/Doc/library/shelve.rst
@@ -14,7 +14,7 @@
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 @@
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 @@
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 @@
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
diff --git a/Doc/library/shlex.rst b/Doc/library/shlex.rst
index ee241f4..0bc99fd 100644
--- a/Doc/library/shlex.rst
+++ b/Doc/library/shlex.rst
@@ -1,4 +1,3 @@
-
:mod:`shlex` --- Simple lexical analysis
========================================
@@ -18,7 +17,7 @@
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 @@
.. note::
- Since the :func:`split` function instantiates a :class:`shlex` instance, passing
- ``None`` for *s* will read the string to split from standard input.
+ Since the :func:`split` function instantiates a :class:`shlex` instance,
+ 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 @@
: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 @@
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
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 7cf8550..7913975 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -1,4 +1,3 @@
-
:mod:`shutil` --- High-level file operations
============================================
@@ -86,7 +85,7 @@
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 @@
ultimate tool.
-.. function:: rmtree(path[, ignore_errors[, onerror]])
+.. function:: rmtree(path, ignore_errors=False, onerror=None)
.. index:: single: directory; deleting
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 7319ac9..4251702 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -1,4 +1,3 @@
-
:mod:`signal` --- Set handlers for asynchronous events
======================================================
@@ -82,7 +81,8 @@
.. 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 @@
.. function:: siginterrupt(signalnum, flag)
- Change system call restart behaviour: if *flag* is :const:`False`, system calls
- will be restarted when interrupted by signal *signalnum*, otherwise system calls will
- be interrupted. Returns nothing. Availability: Unix (see the man page
- :manpage:`siginterrupt(3)` for further information).
+ Change system call restart behaviour: if *flag* is :const:`False`, system
+ calls will be restarted when interrupted by signal *signalnum*, otherwise
+ system calls will be interrupted. Returns nothing. Availability: Unix (see
+ the man page :manpage:`siginterrupt(3)` for further information).
- Note that installing a signal handler with :func:`signal` will reset the restart
- behaviour to interruptible by implicitly calling :cfunc:`siginterrupt` with a true *flag*
- value for the given signal.
+ Note that installing a signal handler with :func:`signal` will reset the
+ restart behaviour to interruptible by implicitly calling
+ :cfunc:`siginterrupt` with a true *flag* value for the given signal.
.. function:: signal(signalnum, handler)
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index 82184cb..e82edde 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -1,4 +1,3 @@
-
:mod:`site` --- Site-specific configuration hook
================================================
@@ -142,6 +141,6 @@
.. versionadded:: 2.7
-XXX Update documentation
-XXX document python -m site --user-base --user-site
+.. XXX Update documentation
+.. XXX document python -m site --user-base --user-site
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 070220e..79396f9 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -1,4 +1,3 @@
-
:mod:`smtplib` --- SMTP protocol client
=======================================
@@ -17,7 +16,7 @@
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 @@
: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 @@
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 @@
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 @@
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 @@
: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 @@
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 @@
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 @@
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
diff --git a/Doc/library/sndhdr.rst b/Doc/library/sndhdr.rst
index 01a3917..8535193 100644
--- a/Doc/library/sndhdr.rst
+++ b/Doc/library/sndhdr.rst
@@ -1,4 +1,3 @@
-
:mod:`sndhdr` --- Determine type of sound file
==============================================
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index e6ad578..dc4d897 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -1,4 +1,3 @@
-
:mod:`socket` --- Low-level networking interface
================================================
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 9e0e926..8fb2603 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -1,4 +1,3 @@
-
:mod:`socketserver` --- A framework for network servers
=======================================================