Doc/lib/libuserdict.tex

\section{\module{UserDict} ---
         Class wrapper for dictionary objects}

\declaremodule{standard}{UserDict}
\modulesynopsis{Class wrapper for dictionary objects.}

This module defines a class that acts as a wrapper around
dictionary objects.  It is a useful base class for
your own dictionary-like classes, which can inherit from
them and override existing methods or add new ones.  In this way one
can add new behaviors to dictionaries.

The \module{UserDict} module defines the \class{UserDict} class:

\begin{classdesc}{UserDict}{\optional{initialdata}}
Return a class instance that simulates a dictionary.  The instance's
contents are kept in a regular dictionary, which is accessible via the
\member{data} attribute of \class{UserDict} instances.  If
\var{initialdata} is provided, \member{data} is initialized with its
contents; note that a reference to \var{initialdata} will not be kept, 
allowing it be used used for other purposes.
\end{classdesc}

In addition to supporting the methods and operations of mappings (see
section \ref{typesmapping}), \class{UserDict} instances provide the
following attribute:

\begin{memberdesc}{data}
A real dictionary used to store the contents of the \class{UserDict}
class.
\end{memberdesc}


\section{\module{UserList} ---
         Class wrapper for list objects}

\declaremodule{standard}{UserList}
\modulesynopsis{Class wrapper for list objects.}


This module defines a class that acts as a wrapper around
list objects.  It is a useful base class for
your own list-like classes, which can inherit from
them and override existing methods or add new ones.  In this way one
can add new behaviors to lists.

The \module{UserList} module defines the \class{UserList} class:

\begin{classdesc}{UserList}{\optional{list}}
Return a class instance that simulates a list.  The instance's
contents are kept in a regular list, which is accessible via the
\member{data} attribute of \class{UserList} instances.  The instance's
contents are initially set to a copy of \var{list}, defaulting to the
empty list \code{[]}.  \var{list} can be either a regular Python list,
or an instance of \class{UserList} (or a subclass).
\end{classdesc}

In addition to supporting the methods and operations of mutable
sequences (see section \ref{typesseq}), \class{UserList} instances
provide the following attribute:

\begin{memberdesc}{data}
A real Python list object used to store the contents of the
\class{UserList} class.
\end{memberdesc}

\strong{Subclassing requirements:}
Subclasses of \class{UserList} are expect to offer a constructor which
can be called with either no arguments or one argument.  List
operations which return a new sequence attempt to create an instance
of the actual implementation class.  To do so, it assumes that the
constructor can be called with a single parameter, which is a sequence
object used as a data source.

If a derived class does not wish to comply with this requirement, all
of the special methods supported by this class will need to be
overridden; please consult the sources for information about the
methods which need to be provided in that case.

\versionchanged[Python versions 1.5.2 and 1.6 also required that the
                constructor be callable with no parameters, and offer
                a mutable \member{data} attribute.  Earlier versions
                of Python did not attempt to create instances of the
                derived class]{2.0}


\section{\module{UserString} ---
         Class wrapper for string objects}

\declaremodule{standard}{UserString}
\modulesynopsis{Class wrapper for string objects.}
\moduleauthor{Peter Funk}{pf@artcom-gmbh.de}
\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}

This module defines a class that acts as a wrapper around
string objects.  It is a useful base class for
your own string-like classes, which can inherit from
them and override existing methods or add new ones.  In this way one
can add new behaviors to strings.

The \module{UserString} module defines the \class{UserString} class:

\begin{classdesc}{UserString}{\optional{sequence}}
Return a class instance that simulates a string or a Unicode string object.
The instance's content is kept in a regular string or Unicode string
object, which is accessible via the
\member{data} attribute of \class{UserString} instances.  The instance's
contents are initially set to a copy of \var{sequence}.
\var{sequence} can be either a regular Python string or Unicode string,
an instance of \class{UserString} (or a subclass) or an arbitrary sequence
which can be converted into a string.
\end{classdesc}

\begin{classdesc}{MutableString}{\optional{sequence}}
This class is derived from the \class{UserString} above and redefines
strings to be \emph{mutable}.  Mutable strings can't be used as
dictionary keys, because dictionaries require \emph{immutable} objects as
keys.  The main intention of this class is to serve as an educational
example for inheritance and necessity to remove (override) the
\function{__hash__} method in order to trap attempts to use a
mutable object as dictionary key, which would be otherwise very
error prone and hard to track down.
\end{classdesc}

In addition to supporting the methods and operations of string  or
Unicode objects (see section \ref{typesseq}), \class{UserString} instances
provide the following attribute:

\begin{memberdesc}{data}
A real Python string or Unicode object used to store the content of the
\class{UserString} class.
\end{memberdesc}