209 lines
8.2 KiB
ReStructuredText
209 lines
8.2 KiB
ReStructuredText
:mod:`UserDict` --- Class wrapper for dictionary objects
|
|
========================================================
|
|
|
|
.. module:: UserDict
|
|
:synopsis: Class wrapper for dictionary objects.
|
|
|
|
|
|
**Source code:** :source:`Lib/UserDict.py`
|
|
|
|
--------------
|
|
|
|
The module defines a mixin, :class:`DictMixin`, defining all dictionary methods
|
|
for classes that already have a minimum mapping interface. This greatly
|
|
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
|
|
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
|
|
sub-classes that obtained new behaviors by overriding existing methods or adding
|
|
new ones.
|
|
|
|
The :mod:`UserDict` module defines the :class:`UserDict` class and
|
|
:class:`DictMixin`:
|
|
|
|
|
|
.. class:: UserDict([initialdata])
|
|
|
|
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
|
|
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.
|
|
|
|
|
|
.. class:: IterableUserDict([initialdata])
|
|
|
|
Subclass of :class:`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
|
|
provide the following attribute:
|
|
|
|
|
|
.. attribute:: IterableUserDict.data
|
|
|
|
A real dictionary used to store the contents of the :class:`UserDict` class.
|
|
|
|
|
|
.. class:: DictMixin()
|
|
|
|
Mixin defining all dictionary methods for classes that already have a minimum
|
|
dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,
|
|
:meth:`__delitem__`, and :meth:`keys`.
|
|
|
|
This mixin should be used as a superclass. Adding each of the above methods
|
|
adds progressively more functionality. For instance, defining all but
|
|
:meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the
|
|
full interface.
|
|
|
|
In addition to the four base methods, progressively more efficiency comes with
|
|
defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
|
|
|
|
Since the mixin has no knowledge of the subclass constructor, it does not define
|
|
:meth:`__init__` or :meth:`copy`.
|
|
|
|
Starting with Python version 2.6, it is recommended to use
|
|
:class:`collections.MutableMapping` instead of :class:`DictMixin`.
|
|
|
|
:mod:`UserList` --- Class wrapper for list objects
|
|
==================================================
|
|
|
|
.. module:: UserList
|
|
:synopsis: Class wrapper for list objects.
|
|
|
|
|
|
.. note::
|
|
|
|
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:`list` type.
|
|
|
|
This module defines a class that acts as a wrapper around list objects. It is a
|
|
useful base class for your own list-like classes, which can inherit from them
|
|
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:
|
|
|
|
|
|
.. 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`
|
|
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.
|
|
|
|
.. note::
|
|
The :class:`UserList` class has been moved to the :mod:`collections`
|
|
module in Python 3.0. The :term:`2to3` tool will automatically adapt
|
|
imports when converting your sources to 3.0.
|
|
|
|
|
|
In addition to supporting the methods and operations of mutable sequences (see
|
|
section :ref:`typesseq`), :class:`UserList` instances provide the following
|
|
attribute:
|
|
|
|
|
|
.. attribute:: UserList.data
|
|
|
|
A real Python list object used to store the contents of the :class:`UserList`
|
|
class.
|
|
|
|
**Subclassing requirements:** Subclasses of :class:`UserList` are expect 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
|
|
constructor can be called with a single parameter, which is a sequence object
|
|
used as a data source.
|
|
|
|
If a derived class does not wish to comply with this requirement, all of the
|
|
special methods supported by this class will need to be overridden; please
|
|
consult the sources for information about the methods which need to be provided
|
|
in that case.
|
|
|
|
.. versionchanged:: 2.0
|
|
Python versions 1.5.2 and 1.6 also required that the constructor be callable
|
|
with no parameters, and offer a mutable :attr:`data` attribute. Earlier
|
|
versions of Python did not attempt to create instances of the derived class.
|
|
|
|
|
|
:mod:`UserString` --- Class wrapper for string objects
|
|
======================================================
|
|
|
|
.. module:: UserString
|
|
:synopsis: Class wrapper for string objects.
|
|
.. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>
|
|
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
|
|
|
|
|
|
.. note::
|
|
|
|
This :class:`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
|
|
is no built-in equivalent to :class:`MutableString`).
|
|
|
|
This module defines a class that acts as a wrapper around string objects. It is
|
|
a useful base class for your own string-like classes, which can inherit from
|
|
them and override existing methods or add new ones. In this way one can add new
|
|
behaviors to strings.
|
|
|
|
It should be noted that these classes are highly inefficient compared to real
|
|
string or Unicode objects; this is especially the case for
|
|
:class:`MutableString`.
|
|
|
|
The :mod:`UserString` module defines the following classes:
|
|
|
|
|
|
.. class:: UserString([sequence])
|
|
|
|
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
|
|
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
|
|
converted into a string using the built-in :func:`str` function.
|
|
|
|
.. note::
|
|
The :class:`UserString` class has been moved to the :mod:`collections`
|
|
module in Python 3.0. The :term:`2to3` tool will automatically adapt
|
|
imports when converting your sources to 3.0.
|
|
|
|
|
|
|
|
.. class:: MutableString([sequence])
|
|
|
|
This class is derived from the :class:`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
|
|
remove (override) the :meth:`__hash__` method in order to trap attempts to use a
|
|
mutable object as dictionary key, which would be otherwise very error prone and
|
|
hard to track down.
|
|
|
|
.. deprecated:: 2.6
|
|
The :class:`MutableString` class has been removed in Python 3.0.
|
|
|
|
In addition to supporting the methods and operations of string and Unicode
|
|
objects (see section :ref:`string-methods`), :class:`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.
|
|
|