[Python-checkins] r61761 - python/trunk/Doc/library/collections.rst
georg.brandl
python-checkins at python.org
Sat Mar 22 22:06:20 CET 2008
Author: georg.brandl
Date: Sat Mar 22 22:06:20 2008
New Revision: 61761
Modified:
python/trunk/Doc/library/collections.rst
Log:
Make collections' doctests executable.
(The <BLANKLINE>s will be stripped from presentation output.)
Modified: python/trunk/Doc/library/collections.rst
==============================================================================
--- python/trunk/Doc/library/collections.rst (original)
+++ python/trunk/Doc/library/collections.rst Sat Mar 22 22:06:20 2008
@@ -7,12 +7,17 @@
.. moduleauthor:: Raymond Hettinger <python at rcn.com>
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
-
.. versionadded:: 2.4
+.. testsetup:: *
+
+ from collections import *
+ import itertools
+ __name__ = '<doctest>'
+
This module implements high-performance container datatypes. Currently,
there are two datatypes, :class:`deque` and :class:`defaultdict`, and
-one datatype factory function, :func:`namedtuple`.
+one datatype factory function, :func:`namedtuple`.
.. versionchanged:: 2.5
Added :class:`defaultdict`.
@@ -21,17 +26,17 @@
Added :func:`namedtuple`.
The specialized containers provided in this module provide alternatives
-to Python's general purpose built-in containers, :class:`dict`,
+to Python's general purpose built-in containers, :class:`dict`,
:class:`list`, :class:`set`, and :class:`tuple`.
Besides the containers provided here, the optional :mod:`bsddb`
-module offers the ability to create in-memory or file based ordered
+module offers the ability to create in-memory or file based ordered
dictionaries with string keys using the :meth:`bsddb.btopen` method.
In addition to containers, the collections module provides some ABCs
-(abstract base classes) that can be used to test whether a class
+(abstract base classes) that can be used to test whether a class
provides a particular interface, for example, is it hashable or
-a mapping.
+a mapping.
.. versionchanged:: 2.6
Added abstract base classes.
@@ -113,15 +118,15 @@
Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
-(1)
+(1)
Since some set operations create new sets, the default mixin methods need
- a way to create new instances from an iterable. The class constructor is
- assumed to have a signature in the form ``ClassName(iterable)``.
+ a way to create new instances from an iterable. The class constructor is
+ assumed to have a signature in the form ``ClassName(iterable)``.
That assumption is factored-out to a singleinternal classmethod called
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
If the :class:`Set` mixin is being used in a class with a different
- constructor signature, you will need to override :meth:`from_iterable`
- with a classmethod that can construct new instances from
+ constructor signature, you will need to override :meth:`from_iterable`
+ with a classmethod that can construct new instances from
an iterable argument.
(2)
@@ -235,12 +240,14 @@
``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
the :keyword:`in` operator, and subscript references such as ``d[-1]``.
-Example::
+Example:
+
+.. doctest::
>>> from collections import deque
>>> d = deque('ghi') # make a new deque with three items
>>> for elem in d: # iterate over the deque's elements
- ... print elem.upper()
+ ... print elem.upper()
G
H
I
@@ -319,7 +326,7 @@
deque.
For example, building a balanced binary tree of nested lists entails reducing
-two adjacent nodes into one by grouping them in a list::
+two adjacent nodes into one by grouping them in a list:
>>> def maketree(iterable):
... d = deque(iterable)
@@ -393,7 +400,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using :class:`list` as the :attr:`default_factory`, it is easy to group a
-sequence of key-value pairs into a dictionary of lists::
+sequence of key-value pairs into a dictionary of lists:
>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
@@ -409,7 +416,7 @@
operation then attaches the value to the new list. When keys are encountered
again, the look-up proceeds normally (returning the list for that key) and the
:meth:`list.append` operation adds another value to the list. This technique is
-simpler and faster than an equivalent technique using :meth:`dict.setdefault`::
+simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
>>> d = {}
>>> for k, v in s:
@@ -420,7 +427,7 @@
Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
-languages)::
+languages):
>>> s = 'mississippi'
>>> d = defaultdict(int)
@@ -437,7 +444,7 @@
The function :func:`int` which always returns zero is just a special case of
constant functions. A faster and more flexible way to create constant functions
is to use :func:`itertools.repeat` which can supply any constant value (not just
-zero)::
+zero):
>>> def constant_factory(value):
... return itertools.repeat(value).next
@@ -447,7 +454,7 @@
'John ran to <missing>'
Setting the :attr:`default_factory` to :class:`set` makes the
-:class:`defaultdict` useful for building a dictionary of sets::
+:class:`defaultdict` useful for building a dictionary of sets:
>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
@@ -492,41 +499,44 @@
.. versionadded:: 2.6
-Example::
+Example:
+
+.. doctest::
+ :options: +NORMALIZE_WHITESPACE
>>> Point = namedtuple('Point', 'x y', verbose=True)
class Point(tuple):
'Point(x, y)'
-
+ <BLANKLINE>
__slots__ = ()
-
+ <BLANKLINE>
_fields = ('x', 'y')
-
+ <BLANKLINE>
def __new__(cls, x, y):
return tuple.__new__(cls, (x, y))
-
+ <BLANKLINE>
@classmethod
- def _make(cls, iterable):
+ def _make(cls, iterable, new=tuple.__new__, len=len):
'Make a new Point object from a sequence or iterable'
- result = tuple.__new__(cls, iterable)
+ result = new(cls, iterable)
if len(result) != 2:
raise TypeError('Expected 2 arguments, got %d' % len(result))
return result
-
+ <BLANKLINE>
def __repr__(self):
return 'Point(x=%r, y=%r)' % self
-
+ <BLANKLINE>
def _asdict(t):
'Return a new dict which maps field names to their values'
return {'x': t[0], 'y': t[1]}
-
+ <BLANKLINE>
def _replace(self, **kwds):
'Return a new Point object replacing specified fields with new values'
result = self._make(map(kwds.pop, ('x', 'y'), self))
if kwds:
raise ValueError('Got unexpected field names: %r' % kwds.keys())
return result
-
+ <BLANKLINE>
x = property(itemgetter(0))
y = property(itemgetter(1))
@@ -565,7 +575,7 @@
Class method that makes a new instance from an existing sequence or iterable.
-::
+.. doctest::
>>> t = [11, 22]
>>> Point._make(t)
@@ -573,16 +583,15 @@
.. method:: somenamedtuple._asdict()
- Return a new dict which maps field names to their corresponding values:
-
-::
+ Return a new dict which maps field names to their corresponding values::
>>> p._asdict()
{'x': 11, 'y': 22}
-
+
.. method:: somenamedtuple._replace(kwargs)
- Return a new instance of the named tuple replacing specified fields with new values:
+ Return a new instance of the named tuple replacing specified fields with new
+ values:
::
@@ -598,7 +607,7 @@
Tuple of strings listing the field names. Useful for introspection
and for creating new named tuple types from existing named tuples.
-::
+.. doctest::
>>> p._fields # view the field names
('x', 'y')
@@ -609,12 +618,12 @@
Pixel(x=11, y=22, red=128, green=255, blue=0)
To retrieve a field whose name is stored in a string, use the :func:`getattr`
-function::
+function:
>>> getattr(p, 'x')
11
-To convert a dictionary to a named tuple, use the double-star-operator [#]_::
+To convert a dictionary to a named tuple, use the double-star-operator [#]_:
>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
@@ -622,7 +631,7 @@
Since a named tuple is a regular Python class, it is easy to add or change
functionality with a subclass. Here is how to add a calculated field and
-a fixed-width print format::
+a fixed-width print format:
>>> class Point(namedtuple('Point', 'x y')):
... __slots__ = ()
@@ -634,7 +643,6 @@
>>> for p in Point(3, 4), Point(14, 5/7.):
... print p
-
Point: x= 3.000 y= 4.000 hypot= 5.000
Point: x=14.000 y= 0.714 hypot=14.018
@@ -642,12 +650,12 @@
keep memory requirements low by preventing the creation of instance dictionaries.
Subclassing is not useful for adding new, stored fields. Instead, simply
-create a new named tuple type from the :attr:`_fields` attribute::
+create a new named tuple type from the :attr:`_fields` attribute:
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
Default values can be implemented by using :meth:`_replace` to
-customize a prototype instance::
+customize a prototype instance:
>>> Account = namedtuple('Account', 'owner balance transaction_count')
>>> default_account = Account('<owner name>', 0.0, 0)
More information about the Python-checkins
mailing list