Source code for zope.interface.common.mapping

##############################################################################
#
# Copyright (c) 2001, 2002 Zope Foundation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Mapping Interfaces.

Importing this module does *not* mark any standard classes as
implementing any of these interfaces.

While this module is not deprecated, new code should generally use
:mod:`zope.interface.common.collections`, specifically
:class:`~zope.interface.common.collections.IMapping` and
:class:`~zope.interface.common.collections.IMutableMapping`. This
module is occasionally useful for its extremely fine grained breakdown
of interfaces.

The standard library :class:`dict` and :class:`collections.UserDict`
implement ``IMutableMapping``, but *do not* implement any of the
interfaces in this module.
"""
from zope.interface import Interface
from zope.interface._compat import PYTHON2 as PY2
from zope.interface.common import collections

[docs] class IItemMapping(Interface): """Simplest readable mapping object """ def __getitem__(key): """Get a value for a key A `KeyError` is raised if there is no value for the key. """
[docs] class IReadMapping(collections.IContainer, IItemMapping): """ Basic mapping interface. .. versionchanged:: 5.0.0 Extend ``IContainer`` """ def get(key, default=None): """Get a value for a key The default is returned if there is no value for the key. """ def __contains__(key): """Tell if a key exists in the mapping."""
# Optional in IContainer, required by this interface.
[docs] class IWriteMapping(Interface): """Mapping methods for changing data""" def __delitem__(key): """Delete a value from the mapping using the key.""" def __setitem__(key, value): """Set a new item in the mapping."""
[docs] class IEnumerableMapping(collections.ISized, IReadMapping): """ Mapping objects whose items can be enumerated. .. versionchanged:: 5.0.0 Extend ``ISized`` """ def keys(): """Return the keys of the mapping object. """ def __iter__(): """Return an iterator for the keys of the mapping object. """ def values(): """Return the values of the mapping object. """ def items(): """Return the items of the mapping object. """
[docs] class IMapping(IWriteMapping, IEnumerableMapping): ''' Simple mapping interface '''
[docs] class IIterableMapping(IEnumerableMapping): """A mapping that has distinct methods for iterating without copying. On Python 2, a `dict` has these methods, but on Python 3 the methods defined in `IEnumerableMapping` already iterate without copying. """ if PY2: def iterkeys(): "iterate over keys; equivalent to ``__iter__``" def itervalues(): "iterate over values" def iteritems(): "iterate over items"
[docs] class IClonableMapping(Interface): """Something that can produce a copy of itself. This is available in `dict`. """ def copy(): "return copy of dict"
[docs] class IExtendedReadMapping(IIterableMapping): """ Something with a particular method equivalent to ``__contains__``. On Python 2, `dict` provides this method, but it was removed in Python 3. """ if PY2: def has_key(key): """Tell if a key exists in the mapping; equivalent to ``__contains__``"""
[docs] class IExtendedWriteMapping(IWriteMapping): """Additional mutation methods. These are all provided by `dict`. """ def clear(): "delete all items" def update(d): " Update D from E: for k in E.keys(): D[k] = E[k]" def setdefault(key, default=None): "D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D" def pop(k, default=None): """ pop(k[,default]) -> value Remove specified key and return the corresponding value. If key is not found, *default* is returned if given, otherwise `KeyError` is raised. Note that *default* must not be passed by name. """ def popitem(): """remove and return some (key, value) pair as a 2-tuple; but raise KeyError if mapping is empty"""
[docs] class IFullMapping( collections.IMutableMapping, IExtendedReadMapping, IExtendedWriteMapping, IClonableMapping, IMapping,): """ Full mapping interface. Most uses of this interface should instead use :class:`~zope.interface.commons.collections.IMutableMapping` (one of the bases of this interface). The required methods are the same. .. versionchanged:: 5.0.0 Extend ``IMutableMapping`` """