<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>8.12. UserDict — Class wrapper for dictionary objects — Python v2.7.1 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.7.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v2.7.1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v2.7.1 documentation" href="../index.html" />
<link rel="up" title="8. Data Types" href="datatypes.html" />
<link rel="next" title="8.15. types — Names for built-in types" href="types.html" />
<link rel="prev" title="8.11. weakref — Weak references" href="weakref.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="types.html" title="8.15. types — Names for built-in types"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="weakref.html" title="8.11. weakref — Weak references"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.7.1 documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="datatypes.html" accesskey="U">8. Data Types</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-UserDict">
<h1>8.12. <tt class="xref docutils literal"><span class="pre">UserDict</span></tt> — Class wrapper for dictionary objects<a class="headerlink" href="#module-UserDict" title="Permalink to this headline">¶</a></h1>
<p>The module defines a mixin, <a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>, 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).</p>
<p>This module also defines a class, <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a>, that acts as a wrapper
around dictionary objects. The need for this class has been largely supplanted
by the ability to subclass directly from <a title="dict" class="reference external" href="stdtypes.html#dict"><tt class="xref docutils literal"><span class="pre">dict</span></tt></a> (a feature that became
available starting with Python version 2.2). Prior to the introduction of
<a title="dict" class="reference external" href="stdtypes.html#dict"><tt class="xref docutils literal"><span class="pre">dict</span></tt></a>, the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class was used to create dictionary-like
sub-classes that obtained new behaviors by overriding existing methods or adding
new ones.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">Latest version of the <a class="reference external" href="http://svn.python.org/view/python/branches/release27-maint/Lib/UserDict.py?view=markup">UserDict Python source code</a></p>
</div>
<p>The <tt class="xref docutils literal"><span class="pre">UserDict</span></tt> module defines the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class and
<a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>:</p>
<dl class="class">
<dt id="UserDict.UserDict">
<em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">UserDict</tt><big>(</big><span class="optional">[</span><em>initialdata</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserDict.UserDict" title="Permalink to this definition">¶</a></dt>
<dd><p>Class that simulates a dictionary. The instance’s contents are kept in a
regular dictionary, which is accessible via the <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute of
<a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> instances. If <em>initialdata</em> is provided, <tt class="xref docutils literal"><span class="pre">data</span></tt> is
initialized with its contents; note that a reference to <em>initialdata</em> will not
be kept, allowing it be used for other purposes.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For backward compatibility, instances of <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> are not iterable.</p>
</div>
</dd></dl>
<dl class="class">
<dt id="UserDict.IterableUserDict">
<em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">IterableUserDict</tt><big>(</big><span class="optional">[</span><em>initialdata</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserDict.IterableUserDict" title="Permalink to this definition">¶</a></dt>
<dd>Subclass of <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> that supports direct iteration (e.g. <tt class="docutils literal"><span class="pre">for</span> <span class="pre">key</span> <span class="pre">in</span>
<span class="pre">myDict</span></tt>).</dd></dl>
<p>In addition to supporting the methods and operations of mappings (see section
<a class="reference external" href="stdtypes.html#typesmapping"><em>Mapping Types — dict</em></a>), <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> and <a title="UserDict.IterableUserDict" class="reference internal" href="#UserDict.IterableUserDict"><tt class="xref docutils literal"><span class="pre">IterableUserDict</span></tt></a> instances
provide the following attribute:</p>
<dl class="attribute">
<dt id="UserDict.IterableUserDict.data">
<tt class="descclassname">IterableUserDict.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserDict.IterableUserDict.data" title="Permalink to this definition">¶</a></dt>
<dd>A real dictionary used to store the contents of the <a title="UserDict.UserDict" class="reference internal" href="#UserDict.UserDict"><tt class="xref docutils literal"><span class="pre">UserDict</span></tt></a> class.</dd></dl>
<dl class="class">
<dt id="UserDict.DictMixin">
<em class="property">class </em><tt class="descclassname">UserDict.</tt><tt class="descname">DictMixin</tt><a class="headerlink" href="#UserDict.DictMixin" title="Permalink to this definition">¶</a></dt>
<dd><p>Mixin defining all dictionary methods for classes that already have a minimum
dictionary interface including <a title="object.__getitem__" class="reference external" href="../reference/datamodel.html#object.__getitem__"><tt class="xref docutils literal"><span class="pre">__getitem__()</span></tt></a>, <a title="object.__setitem__" class="reference external" href="../reference/datamodel.html#object.__setitem__"><tt class="xref docutils literal"><span class="pre">__setitem__()</span></tt></a>,
<a title="object.__delitem__" class="reference external" href="../reference/datamodel.html#object.__delitem__"><tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt></a>, and <tt class="xref docutils literal"><span class="pre">keys()</span></tt>.</p>
<p>This mixin should be used as a superclass. Adding each of the above methods
adds progressively more functionality. For instance, defining all but
<a title="object.__delitem__" class="reference external" href="../reference/datamodel.html#object.__delitem__"><tt class="xref docutils literal"><span class="pre">__delitem__()</span></tt></a> will preclude only <tt class="xref docutils literal"><span class="pre">pop()</span></tt> and <tt class="xref docutils literal"><span class="pre">popitem()</span></tt> from the
full interface.</p>
<p>In addition to the four base methods, progressively more efficiency comes with
defining <a title="object.__contains__" class="reference external" href="../reference/datamodel.html#object.__contains__"><tt class="xref docutils literal"><span class="pre">__contains__()</span></tt></a>, <a title="object.__iter__" class="reference external" href="../reference/datamodel.html#object.__iter__"><tt class="xref docutils literal"><span class="pre">__iter__()</span></tt></a>, and <tt class="xref docutils literal"><span class="pre">iteritems()</span></tt>.</p>
<p>Since the mixin has no knowledge of the subclass constructor, it does not define
<a title="object.__init__" class="reference external" href="../reference/datamodel.html#object.__init__"><tt class="xref docutils literal"><span class="pre">__init__()</span></tt></a> or <tt class="xref docutils literal"><span class="pre">copy()</span></tt>.</p>
<p>Starting with Python version 2.6, it is recommended to use
<tt class="xref docutils literal"><span class="pre">collections.MutableMapping</span></tt> instead of <a title="UserDict.DictMixin" class="reference internal" href="#UserDict.DictMixin"><tt class="xref docutils literal"><span class="pre">DictMixin</span></tt></a>.</p>
</dd></dl>
</div>
<div class="section" id="module-UserList">
<h1>8.13. <tt class="xref docutils literal"><span class="pre">UserList</span></tt> — Class wrapper for list objects<a class="headerlink" href="#module-UserList" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 <a title="list" class="reference external" href="functions.html#list"><tt class="xref docutils literal"><span class="pre">list</span></tt></a> type.</p>
</div>
<p>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.</p>
<p>The <tt class="xref docutils literal"><span class="pre">UserList</span></tt> module defines the <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> class:</p>
<dl class="class">
<dt id="UserList.UserList">
<em class="property">class </em><tt class="descclassname">UserList.</tt><tt class="descname">UserList</tt><big>(</big><span class="optional">[</span><em>list</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserList.UserList" title="Permalink to this definition">¶</a></dt>
<dd><p>Class that simulates a list. The instance’s contents are kept in a regular
list, which is accessible via the <a title="UserList.UserList.data" class="reference internal" href="#UserList.UserList.data"><tt class="xref docutils literal"><span class="pre">data</span></tt></a> attribute of <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a>
instances. The instance’s contents are initially set to a copy of <em>list</em>,
defaulting to the empty list <tt class="docutils literal"><span class="pre">[]</span></tt>. <em>list</em> can be any iterable, e.g. a
real Python list or a <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> object.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> class has been moved to the <a title="High-performance datatypes" class="reference external" href="collections.html#module-collections"><tt class="xref docutils literal"><span class="pre">collections</span></tt></a>
module in Python 3.0. The <a class="reference external" href="../glossary.html#term-to3"><em class="xref">2to3</em></a> tool will automatically adapt
imports when converting your sources to 3.0.</p>
</div>
</dd></dl>
<p>In addition to supporting the methods and operations of mutable sequences (see
section <a class="reference external" href="stdtypes.html#typesseq"><em>Sequence Types — str, unicode, list, tuple, bytearray, buffer, xrange</em></a>), <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> instances provide the following
attribute:</p>
<dl class="attribute">
<dt id="UserList.UserList.data">
<tt class="descclassname">UserList.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserList.UserList.data" title="Permalink to this definition">¶</a></dt>
<dd>A real Python list object used to store the contents of the <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a>
class.</dd></dl>
<p><strong>Subclassing requirements:</strong> Subclasses of <a title="UserList.UserList" class="reference internal" href="#UserList.UserList"><tt class="xref docutils literal"><span class="pre">UserList</span></tt></a> 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.</p>
<p>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.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 2.0: </span>Python versions 1.5.2 and 1.6 also required that the constructor be callable
with no parameters, and offer a mutable <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute. Earlier
versions of Python did not attempt to create instances of the derived class.</p>
</div>
<div class="section" id="module-UserString">
<h1>8.14. <tt class="xref docutils literal"><span class="pre">UserString</span></tt> — Class wrapper for string objects<a class="headerlink" href="#module-UserString" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> 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 <a title="str" class="reference external" href="functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a> type instead of using <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> (there
is no built-in equivalent to <a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a>).</p>
</div>
<p>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.</p>
<p>It should be noted that these classes are highly inefficient compared to real
string or Unicode objects; this is especially the case for
<a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a>.</p>
<p>The <tt class="xref docutils literal"><span class="pre">UserString</span></tt> module defines the following classes:</p>
<dl class="class">
<dt id="UserString.UserString">
<em class="property">class </em><tt class="descclassname">UserString.</tt><tt class="descname">UserString</tt><big>(</big><span class="optional">[</span><em>sequence</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserString.UserString" title="Permalink to this definition">¶</a></dt>
<dd><p>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 <tt class="xref docutils literal"><span class="pre">data</span></tt> attribute of <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> instances. The
instance’s contents are initially set to a copy of <em>sequence</em>. <em>sequence</em> can
be either a regular Python string or Unicode string, an instance of
<a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> (or a subclass) or an arbitrary sequence which can be
converted into a string using the built-in <a title="str" class="reference external" href="functions.html#str"><tt class="xref docutils literal"><span class="pre">str()</span></tt></a> function.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> class has been moved to the <a title="High-performance datatypes" class="reference external" href="collections.html#module-collections"><tt class="xref docutils literal"><span class="pre">collections</span></tt></a>
module in Python 3.0. The <a class="reference external" href="../glossary.html#term-to3"><em class="xref">2to3</em></a> tool will automatically adapt
imports when converting your sources to 3.0.</p>
</div>
</dd></dl>
<dl class="class">
<dt id="UserString.MutableString">
<em class="property">class </em><tt class="descclassname">UserString.</tt><tt class="descname">MutableString</tt><big>(</big><span class="optional">[</span><em>sequence</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#UserString.MutableString" title="Permalink to this definition">¶</a></dt>
<dd><p>This class is derived from the <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> above and redefines strings
to be <em>mutable</em>. Mutable strings can’t be used as dictionary keys, because
dictionaries require <em>immutable</em> objects as keys. The main intention of this
class is to serve as an educational example for inheritance and necessity to
remove (override) the <a title="object.__hash__" class="reference external" href="../reference/datamodel.html#object.__hash__"><tt class="xref docutils literal"><span class="pre">__hash__()</span></tt></a> 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.</p>
<p class="deprecated">
<span class="versionmodified">Deprecated since version 2.6: </span>The <a title="UserString.MutableString" class="reference internal" href="#UserString.MutableString"><tt class="xref docutils literal"><span class="pre">MutableString</span></tt></a> class has been removed in Python 3.0.</p>
</dd></dl>
<p>In addition to supporting the methods and operations of string and Unicode
objects (see section <a class="reference external" href="stdtypes.html#string-methods"><em>String Methods</em></a>), <a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> instances
provide the following attribute:</p>
<dl class="attribute">
<dt id="UserString.MutableString.data">
<tt class="descclassname">MutableString.</tt><tt class="descname">data</tt><a class="headerlink" href="#UserString.MutableString.data" title="Permalink to this definition">¶</a></dt>
<dd>A real Python string or Unicode object used to store the content of the
<a title="UserString.UserString" class="reference internal" href="#UserString.UserString"><tt class="xref docutils literal"><span class="pre">UserString</span></tt></a> class.</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">8.12. <tt class="docutils literal"><span class="pre">UserDict</span></tt> — Class wrapper for dictionary objects</a></li>
<li><a class="reference external" href="#module-UserList">8.13. <tt class="docutils literal"><span class="pre">UserList</span></tt> — Class wrapper for list objects</a></li>
<li><a class="reference external" href="#module-UserString">8.14. <tt class="docutils literal"><span class="pre">UserString</span></tt> — Class wrapper for string objects</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="weakref.html"
title="previous chapter">8.11. <tt class="docutils literal docutils literal"><span class="pre">weakref</span></tt> — Weak references</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="types.html"
title="next chapter">8.15. <tt class="docutils literal docutils literal docutils literal"><span class="pre">types</span></tt> — Names for built-in types</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/library/userdict.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="types.html" title="8.15. types — Names for built-in types"
>next</a> |</li>
<li class="right" >
<a href="weakref.html" title="8.11. weakref — Weak references"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.7.1 documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
<li><a href="datatypes.html" >8. Data Types</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2010, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Nov 27, 2010.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.7.
</div>
</body>
</html>
