diff options
39 files changed, 134 insertions, 160 deletions
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 @@ 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. 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 @@ 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 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 @@ 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: 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 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. 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 @@ 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. 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 @@ 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. 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 @@ 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 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 @@ 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', 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 @@ 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 - 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 @@ 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 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 @@ 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. 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 @@ 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 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 @@ 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 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 @@ 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. 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 @@ 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 - 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 @@ 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]) - 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 @@ 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 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 @@ 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 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 @@ 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 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 @@ 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 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 @@ 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 - ``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 @@ 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 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 @@ 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 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 @@ 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 - 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 @@ empty, and the path manipulations are skipped; however the import of .. 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 @@ 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 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 ======================================================= |