178 lines
7.4 KiB
TeX
178 lines
7.4 KiB
TeX
\section{\module{UserDict} ---
|
|
Class wrapper for dictionary objects}
|
|
|
|
\declaremodule{standard}{UserDict}
|
|
\modulesynopsis{Class wrapper for dictionary objects.}
|
|
|
|
\note{This module is available for backward compatibility only. If
|
|
you are writing code that does not need to work with versions of
|
|
Python earlier than Python 2.2, please consider subclassing directly
|
|
from the built-in \class{dict} type.}
|
|
|
|
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 also defines a mixin defining all dictionary methods for
|
|
classes that already have a minimum mapping interface. This greatly
|
|
simplifies writing classes that need to be substitutable for
|
|
dictionaries (such as the shelve module).
|
|
|
|
The \module{UserDict} module defines the \class{UserDict} class
|
|
and \class{DictMixin}:
|
|
|
|
\begin{classdesc}{UserDict}{\optional{initialdata}}
|
|
Class 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}
|
|
|
|
\begin{classdesc}{DictMixin}{}
|
|
Mixin defining all dictionary methods for classes that already have
|
|
a minimum dictionary interface including \method{__getitem__()},
|
|
\method{__setitem__()}, \method{__delitem__()}, and \method{keys()}.
|
|
|
|
This mixin should be used as a superclass. Adding each of the
|
|
above methods adds progressively more functionality. For instance,
|
|
defining all but \method{__delitem__} will preclude only \method{pop}
|
|
and \method{popitem} from the full interface.
|
|
|
|
In addition to the four base methods, progessively more efficiency
|
|
comes with defining \method{__contains__()}, \method{__iter__()}, and
|
|
\method{iteritems()}.
|
|
|
|
Since the mixin has no knowledge of the subclass constructor, it
|
|
does not define \method{__init__()} or \method{copy()}.
|
|
\end{classdesc}
|
|
|
|
|
|
\section{\module{UserList} ---
|
|
Class wrapper for list objects}
|
|
|
|
\declaremodule{standard}{UserList}
|
|
\modulesynopsis{Class wrapper for list objects.}
|
|
|
|
|
|
\note{This module is available for backward compatibility only. If
|
|
you are writing code that does not need to work with versions of
|
|
Python earlier than Python 2.2, please consider subclassing directly
|
|
from the built-in \class{list} type.}
|
|
|
|
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}}
|
|
Class 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}
|
|
|
|
\note{This \class{UserString} class from this module is available for
|
|
backward compatibility only. If you are writing code that does not
|
|
need to work with versions of Python earlier than Python 2.2, please
|
|
consider subclassing directly from the built-in \class{str} type
|
|
instead of using \class{UserString} (there is no built-in equivalent
|
|
to \class{MutableString}).}
|
|
|
|
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.
|
|
|
|
It should be noted that these classes are highly inefficient compared
|
|
to real string or Unicode objects; this is especially the case for
|
|
\class{MutableString}.
|
|
|
|
The \module{UserString} module defines the following classes:
|
|
|
|
\begin{classdesc}{UserString}{\optional{sequence}}
|
|
Class 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 using the built-in \function{str()} function.
|
|
\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
|
|
\method{__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 and
|
|
Unicode objects (see section \ref{string-methods}, ``String
|
|
Methods''), \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}
|