1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
##############################################################################
#
# 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
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.
"""
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.
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."""
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.
"""
class IMapping(IWriteMapping, IEnumerableMapping):
''' Simple mapping interface '''
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"
class IClonableMapping(Interface):
"""Something that can produce a copy of itself.
This is available in `dict`.
"""
def copy():
"return copy of dict"
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__``"""
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"""
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``
"""
|
