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