Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 also module 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 | |
| 72 | :mod:`UserList` --- Class wrapper for list objects |
| 73 | ================================================== |
| 74 | |
| 75 | .. module:: UserList |
| 76 | :synopsis: Class wrapper for list objects. |
| 77 | |
| 78 | |
| 79 | .. note:: |
| 80 | |
| 81 | This module is available for backward compatibility only. If you are writing |
| 82 | code that does not need to work with versions of Python earlier than Python 2.2, |
| 83 | please consider subclassing directly from the built-in :class:`list` type. |
| 84 | |
| 85 | This module defines a class that acts as a wrapper around list objects. It is a |
| 86 | useful base class for your own list-like classes, which can inherit from them |
| 87 | and override existing methods or add new ones. In this way one can add new |
| 88 | behaviors to lists. |
| 89 | |
| 90 | The :mod:`UserList` module defines the :class:`UserList` class: |
| 91 | |
| 92 | |
| 93 | .. class:: UserList([list]) |
| 94 | |
| 95 | Class that simulates a list. The instance's contents are kept in a regular |
| 96 | list, which is accessible via the :attr:`data` attribute of :class:`UserList` |
| 97 | instances. The instance's contents are initially set to a copy of *list*, |
| 98 | defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a |
| 99 | real Python list or a :class:`UserList` object. |
| 100 | |
| 101 | In addition to supporting the methods and operations of mutable sequences (see |
| 102 | section :ref:`typesseq`), :class:`UserList` instances provide the following |
| 103 | attribute: |
| 104 | |
| 105 | |
| 106 | .. attribute:: UserList.data |
| 107 | |
| 108 | A real Python list object used to store the contents of the :class:`UserList` |
| 109 | class. |
| 110 | |
| 111 | **Subclassing requirements:** Subclasses of :class:`UserList` are expect to |
| 112 | offer a constructor which can be called with either no arguments or one |
| 113 | argument. List operations which return a new sequence attempt to create an |
| 114 | instance of the actual implementation class. To do so, it assumes that the |
| 115 | constructor can be called with a single parameter, which is a sequence object |
| 116 | used as a data source. |
| 117 | |
| 118 | If a derived class does not wish to comply with this requirement, all of the |
| 119 | special methods supported by this class will need to be overridden; please |
| 120 | consult the sources for information about the methods which need to be provided |
| 121 | in that case. |
| 122 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
| 124 | :mod:`UserString` --- Class wrapper for string objects |
| 125 | ====================================================== |
| 126 | |
| 127 | .. module:: UserString |
| 128 | :synopsis: Class wrapper for string objects. |
| 129 | .. moduleauthor:: Peter Funk <pf@artcom-gmbh.de> |
| 130 | .. sectionauthor:: Peter Funk <pf@artcom-gmbh.de> |
| 131 | |
| 132 | |
| 133 | .. note:: |
| 134 | |
| 135 | This :class:`UserString` class from this module is available for backward |
| 136 | compatibility only. If you are writing code that does not need to work with |
| 137 | versions of Python earlier than Python 2.2, please consider subclassing directly |
| 138 | from the built-in :class:`str` type instead of using :class:`UserString` (there |
| 139 | is no built-in equivalent to :class:`MutableString`). |
| 140 | |
| 141 | This module defines a class that acts as a wrapper around string objects. It is |
| 142 | a useful base class for your own string-like classes, which can inherit from |
| 143 | them and override existing methods or add new ones. In this way one can add new |
| 144 | behaviors to strings. |
| 145 | |
| 146 | It should be noted that these classes are highly inefficient compared to real |
| 147 | string or Unicode objects; this is especially the case for |
| 148 | :class:`MutableString`. |
| 149 | |
| 150 | The :mod:`UserString` module defines the following classes: |
| 151 | |
| 152 | |
| 153 | .. class:: UserString([sequence]) |
| 154 | |
| 155 | Class that simulates a string or a Unicode string object. The instance's |
| 156 | content is kept in a regular string or Unicode string object, which is |
| 157 | accessible via the :attr:`data` attribute of :class:`UserString` instances. The |
| 158 | instance's contents are initially set to a copy of *sequence*. *sequence* can |
| 159 | be either a regular Python string or Unicode string, an instance of |
| 160 | :class:`UserString` (or a subclass) or an arbitrary sequence which can be |
| 161 | converted into a string using the built-in :func:`str` function. |
| 162 | |
| 163 | |
| 164 | .. class:: MutableString([sequence]) |
| 165 | |
| 166 | This class is derived from the :class:`UserString` above and redefines strings |
| 167 | to be *mutable*. Mutable strings can't be used as dictionary keys, because |
| 168 | dictionaries require *immutable* objects as keys. The main intention of this |
| 169 | class is to serve as an educational example for inheritance and necessity to |
| 170 | remove (override) the :meth:`__hash__` method in order to trap attempts to use a |
| 171 | mutable object as dictionary key, which would be otherwise very error prone and |
| 172 | hard to track down. |
| 173 | |
| 174 | In addition to supporting the methods and operations of string and Unicode |
| 175 | objects (see section :ref:`string-methods`), :class:`UserString` instances |
| 176 | provide the following attribute: |
| 177 | |
| 178 | |
| 179 | .. attribute:: MutableString.data |
| 180 | |
| 181 | A real Python string or Unicode object used to store the content of the |
| 182 | :class:`UserString` class. |
| 183 | |