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