names.
.. data:: ArrayType
- Obsolete alias for :class:`array`.
+ Obsolete alias for :class:`~array.array`.
Array objects support the ordinary sequence operations of indexing, slicing,
concatenation, and multiplication. When using slice assignment, the assigned
empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a
list of numbers. The string is guaranteed to be able to be converted back to an
array with the same type and value using :func:`eval`, so long as the
-:func:`array` function has been imported using ``from array import array``.
+:class:`~array.array` class has been imported using ``from array import array``.
Examples::
array('l')
single: ini file
single: Windows ini file
-This module defines the class :class:`ConfigParser`. The :class:`ConfigParser`
+This module defines the class :class:`~ConfigParser.ConfigParser`. The :class:`~ConfigParser.ConfigParser`
class implements a basic configuration file parser language which provides a
structure similar to what you would find on Microsoft Windows INI files. You
can use this to write Python programs which can be customized by end users
would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
All reference expansions are done on demand.
-Default values can be specified by passing them into the :class:`ConfigParser`
+Default values can be specified by passing them into the :class:`~ConfigParser.ConfigParser`
constructor as a dictionary. Additional defaults may be passed into the
:meth:`get` method which will override all others.
Sections are normally stored in a built-in dictionary. An alternative dictionary
-type can be passed to the :class:`ConfigParser` constructor. For example, if a
+type can be passed to the :class:`~ConfigParser.ConfigParser` constructor. For example, if a
dictionary type is passed that sorts its keys, the sections will be sorted on
write-back, as will be the keys within each section.
.. class:: SafeConfigParser([defaults[, dict_type[, allow_no_value]]])
- Derived class of :class:`ConfigParser` that implements a more-sane variant of
+ Derived class of :class:`~ConfigParser.ConfigParser` that implements a more-sane variant of
the magical interpolation feature. This implementation is more predictable as
well. New applications should prefer this version if they don't need to be
compatible with older versions of Python.
.. data:: MAX_INTERPOLATION_DEPTH
The maximum depth for recursive interpolation for :meth:`get` when the *raw*
- parameter is false. This is relevant only for the :class:`ConfigParser` class.
+ parameter is false. This is relevant only for the :class:`~ConfigParser.ConfigParser` class.
.. seealso::
list of potential configuration file locations (for example, the current
directory, the user's home directory, and some system-wide directory), and all
existing configuration files in the list will be read. If none of the named
- files exist, the :class:`ConfigParser` instance will contain an empty dataset.
+ files exist, the :class:`~ConfigParser.ConfigParser` instance will contain an empty dataset.
An application which requires initial values to be loaded from a file should
load the required file or files using :meth:`readfp` before calling :meth:`read`
for any optional files::
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. While it is possible to use
- :class:`RawConfigParser` (or :class:`ConfigParser` with *raw* parameters set to
+ :class:`RawConfigParser` (or :class:`~ConfigParser.ConfigParser` with *raw* parameters set to
true) for *internal* storage of non-string values, full functionality (including
interpolation and output to files) can only be achieved using string values.
ConfigParser Objects
--------------------
-The :class:`ConfigParser` class extends some methods of the
+The :class:`~ConfigParser.ConfigParser` class extends some methods of the
:class:`RawConfigParser` interface, adding some optional arguments.
------------------------
The :class:`SafeConfigParser` class implements the same extended interface as
-:class:`ConfigParser`, with the following addition:
+:class:`~ConfigParser.ConfigParser`, with the following addition:
.. method:: SafeConfigParser.set(section, option, value)
if config.getboolean('Section1', 'a_bool'):
print config.get('Section1', 'foo')
-To get interpolation, you will need to use a :class:`ConfigParser` or
+To get interpolation, you will need to use a :class:`~ConfigParser.ConfigParser` or
:class:`SafeConfigParser`::
import ConfigParser
The same security warning from :class:`SerialCookie` applies here.
A further security note is warranted. For backwards compatibility, the
-:mod:`Cookie` module exports a class named :class:`Cookie` which is just an
-alias for :class:`SmartCookie`. This is probably a mistake and will likely be
-removed in a future version. You should not use the :class:`Cookie` class in
-your applications, for the same reason why you should not use the
-:class:`SerialCookie` class.
+:mod:`Cookie` module exports a class named :class:`~Cookie.Cookie` which is
+just an alias for :class:`SmartCookie`. This is probably a mistake and will
+likely be removed in a future version. You should not use the
+:class:`~Cookie.Cookie` class in your applications, for the same reason why
+you should not use the :class:`SerialCookie` class.
.. seealso::
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are
'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
- setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
+ setting the :attr:`version` attribute of the :class:`~cookielib.Cookie` instance to 0.
:class:`DefaultCookiePolicy` also provides some parameters to allow some
fine-tuning of policy.
.. class:: Cookie()
This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not
- expected that users of :mod:`cookielib` construct their own :class:`Cookie`
+ expected that users of :mod:`cookielib` construct their own :class:`~cookielib.Cookie`
instances. Instead, if necessary, call :meth:`make_cookies` on a
:class:`CookieJar` instance.
-----------------------------------
:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
-contained :class:`Cookie` objects.
+contained :class:`~cookielib.Cookie` objects.
:class:`CookieJar` has the following methods:
.. method:: CookieJar.make_cookies(response, request)
- Return sequence of :class:`Cookie` objects extracted from *response* object.
+ Return sequence of :class:`~cookielib.Cookie` objects extracted from *response* object.
See the documentation for :meth:`extract_cookies` for the interfaces required of
the *response* and *request* arguments.
.. method:: CookieJar.set_cookie_if_ok(cookie, request)
- Set a :class:`Cookie` if policy says it's OK to do so.
+ Set a :class:`~cookielib.Cookie` if policy says it's OK to do so.
.. method:: CookieJar.set_cookie(cookie)
- Set a :class:`Cookie`, without checking with policy to see whether or not it
+ Set a :class:`~cookielib.Cookie`, without checking with policy to see whether or not it
should be set.
:meth:`path_return_ok` is called for the cookie path. Otherwise,
:meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
- with the :class:`Cookie` object itself for a full check. Otherwise,
+ with the :class:`~cookielib.Cookie` object itself for a full check. Otherwise,
:meth:`return_ok` is never called for that cookie path.
Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
(ie. cookies received in a :mailheader:`Set-Cookie` header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
- the :class:`Cookie` instance to 0. The default value is :const:`None`, in which
+ the :class:`~cookielib.Cookie` instance to 0. The default value is :const:`None`, in which
case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
off. Therefore, RFC 2109 cookies are downgraded by default.
Cookie Objects
--------------
-:class:`Cookie` instances have Python attributes roughly corresponding to the
+:class:`~cookielib.Cookie` instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the ``max-age`` and ``expires``
Set the value of the named cookie-attribute.
-The :class:`Cookie` class also defines the following method:
+The :class:`~cookielib.Cookie` class also defines the following method:
.. method:: Cookie.is_expired([now=None])
.. _datetime-time:
-:class:`time` Objects
----------------------
+:class:`.time` Objects
+----------------------
A time object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a :class:`tzinfo` object.
The :mod:`DocXMLRPCServer` module extends the classes found in
:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
-requests. Servers can either be free standing, using :class:`DocXMLRPCServer`,
+requests. Servers can either be free standing, using :class:`~DocXMLRPCServer.DocXMLRPCServer`,
or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
Create a new request handler instance. This request handler supports XML-RPC
POST requests, documentation GET requests, and modifies logging so that the
- *logRequests* parameter to the :class:`DocXMLRPCServer` constructor parameter is
+ *logRequests* parameter to the :class:`~DocXMLRPCServer.DocXMLRPCServer` constructor parameter is
honored.
DocXMLRPCServer Objects
-----------------------
-The :class:`DocXMLRPCServer` class is derived from
+The :class:`~DocXMLRPCServer.DocXMLRPCServer` class is derived from
:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
---------------
In addition to the methods provided by the :class:`UserDict.DictMixin` class,
-:class:`dumbdbm` objects provide the following methods.
+:class:`~dumbdbm.dumbdbm` objects provide the following methods.
.. method:: dumbdbm.sync()
.. index:: single: HTMLParser (class in htmllib)
This module supports two interface definitions, each with multiple
-implementations. The *formatter* interface is used by the :class:`HTMLParser`
+implementations. The *formatter* interface is used by the :class:`~HTMLParser.HTMLParser`
class of the :mod:`htmllib` module, and the *writer* interface is required by
the formatter interface.
*fileobj*, since you might wish to append more material after the compressed
data. This also allows you to pass a :class:`~StringIO.StringIO` object opened for
writing as *fileobj*, and retrieve the resulting memory buffer using the
- :class:`StringIO` object's :meth:`~StringIO.StringIO.getvalue` method.
+ :class:`~StringIO.StringIO` object's :meth:`~StringIO.StringIO.getvalue` method.
:class:`GzipFile` supports iteration and the :keyword:`with` statement.
formatted in the HyperText Mark-up Language (HTML). The class is not directly
concerned with I/O --- it must be provided with input in string form via a
method, and makes calls to methods of a "formatter" object in order to produce
-output. The :class:`HTMLParser` class is designed to be used as a base class
+output. The :class:`~HTMLParser.HTMLParser` class is designed to be used as a base class
for other classes in order to add functionality, and allows most of its methods
to be extended or overridden. In turn, this class is derived from and extends
the :class:`SGMLParser` class defined in module :mod:`sgmllib`. The
-:class:`HTMLParser` implementation supports the HTML 2.0 language as described
+:class:`~HTMLParser.HTMLParser` implementation supports the HTML 2.0 language as described
in :rfc:`1866`. Two implementations of formatter objects are provided in the
:mod:`formatter` module; refer to the documentation for that module for
information on the formatter interface.
.. exception:: HTMLParseError
- Exception raised by the :class:`HTMLParser` class when it encounters an error
+ Exception raised by the :class:`~HTMLParser.HTMLParser` class when it encounters an error
while parsing.
.. versionadded:: 2.4
Definition of replacement text for XHTML 1.0 entities.
Module :mod:`sgmllib`
- Base class for :class:`HTMLParser`.
+ Base class for :class:`~HTMLParser.HTMLParser`.
.. _html-parser-objects:
HTMLParser Objects
------------------
-In addition to tag methods, the :class:`HTMLParser` class provides some
+In addition to tag methods, the :class:`~HTMLParser.HTMLParser` class provides some
additional methods and instance variables for use within tag methods.
This module defines three dictionaries, ``name2codepoint``, ``codepoint2name``,
and ``entitydefs``. ``entitydefs`` is used by the :mod:`htmllib` module to
-provide the :attr:`entitydefs` attribute of the :class:`HTMLParser` class. The
+provide the :attr:`entitydefs` attribute of the :class:`~HTMLParser.HTMLParser` class. The
definition provided here contains all the entities defined by XHTML 1.0 that
can be handled using simple textual substitution in the Latin-1 character set
(ISO-8859-1).
streams whose bytes represent text, and handles encoding and decoding
from and to :class:`unicode` strings. :class:`TextIOWrapper`, which extends
it, is a buffered text interface to a buffered raw stream
-(:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory
+(:class:`BufferedIOBase`). Finally, :class:`~io.StringIO` is an in-memory
stream for unicode text.
Argument names are not part of the specification, and only the arguments of
It is also possible to use an :class:`unicode` or :class:`bytes` string
as a file for both reading and writing. For :class:`unicode` strings
- :class:`StringIO` can be used like a file opened in text mode,
+ :class:`~io.StringIO` can be used like a file opened in text mode,
and for :class:`bytes` a :class:`BytesIO` can be used like a
file opened in a binary mode.
After the underlying buffer has been detached, the :class:`TextIOBase` is
in an unusable state.
- Some :class:`TextIOBase` implementations, like :class:`StringIO`, may not
+ Some :class:`TextIOBase` implementations, like :class:`~io.StringIO`, may not
have the concept of an underlying buffer and calling this method will
raise :exc:`UnsupportedOperation`.
newlines are written as ``\n`` on all platforms, but universal
newline decoding is still performed when reading.
- :class:`StringIO` provides this method in addition to those from
+ :class:`~io.StringIO` provides this method in addition to those from
:class:`TextIOWrapper` and its parents:
.. method:: getvalue()
Return a ``unicode`` containing the entire contents of the buffer at any
- time before the :class:`StringIO` object's :meth:`close` method is
+ time before the :class:`~io.StringIO` object's :meth:`close` method is
called. Newlines are decoded as if by :meth:`~TextIOBase.read`,
although the stream position is not changed.
Also, :meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both
quite slow due to the reconstruction algorithm used.
-:class:`StringIO`, however, is a native in-memory unicode container and will
+:class:`~io.StringIO`, however, is a native in-memory unicode container and will
exhibit similar speed to :class:`BytesIO`.
Multi-threading
The :mod:`email` package should be used in preference to the :mod:`MimeWriter`
module. This module is present only to maintain backward compatibility.
-This module defines the class :class:`MimeWriter`. The :class:`MimeWriter`
+This module defines the class :class:`~MimeWriter.MimeWriter`. The :class:`~MimeWriter.MimeWriter`
class implements a basic formatter for creating MIME multi-part files. It
doesn't seek around the output file nor does it use large amounts of buffer
space. You must write the parts out in the order that they should occur in the
-final file. :class:`MimeWriter` does buffer the headers you add, allowing you
+final file. :class:`~MimeWriter.MimeWriter` does buffer the headers you add, allowing you
to rearrange their order.
.. class:: MimeWriter(fp)
- Return a new instance of the :class:`MimeWriter` class. The only argument
+ Return a new instance of the :class:`~MimeWriter.MimeWriter` class. The only argument
passed, *fp*, is a file object to be used for writing. Note that a
:class:`~StringIO.StringIO` object could also be used.
MimeWriter Objects
------------------
-:class:`MimeWriter` instances have the following methods:
+:class:`~MimeWriter.MimeWriter` instances have the following methods:
.. method:: MimeWriter.addheader(key, value[, prefix])
.. method:: MimeWriter.nextpart()
- Returns a new instance of :class:`MimeWriter` which represents an individual
+ Returns a new instance of :class:`~MimeWriter.MimeWriter` which represents an individual
part in a multipart message. This may be used to write the part as well as
used for creating recursively complex multipart messages. The message must first
be initialized with :meth:`startmultipartbody` before using :meth:`nextpart`.
also read and write data starting at the current file position, and
:meth:`seek` through the file to different positions.
-A memory-mapped file is created by the :class:`mmap` constructor, which is
+A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is
different on Unix and on Windows. In either case you must provide a file
descriptor for a file opened for update. If you wish to map an existing Python
file object, use its :meth:`fileno` method to obtain the correct value for the
**(Unix version)** Maps *length* bytes from the file specified by the file
descriptor *fileno*, and returns a mmap object. If *length* is ``0``, the
maximum length of the map will be the current size of the file when
- :class:`mmap` is called.
+ :class:`~mmap.mmap` is called.
*flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a
private copy-on-write mapping, so changes to the contents of the mmap
by the descriptor *fileno* is internally automatically synchronized
with physical backing store on Mac OS X and OpenVMS.
- This example shows a simple way of using :class:`mmap`::
+ This example shows a simple way of using :class:`~mmap.mmap`::
import mmap
Mutex Objects
-------------
-:class:`mutex` objects have following methods:
+:class:`~mutex.mutex` objects have following methods:
.. method:: mutex.test()
--------------
-The :class:`netrc` class parses and encapsulates the netrc file format used by
+The :class:`~netrc.netrc` class parses and encapsulates the netrc file format used by
the Unix :program:`ftp` program and other FTP clients.
.. class:: netrc([file])
- A :class:`netrc` instance or subclass instance encapsulates data from a netrc
+ A :class:`~netrc.netrc` instance or subclass instance encapsulates data from a netrc
file. The initialization argument, if present, specifies the file to parse. If
no argument is given, the file :file:`.netrc` in the user's home directory will
be read. Parse errors will raise :exc:`NetrcParseError` with diagnostic
.. exception:: NetrcParseError
- Exception raised by the :class:`netrc` class when syntactical errors are
+ Exception raised by the :class:`~netrc.netrc` class when syntactical errors are
encountered in source text. Instances of this exception provide three
interesting attributes: :attr:`msg` is a textual explanation of the error,
:attr:`filename` is the name of the source file, and :attr:`lineno` gives the
netrc Objects
-------------
-A :class:`netrc` instance has the following methods:
+A :class:`~netrc.netrc` instance has the following methods:
.. method:: netrc.authenticators(host)
Dump the class data as a string in the format of a netrc file. (This discards
comments and may reorder the entries.)
-Instances of :class:`netrc` have public instance variables:
+Instances of :class:`~netrc.netrc` have public instance variables:
.. attribute:: netrc.hosts
The :mod:`Queue` module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must be
-exchanged safely between multiple threads. The :class:`Queue` class in this
+exchanged safely between multiple threads. The :class:`~Queue.Queue` class in this
module implements all the required locking semantics. It depends on the
availability of thread support in Python; see the :mod:`threading`
module.
Exception raised when non-blocking :meth:`~Queue.get` (or
:meth:`~Queue.get_nowait`) is called
- on a :class:`Queue` object which is empty.
+ on a :class:`~Queue.Queue` object which is empty.
.. exception:: Full
Exception raised when non-blocking :meth:`~Queue.put` (or
:meth:`~Queue.put_nowait`) is called
- on a :class:`Queue` object which is full.
+ on a :class:`~Queue.Queue` object which is full.
.. seealso::
Queue Objects
-------------
-Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
+Queue objects (:class:`~Queue.Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
provide the public methods described below.
The :mod:`ScrolledText` module provides a class of the same name which
implements a basic text widget which has a vertical scroll bar configured to do
-the "right thing." Using the :class:`ScrolledText` class is a lot easier than
+the "right thing." Using the :class:`~ScrolledText.ScrolledText` class is a lot easier than
setting up a text widget and scroll bar directly. The constructor is the same
as that of the :class:`Tkinter.Text` class.
The text widget and scrollbar are packed together in a :class:`Frame`, and the
methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired
-from the :class:`Frame` object. This allows the :class:`ScrolledText` widget to
+from the :class:`Frame` object. This allows the :class:`~ScrolledText.ScrolledText` widget to
be used directly to achieve most normal geometry management behavior.
Should more specific control be necessary, the following attributes are
The :mod:`SimpleXMLRPCServer` module provides a basic server framework for
XML-RPC servers written in Python. Servers can either be free standing, using
-:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
+:class:`~SimpleXMLRPCServer.SimpleXMLRPCServer`, or embedded in a CGI environment, using
:class:`CGIXMLRPCRequestHandler`.
Create a new request handler instance. This request handler supports ``POST``
requests and modifies logging so that the *logRequests* parameter to the
- :class:`SimpleXMLRPCServer` constructor parameter is honored.
+ :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` constructor parameter is honored.
.. _simple-xmlrpc-servers:
SimpleXMLRPCServer Objects
--------------------------
-The :class:`SimpleXMLRPCServer` class is based on
+The :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` class is based on
:class:`SocketServer.TCPServer` and provides a means of creating simple, stand
alone XML-RPC servers.
# Print list of available methods
print s.system.listMethods()
-The following :class:`SimpleXMLRPCServer` example is included in the module
+The following :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` example is included in the module
`Lib/SimpleXMLRPCServer.py`::
server = SimpleXMLRPCServer(("localhost", 8000))
:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
Socket objects also have these (read-only) attributes that correspond to the
-values given to the :class:`socket` constructor.
+values given to the :class:`~socket.socket` constructor.
.. attribute:: socket.family
:synopsis: Read and write strings as if they were files.
-This module implements a file-like class, :class:`StringIO`, that reads and
+This module implements a file-like class, :class:`~StringIO.StringIO`, that reads and
writes a string buffer (also known as *memory files*). See the description of
file objects for operations (section :ref:`bltin-file-objects`). (For
standard strings, see :class:`str` and :class:`unicode`.)
.. class:: StringIO([buffer])
- When a :class:`StringIO` object is created, it can be initialized to an existing
+ When a :class:`~StringIO.StringIO` object is created, it can be initialized to an existing
string by passing the string to the constructor. If no string is given, the
- :class:`StringIO` will start empty. In both cases, the initial file position
+ :class:`~StringIO.StringIO` will start empty. In both cases, the initial file position
starts at zero.
- The :class:`StringIO` object can accept either Unicode or 8-bit strings, but
+ The :class:`~StringIO.StringIO` object can accept either Unicode or 8-bit strings, but
mixing the two may take some care. If both are used, 8-bit strings that cannot
be interpreted as 7-bit ASCII (that use the 8th bit) will cause a
:exc:`UnicodeError` to be raised when :meth:`getvalue` is called.
-The following methods of :class:`StringIO` objects require special mention:
+The following methods of :class:`~StringIO.StringIO` objects require special mention:
.. method:: StringIO.getvalue()
Retrieve the entire contents of the "file" at any time before the
- :class:`StringIO` object's :meth:`close` method is called. See the note above
+ :class:`~StringIO.StringIO` object's :meth:`close` method is called. See the note above
for information about mixing Unicode and 8-bit strings; such mixing can cause
this method to raise :exc:`UnicodeError`.
.. method:: StringIO.close()
Free the memory buffer. Attempting to do further operations with a closed
- :class:`StringIO` object will raise a :exc:`ValueError`.
+ :class:`~StringIO.StringIO` object will raise a :exc:`ValueError`.
Example usage::
simplifies writing classes that need to be substitutable for dictionaries (such
as the shelve module).
-This module also defines a class, :class:`UserDict`, that acts as a wrapper
+This module also defines a class, :class:`~UserDict.UserDict`, that acts as a wrapper
around dictionary objects. The need for this class has been largely supplanted
by the ability to subclass directly from :class:`dict` (a feature that became
available starting with Python version 2.2). Prior to the introduction of
-:class:`dict`, the :class:`UserDict` class was used to create dictionary-like
+:class:`dict`, the :class:`~UserDict.UserDict` class was used to create dictionary-like
sub-classes that obtained new behaviors by overriding existing methods or adding
new ones.
-The :mod:`UserDict` module defines the :class:`UserDict` class and
+The :mod:`UserDict` module defines the :class:`~UserDict.UserDict` class and
:class:`DictMixin`:
Class that simulates a dictionary. The instance's contents are kept in a
regular dictionary, which is accessible via the :attr:`data` attribute of
- :class:`UserDict` instances. If *initialdata* is provided, :attr:`data` is
+ :class:`~UserDict.UserDict` instances. If *initialdata* is provided, :attr:`data` is
initialized with its contents; note that a reference to *initialdata* will not
be kept, allowing it be used for other purposes.
.. note::
- For backward compatibility, instances of :class:`UserDict` are not iterable.
+ For backward compatibility, instances of :class:`~UserDict.UserDict` are not iterable.
.. class:: IterableUserDict([initialdata])
- Subclass of :class:`UserDict` that supports direct iteration (e.g. ``for key in
+ Subclass of :class:`~UserDict.UserDict` that supports direct iteration (e.g. ``for key in
myDict``).
In addition to supporting the methods and operations of mappings (see section
-:ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances
+:ref:`typesmapping`), :class:`~UserDict.UserDict` and :class:`IterableUserDict` instances
provide the following attribute:
.. attribute:: IterableUserDict.data
- A real dictionary used to store the contents of the :class:`UserDict` class.
+ A real dictionary used to store the contents of the :class:`~UserDict.UserDict` class.
.. class:: DictMixin()
In addition, this class can be mixed-in with built-in classes using multiple
inheritance. This can sometimes be useful. For example, you can inherit
- from :class:`UserList` and :class:`str` at the same time. That would not be
+ from :class:`~UserList.UserList` and :class:`str` at the same time. That would not be
possible with both a real :class:`list` and a real :class:`str`.
This module defines a class that acts as a wrapper around list objects. It is a
and override existing methods or add new ones. In this way one can add new
behaviors to lists.
-The :mod:`UserList` module defines the :class:`UserList` class:
+The :mod:`UserList` module defines the :class:`~UserList.UserList` class:
.. class:: UserList([list])
Class that simulates a list. The instance's contents are kept in a regular
- list, which is accessible via the :attr:`data` attribute of :class:`UserList`
+ list, which is accessible via the :attr:`data` attribute of :class:`~UserList.UserList`
instances. The instance's contents are initially set to a copy of *list*,
defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a
- real Python list or a :class:`UserList` object.
+ real Python list or a :class:`~UserList.UserList` object.
.. note::
- The :class:`UserList` class has been moved to the :mod:`collections`
+ The :class:`~UserList.UserList` class has been moved to the :mod:`collections`
module in Python 3. The :term:`2to3` tool will automatically adapt
imports when converting your sources to Python 3.
In addition to supporting the methods and operations of mutable sequences (see
-section :ref:`typesseq`), :class:`UserList` instances provide the following
+section :ref:`typesseq`), :class:`~UserList.UserList` instances provide the following
attribute:
.. attribute:: UserList.data
- A real Python list object used to store the contents of the :class:`UserList`
+ A real Python list object used to store the contents of the :class:`~UserList.UserList`
class.
-**Subclassing requirements:** Subclasses of :class:`UserList` are expected to
+**Subclassing requirements:** Subclasses of :class:`~UserList.UserList` are expected to
offer a constructor which can be called with either no arguments or one
argument. List operations which return a new sequence attempt to create an
instance of the actual implementation class. To do so, it assumes that the
.. note::
- This :class:`UserString` class from this module is available for backward
+ This :class:`~UserString.UserString` class from this module is available for backward
compatibility only. If you are writing code that does not need to work with
versions of Python earlier than Python 2.2, please consider subclassing directly
- from the built-in :class:`str` type instead of using :class:`UserString` (there
+ from the built-in :class:`str` type instead of using :class:`~UserString.UserString` (there
is no built-in equivalent to :class:`MutableString`).
This module defines a class that acts as a wrapper around string objects. It is
Class that simulates a string or a Unicode string object. The instance's
content is kept in a regular string or Unicode string object, which is
- accessible via the :attr:`data` attribute of :class:`UserString` instances. The
+ accessible via the :attr:`data` attribute of :class:`~UserString.UserString` instances. The
instance's contents are initially set to a copy of *sequence*. *sequence* can
be either a regular Python string or Unicode string, an instance of
- :class:`UserString` (or a subclass) or an arbitrary sequence which can be
+ :class:`~UserString.UserString` (or a subclass) or an arbitrary sequence which can be
converted into a string using the built-in :func:`str` function.
.. note::
- The :class:`UserString` class has been moved to the :mod:`collections`
+ The :class:`~UserString.UserString` class has been moved to the :mod:`collections`
module in Python 3. The :term:`2to3` tool will automatically adapt
imports when converting your sources to Python 3.
.. class:: MutableString([sequence])
- This class is derived from the :class:`UserString` above and redefines strings
+ This class is derived from the :class:`~UserString.UserString` above and redefines strings
to be *mutable*. Mutable strings can't be used as dictionary keys, because
dictionaries require *immutable* objects as keys. The main intention of this
class is to serve as an educational example for inheritance and necessity to
The :class:`MutableString` class has been removed in Python 3.
In addition to supporting the methods and operations of string and Unicode
-objects (see section :ref:`string-methods`), :class:`UserString` instances
+objects (see section :ref:`string-methods`), :class:`~UserString.UserString` instances
provide the following attribute:
.. attribute:: MutableString.data
A real Python string or Unicode object used to store the content of the
- :class:`UserString` class.
+ :class:`~UserString.UserString` class.
:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
the new value is restricted to a regular Python dictionary; you *can't* be
-tricky and set it to a :class:`UserDict` instance, or any other random object
+tricky and set it to a :class:`~UserDict.UserDict` instance, or any other random object
that behaves like a mapping.
so you can't just subclass, say, lists in order to add a single useful method to
them. The :mod:`UserList` module provides a class that supports all of the
methods of lists and that can be subclassed further, but there's lots of C code
-that expects a regular Python list and won't accept a :class:`UserList`
+that expects a regular Python list and won't accept a :class:`~UserList.UserList`
instance.
Python 2.2 fixes this, and in the process adds some exciting new capabilities.
fancy features, and just stick to the basics of representing time.
The three primary types are: :class:`date`, representing a day, month, and year;
-:class:`time`, consisting of hour, minute, and second; and :class:`datetime`,
-which contains all the attributes of both :class:`date` and :class:`time`.
+:class:`~datetime.time`, consisting of hour, minute, and second; and :class:`~datetime.datetime`,
+which contains all the attributes of both :class:`date` and :class:`~datetime.time`.
There's also a :class:`timedelta` class representing differences between two
points in time, and time zone logic is implemented by classes inheriting from
the abstract :class:`tzinfo` class.
-You can create instances of :class:`date` and :class:`time` by either supplying
+You can create instances of :class:`date` and :class:`~datetime.time` by either supplying
keyword arguments to the appropriate constructor, e.g.
``datetime.date(year=1972, month=10, day=15)``, or by using one of a number of
class methods. For example, the :meth:`date.today` class method returns the
'2002 30 Dec'
The :meth:`replace` method allows modifying one or more fields of a
-:class:`date` or :class:`datetime` instance, returning a new instance::
+:class:`date` or :class:`~datetime.datetime` instance, returning a new instance::
>>> d = datetime.datetime.now()
>>> d
>>>
Instances can be compared, hashed, and converted to strings (the result is the
-same as that of :meth:`isoformat`). :class:`date` and :class:`datetime`
+same as that of :meth:`isoformat`). :class:`date` and :class:`~datetime.datetime`
instances can be subtracted from each other, and added to :class:`timedelta`
instances. The largest missing feature is that there's no standard library
support for parsing strings and getting back a :class:`date` or
-:class:`datetime`.
+:class:`~datetime.datetime`.
For more information, refer to the module's reference documentation.
(Contributed by Tim Peters.)
empty list instead of raising a :exc:`TypeError` exception if called with no
arguments.
-* You can no longer compare the :class:`date` and :class:`datetime` instances
+* You can no longer compare the :class:`date` and :class:`~datetime.datetime` instances
provided by the :mod:`datetime` module. Two instances of different classes
will now always be unequal, and relative comparisons (``<``, ``>``) will raise
a :exc:`TypeError`.
(Contributed by Skip Montanaro and Andrew McNamara.)
-* The :class:`datetime` class in the :mod:`datetime` module now has a
+* The :class:`~datetime.datetime` class in the :mod:`datetime` module now has a
:meth:`strptime(string, format)` method for parsing date strings, contributed
by Josh Spoerri. It uses the same format characters as :func:`time.strptime` and
:func:`time.strftime`::
* The :mod:`pyexpat` module now uses version 2.0 of the Expat parser.
(Contributed by Trent Mick.)
-* The :class:`Queue` class provided by the :mod:`Queue` module gained two new
+* The :class:`~Queue.Queue` class provided by the :mod:`Queue` module gained two new
methods. :meth:`join` blocks until all items in the queue have been retrieved
and all processing work on the items have been completed. Worker threads call
the other new method, :meth:`task_done`, to signal that processing for an item
.. Patch #754022
-* The :mod:`xmlrpclib` module now supports returning :class:`datetime` objects
+* The :mod:`xmlrpclib` module now supports returning :class:`~datetime.datetime` objects
for the XML-RPC date type. Supply ``use_datetime=True`` to the :func:`loads`
function or the :class:`Unmarshaller` class to enable this feature. (Contributed
by Skip Montanaro.)
result = queue.get()
print 'Factorial', N, '=', result
-A :class:`Queue` is used to communicate the result of the factorial.
-The :class:`Queue` object is stored in a global variable.
+A :class:`~Queue.Queue` is used to communicate the result of the factorial.
+The :class:`~Queue.Queue` object is stored in a global variable.
The child process will use the value of the variable when the child
-was created; because it's a :class:`Queue`, parent and child can use
+was created; because it's a :class:`~Queue.Queue`, parent and child can use
the object to communicate. (If the parent were to change the value of
the global variable, the child's value would be unaffected, and vice
versa.)
There are two concrete implementations. :class:`TextIOWrapper`
wraps a buffered I/O object, supporting all of the methods for
text I/O and adding a :attr:`buffer` attribute for access
- to the underlying object. :class:`StringIO` simply buffers
+ to the underlying object. :class:`~StringIO.StringIO` simply buffers
everything in memory without ever writing anything to disk.
(In Python 2.6, :class:`io.StringIO` is implemented in
(Contributed by Christian Heimes and Mark Dickinson.)
-* :class:`mmap` objects now have a :meth:`rfind` method that searches for a
+* :class:`~mmap.mmap` objects now have a :meth:`rfind` method that searches for a
substring beginning at the end of the string and searching
backwards. The :meth:`find` method also gained an *end* parameter
giving an index at which to stop searching.
intended for testing purposes that lets you temporarily modify the
warning filters and then restore their original values (:issue:`3781`).
-* The XML-RPC :class:`SimpleXMLRPCServer` and :class:`DocXMLRPCServer`
+* The XML-RPC :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` and :class:`~DocXMLRPCServer.DocXMLRPCServer`
classes can now be prevented from immediately opening and binding to
their socket by passing True as the ``bind_and_activate``
constructor parameter. This can be used to modify the instance's
open the socket and begin listening for connections.
(Contributed by Peter Parente; :issue:`1599845`.)
- :class:`SimpleXMLRPCServer` also has a :attr:`_send_traceback_header`
+ :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` also has a :attr:`_send_traceback_header`
attribute; if true, the exception and formatted traceback are returned
as HTTP headers "X-Exception" and "X-Traceback". This feature is
for debugging purposes only and should not be used on production servers
:class:`datetime.date` and :class:`datetime.time` to the
:class:`xmlrpclib.DateTime` type; the conversion semantics were
not necessarily correct for all applications. Code using
- :mod:`xmlrpclib` should convert :class:`date` and :class:`time`
+ :mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
instances. (:issue:`1330538`) The code can also handle
dates before 1900 (contributed by Ralf Schmitt; :issue:`2014`)
and 64-bit integers represented by using ``<i8>`` in XML-RPC responses
:class:`datetime.date` and :class:`datetime.time` to the
:class:`xmlrpclib.DateTime` type; the conversion semantics were
not necessarily correct for all applications. Code using
- :mod:`xmlrpclib` should convert :class:`date` and :class:`time`
+ :mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
instances. (:issue:`1330538`)
* (3.0-warning mode) The :class:`Exception` class now warns
projects / python / commitdiff