Doc/lib/libuserdict.tex

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