From ebcee3f94afabe89722b5aaea1e64f73eaed5859 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Wed, 6 Feb 2008 19:54:00 +0000 Subject: [PATCH] Fix-up the collections docs. * Start filling in detail and examples for ABCs * Fix old reference to IterableUserDict. * Neaten-up the introduction. --- Doc/library/collections.rst | 59 ++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 4c668ee9213..8e04475a4e9 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -10,19 +10,25 @@ This module implements high-performance container datatypes. Currently, there are two datatypes, :class:`deque` and :class:`defaultdict`, and -one datatype factory function, :func:`namedtuple`. Python already -includes built-in containers, :class:`dict`, :class:`list`, -:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb` -module has a :meth:`bsddb.btopen` method that can be used to create in-memory -or file based ordered dictionaries with string keys. +one datatype factory function, :func:`namedtuple`. -Future editions of the standard library may include balanced trees and -ordered dictionaries. +The specialized containers provided in this module provide alternatives +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 +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 provides a particular interface, for example, is it hashable or -a mapping. The ABCs provided include those in the following table: +(abstract base classes) that can be used to test whether a class +provides a particular interface, for example, is it hashable or +a mapping. + +ABCs - abstract base classes +---------------------------- + +The collections module offers the following ABCs: ===================================== ================================================================================ ABC Notes @@ -62,18 +68,36 @@ ABC Notes ``__isub__()`` ===================================== ================================================================================ -.. XXX Have not included them all and the notes are incomplete -.. long = lines improves the layout - These ABCs allow us to ask classes or instances if they provide particular functionality, for example:: - from collections import Sized - size = None - if isinstance(myvar, Sized): + if isinstance(myvar, collections.Sized): size = len(myvar) +Several of the ABCs are also useful as mixins that make it easier to develop +classes supporting container APIs. For example, to write a class supporting +the full :class:`Set` API, it only necessary to supply the three underlying +abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. +The ABC supplies the remaining methods such as :meth:`__and__` and +:meth:`isdisjoint` :: + + class ListBasedSet(collections.Set): + 'Alternate set implementation favoring space over speed' + def __init__(self, iterable): + self.elements = list(set(iterable)) + def __iter__(self): + return iter(self.elements) + def __contains__(self, value): + return value in self.elements + def __len__(self): + return len(self.elements) + + s1 = ListBasedSet('abcdef') + s2 = ListBasedSet('defghi') + overlap = s1 & s2 # The __and__() method is supported automatically + + (For more about ABCs, see the :mod:`abc` module and :pep:`3119`.) @@ -607,8 +631,7 @@ attribute. be kept, allowing it be used for other purposes. In addition to supporting the methods and operations of mappings, -:class:`UserDict` and :class:`IterableUserDict` instances -provide the following attribute: +:class:`UserDict` instances provide the following attribute: .. attribute:: UserDict.data