Doc/library/userdict.rst

   1
   2 :mod:`UserDict` --- Class wrapper for dictionary objects
   3 ========================================================
   4
   5 .. module:: UserDict
   6    :synopsis: Class wrapper for dictionary objects.
   7
   8
   9 The module defines a mixin,  :class:`DictMixin`, defining all dictionary methods
  10 for classes that already have a minimum mapping interface.  This greatly
  11 simplifies writing classes that need to be substitutable for dictionaries (such
  12 as the shelve module).
  13
  14 This module also defines a class, :class:`UserDict`, that acts as a wrapper
  15 around dictionary objects.  The need for this class has been largely supplanted
  16 by the ability to subclass directly from :class:`dict` (a feature that became
  17 available starting with Python version 2.2).  Prior to the introduction of
  18 :class:`dict`, the :class:`UserDict` class was used to create dictionary-like
  19 sub-classes that obtained new behaviors by overriding existing methods or adding
  20 new ones.
  21
  22 The :mod:`UserDict` module defines the :class:`UserDict` class and
  23 :class:`DictMixin`:
  24
  25
  26 .. class:: UserDict([initialdata])
  27
  28    Class that simulates a dictionary.  The instance's contents are kept in a
  29    regular dictionary, which is accessible via the :attr:`data` attribute of
  30    :class:`UserDict` instances.  If *initialdata* is provided, :attr:`data` is
  31    initialized with its contents; note that a reference to *initialdata* will not
  32    be kept, allowing it be used for other purposes.
  33
  34    .. note::
  35
  36       For backward compatibility, instances of :class:`UserDict` are not iterable.
  37
  38
  39 .. class:: IterableUserDict([initialdata])
  40
  41    Subclass of :class:`UserDict` that supports direct iteration (e.g.  ``for key in
  42    myDict``).
  43
  44 In addition to supporting the methods and operations of mappings (see section
  45 :ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances
  46 provide the following attribute:
  47
  48
  49 .. attribute:: IterableUserDict.data
  50
  51    A real dictionary used to store the contents of the :class:`UserDict` class.
  52
  53
  54 .. class:: DictMixin()
  55
  56    Mixin defining all dictionary methods for classes that already have a minimum
  57    dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,
  58    :meth:`__delitem__`, and :meth:`keys`.
  59
  60    This mixin should be used as a superclass.  Adding each of the above methods
  61    adds progressively more functionality.  For instance, defining all but
  62    :meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the
  63    full interface.
  64
  65    In addition to the four base methods, progressively more efficiency comes with
  66    defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
  67
  68    Since the mixin has no knowledge of the subclass constructor, it does not define
  69    :meth:`__init__` or :meth:`copy`.
  70
  71    Starting with Python version 2.6, it is recommended to use
  72    :class:`collections.MutableMapping` instead of :class:`DictMixin`.
  73
  74 :mod:`UserList` --- Class wrapper for list objects
  75 ==================================================
  76
  77 .. module:: UserList
  78    :synopsis: Class wrapper for list objects.
  79
  80
  81 .. note::
  82
  83    This module is available for backward compatibility only.  If you are writing
  84    code that does not need to work with versions of Python earlier than Python 2.2,
  85    please consider subclassing directly from the built-in :class:`list` type.
  86
  87 This module defines a class that acts as a wrapper around list objects.  It is a
  88 useful base class for your own list-like classes, which can inherit from them
  89 and override existing methods or add new ones.  In this way one can add new
  90 behaviors to lists.
  91
  92 The :mod:`UserList` module defines the :class:`UserList` class:
  93
  94
  95 .. class:: UserList([list])
  96
  97    Class that simulates a list.  The instance's contents are kept in a regular
  98    list, which is accessible via the :attr:`data` attribute of :class:`UserList`
  99    instances.  The instance's contents are initially set to a copy of *list*,
 100    defaulting to the empty list ``[]``.  *list* can be any iterable, e.g. a
 101    real Python list or a :class:`UserList` object.
 102
 103    .. note::
 104       The :class:`UserList` class has been moved to the :mod:`collections`
 105       module in Python 3.0. The :term:`2to3` tool will automatically adapt
 106       imports when converting your sources to 3.0.
 107
 108
 109 In addition to supporting the methods and operations of mutable sequences (see
 110 section :ref:`typesseq`), :class:`UserList` instances provide the following
 111 attribute:
 112
 113
 114 .. attribute:: UserList.data
 115
 116    A real Python list object used to store the contents of the :class:`UserList`
 117    class.
 118
 119 **Subclassing requirements:** Subclasses of :class:`UserList` are expect to
 120 offer a constructor which can be called with either no arguments or one
 121 argument.  List operations which return a new sequence attempt to create an
 122 instance of the actual implementation class.  To do so, it assumes that the
 123 constructor can be called with a single parameter, which is a sequence object
 124 used as a data source.
 125
 126 If a derived class does not wish to comply with this requirement, all of the
 127 special methods supported by this class will need to be overridden; please
 128 consult the sources for information about the methods which need to be provided
 129 in that case.
 130
 131 .. versionchanged:: 2.0
 132    Python versions 1.5.2 and 1.6 also required that the constructor be callable
 133    with no parameters, and offer a mutable :attr:`data` attribute.  Earlier
 134    versions of Python did not attempt to create instances of the derived class.
 135
 136
 137 :mod:`UserString` --- Class wrapper for string objects
 138 ======================================================
 139
 140 .. module:: UserString
 141    :synopsis: Class wrapper for string objects.
 142 .. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>
 143 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
 144
 145
 146 .. note::
 147
 148    This :class:`UserString` class from this module is available for backward
 149    compatibility only.  If you are writing code that does not need to work with
 150    versions of Python earlier than Python 2.2, please consider subclassing directly
 151    from the built-in :class:`str` type instead of using :class:`UserString` (there
 152    is no built-in equivalent to :class:`MutableString`).
 153
 154 This module defines a class that acts as a wrapper around string objects.  It is
 155 a useful base class for your own string-like classes, which can inherit from
 156 them and override existing methods or add new ones.  In this way one can add new
 157 behaviors to strings.
 158
 159 It should be noted that these classes are highly inefficient compared to real
 160 string or Unicode objects; this is especially the case for
 161 :class:`MutableString`.
 162
 163 The :mod:`UserString` module defines the following classes:
 164
 165
 166 .. class:: UserString([sequence])
 167
 168    Class that simulates a string or a Unicode string object.  The instance's
 169    content is kept in a regular string or Unicode string object, which is
 170    accessible via the :attr:`data` attribute of :class:`UserString` instances.  The
 171    instance's contents are initially set to a copy of *sequence*.  *sequence* can
 172    be either a regular Python string or Unicode string, an instance of
 173    :class:`UserString` (or a subclass) or an arbitrary sequence which can be
 174    converted into a string using the built-in :func:`str` function.
 175
 176    .. note::
 177       The :class:`UserString` class has been moved to the :mod:`collections`
 178       module in Python 3.0. The :term:`2to3` tool will automatically adapt
 179       imports when converting your sources to 3.0.
 180
 181
 182
 183 .. class:: MutableString([sequence])
 184
 185    This class is derived from the :class:`UserString` above and redefines strings
 186    to be *mutable*.  Mutable strings can't be used as dictionary keys, because
 187    dictionaries require *immutable* objects as keys.  The main intention of this
 188    class is to serve as an educational example for inheritance and necessity to
 189    remove (override) the :meth:`__hash__` method in order to trap attempts to use a
 190    mutable object as dictionary key, which would be otherwise very error prone and
 191    hard to track down.
 192
 193    .. deprecated:: 2.6
 194       The :class:`MutableString` class has been removed in Python 3.0.
 195
 196 In addition to supporting the methods and operations of string and Unicode
 197 objects (see section :ref:`string-methods`), :class:`UserString` instances
 198 provide the following attribute:
 199
 200
 201 .. attribute:: MutableString.data
 202
 203    A real Python string or Unicode object used to store the content of the
 204    :class:`UserString` class.
 205