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 12 The module defines a mixin, :class:`DictMixin`, defining all dictionary methods 13 for classes that already have a minimum mapping interface. This greatly 14 simplifies writing classes that need to be substitutable for dictionaries (such 15 as the shelve module). 16 17 This module also defines a class, :class:`~UserDict.UserDict`, that acts as a wrapper 18 around dictionary objects. The need for this class has been largely supplanted 19 by the ability to subclass directly from :class:`dict` (a feature that became 20 available 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 22 sub-classes that obtained new behaviors by overriding existing methods or adding 23 new ones. 24 25 The :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 47 In addition to supporting the methods and operations of mappings (see section 48 :ref:`typesmapping`), :class:`~UserDict.UserDict` and :class:`IterableUserDict` instances 49 provide 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 102 This module defines a class that acts as a wrapper around list objects. It is a 103 useful base class for your own list-like classes, which can inherit from them 104 and override existing methods or add new ones. In this way one can add new 105 behaviors to lists. 106 107 The :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 124 In addition to supporting the methods and operations of mutable sequences (see 125 section :ref:`typesseq`), :class:`~UserList.UserList` instances provide the following 126 attribute: 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 135 offer a constructor which can be called with either no arguments or one 136 argument. List operations which return a new sequence attempt to create an 137 instance of the actual implementation class. To do so, it assumes that the 138 constructor can be called with a single parameter, which is a sequence object 139 used as a data source. 140 141 If a derived class does not wish to comply with this requirement, all of the 142 special methods supported by this class will need to be overridden; please 143 consult the sources for information about the methods which need to be provided 144 in 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 (a] artcom-gmbh.de> 158 .. sectionauthor:: Peter Funk <pf (a] 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 169 This module defines a class that acts as a wrapper around string objects. It is 170 a useful base class for your own string-like classes, which can inherit from 171 them and override existing methods or add new ones. In this way one can add new 172 behaviors to strings. 173 174 It should be noted that these classes are highly inefficient compared to real 175 string or Unicode objects; this is especially the case for 176 :class:`MutableString`. 177 178 The :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 211 In addition to supporting the methods and operations of string and Unicode 212 objects (see section :ref:`string-methods`), :class:`~UserString.UserString` instances 213 provide 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
