Fixed: #2914 (RFE for UTC support in TimedRotatingFileHandler) and #2929 (wrong filen...
[python.git] / Doc / library / userdict.rst
blob7d3640153c9ed13aca8d44e44bd84b6ce724a8ee
2 :mod:`UserDict` --- Class wrapper for dictionary objects
3 ========================================================
5 .. module:: UserDict
6    :synopsis: Class wrapper for dictionary objects.
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).
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.
22 The :mod:`UserDict` module defines the :class:`UserDict` class and
23 :class:`DictMixin`:
26 .. class:: UserDict([initialdata])
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.
34    .. note::
36       For backward compatibility, instances of :class:`UserDict` are not iterable.
39 .. class:: IterableUserDict([initialdata])
41    Subclass of :class:`UserDict` that supports direct iteration (e.g.  ``for key in
42    myDict``).
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:
49 .. attribute:: IterableUserDict.data
51    A real dictionary used to store the contents of the :class:`UserDict` class.
54 .. class:: DictMixin()
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`.
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.
65    In addition to the four base methods, progressively more efficiency comes with
66    defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
68    Since the mixin has no knowledge of the subclass constructor, it does not define
69    :meth:`__init__` or :meth:`copy`.
71    Starting with Python version 2.6, it is recommended to use
72    :class:`collections.MutableMapping` instead of :class:`DictMixin`.
74 :mod:`UserList` --- Class wrapper for list objects
75 ==================================================
77 .. module:: UserList
78    :synopsis: Class wrapper for list objects.
81 .. note::
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.
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.
92 The :mod:`UserList` module defines the :class:`UserList` class:
95 .. class:: UserList([list])
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.
103 In addition to supporting the methods and operations of mutable sequences (see
104 section :ref:`typesseq`), :class:`UserList` instances provide the following
105 attribute:
108 .. attribute:: UserList.data
110    A real Python list object used to store the contents of the :class:`UserList`
111    class.
113 **Subclassing requirements:** Subclasses of :class:`UserList` are expect to
114 offer a constructor which can be called with either no arguments or one
115 argument.  List operations which return a new sequence attempt to create an
116 instance of the actual implementation class.  To do so, it assumes that the
117 constructor can be called with a single parameter, which is a sequence object
118 used as a data source.
120 If a derived class does not wish to comply with this requirement, all of the
121 special methods supported by this class will need to be overridden; please
122 consult the sources for information about the methods which need to be provided
123 in that case.
125 .. versionchanged:: 2.0
126    Python versions 1.5.2 and 1.6 also required that the constructor be callable
127    with no parameters, and offer a mutable :attr:`data` attribute.  Earlier
128    versions of Python did not attempt to create instances of the derived class.
131 :mod:`UserString` --- Class wrapper for string objects
132 ======================================================
134 .. module:: UserString
135    :synopsis: Class wrapper for string objects.
136 .. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>
137 .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
140 .. note::
142    This :class:`UserString` class from this module is available for backward
143    compatibility only.  If you are writing code that does not need to work with
144    versions of Python earlier than Python 2.2, please consider subclassing directly
145    from the built-in :class:`str` type instead of using :class:`UserString` (there
146    is no built-in equivalent to :class:`MutableString`).
148 This module defines a class that acts as a wrapper around string objects.  It is
149 a useful base class for your own string-like classes, which can inherit from
150 them and override existing methods or add new ones.  In this way one can add new
151 behaviors to strings.
153 It should be noted that these classes are highly inefficient compared to real
154 string or Unicode objects; this is especially the case for
155 :class:`MutableString`.
157 The :mod:`UserString` module defines the following classes:
160 .. class:: UserString([sequence])
162    Class that simulates a string or a Unicode string object.  The instance's
163    content is kept in a regular string or Unicode string object, which is
164    accessible via the :attr:`data` attribute of :class:`UserString` instances.  The
165    instance's contents are initially set to a copy of *sequence*.  *sequence* can
166    be either a regular Python string or Unicode string, an instance of
167    :class:`UserString` (or a subclass) or an arbitrary sequence which can be
168    converted into a string using the built-in :func:`str` function.
171 .. class:: MutableString([sequence])
173    This class is derived from the :class:`UserString` above and redefines strings
174    to be *mutable*.  Mutable strings can't be used as dictionary keys, because
175    dictionaries require *immutable* objects as keys.  The main intention of this
176    class is to serve as an educational example for inheritance and necessity to
177    remove (override) the :meth:`__hash__` method in order to trap attempts to use a
178    mutable object as dictionary key, which would be otherwise very error prone and
179    hard to track down.
181 In addition to supporting the methods and operations of string and Unicode
182 objects (see section :ref:`string-methods`), :class:`UserString` instances
183 provide the following attribute:
186 .. attribute:: MutableString.data
188    A real Python string or Unicode object used to store the content of the
189    :class:`UserString` class.