--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/userdict.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,205 @@
+
+:mod:`UserDict` --- Class wrapper for dictionary objects
+========================================================
+
+.. module:: UserDict
+ :synopsis: Class wrapper for dictionary objects.
+
+
+The module defines a mixin, :class:`DictMixin`, 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).
+
+This module also defines a class, :class:`UserDict`, that acts as a wrapper
+around dictionary objects. The need for this class has been largely supplanted
+by the ability to subclass directly from :class:`dict` (a feature that became
+available starting with Python version 2.2). Prior to the introduction of
+:class:`dict`, the :class:`UserDict` class was used to create dictionary-like
+sub-classes that obtained new behaviors by overriding existing methods or adding
+new ones.
+
+The :mod:`UserDict` module defines the :class:`UserDict` class and
+:class:`DictMixin`:
+
+
+.. class:: UserDict([initialdata])
+
+ Class that simulates a dictionary. The instance's contents are kept in a
+ regular dictionary, which is accessible via the :attr:`data` attribute of
+ :class:`UserDict` instances. If *initialdata* is provided, :attr:`data` is
+ initialized with its contents; note that a reference to *initialdata* will not
+ be kept, allowing it be used for other purposes.
+
+ .. note::
+
+ For backward compatibility, instances of :class:`UserDict` are not iterable.
+
+
+.. class:: IterableUserDict([initialdata])
+
+ Subclass of :class:`UserDict` that supports direct iteration (e.g. ``for key in
+ myDict``).
+
+In addition to supporting the methods and operations of mappings (see section
+:ref:`typesmapping`), :class:`UserDict` and :class:`IterableUserDict` instances
+provide the following attribute:
+
+
+.. attribute:: IterableUserDict.data
+
+ A real dictionary used to store the contents of the :class:`UserDict` class.
+
+
+.. class:: DictMixin()
+
+ Mixin defining all dictionary methods for classes that already have a minimum
+ dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,
+ :meth:`__delitem__`, and :meth:`keys`.
+
+ This mixin should be used as a superclass. Adding each of the above methods
+ adds progressively more functionality. For instance, defining all but
+ :meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the
+ full interface.
+
+ In addition to the four base methods, progressively more efficiency comes with
+ defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
+
+ Since the mixin has no knowledge of the subclass constructor, it does not define
+ :meth:`__init__` or :meth:`copy`.
+
+ Starting with Python version 2.6, it is recommended to use
+ :class:`collections.MutableMapping` instead of :class:`DictMixin`.
+
+:mod:`UserList` --- Class wrapper for list objects
+==================================================
+
+.. module:: UserList
+ :synopsis: 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 :mod:`UserList` module defines the :class:`UserList` class:
+
+
+.. class:: UserList([list])
+
+ Class that simulates a list. The instance's contents are kept in a regular
+ list, which is accessible via the :attr:`data` attribute of :class:`UserList`
+ instances. The instance's contents are initially set to a copy of *list*,
+ defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a
+ real Python list or a :class:`UserList` object.
+
+ .. note::
+ The :class:`UserList` class has been moved to the :mod:`collections`
+ module in Python 3.0. The :term:`2to3` tool will automatically adapt
+ imports when converting your sources to 3.0.
+
+
+In addition to supporting the methods and operations of mutable sequences (see
+section :ref:`typesseq`), :class:`UserList` instances provide the following
+attribute:
+
+
+.. attribute:: UserList.data
+
+ A real Python list object used to store the contents of the :class:`UserList`
+ class.
+
+**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:: 2.0
+ Python versions 1.5.2 and 1.6 also required that the constructor be callable
+ with no parameters, and offer a mutable :attr:`data` attribute. Earlier
+ versions of Python did not attempt to create instances of the derived class.
+
+
+:mod:`UserString` --- Class wrapper for string objects
+======================================================
+
+.. module:: UserString
+ :synopsis: 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 :mod:`UserString` module defines the following classes:
+
+
+.. class:: UserString([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 :attr:`data` attribute of :class:`UserString` instances. The
+ instance's contents are initially set to a copy of *sequence*. *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 :func:`str` function.
+
+ .. note::
+ The :class:`UserString` class has been moved to the :mod:`collections`
+ module in Python 3.0. The :term:`2to3` tool will automatically adapt
+ imports when converting your sources to 3.0.
+
+
+
+.. class:: MutableString([sequence])
+
+ This class is derived from the :class:`UserString` above and redefines strings
+ to be *mutable*. Mutable strings can't be used as dictionary keys, because
+ dictionaries require *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 :meth:`__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.
+
+ .. deprecated:: 2.6
+ The :class:`MutableString` class has been removed in Python 3.0.
+
+In addition to supporting the methods and operations of string and Unicode
+objects (see section :ref:`string-methods`), :class:`UserString` instances
+provide the following attribute:
+
+
+.. attribute:: MutableString.data
+
+ A real Python string or Unicode object used to store the content of the
+ :class:`UserString` class.
+