Issue #18758: Fixed and improved cross-references.
This commit is contained in:
commit
98b28fddd8
|
@ -634,7 +634,8 @@ Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes
|
|||
(ABCs). You can then use :func:`isinstance` and :func:`issubclass` to check
|
||||
whether an instance or a class implements a particular ABC. The
|
||||
:mod:`collections.abc` module defines a set of useful ABCs such as
|
||||
:class:`Iterable`, :class:`Container`, and :class:`MutableMapping`.
|
||||
:class:`~collections.abc.Iterable`, :class:`~collections.abc.Container`, and
|
||||
:class:`~collections.abc.MutableMapping`.
|
||||
|
||||
For Python, many of the advantages of interface specifications can be obtained
|
||||
by an appropriate test discipline for components. There is also a tool,
|
||||
|
|
|
@ -531,9 +531,10 @@ The solution would be to use the low-level decoding interface to catch the case
|
|||
of partial coding sequences. The work of implementing this has already been
|
||||
done for you: the built-in :func:`open` function can return a file-like object
|
||||
that assumes the file's contents are in a specified encoding and accepts Unicode
|
||||
parameters for methods such as :meth:`read` and :meth:`write`. This works through
|
||||
:func:`open`\'s *encoding* and *errors* parameters which are interpreted just
|
||||
like those in :meth:`str.encode` and :meth:`bytes.decode`.
|
||||
parameters for methods such as :meth:`~io.TextIOBase.read` and
|
||||
:meth:`~io.TextIOBase.write`. This works through:func:`open`\'s *encoding* and
|
||||
*errors* parameters which are interpreted just like those in :meth:`str.encode`
|
||||
and :meth:`bytes.decode`.
|
||||
|
||||
Reading Unicode from a file is therefore simple::
|
||||
|
||||
|
@ -656,7 +657,8 @@ encodings, taking a stream that returns data in encoding #1
|
|||
and behaving like a stream returning data in encoding #2.
|
||||
|
||||
For example, if you have an input file *f* that's in Latin-1, you
|
||||
can wrap it with a :class:`StreamRecoder` to return bytes encoded in UTF-8::
|
||||
can wrap it with a :class:`~codecs.StreamRecoder` to return bytes encoded in
|
||||
UTF-8::
|
||||
|
||||
new_f = codecs.StreamRecoder(f,
|
||||
# en/decoder: used by read() to encode its results and
|
||||
|
|
|
@ -57,7 +57,7 @@ The simplest way to use urllib.request is as follows::
|
|||
html = response.read()
|
||||
|
||||
If you wish to retrieve a resource via URL and store it in a temporary location,
|
||||
you can do so via the :func:`urlretrieve` function::
|
||||
you can do so via the :func:`~urllib.request.urlretrieve` function::
|
||||
|
||||
import urllib.request
|
||||
local_filename, headers = urllib.request.urlretrieve('http://python.org/')
|
||||
|
|
|
@ -290,11 +290,11 @@ and off individually. They are described here in more detail.
|
|||
|
||||
Converts the use of iterator's :meth:`~iterator.next` methods to the
|
||||
:func:`next` function. It also renames :meth:`next` methods to
|
||||
:meth:`~object.__next__`.
|
||||
:meth:`~iterator.__next__`.
|
||||
|
||||
.. 2to3fixer:: nonzero
|
||||
|
||||
Renames :meth:`~object.__nonzero__` to :meth:`~object.__bool__`.
|
||||
Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
|
||||
|
||||
.. 2to3fixer:: numliterals
|
||||
|
||||
|
|
|
@ -177,7 +177,7 @@ In addition to these methods, lock objects can also be used via the
|
|||
equivalent to calling :func:`_thread.exit`.
|
||||
|
||||
* Not all built-in functions that may block waiting for I/O allow other threads
|
||||
to run. (The most popular ones (:func:`time.sleep`, :meth:`file.read`,
|
||||
to run. (The most popular ones (:func:`time.sleep`, :meth:`io.FileIO.read`,
|
||||
:func:`select.select`) work as expected.)
|
||||
|
||||
* It is not possible to interrupt the :meth:`acquire` method on a lock --- the
|
||||
|
|
|
@ -114,19 +114,19 @@ This module provides the following classes:
|
|||
MyIterable.register(Foo)
|
||||
|
||||
The ABC ``MyIterable`` defines the standard iterable method,
|
||||
:meth:`__iter__`, as an abstract method. The implementation given here can
|
||||
still be called from subclasses. The :meth:`get_iterator` method is also
|
||||
part of the ``MyIterable`` abstract base class, but it does not have to be
|
||||
overridden in non-abstract derived classes.
|
||||
:meth:`~iterator.__iter__`, as an abstract method. The implementation given
|
||||
here can still be called from subclasses. The :meth:`get_iterator` method
|
||||
is also part of the ``MyIterable`` abstract base class, but it does not have
|
||||
to be overridden in non-abstract derived classes.
|
||||
|
||||
The :meth:`__subclasshook__` class method defined here says that any class
|
||||
that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of
|
||||
one of its base classes, accessed via the :attr:`__mro__` list) is
|
||||
considered a ``MyIterable`` too.
|
||||
that has an :meth:`~iterator.__iter__` method in its
|
||||
:attr:`~object.__dict__` (or in that of one of its base classes, accessed
|
||||
via the :attr:`~class.__mro__` list) is considered a ``MyIterable`` too.
|
||||
|
||||
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
|
||||
even though it does not define an :meth:`__iter__` method (it uses the
|
||||
old-style iterable protocol, defined in terms of :meth:`__len__` and
|
||||
even though it does not define an :meth:`~iterator.__iter__` method (it uses
|
||||
the old-style iterable protocol, defined in terms of :meth:`__len__` and
|
||||
:meth:`__getitem__`). Note that this will not make ``get_iterator``
|
||||
available as a method of ``Foo``, so it is provided separately.
|
||||
|
||||
|
|
|
@ -53,10 +53,10 @@ any that have been added to the map during asynchronous service) is closed.
|
|||
channels have been closed. All arguments are optional. The *count*
|
||||
parameter defaults to None, resulting in the loop terminating only when all
|
||||
channels have been closed. The *timeout* argument sets the timeout
|
||||
parameter for the appropriate :func:`select` or :func:`poll` call, measured
|
||||
in seconds; the default is 30 seconds. The *use_poll* parameter, if true,
|
||||
indicates that :func:`poll` should be used in preference to :func:`select`
|
||||
(the default is ``False``).
|
||||
parameter for the appropriate :func:`~select.select` or :func:`~select.poll`
|
||||
call, measured in seconds; the default is 30 seconds. The *use_poll*
|
||||
parameter, if true, indicates that :func:`~select.poll` should be used in
|
||||
preference to :func:`~select.select` (the default is ``False``).
|
||||
|
||||
The *map* parameter is a dictionary whose items are the channels to watch.
|
||||
As channels are closed they are deleted from their map. If *map* is
|
||||
|
|
|
@ -241,7 +241,7 @@ to be stateless (i.e. to be able to tolerate packet loss) you should not only
|
|||
transmit the data but also the state. Note that you should send the *initial*
|
||||
state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
|
||||
final state (as returned by the coder). If you want to use
|
||||
:func:`struct.struct` to store the state in binary you can code the first
|
||||
:class:`struct.Struct` to store the state in binary you can code the first
|
||||
element (the predicted value) in 16 bits and the second (the delta index) in 8.
|
||||
|
||||
The ADPCM coders have never been tried against other ADPCM coders, only against
|
||||
|
|
|
@ -272,10 +272,11 @@ For simple text calendars this module provides the following functions.
|
|||
|
||||
.. function:: timegm(tuple)
|
||||
|
||||
An unrelated but handy function that takes a time tuple such as returned by the
|
||||
:func:`gmtime` function in the :mod:`time` module, and returns the corresponding
|
||||
Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In
|
||||
fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
|
||||
An unrelated but handy function that takes a time tuple such as returned by
|
||||
the :func:`~time.gmtime` function in the :mod:`time` module, and returns the
|
||||
corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX
|
||||
encoding. In fact, :func:`time.gmtime` and :func:`timegm` are each others'
|
||||
inverse.
|
||||
|
||||
|
||||
The :mod:`calendar` module exports the following data attributes:
|
||||
|
|
|
@ -54,8 +54,9 @@ instance will fail with a :exc:`EOFError` exception.
|
|||
|
||||
Class which represents a chunk. The *file* argument is expected to be a
|
||||
file-like object. An instance of this class is specifically allowed. The
|
||||
only method that is needed is :meth:`read`. If the methods :meth:`seek` and
|
||||
:meth:`tell` are present and don't raise an exception, they are also used.
|
||||
only method that is needed is :meth:`~io.IOBase.read`. If the methods
|
||||
:meth:`~io.IOBase.seek` and :meth:`~io.IOBase.tell` are present and don't
|
||||
raise an exception, they are also used.
|
||||
If these methods are present and raise an exception, they are expected to not
|
||||
have altered the object. If the optional argument *align* is true, chunks
|
||||
are assumed to be aligned on 2-byte boundaries. If *align* is false, no
|
||||
|
|
|
@ -29,13 +29,13 @@ build applications which provide an interactive interpreter prompt.
|
|||
|
||||
.. function:: interact(banner=None, readfunc=None, local=None)
|
||||
|
||||
Convenience function to run a read-eval-print loop. This creates a new instance
|
||||
of :class:`InteractiveConsole` and sets *readfunc* to be used as the
|
||||
:meth:`raw_input` method, if provided. If *local* is provided, it is passed to
|
||||
the :class:`InteractiveConsole` constructor for use as the default namespace for
|
||||
the interpreter loop. The :meth:`interact` method of the instance is then run
|
||||
with *banner* passed as the banner to use, if provided. The console object is
|
||||
discarded after use.
|
||||
Convenience function to run a read-eval-print loop. This creates a new
|
||||
instance of :class:`InteractiveConsole` and sets *readfunc* to be used as
|
||||
the :meth:`InteractiveConsole.raw_input` method, if provided. If *local* is
|
||||
provided, it is passed to the :class:`InteractiveConsole` constructor for
|
||||
use as the default namespace for the interpreter loop. The :meth:`interact`
|
||||
method of the instance is then run with *banner* passed as the banner to
|
||||
use, if provided. The console object is discarded after use.
|
||||
|
||||
|
||||
.. function:: compile_command(source, filename="<input>", symbol="single")
|
||||
|
|
|
@ -65,9 +65,9 @@ It defines the following functions:
|
|||
The various functions or classes take the following arguments:
|
||||
|
||||
*encode* and *decode*: These must be functions or methods which have the same
|
||||
interface as the :meth:`encode`/:meth:`decode` methods of Codec instances (see
|
||||
Codec Interface). The functions/methods are expected to work in a stateless
|
||||
mode.
|
||||
interface as the :meth:`~Codec.encode`/:meth:`~Codec.decode` methods of Codec
|
||||
instances (see :ref:`Codec Interface <codec-objects>`). The functions/methods
|
||||
are expected to work in a stateless mode.
|
||||
|
||||
*incrementalencoder* and *incrementaldecoder*: These have to be factory
|
||||
functions providing the following interface:
|
||||
|
@ -333,8 +333,8 @@ implement the file protocols.
|
|||
|
||||
The :class:`Codec` class defines the interface for stateless encoders/decoders.
|
||||
|
||||
To simplify and standardize error handling, the :meth:`encode` and
|
||||
:meth:`decode` methods may implement different error handling schemes by
|
||||
To simplify and standardize error handling, the :meth:`~Codec.encode` and
|
||||
:meth:`~Codec.decode` methods may implement different error handling schemes by
|
||||
providing the *errors* string argument. The following string values are defined
|
||||
and implemented by all standard Python codecs:
|
||||
|
||||
|
@ -428,12 +428,14 @@ interfaces of the stateless encoder and decoder:
|
|||
The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes provide
|
||||
the basic interface for incremental encoding and decoding. Encoding/decoding the
|
||||
input isn't done with one call to the stateless encoder/decoder function, but
|
||||
with multiple calls to the :meth:`encode`/:meth:`decode` method of the
|
||||
incremental encoder/decoder. The incremental encoder/decoder keeps track of the
|
||||
encoding/decoding process during method calls.
|
||||
with multiple calls to the
|
||||
:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method of
|
||||
the incremental encoder/decoder. The incremental encoder/decoder keeps track of
|
||||
the encoding/decoding process during method calls.
|
||||
|
||||
The joined output of calls to the :meth:`encode`/:meth:`decode` method is the
|
||||
same as if all the single inputs were joined into one, and this input was
|
||||
The joined output of calls to the
|
||||
:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method is
|
||||
the same as if all the single inputs were joined into one, and this input was
|
||||
encoded/decoded with the stateless encoder/decoder.
|
||||
|
||||
|
||||
|
|
|
@ -98,8 +98,9 @@ ABC Inherits from Abstract Methods Mixin
|
|||
|
||||
.. class:: Iterator
|
||||
|
||||
ABC for classes that provide the :meth:`__iter__` and :meth:`__next__` methods.
|
||||
See also the definition of :term:`iterator`.
|
||||
ABC for classes that provide the :meth:`~iterator.__iter__` and
|
||||
:meth:`~iterator.__next__` methods. See also the definition of
|
||||
:term:`iterator`.
|
||||
|
||||
.. class:: Sequence
|
||||
MutableSequence
|
||||
|
|
|
@ -979,9 +979,9 @@ reverse iteration using :func:`reversed`.
|
|||
Equality tests between :class:`OrderedDict` objects are order-sensitive
|
||||
and are implemented as ``list(od1.items())==list(od2.items())``.
|
||||
Equality tests between :class:`OrderedDict` objects and other
|
||||
:class:`Mapping` objects are order-insensitive like regular dictionaries.
|
||||
This allows :class:`OrderedDict` objects to be substituted anywhere a
|
||||
regular dictionary is used.
|
||||
:class:`~collections.abc.Mapping` objects are order-insensitive like regular
|
||||
dictionaries. This allows :class:`OrderedDict` objects to be substituted
|
||||
anywhere a regular dictionary is used.
|
||||
|
||||
The :class:`OrderedDict` constructor and :meth:`update` method both accept
|
||||
keyword arguments, but their order is lost because Python's function call
|
||||
|
|
|
@ -371,7 +371,8 @@ are changed on a section proxy, they are actually mutated in the original
|
|||
parser.
|
||||
|
||||
:mod:`configparser` objects behave as close to actual dictionaries as possible.
|
||||
The mapping interface is complete and adheres to the ``MutableMapping`` ABC.
|
||||
The mapping interface is complete and adheres to the
|
||||
:class:`~collections.abc.MutableMapping` ABC.
|
||||
However, there are a few differences that should be taken into account:
|
||||
|
||||
* By default, all keys in sections are accessible in a case-insensitive manner
|
||||
|
|
|
@ -317,8 +317,9 @@ The module defines the following:
|
|||
database has to be created. It defaults to octal ``0o666`` (and will be modified
|
||||
by the prevailing umask).
|
||||
|
||||
In addition to the methods provided by the :class:`collections.MutableMapping` class,
|
||||
:class:`dumbdbm` objects provide the following method:
|
||||
In addition to the methods provided by the
|
||||
:class:`collections.abc.MutableMapping` class, :class:`dumbdbm` objects
|
||||
provide the following method:
|
||||
|
||||
.. method:: dumbdbm.sync()
|
||||
|
||||
|
|
|
@ -143,8 +143,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
|
|||
|
||||
By default, the diff control lines (those with ``***`` or ``---``) are created
|
||||
with a trailing newline. This is helpful so that inputs created from
|
||||
:func:`file.readlines` result in diffs that are suitable for use with
|
||||
:func:`file.writelines` since both the inputs and outputs have trailing
|
||||
:func:`io.IOBase.readlines` result in diffs that are suitable for use with
|
||||
:func:`io.IOBase.writelines` since both the inputs and outputs have trailing
|
||||
newlines.
|
||||
|
||||
For inputs that do not have trailing newlines, set the *lineterm* argument to
|
||||
|
@ -275,8 +275,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
|
|||
|
||||
By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
|
||||
created with a trailing newline. This is helpful so that inputs created from
|
||||
:func:`file.readlines` result in diffs that are suitable for use with
|
||||
:func:`file.writelines` since both the inputs and outputs have trailing
|
||||
:func:`io.IOBase.readlines` result in diffs that are suitable for use with
|
||||
:func:`io.IOBase.writelines` since both the inputs and outputs have trailing
|
||||
newlines.
|
||||
|
||||
For inputs that do not have trailing newlines, set the *lineterm* argument to
|
||||
|
@ -629,10 +629,12 @@ The :class:`Differ` class has this constructor:
|
|||
|
||||
Compare two sequences of lines, and generate the delta (a sequence of lines).
|
||||
|
||||
Each sequence must contain individual single-line strings ending with newlines.
|
||||
Such sequences can be obtained from the :meth:`readlines` method of file-like
|
||||
objects. The delta generated also consists of newline-terminated strings, ready
|
||||
to be printed as-is via the :meth:`writelines` method of a file-like object.
|
||||
Each sequence must contain individual single-line strings ending with
|
||||
newlines. Such sequences can be obtained from the
|
||||
:meth:`~io.IOBase.readlines` method of file-like objects. The delta
|
||||
generated also consists of newline-terminated strings, ready to be
|
||||
printed as-is via the :meth:`~io.IOBase.writelines` method of a
|
||||
file-like object.
|
||||
|
||||
|
||||
.. _differ-examples:
|
||||
|
@ -642,7 +644,7 @@ Differ Example
|
|||
|
||||
This example compares two texts. First we set up the texts, sequences of
|
||||
individual single-line strings ending with newlines (such sequences can also be
|
||||
obtained from the :meth:`readlines` method of file-like objects):
|
||||
obtained from the :meth:`~io.BaseIO.readlines` method of file-like objects):
|
||||
|
||||
>>> text1 = ''' 1. Beautiful is better than ugly.
|
||||
... 2. Explicit is better than implicit.
|
||||
|
|
|
@ -371,8 +371,8 @@ The :class:`Enum` class is callable, providing the following functional API::
|
|||
>>> list(Animal)
|
||||
[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]
|
||||
|
||||
The semantics of this API resemble :class:`namedtuple`. The first argument
|
||||
of the call to :class:`Enum` is the name of the enumeration.
|
||||
The semantics of this API resemble :class:`~collections.namedtuple`. The first
|
||||
argument of the call to :class:`Enum` is the name of the enumeration.
|
||||
|
||||
The second argument is the *source* of enumeration member names. It can be a
|
||||
whitespace-separated string of names, a sequence of names, a sequence of
|
||||
|
|
|
@ -146,10 +146,9 @@ The following exceptions are the exceptions that are usually raised.
|
|||
|
||||
.. exception:: EOFError
|
||||
|
||||
Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
|
||||
hits an end-of-file condition (EOF) without reading any data. (N.B.: the
|
||||
:meth:`file.read` and :meth:`file.readline` methods return an empty string
|
||||
when they hit EOF.)
|
||||
Raised when the :func:`input` function hits an end-of-file condition (EOF)
|
||||
without reading any data. (N.B.: the :meth:`io.IOBase.read` and
|
||||
:meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
|
||||
|
||||
|
||||
.. exception:: FloatingPointError
|
||||
|
@ -366,7 +365,7 @@ The following exceptions are the exceptions that are usually raised.
|
|||
executed, and so that a debugger can execute a script without running the risk
|
||||
of losing control. The :func:`os._exit` function can be used if it is
|
||||
absolutely positively necessary to exit immediately (for example, in the child
|
||||
process after a call to :func:`fork`).
|
||||
process after a call to :func:`os.fork`).
|
||||
|
||||
The exception inherits from :exc:`BaseException` instead of :exc:`Exception` so
|
||||
that it is not accidentally caught by code that catches :exc:`Exception`. This
|
||||
|
@ -629,7 +628,7 @@ module for more information.
|
|||
|
||||
.. exception:: BytesWarning
|
||||
|
||||
Base class for warnings related to :class:`bytes` and :class:`buffer`.
|
||||
Base class for warnings related to :class:`bytes` and :class:`bytearray`.
|
||||
|
||||
|
||||
.. exception:: ResourceWarning
|
||||
|
|
|
@ -136,11 +136,12 @@ available for subclassing as well:
|
|||
|
||||
Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
|
||||
:meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
|
||||
:meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
|
||||
of the same name in the module. In addition it has a :meth:`readline` method
|
||||
which returns the next input line, and a :meth:`__getitem__` method which
|
||||
implements the sequence behavior. The sequence must be accessed in strictly
|
||||
sequential order; random access and :meth:`readline` cannot be mixed.
|
||||
:meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the
|
||||
functions of the same name in the module. In addition it has a
|
||||
:meth:`~io.TextIOBase.readline` method which returns the next input line,
|
||||
and a :meth:`__getitem__` method which implements the sequence behavior.
|
||||
The sequence must be accessed in strictly sequential order; random access
|
||||
and :meth:`~io.TextIOBase.readline` cannot be mixed.
|
||||
|
||||
With *mode* you can specify which file mode will be passed to :func:`open`. It
|
||||
must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
|
||||
|
|
|
@ -272,7 +272,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
|
||||
Store a file in binary transfer mode. *cmd* should be an appropriate
|
||||
``STOR`` command: ``"STOR filename"``. *file* is a :term:`file object`
|
||||
(opened in binary mode) which is read until EOF using its :meth:`read`
|
||||
(opened in binary mode) which is read until EOF using its :meth:`~io.IOBase.read`
|
||||
method in blocks of size *blocksize* to provide the data to be stored.
|
||||
The *blocksize* argument defaults to 8192. *callback* is an optional single
|
||||
parameter callable that is called on each block of data after it is sent.
|
||||
|
@ -286,7 +286,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
|
||||
Store a file in ASCII transfer mode. *cmd* should be an appropriate
|
||||
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
|
||||
:term:`file object` *file* (opened in binary mode) using its :meth:`readline`
|
||||
:term:`file object` *file* (opened in binary mode) using its :meth:`~io.IOBase.readline`
|
||||
method to provide the data to be stored. *callback* is an optional single
|
||||
parameter callable that is called on each line after it is sent.
|
||||
|
||||
|
|
|
@ -29,8 +29,8 @@ handler. Code to create and run the server looks like this::
|
|||
|
||||
.. class:: HTTPServer(server_address, RequestHandlerClass)
|
||||
|
||||
This class builds on the :class:`TCPServer` class by storing the server
|
||||
address as instance variables named :attr:`server_name` and
|
||||
This class builds on the :class:`~socketserver.TCPServer` class by storing
|
||||
the server address as instance variables named :attr:`server_name` and
|
||||
:attr:`server_port`. The server is accessible by the handler, typically
|
||||
through the handler's :attr:`server` instance variable.
|
||||
|
||||
|
@ -326,7 +326,7 @@ of which this module provides three different variants:
|
|||
file's contents are returned; otherwise a directory listing is generated
|
||||
by calling the :meth:`list_directory` method. This method uses
|
||||
:func:`os.listdir` to scan the directory, and returns a ``404`` error
|
||||
response if the :func:`listdir` fails.
|
||||
response if the :func:`~os.listdir` fails.
|
||||
|
||||
If the request was mapped to a file, it is opened and the contents are
|
||||
returned. Any :exc:`OSError` exception in opening the requested file is
|
||||
|
|
|
@ -310,8 +310,9 @@ An :class:`IMAP4` instance has the following methods:
|
|||
|
||||
Opens socket to *port* at *host*. This method is implicitly called by
|
||||
the :class:`IMAP4` constructor. The connection objects established by this
|
||||
method will be used in the ``read``, ``readline``, ``send``, and ``shutdown``
|
||||
methods. You may override this method.
|
||||
method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
|
||||
:meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
|
||||
this method.
|
||||
|
||||
|
||||
.. method:: IMAP4.partial(message_num, message_part, start, length)
|
||||
|
|
|
@ -165,7 +165,7 @@ Functions
|
|||
|
||||
It is legal though generally not very useful to reload built-in or
|
||||
dynamically loaded modules (this is not true for e.g. :mod:`sys`,
|
||||
:mod:`__main__`, :mod:`__builtin__` and other key modules where reloading is
|
||||
:mod:`__main__`, :mod:`builtins` and other key modules where reloading is
|
||||
frowned upon). In many cases, however, extension modules are not designed to
|
||||
be initialized more than once, and may fail in arbitrary ways when reloaded.
|
||||
|
||||
|
|
|
@ -928,8 +928,9 @@ but avoids executing code when it fetches attributes.
|
|||
that raise AttributeError). It can also return descriptors objects
|
||||
instead of instance members.
|
||||
|
||||
If the instance :attr:`__dict__` is shadowed by another member (for example a
|
||||
property) then this function will be unable to find instance members.
|
||||
If the instance :attr:`~object.__dict__` is shadowed by another member (for
|
||||
example a property) then this function will be unable to find instance
|
||||
members.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
|
|
@ -157,7 +157,7 @@ standard stream implementations.
|
|||
The abstract base classes also provide default implementations of some
|
||||
methods in order to help implementation of concrete stream classes. For
|
||||
example, :class:`BufferedIOBase` provides unoptimized implementations of
|
||||
``readinto()`` and ``readline()``.
|
||||
:meth:`~IOBase.readinto` and :meth:`~IOBase.readline`.
|
||||
|
||||
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
|
||||
defines the basic interface to a stream. Note, however, that there is no
|
||||
|
@ -228,7 +228,7 @@ I/O Base Classes
|
|||
|
||||
The basic type used for binary data read from or written to a file is
|
||||
:class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases
|
||||
(such as :class:`readinto`) required. Text I/O classes work with
|
||||
(such as :meth:`readinto`) required. Text I/O classes work with
|
||||
:class:`str` data.
|
||||
|
||||
Note that calling any method (even inquiries) on a closed stream is
|
||||
|
|
|
@ -88,9 +88,9 @@ loops that truncate the stream.
|
|||
.. function:: accumulate(iterable[, func])
|
||||
|
||||
Make an iterator that returns accumulated sums. Elements may be any addable
|
||||
type including :class:`Decimal` or :class:`Fraction`. If the optional
|
||||
*func* argument is supplied, it should be a function of two arguments
|
||||
and it will be used instead of addition.
|
||||
type including :class:`~decimal.Decimal` or :class:`~fractions.Fraction`.
|
||||
If the optional *func* argument is supplied, it should be a function of two
|
||||
arguments and it will be used instead of addition.
|
||||
|
||||
Equivalent to::
|
||||
|
||||
|
|
|
@ -1009,7 +1009,7 @@ When a :class:`MaildirMessage` instance is created based upon a
|
|||
Set the "From " line to *from_*, which should be specified without a
|
||||
leading "From " or trailing newline. For convenience, *time_* may be
|
||||
specified and will be formatted appropriately and appended to *from_*. If
|
||||
*time_* is specified, it should be a :class:`struct_time` instance, a
|
||||
*time_* is specified, it should be a :class:`time.struct_time` instance, a
|
||||
tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
|
||||
:meth:`time.gmtime`).
|
||||
|
||||
|
@ -1380,7 +1380,7 @@ When a :class:`BabylMessage` instance is created based upon an
|
|||
Set the "From " line to *from_*, which should be specified without a
|
||||
leading "From " or trailing newline. For convenience, *time_* may be
|
||||
specified and will be formatted appropriately and appended to *from_*. If
|
||||
*time_* is specified, it should be a :class:`struct_time` instance, a
|
||||
*time_* is specified, it should be a :class:`time.struct_time` instance, a
|
||||
tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
|
||||
:meth:`time.gmtime`).
|
||||
|
||||
|
|
|
@ -31,7 +31,7 @@ Number-theoretic and representation functions
|
|||
|
||||
Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
|
||||
If *x* is not a float, delegates to ``x.__ceil__()``, which should return an
|
||||
:class:`Integral` value.
|
||||
:class:`~numbers.Integral` value.
|
||||
|
||||
|
||||
.. function:: copysign(x, y)
|
||||
|
@ -53,7 +53,7 @@ Number-theoretic and representation functions
|
|||
|
||||
Return the floor of *x*, the largest integer less than or equal to *x*.
|
||||
If *x* is not a float, delegates to ``x.__floor__()``, which should return an
|
||||
:class:`Integral` value.
|
||||
:class:`~numbers.Integral` value.
|
||||
|
||||
|
||||
.. function:: fmod(x, y)
|
||||
|
@ -133,8 +133,9 @@ Number-theoretic and representation functions
|
|||
|
||||
.. function:: trunc(x)
|
||||
|
||||
Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
|
||||
an integer). Delegates to ``x.__trunc__()``.
|
||||
Return the :class:`~numbers.Real` value *x* truncated to an
|
||||
:class:`~numbers.Integral` (usually an integer). Delegates to
|
||||
``x.__trunc__()``.
|
||||
|
||||
|
||||
Note that :func:`frexp` and :func:`modf` have a different call/return pattern
|
||||
|
|
|
@ -429,8 +429,9 @@ GUI classes
|
|||
-----------
|
||||
|
||||
:mod:`msilib` provides several classes that wrap the GUI tables in an MSI
|
||||
database. However, no standard user interface is provided; use :mod:`bdist_msi`
|
||||
to create MSI files with a user-interface for installing Python packages.
|
||||
database. However, no standard user interface is provided; use
|
||||
:mod:`~distutils.command.bdist_msi` to create MSI files with a user-interface
|
||||
for installing Python packages.
|
||||
|
||||
|
||||
.. class:: Control(dlg, name)
|
||||
|
|
|
@ -169,11 +169,11 @@ and (read-only) attributes:
|
|||
be used in a :keyword:`with` statement.
|
||||
|
||||
|
||||
The following methods each map to exactly one :func:`ioctl` system call. The
|
||||
The following methods each map to exactly one :c:func:`ioctl` system call. The
|
||||
correspondence is obvious: for example, :meth:`setfmt` corresponds to the
|
||||
``SNDCTL_DSP_SETFMT`` ioctl, and :meth:`sync` to ``SNDCTL_DSP_SYNC`` (this can
|
||||
be useful when consulting the OSS documentation). If the underlying
|
||||
:func:`ioctl` fails, they all raise :exc:`OSError`.
|
||||
:c:func:`ioctl` fails, they all raise :exc:`OSError`.
|
||||
|
||||
|
||||
.. method:: oss_audio_device.nonblock()
|
||||
|
|
|
@ -484,8 +484,8 @@ ExpatError Exceptions
|
|||
.. attribute:: ExpatError.code
|
||||
|
||||
Expat's internal error number for the specific error. The
|
||||
:data:`errors.messages` dictionary maps these error numbers to Expat's error
|
||||
messages. For example::
|
||||
:data:`errors.messages <xml.parsers.expat.errors.messages>` dictionary maps
|
||||
these error numbers to Expat's error messages. For example::
|
||||
|
||||
from xml.parsers.expat import ParserCreate, ExpatError, errors
|
||||
|
||||
|
@ -495,9 +495,9 @@ ExpatError Exceptions
|
|||
except ExpatError as err:
|
||||
print("Error:", errors.messages[err.code])
|
||||
|
||||
The :mod:`errors` module also provides error message constants and a
|
||||
dictionary :data:`~errors.codes` mapping these messages back to the error
|
||||
codes, see below.
|
||||
The :mod:`~xml.parsers.expat.errors` module also provides error message
|
||||
constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping
|
||||
these messages back to the error codes, see below.
|
||||
|
||||
|
||||
.. attribute:: ExpatError.lineno
|
||||
|
|
|
@ -106,8 +106,8 @@ Restrictions
|
|||
|
||||
.. class:: Shelf(dict, protocol=None, writeback=False, keyencoding='utf-8')
|
||||
|
||||
A subclass of :class:`collections.MutableMapping` which stores pickled values
|
||||
in the *dict* object.
|
||||
A subclass of :class:`collections.abc.MutableMapping` which stores pickled
|
||||
values in the *dict* object.
|
||||
|
||||
By default, version 0 pickles are used to serialize values. The version of the
|
||||
pickle protocol can be specified with the *protocol* parameter. See the
|
||||
|
|
|
@ -27,7 +27,7 @@ SMTPServer Objects
|
|||
------------------
|
||||
|
||||
|
||||
.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,
|
||||
.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\
|
||||
map=None)
|
||||
|
||||
Create a new :class:`SMTPServer` object, which binds to local address
|
||||
|
@ -96,7 +96,7 @@ MailmanProxy Objects
|
|||
SMTPChannel Objects
|
||||
-------------------
|
||||
|
||||
.. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,
|
||||
.. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,\
|
||||
map=None))
|
||||
|
||||
Create a new :class:`SMTPChannel` object which manages the communication
|
||||
|
|
|
@ -285,7 +285,7 @@ The module :mod:`socket` exports the following constants and functions:
|
|||
RCVALL_*
|
||||
|
||||
Constants for Windows' WSAIoctl(). The constants are used as arguments to the
|
||||
:meth:`ioctl` method of socket objects.
|
||||
:meth:`~socket.socket.ioctl` method of socket objects.
|
||||
|
||||
|
||||
.. data:: TIPC_*
|
||||
|
|
|
@ -111,13 +111,13 @@ can be implemented by using a synchronous server and doing an explicit fork in
|
|||
the request handler class :meth:`handle` method.
|
||||
|
||||
Another approach to handling multiple simultaneous requests in an environment
|
||||
that supports neither threads nor :func:`fork` (or where these are too expensive
|
||||
or inappropriate for the service) is to maintain an explicit table of partially
|
||||
finished requests and to use :func:`select` to decide which request to work on
|
||||
next (or whether to handle a new incoming request). This is particularly
|
||||
important for stream services where each client can potentially be connected for
|
||||
a long time (if threads or subprocesses cannot be used). See :mod:`asyncore`
|
||||
for another way to manage this.
|
||||
that supports neither threads nor :func:`~os.fork` (or where these are too
|
||||
expensive or inappropriate for the service) is to maintain an explicit table of
|
||||
partially finished requests and to use :func:`~select.select` to decide which
|
||||
request to work on next (or whether to handle a new incoming request). This is
|
||||
particularly important for stream services where each client can potentially be
|
||||
connected for a long time (if threads or subprocesses cannot be used). See
|
||||
:mod:`asyncore` for another way to manage this.
|
||||
|
||||
.. XXX should data and methods be intermingled, or separate?
|
||||
how should the distinction between class and instance variables be drawn?
|
||||
|
|
|
@ -1,5 +1,5 @@
|
|||
:mod:`stat` --- Interpreting :func:`stat` results
|
||||
=================================================
|
||||
:mod:`stat` --- Interpreting :func:`~os.stat` results
|
||||
=====================================================
|
||||
|
||||
.. module:: stat
|
||||
:synopsis: Utilities for interpreting the results of os.stat(),
|
||||
|
|
|
@ -185,7 +185,7 @@ Telnet Objects
|
|||
Read until one from a list of a regular expressions matches.
|
||||
|
||||
The first argument is a list of regular expressions, either compiled
|
||||
(:class:`re.RegexObject` instances) or uncompiled (byte strings). The
|
||||
(:ref:`regex objects <re-objects>`) or uncompiled (byte strings). The
|
||||
optional second argument is a timeout, in seconds; the default is to block
|
||||
indefinitely.
|
||||
|
||||
|
|
|
@ -677,8 +677,8 @@ The module defines the following functions and data items:
|
|||
of many format specifiers in :func:`strftime` and :func:`strptime`.
|
||||
|
||||
Module :mod:`calendar`
|
||||
General calendar-related functions. :func:`timegm` is the inverse of
|
||||
:func:`gmtime` from this module.
|
||||
General calendar-related functions. :func:`~calendar.timegm` is the
|
||||
inverse of :func:`gmtime` from this module.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
|
|
|
@ -210,8 +210,8 @@ the `new_callable` argument to `patch`.
|
|||
Accessing any attribute not in this list will raise an `AttributeError`.
|
||||
|
||||
If `spec` is an object (rather than a list of strings) then
|
||||
:attr:`__class__` returns the class of the spec object. This allows mocks
|
||||
to pass `isinstance` tests.
|
||||
:attr:`~instance.__class__` returns the class of the spec object. This
|
||||
allows mocks to pass `isinstance` tests.
|
||||
|
||||
* `spec_set`: A stricter variant of `spec`. If used, attempting to *set*
|
||||
or get an attribute on the mock that isn't on the object passed as
|
||||
|
@ -1989,7 +1989,8 @@ mock_open
|
|||
default) then a `MagicMock` will be created for you, with the API limited
|
||||
to methods or attributes available on standard file handles.
|
||||
|
||||
`read_data` is a string for the `read`, `readline`, and `readlines` methods
|
||||
`read_data` is a string for the :meth:`~io.IOBase.read`,
|
||||
:meth:`~io.IOBase.readline`, and :meth:`~io.IOBase.readlines` methods
|
||||
of the file handle to return. Calls to those methods will take data from
|
||||
`read_data` until it is depleted. The mock of these methods is pretty
|
||||
simplistic. If you need more control over the data that you are feeding to
|
||||
|
|
|
@ -89,7 +89,7 @@ following warnings category classes are currently defined:
|
|||
| | Unicode. |
|
||||
+----------------------------------+-----------------------------------------------+
|
||||
| :exc:`BytesWarning` | Base category for warnings related to |
|
||||
| | :class:`bytes` and :class:`buffer`. |
|
||||
| | :class:`bytes` and :class:`bytearray`. |
|
||||
+----------------------------------+-----------------------------------------------+
|
||||
| :exc:`ResourceWarning` | Base category for warnings related to |
|
||||
| | resource usage. |
|
||||
|
|
|
@ -213,8 +213,9 @@ ZipFile Objects
|
|||
.. note::
|
||||
|
||||
The file-like object is read-only and provides the following methods:
|
||||
:meth:`!read`, :meth:`!readline`, :meth:`!readlines`, :meth:`!__iter__`,
|
||||
:meth:`!__next__`.
|
||||
:meth:`~io.BufferedIOBase.read`, :meth:`~io.IOBase.readline`,
|
||||
:meth:`~io.IOBase.readlines`, :meth:`__iter__`,
|
||||
:meth:`~iterator.__next__`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
|
@ -234,9 +234,9 @@ other than :data:`sys.stdout`.
|
|||
dis
|
||||
---
|
||||
|
||||
The :mod:`dis` module is now built around an :class:`Instruction` class that
|
||||
provides details of individual bytecode operations and a
|
||||
:func:`get_instructions` iterator that emits the Instruction stream for a
|
||||
The :mod:`dis` module is now built around an :class:`~dis.Instruction` class
|
||||
that provides details of individual bytecode operations and a
|
||||
:func:`~dis.get_instructions` iterator that emits the Instruction stream for a
|
||||
given piece of Python code. The various display tools in the :mod:`dis`
|
||||
module have been updated to be based on these new components.
|
||||
|
||||
|
|
Loading…
Reference in New Issue