/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
  9The module defines a mixin,  :class:`DictMixin`, defining all dictionary methods
 10for classes that already have a minimum mapping interface.  This greatly
 11simplifies writing classes that need to be substitutable for dictionaries (such
 12as the shelve module).
 13
 14This module also defines a class, :class:`UserDict`, that acts as a wrapper
 15around dictionary objects.  The need for this class has been largely supplanted
 16by the ability to subclass directly from :class:`dict` (a feature that became
 17available starting with Python version 2.2).  Prior to the introduction of
 18:class:`dict`, the :class:`UserDict` class was used to create dictionary-like
 19sub-classes that obtained new behaviors by overriding existing methods or adding
 20new ones.
 21
 22The :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
 44In addition to supporting the methods and operations of mappings (see section
 45:ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances
 46provide 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
 87This module defines a class that acts as a wrapper around list objects.  It is a
 88useful base class for your own list-like classes, which can inherit from them
 89and override existing methods or add new ones.  In this way one can add new
 90behaviors to lists.
 91
 92The :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
109In addition to supporting the methods and operations of mutable sequences (see
110section :ref:`typesseq`), :class:`UserList` instances provide the following
111attribute:
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
120offer a constructor which can be called with either no arguments or one
121argument.  List operations which return a new sequence attempt to create an
122instance of the actual implementation class.  To do so, it assumes that the
123constructor can be called with a single parameter, which is a sequence object
124used as a data source.
125
126If a derived class does not wish to comply with this requirement, all of the
127special methods supported by this class will need to be overridden; please
128consult the sources for information about the methods which need to be provided
129in 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
154This module defines a class that acts as a wrapper around string objects.  It is
155a useful base class for your own string-like classes, which can inherit from
156them and override existing methods or add new ones.  In this way one can add new
157behaviors to strings.
158
159It should be noted that these classes are highly inefficient compared to real
160string or Unicode objects; this is especially the case for
161:class:`MutableString`.
162
163The :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
196In addition to supporting the methods and operations of string and Unicode
197objects (see section :ref:`string-methods`), :class:`UserString` instances
198provide 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