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