Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{UserDict} --- |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 2 | Class wrapper for dictionary objects} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{UserDict} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Class wrapper for dictionary objects.} |
| 6 | |
Fred Drake | d5be3b7 | 2001-10-26 18:37:27 +0000 | [diff] [blame] | 7 | |
Raymond Hettinger | 31043cd | 2005-01-04 21:25:00 +0000 | [diff] [blame] | 8 | The module defines a mixin, \class{DictMixin}, defining all dictionary |
| 9 | methods for classes that already have a minimum mapping interface. This |
| 10 | greatly simplifies writing classes that need to be substitutable for |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 11 | dictionaries (such as the shelve module). |
| 12 | |
Raymond Hettinger | 31043cd | 2005-01-04 21:25:00 +0000 | [diff] [blame] | 13 | This also module defines a class, \class{UserDict}, that acts as a wrapper |
| 14 | around dictionary objects. The need for this class has been largely |
| 15 | supplanted by the ability to subclass directly from \class{dict} (a feature |
| 16 | that became available starting with Python version 2.2). Prior to the |
| 17 | introduction of \class{dict}, the \class{UserDict} class was used to |
| 18 | create dictionary-like sub-classes that obtained new behaviors by overriding |
| 19 | existing methods or adding new ones. |
| 20 | |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 21 | The \module{UserDict} module defines the \class{UserDict} class |
| 22 | and \class{DictMixin}: |
Guido van Rossum | 7f3b042 | 1997-03-27 14:56:18 +0000 | [diff] [blame] | 23 | |
Georg Brandl | 54d8b68 | 2005-06-25 21:03:52 +0000 | [diff] [blame] | 24 | \begin{classdesc}{UserDict}{\optional{initialdata}} |
| 25 | Class that simulates a dictionary. The instance's contents are kept |
| 26 | in a regular dictionary, which is accessible via the \member{data} |
| 27 | attribute of \class{UserDict} instances. If \var{initialdata} is |
| 28 | provided, \member{data} is initialized with its contents; note that a |
| 29 | reference to \var{initialdata} will not be kept, allowing it be used |
| 30 | for other purposes. \note{For backward compatibility, instances of |
| 31 | \class{UserDict} are not iterable.} |
| 32 | \end{classdesc} |
| 33 | |
| 34 | \begin{classdesc}{IterableUserDict}{\optional{initialdata}} |
| 35 | Subclass of \class{UserDict} that supports direct iteration (e.g. |
| 36 | \code{for key in myDict}). |
Fred Drake | 802a202 | 1998-02-19 06:26:35 +0000 | [diff] [blame] | 37 | \end{classdesc} |
Guido van Rossum | 7f3b042 | 1997-03-27 14:56:18 +0000 | [diff] [blame] | 38 | |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 39 | In addition to supporting the methods and operations of mappings (see |
Georg Brandl | 54d8b68 | 2005-06-25 21:03:52 +0000 | [diff] [blame] | 40 | section \ref{typesmapping}), \class{UserDict} and |
| 41 | \class{IterableUserDict} instances provide the following attribute: |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 42 | |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 43 | \begin{memberdesc}{data} |
| 44 | A real dictionary used to store the contents of the \class{UserDict} |
| 45 | class. |
| 46 | \end{memberdesc} |
| 47 | |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 48 | \begin{classdesc}{DictMixin}{} |
| 49 | Mixin defining all dictionary methods for classes that already have |
Raymond Hettinger | 8ddc176e | 2002-11-18 04:34:10 +0000 | [diff] [blame] | 50 | a minimum dictionary interface including \method{__getitem__()}, |
| 51 | \method{__setitem__()}, \method{__delitem__()}, and \method{keys()}. |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 52 | |
| 53 | This mixin should be used as a superclass. Adding each of the |
| 54 | above methods adds progressively more functionality. For instance, |
Raymond Hettinger | 8ddc176e | 2002-11-18 04:34:10 +0000 | [diff] [blame] | 55 | defining all but \method{__delitem__} will preclude only \method{pop} |
| 56 | and \method{popitem} from the full interface. |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 57 | |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 58 | In addition to the four base methods, progressively more efficiency |
Raymond Hettinger | 8ddc176e | 2002-11-18 04:34:10 +0000 | [diff] [blame] | 59 | comes with defining \method{__contains__()}, \method{__iter__()}, and |
| 60 | \method{iteritems()}. |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 61 | |
Raymond Hettinger | 8ddc176e | 2002-11-18 04:34:10 +0000 | [diff] [blame] | 62 | Since the mixin has no knowledge of the subclass constructor, it |
| 63 | does not define \method{__init__()} or \method{copy()}. |
Raymond Hettinger | 7994716 | 2002-11-15 06:46:14 +0000 | [diff] [blame] | 64 | \end{classdesc} |
| 65 | |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 66 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 67 | \section{\module{UserList} --- |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 68 | Class wrapper for list objects} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 69 | |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 70 | \declaremodule{standard}{UserList} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 71 | \modulesynopsis{Class wrapper for list objects.} |
| 72 | |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 73 | |
Fred Drake | d5be3b7 | 2001-10-26 18:37:27 +0000 | [diff] [blame] | 74 | \note{This module is available for backward compatibility only. If |
| 75 | you are writing code that does not need to work with versions of |
| 76 | Python earlier than Python 2.2, please consider subclassing directly |
| 77 | from the built-in \class{list} type.} |
| 78 | |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 79 | This module defines a class that acts as a wrapper around |
| 80 | list objects. It is a useful base class for |
| 81 | your own list-like classes, which can inherit from |
| 82 | them and override existing methods or add new ones. In this way one |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 83 | can add new behaviors to lists. |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 84 | |
Fred Drake | 802a202 | 1998-02-19 06:26:35 +0000 | [diff] [blame] | 85 | The \module{UserList} module defines the \class{UserList} class: |
Guido van Rossum | 7f3b042 | 1997-03-27 14:56:18 +0000 | [diff] [blame] | 86 | |
Fred Drake | 802a202 | 1998-02-19 06:26:35 +0000 | [diff] [blame] | 87 | \begin{classdesc}{UserList}{\optional{list}} |
Fred Drake | 2c4f554 | 2000-10-10 22:00:03 +0000 | [diff] [blame] | 88 | Class that simulates a list. The instance's |
Guido van Rossum | 7f3b042 | 1997-03-27 14:56:18 +0000 | [diff] [blame] | 89 | contents are kept in a regular list, which is accessible via the |
Fred Drake | 802a202 | 1998-02-19 06:26:35 +0000 | [diff] [blame] | 90 | \member{data} attribute of \class{UserList} instances. The instance's |
Fred Drake | fcda560 | 1998-01-07 22:05:25 +0000 | [diff] [blame] | 91 | contents are initially set to a copy of \var{list}, defaulting to the |
Guido van Rossum | 7f3b042 | 1997-03-27 14:56:18 +0000 | [diff] [blame] | 92 | empty list \code{[]}. \var{list} can be either a regular Python list, |
Fred Drake | 802a202 | 1998-02-19 06:26:35 +0000 | [diff] [blame] | 93 | or an instance of \class{UserList} (or a subclass). |
| 94 | \end{classdesc} |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 95 | |
Fred Drake | 6bf37de | 1999-06-29 18:13:37 +0000 | [diff] [blame] | 96 | In addition to supporting the methods and operations of mutable |
| 97 | sequences (see section \ref{typesseq}), \class{UserList} instances |
| 98 | provide the following attribute: |
| 99 | |
Fred Drake | 1ce3604 | 1998-04-07 20:05:33 +0000 | [diff] [blame] | 100 | \begin{memberdesc}{data} |
| 101 | A real Python list object used to store the contents of the |
| 102 | \class{UserList} class. |
| 103 | \end{memberdesc} |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 104 | |
Fred Drake | c6243e4 | 2000-10-06 20:04:48 +0000 | [diff] [blame] | 105 | \strong{Subclassing requirements:} |
| 106 | Subclasses of \class{UserList} are expect to offer a constructor which |
| 107 | can be called with either no arguments or one argument. List |
| 108 | operations which return a new sequence attempt to create an instance |
| 109 | of the actual implementation class. To do so, it assumes that the |
| 110 | constructor can be called with a single parameter, which is a sequence |
| 111 | object used as a data source. |
| 112 | |
| 113 | If a derived class does not wish to comply with this requirement, all |
| 114 | of the special methods supported by this class will need to be |
| 115 | overridden; please consult the sources for information about the |
| 116 | methods which need to be provided in that case. |
| 117 | |
| 118 | \versionchanged[Python versions 1.5.2 and 1.6 also required that the |
| 119 | constructor be callable with no parameters, and offer |
| 120 | a mutable \member{data} attribute. Earlier versions |
| 121 | of Python did not attempt to create instances of the |
| 122 | derived class]{2.0} |
| 123 | |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 124 | |
| 125 | \section{\module{UserString} --- |
| 126 | Class wrapper for string objects} |
| 127 | |
| 128 | \declaremodule{standard}{UserString} |
| 129 | \modulesynopsis{Class wrapper for string objects.} |
| 130 | \moduleauthor{Peter Funk}{pf@artcom-gmbh.de} |
| 131 | \sectionauthor{Peter Funk}{pf@artcom-gmbh.de} |
| 132 | |
Fred Drake | d5be3b7 | 2001-10-26 18:37:27 +0000 | [diff] [blame] | 133 | \note{This \class{UserString} class from this module is available for |
| 134 | backward compatibility only. If you are writing code that does not |
| 135 | need to work with versions of Python earlier than Python 2.2, please |
| 136 | consider subclassing directly from the built-in \class{str} type |
| 137 | instead of using \class{UserString} (there is no built-in equivalent |
| 138 | to \class{MutableString}).} |
| 139 | |
Fred Drake | 66c9f07 | 2000-10-10 20:58:48 +0000 | [diff] [blame] | 140 | This module defines a class that acts as a wrapper around string |
| 141 | objects. It is a useful base class for your own string-like classes, |
| 142 | which can inherit from them and override existing methods or add new |
| 143 | ones. In this way one can add new behaviors to strings. |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 144 | |
Fred Drake | 66c9f07 | 2000-10-10 20:58:48 +0000 | [diff] [blame] | 145 | It should be noted that these classes are highly inefficient compared |
| 146 | to real string or Unicode objects; this is especially the case for |
| 147 | \class{MutableString}. |
| 148 | |
| 149 | The \module{UserString} module defines the following classes: |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 150 | |
| 151 | \begin{classdesc}{UserString}{\optional{sequence}} |
Fred Drake | 2c4f554 | 2000-10-10 22:00:03 +0000 | [diff] [blame] | 152 | Class that simulates a string or a Unicode string |
Fred Drake | 66c9f07 | 2000-10-10 20:58:48 +0000 | [diff] [blame] | 153 | object. The instance's content is kept in a regular string or Unicode |
| 154 | string object, which is accessible via the \member{data} attribute of |
| 155 | \class{UserString} instances. The instance's contents are initially |
| 156 | set to a copy of \var{sequence}. \var{sequence} can be either a |
| 157 | regular Python string or Unicode string, an instance of |
| 158 | \class{UserString} (or a subclass) or an arbitrary sequence which can |
| 159 | be converted into a string using the built-in \function{str()} function. |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 160 | \end{classdesc} |
| 161 | |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 162 | \begin{classdesc}{MutableString}{\optional{sequence}} |
| 163 | This class is derived from the \class{UserString} above and redefines |
| 164 | strings to be \emph{mutable}. Mutable strings can't be used as |
| 165 | dictionary keys, because dictionaries require \emph{immutable} objects as |
| 166 | keys. The main intention of this class is to serve as an educational |
| 167 | example for inheritance and necessity to remove (override) the |
Fred Drake | 66c9f07 | 2000-10-10 20:58:48 +0000 | [diff] [blame] | 168 | \method{__hash__()} method in order to trap attempts to use a |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 169 | mutable object as dictionary key, which would be otherwise very |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 170 | error prone and hard to track down. |
Fred Drake | a22b576 | 2000-04-03 03:51:50 +0000 | [diff] [blame] | 171 | \end{classdesc} |
Fred Drake | 621d2be | 2000-09-09 03:23:50 +0000 | [diff] [blame] | 172 | |
Fred Drake | 66c9f07 | 2000-10-10 20:58:48 +0000 | [diff] [blame] | 173 | In addition to supporting the methods and operations of string and |
| 174 | Unicode objects (see section \ref{string-methods}, ``String |
| 175 | Methods''), \class{UserString} instances provide the following |
| 176 | attribute: |
Fred Drake | 621d2be | 2000-09-09 03:23:50 +0000 | [diff] [blame] | 177 | |
| 178 | \begin{memberdesc}{data} |
| 179 | A real Python string or Unicode object used to store the content of the |
| 180 | \class{UserString} class. |
| 181 | \end{memberdesc} |