开源软件构建与测试

_service:tar_scm:python-zope-interface.spec Changed

@@ -1,11 +1,11 @@
 %global _empty_manifest_terminate_build 0
 Name:           python-zope-interface
-Version:        5.4.0
-Release:        2
+Version:        5.5.2
+Release:        1
 Summary:        Interfaces for Python
 License:        ZPL 2.1
 URL:            https://github.com/zopefoundation/zope.interface
-Source0:        https://files.pythonhosted.org/packages/ae/58/e0877f58daa69126a5fb325d6df92b20b77431cd281e189c5ec42b722f58/zope.interface-5.4.0.tar.gz
+Source0:        https://files.pythonhosted.org/packages/38/6f/fbfb7dde38be7e5644bb342c4c7cdc444cd5e2ffbd70d091263b3858a8cb/zope.interface-5.5.2.tar.gz
 %description
 This package is intended to be independently reusable in any Python project.
 It is maintained by the Zope Toolkit project.
@@ -88,6 +88,12 @@
 %{_docdir}/*
 
 %changelog
+* Thu Dec 15 2022 chendexi <chendexi@kylinos.cn> - 5.5.2-1
+- Upgrade package to version 5.5.2
+
+* Wed Nov 09 2022 jiangxinyu <jiangxinyu@kylinos.cn> - 5.5.1-1
+- Upgrade package to version 5.5.1
+
 * Thu Mar 03 2022 zhaoshuang <zhaoshuang@uniontech.com> - 5.4.0-2
 - remove some unnecessary buildrequires

_service Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/_static Deleted

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/_static/.gitignore Deleted

_service:tar_scm:zope.interface-5.4.0.tar.gz/.coveragerc -> _service:tar_scm:zope.interface-5.5.2.tar.gz/.coveragerc Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/.manylinux-install.sh -> _service:tar_scm:zope.interface-5.5.2.tar.gz/.manylinux-install.sh Changed

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Generated from:
+# https://github.com/zopefoundation/meta/tree/master/config/c-code
 
 set -e -x
 
@@ -21,21 +23,42 @@
 ls -ld /cache
 ls -ld /cache/pip
 
+# We need some libraries because we build wheels from scratch:
+yum -y install libffi-devel
+
+tox_env_map() {
+    case $1 in
+        *"cp27"*) echo 'py27';;
+        *"cp35"*) echo 'py35';;
+        *"cp36"*) echo 'py36';;
+        *"cp37"*) echo 'py37';;
+        *"cp38"*) echo 'py38';;
+        *"cp39"*) echo 'py39';;
+        *"cp310"*) echo 'py310';;
+        *"cp311"*) echo 'py311';;
+        *) echo 'py';;
+    esac
+}
+
 # Compile wheels
 for PYBIN in /opt/python/*/bin; do
-    if  "${PYBIN}" == *"cp27"*  || \
+    if \
+        "${PYBIN}" == *"cp27"*  || \
         "${PYBIN}" == *"cp35"*  || \
+        "${PYBIN}" == *"cp311"*  || \
         "${PYBIN}" == *"cp36"*  || \
         "${PYBIN}" == *"cp37"*  || \
         "${PYBIN}" == *"cp38"*  || \
-        "${PYBIN}" == *"cp39"* ; then
+        "${PYBIN}" == *"cp39"*  || \
+        "${PYBIN}" == *"cp310"*  ; then
         "${PYBIN}/pip" install -e /io/
         "${PYBIN}/pip" wheel /io/ -w wheelhouse/
         if  `uname -m` == 'aarch64' ; then
-         cd /io/
-         "${PYBIN}/pip" install tox
-         "${PYBIN}/tox" -e py
-         cd ..
+          cd /io/
+          ${PYBIN}/pip install tox
+          TOXENV=$(tox_env_map "${PYBIN}")
+          ${PYBIN}/tox -e ${TOXENV}
+          cd ..
         fi
         rm -rf /io/build /io/*.egg-info
     fi

_service:tar_scm:zope.interface-5.4.0.tar.gz/.manylinux.sh -> _service:tar_scm:zope.interface-5.5.2.tar.gz/.manylinux.sh Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/CHANGES.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/CHANGES.rst Changed

@@ -2,6 +2,31 @@
  Changes
 =========
 
+5.5.2 (2022-11-17)
+==================
+
+- Add support for building arm64 wheels on macOS.
+
+
+5.5.1 (2022-11-03)
+==================
+
+- Add support for final Python 3.11 release.
+
+
+5.5.0 (2022-10-10)
+==================
+
+- Add support for Python 3.10 and 3.11 (as of 3.11.0rc2).
+
+- Add missing Trove classifier showing support for Python 3.9.
+
+- Add some more entries to ``zope.interface.interfaces.__all__``.
+
+- Disable unsafe math optimizations in C code.  See `pull request 262
+  <https://github.com/zopefoundation/zope.interface/pull/262>`_.
+
+
 5.4.0 (2021-04-15)
 ==================
 
@@ -960,14 +985,14 @@
 3.2.0 (2006-01-05)
 ==================
 
-- Corresponds to the verison of the zope.interface package shipped as part of
+- Corresponds to the version of the zope.interface package shipped as part of
   the Zope 3.2.0 release.
 
 
 3.1.0 (2005-10-03)
 ==================
 
-- Corresponds to the verison of the zope.interface package shipped as part of
+- Corresponds to the version of the zope.interface package shipped as part of
   the Zope 3.1.0 release.
 
 - Made attribute resolution order consistent with component lookup order,
@@ -980,7 +1005,7 @@
 3.0.1 (2005-07-27)
 ==================
 
-- Corresponds to the verison of the zope.interface package shipped as part of
+- Corresponds to the version of the zope.interface package shipped as part of
   the Zope X3.0.1 release.
 
 - Fix a bug reported by James Knight, which caused adapter registries
@@ -990,5 +1015,5 @@
 3.0.0 (2004-11-07)
 ==================
 
-- Corresponds to the verison of the zope.interface package shipped as part of
+- Corresponds to the version of the zope.interface package shipped as part of
   the Zope X3.0.0 release.

_service:tar_scm:zope.interface-5.5.2.tar.gz/CONTRIBUTING.md Added

_service:tar_scm:zope.interface-5.4.0.tar.gz/MANIFEST.in -> _service:tar_scm:zope.interface-5.5.2.tar.gz/MANIFEST.in Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/PKG-INFO -> _service:tar_scm:zope.interface-5.5.2.tar.gz/PKG-INFO Changed

@@ -1,1040 +1,12 @@
 Metadata-Version: 2.1
 Name: zope.interface
-Version: 5.4.0
+Version: 5.5.2
 Summary: Interfaces for Python
 Home-page: https://github.com/zopefoundation/zope.interface
 Author: Zope Foundation and Contributors
 Author-email: zope-dev@zope.org
 License: ZPL 2.1
-Description: ====================
-         ``zope.interface``
-        ====================
-        
-        .. image:: https://img.shields.io/pypi/v/zope.interface.svg
-            :target: https://pypi.python.org/pypi/zope.interface/
-            :alt: Latest Version
-        
-        .. image:: https://img.shields.io/pypi/pyversions/zope.interface.svg
-                :target: https://pypi.org/project/zope.interface/
-                :alt: Supported Python versions
-        
-        .. image:: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml/badge.svg
-                :target: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml
-        
-        .. image:: https://readthedocs.org/projects/zopeinterface/badge/?version=latest
-                :target: https://zopeinterface.readthedocs.io/en/latest/
-                :alt: Documentation Status
-        
-        This package is intended to be independently reusable in any Python
-        project. It is maintained by the `Zope Toolkit project
-        <https://zopetoolkit.readthedocs.io/>`_.
-        
-        This package provides an implementation of "object interfaces" for Python.
-        Interfaces are a mechanism for labeling objects as conforming to a given
-        API or contract. So, this package can be considered as implementation of
-        the `Design By Contract`_ methodology support in Python.
-        
-        .. _Design By Contract: http://en.wikipedia.org/wiki/Design_by_contract
-        
-        For detailed documentation, please see https://zopeinterface.readthedocs.io/en/latest/
-        
-        =========
-         Changes
-        =========
-        
-        5.4.0 (2021-04-15)
-        ==================
-        
-        - Make the C implementation of the ``__providedBy__`` descriptor stop
-          ignoring all errors raised when accessing the instance's
-          ``__provides__``. Now it behaves like the Python version and only
-          catches ``AttributeError``. The previous behaviour could lead to
-          crashing the interpreter in cases of recursion and errors. See
-          `issue 239 <https://github.com/zopefoundation/zope.interface/issues>`_.
-        
-        - Update the ``repr()`` and ``str()`` of various objects to be shorter
-          and more informative. In many cases, the ``repr()`` is now something
-          that can be evaluated to produce an equal object. For example, what
-          was previously printed as ``<implementedBy builtins.list>`` is now
-          shown as ``classImplements(list, IMutableSequence, IIterable)``. See
-          `issue 236 <https://github.com/zopefoundation/zope.interface/issues/236>`_.
-        
-        - Make ``Declaration.__add__`` (as in ``implementedBy(Cls) +
-          ISomething``) try harder to preserve a consistent resolution order
-          when the two arguments share overlapping pieces of the interface
-          inheritance hierarchy. Previously, the right hand side was always
-          put at the end of the resolution order, which could easily produce
-          invalid orders. See `issue 193
-          <https://github.com/zopefoundation/zope.interface/issues/193>`_.
-        
-        5.3.0 (2020-03-21)
-        ==================
-        
-        - No changes from 5.3.0a1
-        
-        
-        5.3.0a1 (2021-03-18)
-        ====================
-        
-        - Improve the repr of ``zope.interface.Provides`` to remove ambiguity
-          about what is being provided. This is especially helpful diagnosing
-          IRO issues.
-        
-        - Allow subclasses of ``BaseAdapterRegistry`` (including
-          ``AdapterRegistry`` and ``VerifyingAdapterRegistry``) to have
-          control over the data structures. This allows persistent
-          implementations such as those based on ZODB to choose more scalable
-          options (e.g., BTrees instead of dicts). See `issue 224
-          <https://github.com/zopefoundation/zope.interface/issues/224>`_.
-        
-        - Fix a reference counting issue in ``BaseAdapterRegistry`` that could
-          lead to references to interfaces being kept around even when all
-          utilities/adapters/subscribers providing that interface have been
-          removed. This is mostly an issue for persistent implementations.
-          Note that this only corrects the issue moving forward, it does not
-          solve any already corrupted reference counts. See `issue 227
-          <https://github.com/zopefoundation/zope.interface/issues/227>`_.
-        
-        - Add the method ``BaseAdapterRegistry.rebuild()``. This can be used
-          to fix the reference counting issue mentioned above, as well as to
-          update the data structures when custom data types have changed.
-        
-        - Add the interface method ``IAdapterRegistry.subscribed()`` and
-          implementation ``BaseAdapterRegistry.subscribed()`` for querying
-          directly registered subscribers. See `issue 230
-          <https://github.com/zopefoundation/zope.interface/issues/230>`_.
-        
-        - Add the maintenance method
-          ``Components.rebuildUtilityRegistryFromLocalCache()``. Most users
-          will not need this, but it can be useful if the ``Components.utilities``
-          registry is suspected to be out of sync with the ``Components``
-          object itself (this might happen to persistent ``Components``
-          implementations in the face of bugs).
-        
-        - Fix the ``Provides`` and ``ClassProvides`` descriptors to stop
-          allowing redundant interfaces (those already implemented by the
-          underlying class or meta class) to produce an inconsistent
-          resolution order. This is similar to the change in ``@implementer``
-          in 5.1.0, and resolves inconsistent resolution orders with
-          ``zope.proxy`` and ``zope.location``. See `issue 207
-          <https://github.com/zopefoundation/zope.interface/issues/207>`_.
-        
-        5.2.0 (2020-11-05)
-        ==================
-        
-        - Add documentation section ``Persistency and Equality``
-          (`#218 <https://github.com/zopefoundation/zope.interface/issues/218>`_).
-        
-        - Create arm64 wheels.
-        
-        - Add support for Python 3.9.
-        
-        
-        5.1.2 (2020-10-01)
-        ==================
-        
-        - Make sure to call each invariant only once when validating invariants.
-          Previously, invariants could be called multiple times because when an
-          invariant is defined in an interface, it's found by in all interfaces
-          inheriting from that interface.  See `pull request 215
-          <https://github.com/zopefoundation/zope.interface/pull/215/>`_.
-        
-        5.1.1 (2020-09-30)
-        ==================
-        
-        - Fix the method definitions of ``IAdapterRegistry.subscribe``,
-          ``subscriptions`` and ``subscribers``. Previously, they all were
-          defined to accept a ``name`` keyword argument, but subscribers have
-          no names and the implementation of that interface did not accept
-          that argument. See `issue 208
-          <https://github.com/zopefoundation/zope.interface/issues/208>`_.
-        
-        - Fix a potential reference leak in the C optimizations. Previously,
-          applications that dynamically created unique ``Specification``
-          objects (e.g., used ``@implementer`` on dynamic classes) could
-          notice a growth of small objects over time leading to increased
-          garbage collection times. See `issue 216
-          <https://github.com/zopefoundation/zope.interface/issues/216>`_.
-        
-          .. caution::
-        
-             This leak could prevent interfaces used as the bases of
-             other interfaces from being garbage collected. Those interfaces
-             will now be collected.
-        
-             One way in which this would manifest was that ``weakref.ref``
-             objects (and things built upon them, like
-             ``WeakKey|ValueDictionary``) would continue to have access to
-             the original object even if there were no other visible
-             references to Python and the original object *should* have been
-             collected. This could be especially problematic for the
-             ``WeakKeyDictionary`` when combined with dynamic or local
-             (created in the scope of a function) interfaces, since interfaces
-             are hashed based just on their name and module name. See the
-             linked issue for an example of a resulting ``KeyError``.
-        
-             Note that such potential errors are not new, they are just once
-             again a possibility.
-        
-        5.1.0 (2020-04-08)
-        ==================
-        
-        - Make ``@implementer(*iface)`` and ``classImplements(cls, *iface)``
-          ignore redundant interfaces. If the class already implements an
-          interface through inheritance, it is no longer redeclared
-          specifically for *cls*. This solves many instances of inconsistent
-          resolution orders, while still allowing the interface to be declared
-          for readability and maintenance purposes. See `issue 199
-          <https://github.com/zopefoundation/zope.interface/issues/199>`_.
-        
-        - Remove all bare ``except:`` statements. Previously, when accessing
-          special attributes such as ``__provides__``, ``__providedBy__``,
-          ``__class__`` and ``__conform__``, this package wrapped such access
-          in a bare ``except:`` statement, meaning that many errors could pass
-          silently; typically this would result in a fallback path being taken
-          and sometimes (like with ``providedBy()``) the result would be
-          non-sensical. This is especially true when those attributes are
-          implemented with descriptors. Now, only ``AttributeError`` is
-          caught. This makes errors more obvious.
-        
-          Obviously, this means that some exceptions will be propagated
-          differently than before. In particular, ``RuntimeError`` raised by
-          Acquisition in the case of circular containment will now be
-          propagated. Previously, when adapting such a broken object, a
-          ``TypeError`` would be the common result, but now it will be a more
-          informative ``RuntimeError``.
-        
-          In addition, ZODB errors like ``POSKeyError`` could now be
-          propagated where previously they would ignored by this package.
-        
-          See `issue 200 <https://github.com/zopefoundation/zope.interface/issues/200>`_.
-        
-        - Require that the second argument (*bases*) to ``InterfaceClass`` is
-          a tuple. This only matters when directly using ``InterfaceClass`` to
-          create new interfaces dynamically. Previously, an individual
-          interface was allowed, but did not work correctly. Now it is
-          consistent with ``type`` and requires a tuple.
-        
-        - Let interfaces define custom ``__adapt__`` methods. This implements
-          the other side of the :pep:`246` adaptation protocol: objects being
-          adapted could already implement ``__conform__`` if they know about
-          the interface, and now interfaces can implement ``__adapt__`` if
-          they know about particular objects. There is no performance penalty
-          for interfaces that do not supply custom ``__adapt__`` methods.
-        
-          This includes the ability to add new methods, or override existing
-          interface methods using the new ``@interfacemethod`` decorator.
-        
-          See `issue 3 <https://github.com/zopefoundation/zope.interface/issues/3>`_.
-        
-        - Make the internal singleton object returned by APIs like
-          ``implementedBy`` and ``directlyProvidedBy`` for objects that
-          implement or provide no interfaces more immutable. Previously an
-          internal cache could be mutated. See `issue 204
-          <https://github.com/zopefoundation/zope.interface/issues/204>`_.
-        
-        5.0.2 (2020-03-30)
-        ==================
-        
-        - Ensure that objects that implement no interfaces (such as direct
-          subclasses of ``object``) still include ``Interface`` itself in
-          their ``__iro___`` and ``__sro___``. This fixes adapter registry
-          lookups for such objects when the adapter is registered for
-          ``Interface``. See `issue 197
-          <https://github.com/zopefoundation/zope.interface/issues/197>`_.
-        
-        
-        5.0.1 (2020-03-21)
-        ==================
-        
-        - Ensure the resolution order for ``InterfaceClass`` is consistent.
-          See `issue 192 <https://github.com/zopefoundation/zope.interface/issues/192>`_.
-        
-        - Ensure the resolution order for ``collections.OrderedDict`` is
-          consistent on CPython 2. (It was already consistent on Python 3 and PyPy).
-        
-        - Fix the handling of the ``ZOPE_INTERFACE_STRICT_IRO`` environment
-          variable. Previously, ``ZOPE_INTERFACE_STRICT_RO`` was read, in
-          contrast with the documentation. See `issue 194
-          <https://github.com/zopefoundation/zope.interface/issues/194>`_.
-        
-        
-        5.0.0 (2020-03-19)
-        ==================
-        
-        - Make an internal singleton object returned by APIs like
-          ``implementedBy`` and ``directlyProvidedBy`` immutable. Previously,
-          it was fully mutable and allowed changing its ``__bases___``. That
-          could potentially lead to wrong results in pathological corner
-          cases. See `issue 158
-          <https://github.com/zopefoundation/zope.interface/issues/158>`_.
-        
-        - Support the ``PURE_PYTHON`` environment variable at runtime instead
-          of just at wheel build time. A value of 0 forces the C extensions to
-          be used (even on PyPy) failing if they aren't present. Any other
-          value forces the Python implementation to be used, ignoring the C
-          extensions. See `PR 151 <https://github.com/zopefoundation/zope.interface/pull/151>`_.
-        
-        - Cache the result of ``__hash__`` method in ``InterfaceClass`` as a
-          speed optimization. The method is called very often (i.e several
-          hundred thousand times during Plone 5.2 startup). Because the hash value never
-          changes it can be cached. This improves test performance from 0.614s
-          down to 0.575s (1.07x faster). In a real world Plone case a reindex
-          index came down from 402s to 320s (1.26x faster). See `PR 156
-          <https://github.com/zopefoundation/zope.interface/pull/156>`_.
-        
-        - Change the C classes ``SpecificationBase`` and its subclass
-          ``ClassProvidesBase`` to store implementation attributes in their structures
-          instead of their instance dictionaries. This eliminates the use of
-          an undocumented private C API function, and helps make some
-          instances require less memory. See `PR 154 <https://github.com/zopefoundation/zope.interface/pull/154>`_.
-        
-        - Reduce memory usage in other ways based on observations of usage
-          patterns in Zope (3) and Plone code bases.
-        
-          - Specifications with no dependents are common (more than 50%) so
-            avoid allocating a ``WeakKeyDictionary`` unless we need it.
-          - Likewise, tagged values are relatively rare, so don't allocate a
-            dictionary to hold them until they are used.
-          - Use ``__slots___`` or the C equivalent ``tp_members`` in more
-            common places. Note that this removes the ability to set arbitrary
-            instance variables on certain objects.
-            See `PR 155 <https://github.com/zopefoundation/zope.interface/pull/155>`_.
-        
-          The changes in this release resulted in a 7% memory reduction after
-          loading about 6,000 modules that define about 2,200 interfaces.
-        
-          .. caution::
-        
-             Details of many private attributes have changed, and external use
-             of those private attributes may break. In particular, the
-             lifetime and default value of ``_v_attrs`` has changed.
-        
-        - Remove support for hashing uninitialized interfaces. This could only
-          be done by subclassing ``InterfaceClass``. This has generated a
-          warning since it was first added in 2011 (3.6.5). Please call the
-          ``InterfaceClass`` constructor or otherwise set the appropriate
-          fields in your subclass before attempting to hash or sort it. See
-          `issue 157 <https://github.com/zopefoundation/zope.interface/issues/157>`_.
-        
-        - Remove unneeded override of the ``__hash__`` method from
-          ``zope.interface.declarations.Implements``. Watching a reindex index
-          process in ZCatalog with on a Py-Spy after 10k samples the time for
-          ``.adapter._lookup`` was reduced from 27.5s to 18.8s (~1.5x faster).
-          Overall reindex index time shrunk from 369s to 293s (1.26x faster).
-          See `PR 161
-          <https://github.com/zopefoundation/zope.interface/pull/161>`_.
-        
-        - Make the Python implementation closer to the C implementation by
-          ignoring all exceptions, not just ``AttributeError``, during (parts
-          of) interface adaptation. See `issue 163
-          <https://github.com/zopefoundation/zope.interface/issues/163>`_.
-        
-        - Micro-optimization in ``.adapter._lookup`` , ``.adapter._lookupAll``
-          and ``.adapter._subscriptions``: By loading ``components.get`` into
-          a local variable before entering the loop a bytcode "LOAD_FAST 0
-          (components)" in the loop can be eliminated. In Plone, while running
-          all tests, average speedup of the "owntime" of ``_lookup`` is ~5x.
-          See `PR 167
-          <https://github.com/zopefoundation/zope.interface/pull/167>`_.
-        
-        - Add ``__all__`` declarations to all modules. This helps tools that
-          do auto-completion and documentation and results in less cluttered
-          results. Wildcard ("*") are not recommended and may be affected. See
-          `issue 153
-          <https://github.com/zopefoundation/zope.interface/issues/153>`_.
-        
-        - Fix ``verifyClass`` and ``verifyObject`` for builtin types like
-          ``dict`` that have methods taking an optional, unnamed argument with
-          no default value like ``dict.pop``. On PyPy3, the verification is
-          strict, but on PyPy2 (as on all versions of CPython) those methods
-          cannot be verified and are ignored. See `issue 118
-          <https://github.com/zopefoundation/zope.interface/issues/118>`_.
-        
-        - Update the common interfaces ``IEnumerableMapping``,
-          ``IExtendedReadMapping``, ``IExtendedWriteMapping``,
-          ``IReadSequence`` and ``IUniqueMemberWriteSequence`` to no longer
-          require methods that were removed from Python 3 on Python 3, such as
-          ``__setslice___``. Now, ``dict``, ``list`` and ``tuple`` properly
-          verify as ``IFullMapping``, ``ISequence`` and ``IReadSequence,``
-          respectively on all versions of Python.
-        
-        - Add human-readable ``__str___`` and ``__repr___`` to ``Attribute``
-          and ``Method``. These contain the name of the defining interface
-          and the attribute. For methods, it also includes the signature.
-        
-        - Change the error strings raised by ``verifyObject`` and
-          ``verifyClass``. They now include more human-readable information
-          and exclude extraneous lines and spaces. See `issue 170
-          <https://github.com/zopefoundation/zope.interface/issues/170>`_.
-        
-          .. caution:: This will break consumers (such as doctests) that
-                       depended on the exact error messages.
-        
-        - Make ``verifyObject`` and ``verifyClass`` report all errors, if the
-          candidate object has multiple detectable violations. Previously they
-          reported only the first error. See `issue
-          <https://github.com/zopefoundation/zope.interface/issues/171>`_.
-        
-          Like the above, this will break consumers depending on the exact
-          output of error messages if more than one error is present.
-        
-        - Add ``zope.interface.common.collections``,
-          ``zope.interface.common.numbers``, and ``zope.interface.common.io``.
-          These modules define interfaces based on the ABCs defined in the
-          standard library ``collections.abc``, ``numbers`` and ``io``
-          modules, respectively. Importing these modules will make the
-          standard library concrete classes that are registered with those
-          ABCs declare the appropriate interface. See `issue 138
-          <https://github.com/zopefoundation/zope.interface/issues/138>`_.
-        
-        - Add ``zope.interface.common.builtins``. This module defines
-          interfaces of common builtin types, such as ``ITextString`` and
-          ``IByteString``, ``IDict``, etc. These interfaces extend the
-          appropriate interfaces from ``collections`` and ``numbers``, and the
-          standard library classes implement them after importing this module.
-          This is intended as a replacement for third-party packages like
-          `dolmen.builtins <https://pypi.org/project/dolmen.builtins/>`_.
-          See `issue 138 <https://github.com/zopefoundation/zope.interface/issues/138>`_.
-        
-        - Make ``providedBy()`` and ``implementedBy()`` respect ``super``
-          objects. For instance, if class ``Derived`` implements ``IDerived``
-          and extends ``Base`` which in turn implements ``IBase``, then
-          ``providedBy(super(Derived, derived))`` will return ``IBase``.
-          Previously it would have returned ``IDerived`` (in general, it
-          would previously have returned whatever would have been returned
-          without ``super``).
-        
-          Along with this change, adapter registries will unpack ``super``
-          objects into their ``__self___`` before passing it to the factory.
-          Together, this means that ``component.getAdapter(super(Derived,
-          self), ITarget)`` is now meaningful.
-        
-          See `issue 11 <https://github.com/zopefoundation/zope.interface/issues/11>`_.
-        
-        - Fix a potential interpreter crash in the low-level adapter
-          registry lookup functions. See issue 11.
-        
-        - Adopt Python's standard `C3 resolution order
-          <https://www.python.org/download/releases/2.3/mro/>`_ to compute the
-          ``__iro__`` and ``__sro__`` of interfaces, with tweaks to support
-          additional cases that are common in interfaces but disallowed for
-          Python classes. Previously, an ad-hoc ordering that made no
-          particular guarantees was used.
-        
-          This has many beneficial properties, including the fact that base
-          interface and base classes tend to appear near the end of the
-          resolution order instead of the beginning. The resolution order in
-          general should be more predictable and consistent.
-        
-          .. caution::
-             In some cases, especially with complex interface inheritance
-             trees or when manually providing or implementing interfaces, the
-             resulting IRO may be quite different. This may affect adapter
-             lookup.
-        
-          The C3 order enforces some constraints in order to be able to
-          guarantee a sensible ordering. Older versions of zope.interface did
-          not impose similar constraints, so it was possible to create
-          interfaces and declarations that are inconsistent with the C3
-          constraints. In that event, zope.interface will still produce a
-          resolution order equal to the old order, but it won't be guaranteed
-          to be fully C3 compliant. In the future, strict enforcement of C3
-          order may be the default.
-        
-          A set of environment variables and module constants allows
-          controlling several aspects of this new behaviour. It is possible to
-          request warnings about inconsistent resolution orders encountered,
-          and even to forbid them. Differences between the C3 resolution order
-          and the previous order can be logged, and, in extreme cases, the
-          previous order can still be used (this ability will be removed in
-          the future). For details, see the documentation for
-          ``zope.interface.ro``.
-        
-        - Make inherited tagged values in interfaces respect the resolution
-          order (``__iro__``), as method and attribute lookup does. Previously
-          tagged values could give inconsistent results. See `issue 190
-          <https://github.com/zopefoundation/zope.interface/issues/190>`_.
-        
-        - Add ``getDirectTaggedValue`` (and related methods) to interfaces to
-          allow accessing tagged values irrespective of inheritance. See
-          `issue 190
-          <https://github.com/zopefoundation/zope.interface/issues/190>`_.
-        
-        - Ensure that ``Interface`` is always the last item in the ``__iro__``
-          and ``__sro__``. This is usually the case, but if classes that do
-          not implement any interfaces are part of a class inheritance
-          hierarchy, ``Interface`` could be assigned too high a priority.
-          See `issue 8 <https://github.com/zopefoundation/zope.interface/issues/8>`_.
-        
-        - Implement sorting, equality, and hashing in C for ``Interface``
-          objects. In micro benchmarks, this makes those operations 40% to 80%
-          faster. This translates to a 20% speed up in querying adapters.
-        
-          Note that this changes certain implementation details. In
-          particular, ``InterfaceClass`` now has a non-default metaclass, and
-          it is enforced that ``__module__`` in instances of
-          ``InterfaceClass`` is read-only.
-        
-          See `PR 183 <https://github.com/zopefoundation/zope.interface/pull/183>`_.
-        
-        
-        4.7.2 (2020-03-10)
-        ==================
-        
-        - Remove deprecated use of setuptools features.  See `issue 30
-          <https://github.com/zopefoundation/zope.interface/issues/30>`_.
-        
-        
-        4.7.1 (2019-11-11)
-        ==================
-        
-        - Use Python 3 syntax in the documentation.  See `issue 119
-          <https://github.com/zopefoundation/zope.interface/issues/119>`_.
-        
-        
-        4.7.0 (2019-11-11)
-        ==================
-        
-        - Drop support for Python 3.4.
-        
-        - Change ``queryTaggedValue``, ``getTaggedValue``,
-          ``getTaggedValueTags`` in interfaces. They now include inherited
-          values by following ``__bases__``. See `PR 144
-          <https://github.com/zopefoundation/zope.interface/pull/144>`_.
-        
-          .. caution:: This may be a breaking change.
-        
-        - Add support for Python 3.8.
-        
-        
-        4.6.0 (2018-10-23)
-        ==================
-        
-        - Add support for Python 3.7
-        
-        - Fix ``verifyObject`` for class objects with staticmethods on
-          Python 3. See `issue 126
-          <https://github.com/zopefoundation/zope.interface/issues/126>`_.
-        
-        
-        4.5.0 (2018-04-19)
-        ==================
-        
-        - Drop support for 3.3, avoid accidental dependence breakage via setup.py.
-          See `PR 110 <https://github.com/zopefoundation/zope.interface/pull/110>`_.
-        - Allow registering and unregistering instance methods as listeners.
-          See `issue 12 <https://github.com/zopefoundation/zope.interface/issues/12>`_
-          and `PR 102 <https://github.com/zopefoundation/zope.interface/pull/102>`_.
-        - Synchronize and simplify zope/__init__.py. See `issue 114
-          <https://github.com/zopefoundation/zope.interface/issues/114>`_
-        
-        
-        4.4.3 (2017-09-22)
-        ==================
-        
-        - Avoid exceptions when the ``__annotations__`` attribute is added to
-          interface definitions with Python 3.x type hints. See `issue 98
-          <https://github.com/zopefoundation/zope.interface/issues/98>`_.
-        - Fix the possibility of a rare crash in the C extension when
-          deallocating items. See `issue 100
-          <https://github.com/zopefoundation/zope.interface/issues/100>`_.
-        
-        
-        4.4.2 (2017-06-14)
-        ==================
-        
-        - Fix a regression storing
-          ``zope.component.persistentregistry.PersistentRegistry`` instances.
-          See `issue 85 <https://github.com/zopefoundation/zope.interface/issues/85>`_.
-        
-        - Fix a regression that could lead to the utility registration cache
-          of ``Components`` getting out of sync. See `issue 93
-          <https://github.com/zopefoundation/zope.interface/issues/93>`_.
-        
-        4.4.1 (2017-05-13)
-        ==================
-        
-        - Simplify the caching of utility-registration data. In addition to
-          simplification, avoids spurious test failures when checking for
-          leaks in tests with persistent registries. See `pull 84
-          <https://github.com/zopefoundation/zope.interface/pull/84>`_.
-        
-        - Raise ``ValueError`` when non-text names are passed to adapter registry
-          methods:  prevents corruption of lookup caches.
-        
-        4.4.0 (2017-04-21)
-        ==================
-        
-        - Avoid a warning from the C compiler.
-          (https://github.com/zopefoundation/zope.interface/issues/71)
-        
-        - Add support for Python 3.6.
-        
-        4.3.3 (2016-12-13)
-        ==================
-        
-        - Correct typos and ReST formatting errors in documentation.
-        
-        - Add API documentation for the adapter registry.
-        
-        - Ensure that the ``LICENSE.txt`` file is included in built wheels.
-        
-        - Fix C optimizations broken on Py3k.  See the Python bug at:
-          http://bugs.python.org/issue15657
-          (https://github.com/zopefoundation/zope.interface/issues/60)
-        
-        
-        4.3.2 (2016-09-05)
-        ==================
-        
-        - Fix equality testing of ``implementedBy`` objects and proxies.
-          (https://github.com/zopefoundation/zope.interface/issues/55)
-        
-        
-        4.3.1 (2016-08-31)
-        ==================
-        
-        - Support Components subclasses that are not hashable.
-          (https://github.com/zopefoundation/zope.interface/issues/53)
-        
-        
-        4.3.0 (2016-08-31)
-        ==================
-        
-        - Add the ability to sort the objects returned by ``implementedBy``.
-          This is compatible with the way interface classes sort so they can
-          be used together in ordered containers like BTrees.
-          (https://github.com/zopefoundation/zope.interface/issues/42)
-        
-        - Make ``setuptools`` a hard dependency of ``setup.py``.
-          (https://github.com/zopefoundation/zope.interface/issues/13)
-        
-        - Change a linear algorithm (O(n)) in ``Components.registerUtility`` and
-          ``Components.unregisterUtility`` into a dictionary lookup (O(1)) for
-          hashable components. This substantially improves the time taken to
-          manipulate utilities in large registries at the cost of some
-          additional memory usage. (https://github.com/zopefoundation/zope.interface/issues/46)
-        
-        
-        4.2.0 (2016-06-10)
-        ==================
-        
-        - Add support for Python 3.5
-        
-        - Drop support for Python 2.6 and 3.2.
-        
-        
-        4.1.3 (2015-10-05)
-        ==================
-        
-        - Fix installation without a C compiler on Python 3.5
-          (https://github.com/zopefoundation/zope.interface/issues/24).
-        
-        
-        4.1.2 (2014-12-27)
-        ==================
-        
-        - Add support for PyPy3.
-        
-        - Remove unittest assertions deprecated in Python3.x.
-        
-        - Add ``zope.interface.document.asReStructuredText``, which formats the
-          generated text for an interface using ReST double-backtick markers.
-        
-        
-        4.1.1 (2014-03-19)
-        ==================
-        
-        - Add support for Python 3.4.
-        
-        
-        4.1.0 (2014-02-05)
-        ==================
-        
-        - Update ``boostrap.py`` to version 2.2.
-        
-        - Add ``@named(name)`` declaration, that specifies the component name, so it
-          does not have to be passed in during registration.
-        
-        
-        4.0.5 (2013-02-28)
-        ==================
-        
-        - Fix a bug where a decorated method caused false positive failures on
-          ``verifyClass()``.
-        
-        
-        4.0.4 (2013-02-21)
-        ==================
-        
-        - Fix a bug that was revealed by porting zope.traversing. During a loop, the
-          loop body modified a weakref dict causing a ``RuntimeError`` error.
-        
-        4.0.3 (2012-12-31)
-        ==================
-        
-        - Fleshed out PyPI Trove classifiers.
-        
-        4.0.2 (2012-11-21)
-        ==================
-        
-        - Add support for Python 3.3.
-        
-        - Restored ability to install the package in the absence of ``setuptools``.
-        
-        - LP #1055223:  Fix test which depended on dictionary order and failed randomly
-          in Python 3.3.
-        
-        4.0.1 (2012-05-22)
-        ==================
-        
-        - Drop explicit ``DeprecationWarnings`` for "class advice" APIS (these
-          APIs are still deprecated under Python 2.x, and still raise an exception
-          under Python 3.x, but no longer cause a warning to be emitted under
-          Python 2.x).
-        
-        4.0.0 (2012-05-16)
-        ==================
-        
-        - Automated build of Sphinx HTML docs and running doctest snippets via tox.
-        
-        - Deprecate the "class advice" APIs from ``zope.interface.declarations``:
-          ``implements``, ``implementsOnly``, and ``classProvides``.  In their place,
-          prefer the equivalent class decorators: ``@implementer``,
-          ``@implementer_only``, and ``@provider``.  Code which uses the deprecated
-          APIs will not work as expected under Py3k.
-        
-        - Remove use of '2to3' and associated fixers when installing under Py3k.
-          The code is now in a "compatible subset" which supports Python 2.6, 2.7,
-          and 3.2, including PyPy 1.8 (the version compatible with the 2.7 language
-          spec).
-        
-        - Drop explicit support for Python 2.4 / 2.5 / 3.1.
-        
-        - Add support for PyPy.
-        
-        - Add support for continuous integration using ``tox`` and ``jenkins``.
-        
-        - Add 'setup.py dev' alias (runs ``setup.py develop`` plus installs
-          ``nose`` and ``coverage``).
-        
-        - Add 'setup.py docs' alias (installs ``Sphinx`` and dependencies).
-        
-        - Replace all unittest coverage previously accomplished via doctests with
-          unittests.  The doctests have been moved into a ``docs`` section, managed
-          as a Sphinx collection.
-        
-        - LP #910987:  Ensure that the semantics of the ``lookup`` method of
-          ``zope.interface.adapter.LookupBase`` are the same in both the C and
-          Python implementations.
-        
-        - LP #900906:  Avoid exceptions due to tne new ``__qualname__`` attribute
-          added in Python 3.3 (see PEP 3155 for rationale).  Thanks to Antoine
-          Pitrou for the patch.
-        
-        3.8.0 (2011-09-22)
-        ==================
-        
-        - New module ``zope.interface.registry``.  This is code moved from
-          ``zope.component.registry`` which implements a basic nonperistent component
-          registry as ``zope.interface.registry.Components``.  This class was moved
-          from ``zope.component`` to make porting systems (such as Pyramid) that rely
-          only on a basic component registry to Python 3 possible without needing to
-          port the entirety of the ``zope.component`` package.  Backwards
-          compatibility import shims have been left behind in ``zope.component``, so
-          this change will not break any existing code.
-        
-        - New ``tests_require`` dependency: ``zope.event`` to test events sent by
-          Components implementation.  The ``zope.interface`` package does not have a
-          hard dependency on ``zope.event``, but if ``zope.event`` is importable, it
-          will send component registration events when methods of an instance of
-          ``zope.interface.registry.Components`` are called.
-        
-        - New interfaces added to support ``zope.interface.registry.Components``
-          addition: ``ComponentLookupError``, ``Invalid``, ``IObjectEvent``,
-          ``ObjectEvent``, ``IComponentLookup``, ``IRegistration``,
-          ``IUtilityRegistration``, ``IAdapterRegistration``,
-          ``ISubscriptionAdapterRegistration``, ``IHandlerRegistration``,
-          ``IRegistrationEvent``, ``RegistrationEvent``, ``IRegistered``,
-          ``Registered``, ``IUnregistered``, ``Unregistered``,
-          ``IComponentRegistry``, and ``IComponents``.
-        
-        - No longer Python 2.4 compatible (tested under 2.5, 2.6, 2.7, and 3.2).
-        
-        3.7.0 (2011-08-13)
-        ==================
-        
-        - Move changes from 3.6.2 - 3.6.5 to a new 3.7.x release line.
-        
-        3.6.7 (2011-08-20)
-        ==================
-        
-        - Fix sporadic failures on x86-64 platforms in tests of rich comparisons
-          of interfaces.
-        
-        3.6.6 (2011-08-13)
-        ==================
-        
-        - LP #570942:  Now correctly compare interfaces  from different modules but
-          with the same names.
-        
-          N.B.: This is a less intrusive / destabilizing fix than the one applied in
-          3.6.3:  we only fix the underlying cmp-alike function, rather than adding
-          the other "rich comparison" functions.
-        
-        - Revert to software as released with 3.6.1 for "stable" 3.6 release branch.
-        
-        3.6.5 (2011-08-11)
-        ==================
-        
-        - LP #811792:  work around buggy behavior in some subclasses of
-          ``zope.interface.interface.InterfaceClass``, which invoke ``__hash__``
-          before initializing ``__module__`` and ``__name__``.  The workaround
-          returns a fixed constant hash in such cases, and issues a ``UserWarning``.
-        
-        - LP #804832:  Under PyPy, ``zope.interface`` should not build its C
-          extension.  Also, prevent attempting to build it under Jython.
-        
-        - Add a tox.ini for easier xplatform testing.
-        
-        - Fix testing deprecation warnings issued when tested under Py3K.
-        
-        3.6.4 (2011-07-04)
-        ==================
-        
-        - LP 804951:  InterfaceClass instances were unhashable under Python 3.x.
-        
-        3.6.3 (2011-05-26)
-        ==================
-        
-        - LP #570942:  Now correctly compare interfaces  from different modules but
-          with the same names.
-        
-        3.6.2 (2011-05-17)
-        ==================
-        
-        - Moved detailed documentation out-of-line from PyPI page, linking instead to
-          http://docs.zope.org/zope.interface .
-        
-        - Fixes for small issues when running tests under Python 3.2 using
-          ``zope.testrunner``.
-        
-        - LP # 675064:  Specify return value type for C optimizations module init
-          under Python 3:  undeclared value caused warnings, and segfaults on some
-          64 bit architectures.
-        
-        - setup.py now raises RuntimeError if you don't have Distutils installed when
-          running under Python 3.
-        
-        3.6.1 (2010-05-03)
-        ==================
-        
-        - A non-ASCII character in the changelog made 3.6.0 uninstallable on
-          Python 3 systems with another default encoding than UTF-8.
-        
-        - Fix compiler warnings under GCC 4.3.3.
-        
-        3.6.0 (2010-04-29)
-        ==================
-        
-        - LP #185974:  Clear the cache used by ``Specificaton.get`` inside
-          ``Specification.changed``.  Thanks to Jacob Holm for the patch.
-        
-        - Add support for Python 3.1. Contributors:
-        
-            Lennart Regebro
-            Martin v Loewis
-            Thomas Lotze
-            Wolfgang Schnerring
-        
-          The 3.1 support is completely backwards compatible. However, the implements
-          syntax used under Python 2.X does not work under 3.X, since it depends on
-          how metaclasses are implemented and this has changed. Instead it now supports
-          a decorator syntax (also under Python 2.X)::
-        
-            class Foo:
-                implements(IFoo)
-                ...
-        
-          can now also be written::
-        
-            @implementer(IFoo):
-            class Foo:
-                ...
-        
-          There are 2to3 fixers available to do this change automatically in the
-          zope.fixers package.
-        
-        - Python 2.3 is no longer supported.
-        
-        
-        3.5.4 (2009-12-23)
-        ==================
-        
-        - Use the standard Python doctest module instead of zope.testing.doctest, which
-          has been deprecated.
-        
-        
-        3.5.3 (2009-12-08)
-        ==================
-        
-        - Fix an edge case: make providedBy() work when a class has '__provides__' in
-          its __slots__ (see http://thread.gmane.org/gmane.comp.web.zope.devel/22490)
-        
-        
-        3.5.2 (2009-07-01)
-        ==================
-        
-        - BaseAdapterRegistry.unregister, unsubscribe: Remove empty portions of
-          the data structures when something is removed.  This avoids leaving
-          references to global objects (interfaces) that may be slated for
-          removal from the calling application.
-        
-        
-        3.5.1 (2009-03-18)
-        ==================
-        
-        - verifyObject: use getattr instead of hasattr to test for object attributes
-          in order to let exceptions other than AttributeError raised by properties
-          propagate to the caller
-        
-        - Add Sphinx-based documentation building to the package buildout
-          configuration. Use the ``bin/docs`` command after buildout.
-        
-        - Improve package description a bit. Unify changelog entries formatting.
-        
-        - Change package's mailing list address to zope-dev at zope.org as
-          zope3-dev at zope.org is now retired.
-        
-        
-        3.5.0 (2008-10-26)
-        ==================
-        
-        - Fix declaration of _zope_interface_coptimizations, it's not a top level
-          package.
-        
-        - Add a DocTestSuite for odd.py module, so their tests are run.
-        
-        - Allow to bootstrap on Jython.
-        
-        - Fix https://bugs.launchpad.net/zope3/3.3/+bug/98388: ISpecification
-          was missing a declaration for __iro__.
-        
-        - Add optional code optimizations support, which allows the building
-          of C code optimizations to fail (Jython).
-        
-        - Replace `_flatten` with a non-recursive implementation, effectively making
-          it 3x faster.
-        
-        
-        3.4.1 (2007-10-02)
-        ==================
-        
-        - Fix a setup bug that prevented installation from source on systems
-          without setuptools.
-        
-        
-        3.4.0 (2007-07-19)
-        ==================
-        
-        - Final release for 3.4.0.
-        
-        
-        3.4.0b3 (2007-05-22)
-        ====================
-        
-        
-        - When checking whether an object is already registered, use identity
-          comparison, to allow adding registering with picky custom comparison methods.
-        
-        
-        3.3.0.1 (2007-01-03)
-        ====================
-        
-        - Made a reference to OverflowWarning, which disappeared in Python
-          2.5, conditional.
-        
-        
-        3.3.0 (2007/01/03)
-        ==================
-        
-        New Features
-        ------------
-        
-        - Refactor the adapter-lookup algorithim to make it much simpler and faster.
-        
-          Also, implement more of the adapter-lookup logic in C, making
-          debugging of application code easier, since there is less
-          infrastructre code to step through.
-        
-        - Treat objects without interface declarations as if they
-          declared that they provide ``zope.interface.Interface``.
-        
-        - Add a number of richer new adapter-registration interfaces
-          that provide greater control and introspection.
-        
-        - Add a new interface decorator to zope.interface that allows the
-          setting of tagged values on an interface at definition time (see
-          zope.interface.taggedValue).
-        
-        Bug Fixes
-        ---------
-        
-        - A bug in multi-adapter lookup sometimes caused incorrect adapters to
-          be returned.
-        
-        
-        3.2.0.2 (2006-04-15)
-        ====================
-        
-        - Fix packaging bug:  'package_dir' must be a *relative* path.
-        
-        
-        3.2.0.1 (2006-04-14)
-        ====================
-        
-        - Packaging change:  suppress inclusion of 'setup.cfg' in 'sdist' builds.
-        
-        
-        3.2.0 (2006-01-05)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope 3.2.0 release.
-        
-        
-        3.1.0 (2005-10-03)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope 3.1.0 release.
-        
-        - Made attribute resolution order consistent with component lookup order,
-          i.e. new-style class MRO semantics.
-        
-        - Deprecate 'isImplementedBy' and 'isImplementedByInstancesOf' APIs in
-          favor of 'implementedBy' and 'providedBy'.
-        
-        
-        3.0.1 (2005-07-27)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope X3.0.1 release.
-        
-        - Fix a bug reported by James Knight, which caused adapter registries
-          to fail occasionally to reflect declaration changes.
-        
-        
-        3.0.0 (2004-11-07)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope X3.0.0 release.
-        
 Keywords: interface,components,plugins
-Platform: UNKNOWN
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Zope Public License
@@ -1047,6 +19,9 @@
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Framework :: Zope :: 3
@@ -1055,3 +30,1056 @@
 Provides-Extra: docs
 Provides-Extra: test
 Provides-Extra: testing
+License-File: LICENSE.txt
+
+====================
+ ``zope.interface``
+====================
+
+.. image:: https://img.shields.io/pypi/v/zope.interface.svg
+    :target: https://pypi.python.org/pypi/zope.interface/
+    :alt: Latest Version
+
+.. image:: https://img.shields.io/pypi/pyversions/zope.interface.svg
+        :target: https://pypi.org/project/zope.interface/
+        :alt: Supported Python versions
+
+.. image:: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml/badge.svg
+        :target: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml
+
+.. image:: https://readthedocs.org/projects/zopeinterface/badge/?version=latest
+        :target: https://zopeinterface.readthedocs.io/en/latest/
+        :alt: Documentation Status
+
+This package is intended to be independently reusable in any Python
+project. It is maintained by the `Zope Toolkit project
+<https://zopetoolkit.readthedocs.io/>`_.
+
+This package provides an implementation of "object interfaces" for Python.
+Interfaces are a mechanism for labeling objects as conforming to a given
+API or contract. So, this package can be considered as implementation of
+the `Design By Contract`_ methodology support in Python.
+
+.. _Design By Contract: http://en.wikipedia.org/wiki/Design_by_contract
+
+For detailed documentation, please see https://zopeinterface.readthedocs.io/en/latest/
+
+=========
+ Changes
+=========
+
+5.5.2 (2022-11-17)
+==================
+
+- Add support for building arm64 wheels on macOS.
+
+
+5.5.1 (2022-11-03)
+==================
+
+- Add support for final Python 3.11 release.
+
+
+5.5.0 (2022-10-10)
+==================
+
+- Add support for Python 3.10 and 3.11 (as of 3.11.0rc2).
+
+- Add missing Trove classifier showing support for Python 3.9.
+
+- Add some more entries to ``zope.interface.interfaces.__all__``.
+
+- Disable unsafe math optimizations in C code.  See `pull request 262
+  <https://github.com/zopefoundation/zope.interface/pull/262>`_.
+
+
+5.4.0 (2021-04-15)
+==================
+
+- Make the C implementation of the ``__providedBy__`` descriptor stop
+  ignoring all errors raised when accessing the instance's
+  ``__provides__``. Now it behaves like the Python version and only
+  catches ``AttributeError``. The previous behaviour could lead to
+  crashing the interpreter in cases of recursion and errors. See
+  `issue 239 <https://github.com/zopefoundation/zope.interface/issues>`_.
+
+- Update the ``repr()`` and ``str()`` of various objects to be shorter
+  and more informative. In many cases, the ``repr()`` is now something
+  that can be evaluated to produce an equal object. For example, what
+  was previously printed as ``<implementedBy builtins.list>`` is now
+  shown as ``classImplements(list, IMutableSequence, IIterable)``. See
+  `issue 236 <https://github.com/zopefoundation/zope.interface/issues/236>`_.
+
+- Make ``Declaration.__add__`` (as in ``implementedBy(Cls) +
+  ISomething``) try harder to preserve a consistent resolution order
+  when the two arguments share overlapping pieces of the interface
+  inheritance hierarchy. Previously, the right hand side was always
+  put at the end of the resolution order, which could easily produce
+  invalid orders. See `issue 193
+  <https://github.com/zopefoundation/zope.interface/issues/193>`_.
+
+5.3.0 (2020-03-21)
+==================
+
+- No changes from 5.3.0a1
+
+
+5.3.0a1 (2021-03-18)
+====================
+
+- Improve the repr of ``zope.interface.Provides`` to remove ambiguity
+  about what is being provided. This is especially helpful diagnosing
+  IRO issues.
+
+- Allow subclasses of ``BaseAdapterRegistry`` (including
+  ``AdapterRegistry`` and ``VerifyingAdapterRegistry``) to have
+  control over the data structures. This allows persistent
+  implementations such as those based on ZODB to choose more scalable
+  options (e.g., BTrees instead of dicts). See `issue 224
+  <https://github.com/zopefoundation/zope.interface/issues/224>`_.
+
+- Fix a reference counting issue in ``BaseAdapterRegistry`` that could
+  lead to references to interfaces being kept around even when all
+  utilities/adapters/subscribers providing that interface have been
+  removed. This is mostly an issue for persistent implementations.
+  Note that this only corrects the issue moving forward, it does not
+  solve any already corrupted reference counts. See `issue 227
+  <https://github.com/zopefoundation/zope.interface/issues/227>`_.
+
+- Add the method ``BaseAdapterRegistry.rebuild()``. This can be used
+  to fix the reference counting issue mentioned above, as well as to
+  update the data structures when custom data types have changed.
+
+- Add the interface method ``IAdapterRegistry.subscribed()`` and
+  implementation ``BaseAdapterRegistry.subscribed()`` for querying
+  directly registered subscribers. See `issue 230
+  <https://github.com/zopefoundation/zope.interface/issues/230>`_.
+
+- Add the maintenance method
+  ``Components.rebuildUtilityRegistryFromLocalCache()``. Most users
+  will not need this, but it can be useful if the ``Components.utilities``
+  registry is suspected to be out of sync with the ``Components``
+  object itself (this might happen to persistent ``Components``
+  implementations in the face of bugs).
+
+- Fix the ``Provides`` and ``ClassProvides`` descriptors to stop
+  allowing redundant interfaces (those already implemented by the
+  underlying class or meta class) to produce an inconsistent
+  resolution order. This is similar to the change in ``@implementer``
+  in 5.1.0, and resolves inconsistent resolution orders with
+  ``zope.proxy`` and ``zope.location``. See `issue 207
+  <https://github.com/zopefoundation/zope.interface/issues/207>`_.
+
+5.2.0 (2020-11-05)
+==================
+
+- Add documentation section ``Persistency and Equality``
+  (`#218 <https://github.com/zopefoundation/zope.interface/issues/218>`_).
+
+- Create arm64 wheels.
+
+- Add support for Python 3.9.
+
+
+5.1.2 (2020-10-01)
+==================
+
+- Make sure to call each invariant only once when validating invariants.
+  Previously, invariants could be called multiple times because when an
+  invariant is defined in an interface, it's found by in all interfaces
+  inheriting from that interface.  See `pull request 215
+  <https://github.com/zopefoundation/zope.interface/pull/215/>`_.
+
+5.1.1 (2020-09-30)
+==================
+
+- Fix the method definitions of ``IAdapterRegistry.subscribe``,
+  ``subscriptions`` and ``subscribers``. Previously, they all were
+  defined to accept a ``name`` keyword argument, but subscribers have
+  no names and the implementation of that interface did not accept
+  that argument. See `issue 208
+  <https://github.com/zopefoundation/zope.interface/issues/208>`_.
+
+- Fix a potential reference leak in the C optimizations. Previously,
+  applications that dynamically created unique ``Specification``
+  objects (e.g., used ``@implementer`` on dynamic classes) could
+  notice a growth of small objects over time leading to increased
+  garbage collection times. See `issue 216
+  <https://github.com/zopefoundation/zope.interface/issues/216>`_.
+
+  .. caution::
+
+     This leak could prevent interfaces used as the bases of
+     other interfaces from being garbage collected. Those interfaces
+     will now be collected.
+
+     One way in which this would manifest was that ``weakref.ref``
+     objects (and things built upon them, like
+     ``WeakKey|ValueDictionary``) would continue to have access to
+     the original object even if there were no other visible
+     references to Python and the original object *should* have been
+     collected. This could be especially problematic for the
+     ``WeakKeyDictionary`` when combined with dynamic or local
+     (created in the scope of a function) interfaces, since interfaces
+     are hashed based just on their name and module name. See the
+     linked issue for an example of a resulting ``KeyError``.
+
+     Note that such potential errors are not new, they are just once
+     again a possibility.
+
+5.1.0 (2020-04-08)
+==================
+
+- Make ``@implementer(*iface)`` and ``classImplements(cls, *iface)``
+  ignore redundant interfaces. If the class already implements an
+  interface through inheritance, it is no longer redeclared
+  specifically for *cls*. This solves many instances of inconsistent
+  resolution orders, while still allowing the interface to be declared
+  for readability and maintenance purposes. See `issue 199
+  <https://github.com/zopefoundation/zope.interface/issues/199>`_.
+
+- Remove all bare ``except:`` statements. Previously, when accessing
+  special attributes such as ``__provides__``, ``__providedBy__``,
+  ``__class__`` and ``__conform__``, this package wrapped such access
+  in a bare ``except:`` statement, meaning that many errors could pass
+  silently; typically this would result in a fallback path being taken
+  and sometimes (like with ``providedBy()``) the result would be
+  non-sensical. This is especially true when those attributes are
+  implemented with descriptors. Now, only ``AttributeError`` is
+  caught. This makes errors more obvious.
+
+  Obviously, this means that some exceptions will be propagated
+  differently than before. In particular, ``RuntimeError`` raised by
+  Acquisition in the case of circular containment will now be
+  propagated. Previously, when adapting such a broken object, a
+  ``TypeError`` would be the common result, but now it will be a more
+  informative ``RuntimeError``.
+
+  In addition, ZODB errors like ``POSKeyError`` could now be
+  propagated where previously they would ignored by this package.
+
+  See `issue 200 <https://github.com/zopefoundation/zope.interface/issues/200>`_.
+
+- Require that the second argument (*bases*) to ``InterfaceClass`` is
+  a tuple. This only matters when directly using ``InterfaceClass`` to
+  create new interfaces dynamically. Previously, an individual
+  interface was allowed, but did not work correctly. Now it is
+  consistent with ``type`` and requires a tuple.
+
+- Let interfaces define custom ``__adapt__`` methods. This implements
+  the other side of the :pep:`246` adaptation protocol: objects being
+  adapted could already implement ``__conform__`` if they know about
+  the interface, and now interfaces can implement ``__adapt__`` if
+  they know about particular objects. There is no performance penalty
+  for interfaces that do not supply custom ``__adapt__`` methods.
+
+  This includes the ability to add new methods, or override existing
+  interface methods using the new ``@interfacemethod`` decorator.
+
+  See `issue 3 <https://github.com/zopefoundation/zope.interface/issues/3>`_.
+
+- Make the internal singleton object returned by APIs like
+  ``implementedBy`` and ``directlyProvidedBy`` for objects that
+  implement or provide no interfaces more immutable. Previously an
+  internal cache could be mutated. See `issue 204
+  <https://github.com/zopefoundation/zope.interface/issues/204>`_.
+
+5.0.2 (2020-03-30)
+==================
+
+- Ensure that objects that implement no interfaces (such as direct
+  subclasses of ``object``) still include ``Interface`` itself in
+  their ``__iro___`` and ``__sro___``. This fixes adapter registry
+  lookups for such objects when the adapter is registered for
+  ``Interface``. See `issue 197
+  <https://github.com/zopefoundation/zope.interface/issues/197>`_.
+
+
+5.0.1 (2020-03-21)
+==================
+
+- Ensure the resolution order for ``InterfaceClass`` is consistent.
+  See `issue 192 <https://github.com/zopefoundation/zope.interface/issues/192>`_.
+
+- Ensure the resolution order for ``collections.OrderedDict`` is
+  consistent on CPython 2. (It was already consistent on Python 3 and PyPy).
+
+- Fix the handling of the ``ZOPE_INTERFACE_STRICT_IRO`` environment
+  variable. Previously, ``ZOPE_INTERFACE_STRICT_RO`` was read, in
+  contrast with the documentation. See `issue 194
+  <https://github.com/zopefoundation/zope.interface/issues/194>`_.
+
+
+5.0.0 (2020-03-19)
+==================
+
+- Make an internal singleton object returned by APIs like
+  ``implementedBy`` and ``directlyProvidedBy`` immutable. Previously,
+  it was fully mutable and allowed changing its ``__bases___``. That
+  could potentially lead to wrong results in pathological corner
+  cases. See `issue 158
+  <https://github.com/zopefoundation/zope.interface/issues/158>`_.
+
+- Support the ``PURE_PYTHON`` environment variable at runtime instead
+  of just at wheel build time. A value of 0 forces the C extensions to
+  be used (even on PyPy) failing if they aren't present. Any other
+  value forces the Python implementation to be used, ignoring the C
+  extensions. See `PR 151 <https://github.com/zopefoundation/zope.interface/pull/151>`_.
+
+- Cache the result of ``__hash__`` method in ``InterfaceClass`` as a
+  speed optimization. The method is called very often (i.e several
+  hundred thousand times during Plone 5.2 startup). Because the hash value never
+  changes it can be cached. This improves test performance from 0.614s
+  down to 0.575s (1.07x faster). In a real world Plone case a reindex
+  index came down from 402s to 320s (1.26x faster). See `PR 156
+  <https://github.com/zopefoundation/zope.interface/pull/156>`_.
+
+- Change the C classes ``SpecificationBase`` and its subclass
+  ``ClassProvidesBase`` to store implementation attributes in their structures
+  instead of their instance dictionaries. This eliminates the use of
+  an undocumented private C API function, and helps make some
+  instances require less memory. See `PR 154 <https://github.com/zopefoundation/zope.interface/pull/154>`_.
+
+- Reduce memory usage in other ways based on observations of usage
+  patterns in Zope (3) and Plone code bases.
+
+  - Specifications with no dependents are common (more than 50%) so
+    avoid allocating a ``WeakKeyDictionary`` unless we need it.
+  - Likewise, tagged values are relatively rare, so don't allocate a
+    dictionary to hold them until they are used.
+  - Use ``__slots___`` or the C equivalent ``tp_members`` in more
+    common places. Note that this removes the ability to set arbitrary
+    instance variables on certain objects.
+    See `PR 155 <https://github.com/zopefoundation/zope.interface/pull/155>`_.
+
+  The changes in this release resulted in a 7% memory reduction after
+  loading about 6,000 modules that define about 2,200 interfaces.
+
+  .. caution::
+
+     Details of many private attributes have changed, and external use
+     of those private attributes may break. In particular, the
+     lifetime and default value of ``_v_attrs`` has changed.
+
+- Remove support for hashing uninitialized interfaces. This could only
+  be done by subclassing ``InterfaceClass``. This has generated a
+  warning since it was first added in 2011 (3.6.5). Please call the
+  ``InterfaceClass`` constructor or otherwise set the appropriate
+  fields in your subclass before attempting to hash or sort it. See
+  `issue 157 <https://github.com/zopefoundation/zope.interface/issues/157>`_.
+
+- Remove unneeded override of the ``__hash__`` method from
+  ``zope.interface.declarations.Implements``. Watching a reindex index
+  process in ZCatalog with on a Py-Spy after 10k samples the time for
+  ``.adapter._lookup`` was reduced from 27.5s to 18.8s (~1.5x faster).
+  Overall reindex index time shrunk from 369s to 293s (1.26x faster).
+  See `PR 161
+  <https://github.com/zopefoundation/zope.interface/pull/161>`_.
+
+- Make the Python implementation closer to the C implementation by
+  ignoring all exceptions, not just ``AttributeError``, during (parts
+  of) interface adaptation. See `issue 163
+  <https://github.com/zopefoundation/zope.interface/issues/163>`_.
+
+- Micro-optimization in ``.adapter._lookup`` , ``.adapter._lookupAll``
+  and ``.adapter._subscriptions``: By loading ``components.get`` into
+  a local variable before entering the loop a bytcode "LOAD_FAST 0
+  (components)" in the loop can be eliminated. In Plone, while running
+  all tests, average speedup of the "owntime" of ``_lookup`` is ~5x.
+  See `PR 167
+  <https://github.com/zopefoundation/zope.interface/pull/167>`_.
+
+- Add ``__all__`` declarations to all modules. This helps tools that
+  do auto-completion and documentation and results in less cluttered
+  results. Wildcard ("*") are not recommended and may be affected. See
+  `issue 153
+  <https://github.com/zopefoundation/zope.interface/issues/153>`_.
+
+- Fix ``verifyClass`` and ``verifyObject`` for builtin types like
+  ``dict`` that have methods taking an optional, unnamed argument with
+  no default value like ``dict.pop``. On PyPy3, the verification is
+  strict, but on PyPy2 (as on all versions of CPython) those methods
+  cannot be verified and are ignored. See `issue 118
+  <https://github.com/zopefoundation/zope.interface/issues/118>`_.
+
+- Update the common interfaces ``IEnumerableMapping``,
+  ``IExtendedReadMapping``, ``IExtendedWriteMapping``,
+  ``IReadSequence`` and ``IUniqueMemberWriteSequence`` to no longer
+  require methods that were removed from Python 3 on Python 3, such as
+  ``__setslice___``. Now, ``dict``, ``list`` and ``tuple`` properly
+  verify as ``IFullMapping``, ``ISequence`` and ``IReadSequence,``
+  respectively on all versions of Python.
+
+- Add human-readable ``__str___`` and ``__repr___`` to ``Attribute``
+  and ``Method``. These contain the name of the defining interface
+  and the attribute. For methods, it also includes the signature.
+
+- Change the error strings raised by ``verifyObject`` and
+  ``verifyClass``. They now include more human-readable information
+  and exclude extraneous lines and spaces. See `issue 170
+  <https://github.com/zopefoundation/zope.interface/issues/170>`_.
+
+  .. caution:: This will break consumers (such as doctests) that
+               depended on the exact error messages.
+
+- Make ``verifyObject`` and ``verifyClass`` report all errors, if the
+  candidate object has multiple detectable violations. Previously they
+  reported only the first error. See `issue
+  <https://github.com/zopefoundation/zope.interface/issues/171>`_.
+
+  Like the above, this will break consumers depending on the exact
+  output of error messages if more than one error is present.
+
+- Add ``zope.interface.common.collections``,
+  ``zope.interface.common.numbers``, and ``zope.interface.common.io``.
+  These modules define interfaces based on the ABCs defined in the
+  standard library ``collections.abc``, ``numbers`` and ``io``
+  modules, respectively. Importing these modules will make the
+  standard library concrete classes that are registered with those
+  ABCs declare the appropriate interface. See `issue 138
+  <https://github.com/zopefoundation/zope.interface/issues/138>`_.
+
+- Add ``zope.interface.common.builtins``. This module defines
+  interfaces of common builtin types, such as ``ITextString`` and
+  ``IByteString``, ``IDict``, etc. These interfaces extend the
+  appropriate interfaces from ``collections`` and ``numbers``, and the
+  standard library classes implement them after importing this module.
+  This is intended as a replacement for third-party packages like
+  `dolmen.builtins <https://pypi.org/project/dolmen.builtins/>`_.
+  See `issue 138 <https://github.com/zopefoundation/zope.interface/issues/138>`_.
+
+- Make ``providedBy()`` and ``implementedBy()`` respect ``super``
+  objects. For instance, if class ``Derived`` implements ``IDerived``
+  and extends ``Base`` which in turn implements ``IBase``, then
+  ``providedBy(super(Derived, derived))`` will return ``IBase``.
+  Previously it would have returned ``IDerived`` (in general, it
+  would previously have returned whatever would have been returned
+  without ``super``).
+
+  Along with this change, adapter registries will unpack ``super``
+  objects into their ``__self___`` before passing it to the factory.
+  Together, this means that ``component.getAdapter(super(Derived,
+  self), ITarget)`` is now meaningful.
+
+  See `issue 11 <https://github.com/zopefoundation/zope.interface/issues/11>`_.
+
+- Fix a potential interpreter crash in the low-level adapter
+  registry lookup functions. See issue 11.
+
+- Adopt Python's standard `C3 resolution order
+  <https://www.python.org/download/releases/2.3/mro/>`_ to compute the
+  ``__iro__`` and ``__sro__`` of interfaces, with tweaks to support
+  additional cases that are common in interfaces but disallowed for
+  Python classes. Previously, an ad-hoc ordering that made no
+  particular guarantees was used.
+
+  This has many beneficial properties, including the fact that base
+  interface and base classes tend to appear near the end of the
+  resolution order instead of the beginning. The resolution order in
+  general should be more predictable and consistent.
+
+  .. caution::
+     In some cases, especially with complex interface inheritance
+     trees or when manually providing or implementing interfaces, the
+     resulting IRO may be quite different. This may affect adapter
+     lookup.
+
+  The C3 order enforces some constraints in order to be able to
+  guarantee a sensible ordering. Older versions of zope.interface did
+  not impose similar constraints, so it was possible to create
+  interfaces and declarations that are inconsistent with the C3
+  constraints. In that event, zope.interface will still produce a
+  resolution order equal to the old order, but it won't be guaranteed
+  to be fully C3 compliant. In the future, strict enforcement of C3
+  order may be the default.
+
+  A set of environment variables and module constants allows
+  controlling several aspects of this new behaviour. It is possible to
+  request warnings about inconsistent resolution orders encountered,
+  and even to forbid them. Differences between the C3 resolution order
+  and the previous order can be logged, and, in extreme cases, the
+  previous order can still be used (this ability will be removed in
+  the future). For details, see the documentation for
+  ``zope.interface.ro``.
+
+- Make inherited tagged values in interfaces respect the resolution
+  order (``__iro__``), as method and attribute lookup does. Previously
+  tagged values could give inconsistent results. See `issue 190
+  <https://github.com/zopefoundation/zope.interface/issues/190>`_.
+
+- Add ``getDirectTaggedValue`` (and related methods) to interfaces to
+  allow accessing tagged values irrespective of inheritance. See
+  `issue 190
+  <https://github.com/zopefoundation/zope.interface/issues/190>`_.
+
+- Ensure that ``Interface`` is always the last item in the ``__iro__``
+  and ``__sro__``. This is usually the case, but if classes that do
+  not implement any interfaces are part of a class inheritance
+  hierarchy, ``Interface`` could be assigned too high a priority.
+  See `issue 8 <https://github.com/zopefoundation/zope.interface/issues/8>`_.
+
+- Implement sorting, equality, and hashing in C for ``Interface``
+  objects. In micro benchmarks, this makes those operations 40% to 80%
+  faster. This translates to a 20% speed up in querying adapters.
+
+  Note that this changes certain implementation details. In
+  particular, ``InterfaceClass`` now has a non-default metaclass, and
+  it is enforced that ``__module__`` in instances of
+  ``InterfaceClass`` is read-only.
+
+  See `PR 183 <https://github.com/zopefoundation/zope.interface/pull/183>`_.
+
+
+4.7.2 (2020-03-10)
+==================
+
+- Remove deprecated use of setuptools features.  See `issue 30
+  <https://github.com/zopefoundation/zope.interface/issues/30>`_.
+
+
+4.7.1 (2019-11-11)
+==================
+
+- Use Python 3 syntax in the documentation.  See `issue 119
+  <https://github.com/zopefoundation/zope.interface/issues/119>`_.
+
+
+4.7.0 (2019-11-11)
+==================
+
+- Drop support for Python 3.4.
+
+- Change ``queryTaggedValue``, ``getTaggedValue``,
+  ``getTaggedValueTags`` in interfaces. They now include inherited
+  values by following ``__bases__``. See `PR 144
+  <https://github.com/zopefoundation/zope.interface/pull/144>`_.
+
+  .. caution:: This may be a breaking change.
+
+- Add support for Python 3.8.
+
+
+4.6.0 (2018-10-23)
+==================
+
+- Add support for Python 3.7
+
+- Fix ``verifyObject`` for class objects with staticmethods on
+  Python 3. See `issue 126
+  <https://github.com/zopefoundation/zope.interface/issues/126>`_.
+
+
+4.5.0 (2018-04-19)
+==================
+
+- Drop support for 3.3, avoid accidental dependence breakage via setup.py.
+  See `PR 110 <https://github.com/zopefoundation/zope.interface/pull/110>`_.
+- Allow registering and unregistering instance methods as listeners.
+  See `issue 12 <https://github.com/zopefoundation/zope.interface/issues/12>`_
+  and `PR 102 <https://github.com/zopefoundation/zope.interface/pull/102>`_.
+- Synchronize and simplify zope/__init__.py. See `issue 114
+  <https://github.com/zopefoundation/zope.interface/issues/114>`_
+
+
+4.4.3 (2017-09-22)
+==================
+
+- Avoid exceptions when the ``__annotations__`` attribute is added to
+  interface definitions with Python 3.x type hints. See `issue 98
+  <https://github.com/zopefoundation/zope.interface/issues/98>`_.
+- Fix the possibility of a rare crash in the C extension when
+  deallocating items. See `issue 100
+  <https://github.com/zopefoundation/zope.interface/issues/100>`_.
+
+
+4.4.2 (2017-06-14)
+==================
+
+- Fix a regression storing
+  ``zope.component.persistentregistry.PersistentRegistry`` instances.
+  See `issue 85 <https://github.com/zopefoundation/zope.interface/issues/85>`_.
+
+- Fix a regression that could lead to the utility registration cache
+  of ``Components`` getting out of sync. See `issue 93
+  <https://github.com/zopefoundation/zope.interface/issues/93>`_.
+
+4.4.1 (2017-05-13)
+==================
+
+- Simplify the caching of utility-registration data. In addition to
+  simplification, avoids spurious test failures when checking for
+  leaks in tests with persistent registries. See `pull 84
+  <https://github.com/zopefoundation/zope.interface/pull/84>`_.
+
+- Raise ``ValueError`` when non-text names are passed to adapter registry
+  methods:  prevents corruption of lookup caches.
+
+4.4.0 (2017-04-21)
+==================
+
+- Avoid a warning from the C compiler.
+  (https://github.com/zopefoundation/zope.interface/issues/71)
+
+- Add support for Python 3.6.
+
+4.3.3 (2016-12-13)
+==================
+
+- Correct typos and ReST formatting errors in documentation.
+
+- Add API documentation for the adapter registry.
+
+- Ensure that the ``LICENSE.txt`` file is included in built wheels.
+
+- Fix C optimizations broken on Py3k.  See the Python bug at:
+  http://bugs.python.org/issue15657
+  (https://github.com/zopefoundation/zope.interface/issues/60)
+
+
+4.3.2 (2016-09-05)
+==================
+
+- Fix equality testing of ``implementedBy`` objects and proxies.
+  (https://github.com/zopefoundation/zope.interface/issues/55)
+
+
+4.3.1 (2016-08-31)
+==================
+
+- Support Components subclasses that are not hashable.
+  (https://github.com/zopefoundation/zope.interface/issues/53)
+
+
+4.3.0 (2016-08-31)
+==================
+
+- Add the ability to sort the objects returned by ``implementedBy``.
+  This is compatible with the way interface classes sort so they can
+  be used together in ordered containers like BTrees.
+  (https://github.com/zopefoundation/zope.interface/issues/42)
+
+- Make ``setuptools`` a hard dependency of ``setup.py``.
+  (https://github.com/zopefoundation/zope.interface/issues/13)
+
+- Change a linear algorithm (O(n)) in ``Components.registerUtility`` and
+  ``Components.unregisterUtility`` into a dictionary lookup (O(1)) for
+  hashable components. This substantially improves the time taken to
+  manipulate utilities in large registries at the cost of some
+  additional memory usage. (https://github.com/zopefoundation/zope.interface/issues/46)
+
+
+4.2.0 (2016-06-10)
+==================
+
+- Add support for Python 3.5
+
+- Drop support for Python 2.6 and 3.2.
+
+
+4.1.3 (2015-10-05)
+==================
+
+- Fix installation without a C compiler on Python 3.5
+  (https://github.com/zopefoundation/zope.interface/issues/24).
+
+
+4.1.2 (2014-12-27)
+==================
+
+- Add support for PyPy3.
+
+- Remove unittest assertions deprecated in Python3.x.
+
+- Add ``zope.interface.document.asReStructuredText``, which formats the
+  generated text for an interface using ReST double-backtick markers.
+
+
+4.1.1 (2014-03-19)
+==================
+
+- Add support for Python 3.4.
+
+
+4.1.0 (2014-02-05)
+==================
+
+- Update ``boostrap.py`` to version 2.2.
+
+- Add ``@named(name)`` declaration, that specifies the component name, so it
+  does not have to be passed in during registration.
+
+
+4.0.5 (2013-02-28)
+==================
+
+- Fix a bug where a decorated method caused false positive failures on
+  ``verifyClass()``.
+
+
+4.0.4 (2013-02-21)
+==================
+
+- Fix a bug that was revealed by porting zope.traversing. During a loop, the
+  loop body modified a weakref dict causing a ``RuntimeError`` error.
+
+4.0.3 (2012-12-31)
+==================
+
+- Fleshed out PyPI Trove classifiers.
+
+4.0.2 (2012-11-21)
+==================
+
+- Add support for Python 3.3.
+
+- Restored ability to install the package in the absence of ``setuptools``.
+
+- LP #1055223:  Fix test which depended on dictionary order and failed randomly
+  in Python 3.3.
+
+4.0.1 (2012-05-22)
+==================
+
+- Drop explicit ``DeprecationWarnings`` for "class advice" APIS (these
+  APIs are still deprecated under Python 2.x, and still raise an exception
+  under Python 3.x, but no longer cause a warning to be emitted under
+  Python 2.x).
+
+4.0.0 (2012-05-16)
+==================
+
+- Automated build of Sphinx HTML docs and running doctest snippets via tox.
+
+- Deprecate the "class advice" APIs from ``zope.interface.declarations``:
+  ``implements``, ``implementsOnly``, and ``classProvides``.  In their place,
+  prefer the equivalent class decorators: ``@implementer``,
+  ``@implementer_only``, and ``@provider``.  Code which uses the deprecated
+  APIs will not work as expected under Py3k.
+
+- Remove use of '2to3' and associated fixers when installing under Py3k.
+  The code is now in a "compatible subset" which supports Python 2.6, 2.7,
+  and 3.2, including PyPy 1.8 (the version compatible with the 2.7 language
+  spec).
+
+- Drop explicit support for Python 2.4 / 2.5 / 3.1.
+
+- Add support for PyPy.
+
+- Add support for continuous integration using ``tox`` and ``jenkins``.
+
+- Add 'setup.py dev' alias (runs ``setup.py develop`` plus installs
+  ``nose`` and ``coverage``).
+
+- Add 'setup.py docs' alias (installs ``Sphinx`` and dependencies).
+
+- Replace all unittest coverage previously accomplished via doctests with
+  unittests.  The doctests have been moved into a ``docs`` section, managed
+  as a Sphinx collection.
+
+- LP #910987:  Ensure that the semantics of the ``lookup`` method of
+  ``zope.interface.adapter.LookupBase`` are the same in both the C and
+  Python implementations.
+
+- LP #900906:  Avoid exceptions due to tne new ``__qualname__`` attribute
+  added in Python 3.3 (see PEP 3155 for rationale).  Thanks to Antoine
+  Pitrou for the patch.
+
+3.8.0 (2011-09-22)
+==================
+
+- New module ``zope.interface.registry``.  This is code moved from
+  ``zope.component.registry`` which implements a basic nonperistent component
+  registry as ``zope.interface.registry.Components``.  This class was moved
+  from ``zope.component`` to make porting systems (such as Pyramid) that rely
+  only on a basic component registry to Python 3 possible without needing to
+  port the entirety of the ``zope.component`` package.  Backwards
+  compatibility import shims have been left behind in ``zope.component``, so
+  this change will not break any existing code.
+
+- New ``tests_require`` dependency: ``zope.event`` to test events sent by
+  Components implementation.  The ``zope.interface`` package does not have a
+  hard dependency on ``zope.event``, but if ``zope.event`` is importable, it
+  will send component registration events when methods of an instance of
+  ``zope.interface.registry.Components`` are called.
+
+- New interfaces added to support ``zope.interface.registry.Components``
+  addition: ``ComponentLookupError``, ``Invalid``, ``IObjectEvent``,
+  ``ObjectEvent``, ``IComponentLookup``, ``IRegistration``,
+  ``IUtilityRegistration``, ``IAdapterRegistration``,
+  ``ISubscriptionAdapterRegistration``, ``IHandlerRegistration``,
+  ``IRegistrationEvent``, ``RegistrationEvent``, ``IRegistered``,
+  ``Registered``, ``IUnregistered``, ``Unregistered``,
+  ``IComponentRegistry``, and ``IComponents``.
+
+- No longer Python 2.4 compatible (tested under 2.5, 2.6, 2.7, and 3.2).
+
+3.7.0 (2011-08-13)
+==================
+
+- Move changes from 3.6.2 - 3.6.5 to a new 3.7.x release line.
+
+3.6.7 (2011-08-20)
+==================
+
+- Fix sporadic failures on x86-64 platforms in tests of rich comparisons
+  of interfaces.
+
+3.6.6 (2011-08-13)
+==================
+
+- LP #570942:  Now correctly compare interfaces  from different modules but
+  with the same names.
+
+  N.B.: This is a less intrusive / destabilizing fix than the one applied in
+  3.6.3:  we only fix the underlying cmp-alike function, rather than adding
+  the other "rich comparison" functions.
+
+- Revert to software as released with 3.6.1 for "stable" 3.6 release branch.
+
+3.6.5 (2011-08-11)
+==================
+
+- LP #811792:  work around buggy behavior in some subclasses of
+  ``zope.interface.interface.InterfaceClass``, which invoke ``__hash__``
+  before initializing ``__module__`` and ``__name__``.  The workaround
+  returns a fixed constant hash in such cases, and issues a ``UserWarning``.
+
+- LP #804832:  Under PyPy, ``zope.interface`` should not build its C
+  extension.  Also, prevent attempting to build it under Jython.
+
+- Add a tox.ini for easier xplatform testing.
+
+- Fix testing deprecation warnings issued when tested under Py3K.
+
+3.6.4 (2011-07-04)
+==================
+
+- LP 804951:  InterfaceClass instances were unhashable under Python 3.x.
+
+3.6.3 (2011-05-26)
+==================
+
+- LP #570942:  Now correctly compare interfaces  from different modules but
+  with the same names.
+
+3.6.2 (2011-05-17)
+==================
+
+- Moved detailed documentation out-of-line from PyPI page, linking instead to
+  http://docs.zope.org/zope.interface .
+
+- Fixes for small issues when running tests under Python 3.2 using
+  ``zope.testrunner``.
+
+- LP # 675064:  Specify return value type for C optimizations module init
+  under Python 3:  undeclared value caused warnings, and segfaults on some
+  64 bit architectures.
+
+- setup.py now raises RuntimeError if you don't have Distutils installed when
+  running under Python 3.
+
+3.6.1 (2010-05-03)
+==================
+
+- A non-ASCII character in the changelog made 3.6.0 uninstallable on
+  Python 3 systems with another default encoding than UTF-8.
+
+- Fix compiler warnings under GCC 4.3.3.
+
+3.6.0 (2010-04-29)
+==================
+
+- LP #185974:  Clear the cache used by ``Specificaton.get`` inside
+  ``Specification.changed``.  Thanks to Jacob Holm for the patch.
+
+- Add support for Python 3.1. Contributors:
+
+    Lennart Regebro
+    Martin v Loewis
+    Thomas Lotze
+    Wolfgang Schnerring
+
+  The 3.1 support is completely backwards compatible. However, the implements
+  syntax used under Python 2.X does not work under 3.X, since it depends on
+  how metaclasses are implemented and this has changed. Instead it now supports
+  a decorator syntax (also under Python 2.X)::
+
+    class Foo:
+        implements(IFoo)
+        ...
+
+  can now also be written::
+
+    @implementer(IFoo):
+    class Foo:
+        ...
+
+  There are 2to3 fixers available to do this change automatically in the
+  zope.fixers package.
+
+- Python 2.3 is no longer supported.
+
+
+3.5.4 (2009-12-23)
+==================
+
+- Use the standard Python doctest module instead of zope.testing.doctest, which
+  has been deprecated.
+
+
+3.5.3 (2009-12-08)
+==================
+
+- Fix an edge case: make providedBy() work when a class has '__provides__' in
+  its __slots__ (see http://thread.gmane.org/gmane.comp.web.zope.devel/22490)
+
+
+3.5.2 (2009-07-01)
+==================
+
+- BaseAdapterRegistry.unregister, unsubscribe: Remove empty portions of
+  the data structures when something is removed.  This avoids leaving
+  references to global objects (interfaces) that may be slated for
+  removal from the calling application.
+
+
+3.5.1 (2009-03-18)
+==================
+
+- verifyObject: use getattr instead of hasattr to test for object attributes
+  in order to let exceptions other than AttributeError raised by properties
+  propagate to the caller
+
+- Add Sphinx-based documentation building to the package buildout
+  configuration. Use the ``bin/docs`` command after buildout.
+
+- Improve package description a bit. Unify changelog entries formatting.
+
+- Change package's mailing list address to zope-dev at zope.org as
+  zope3-dev at zope.org is now retired.
+
+
+3.5.0 (2008-10-26)
+==================
+
+- Fix declaration of _zope_interface_coptimizations, it's not a top level
+  package.
+
+- Add a DocTestSuite for odd.py module, so their tests are run.
+
+- Allow to bootstrap on Jython.
+
+- Fix https://bugs.launchpad.net/zope3/3.3/+bug/98388: ISpecification
+  was missing a declaration for __iro__.
+
+- Add optional code optimizations support, which allows the building
+  of C code optimizations to fail (Jython).
+
+- Replace `_flatten` with a non-recursive implementation, effectively making
+  it 3x faster.
+
+
+3.4.1 (2007-10-02)
+==================
+
+- Fix a setup bug that prevented installation from source on systems
+  without setuptools.
+
+
+3.4.0 (2007-07-19)
+==================
+
+- Final release for 3.4.0.
+
+
+3.4.0b3 (2007-05-22)
+====================
+
+
+- When checking whether an object is already registered, use identity
+  comparison, to allow adding registering with picky custom comparison methods.
+
+
+3.3.0.1 (2007-01-03)
+====================
+
+- Made a reference to OverflowWarning, which disappeared in Python
+  2.5, conditional.
+
+
+3.3.0 (2007/01/03)
+==================
+
+New Features
+------------
+
+- Refactor the adapter-lookup algorithim to make it much simpler and faster.
+
+  Also, implement more of the adapter-lookup logic in C, making
+  debugging of application code easier, since there is less
+  infrastructre code to step through.
+
+- Treat objects without interface declarations as if they
+  declared that they provide ``zope.interface.Interface``.
+
+- Add a number of richer new adapter-registration interfaces
+  that provide greater control and introspection.
+
+- Add a new interface decorator to zope.interface that allows the
+  setting of tagged values on an interface at definition time (see
+  zope.interface.taggedValue).
+
+Bug Fixes
+---------
+
+- A bug in multi-adapter lookup sometimes caused incorrect adapters to
+  be returned.
+
+
+3.2.0.2 (2006-04-15)
+====================
+
+- Fix packaging bug:  'package_dir' must be a *relative* path.
+
+
+3.2.0.1 (2006-04-14)
+====================
+
+- Packaging change:  suppress inclusion of 'setup.cfg' in 'sdist' builds.
+
+
+3.2.0 (2006-01-05)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope 3.2.0 release.
+
+
+3.1.0 (2005-10-03)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope 3.1.0 release.
+
+- Made attribute resolution order consistent with component lookup order,
+  i.e. new-style class MRO semantics.
+
+- Deprecate 'isImplementedBy' and 'isImplementedByInstancesOf' APIs in
+  favor of 'implementedBy' and 'providedBy'.
+
+
+3.0.1 (2005-07-27)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope X3.0.1 release.
+
+- Fix a bug reported by James Knight, which caused adapter registries
+  to fail occasionally to reflect declaration changes.
+
+
+3.0.0 (2004-11-07)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope X3.0.0 release.

_service:tar_scm:zope.interface-5.5.2.tar.gz/appveyor.yml Added

@@ -0,0 +1,52 @@
+# Generated from:
+# https://github.com/zopefoundation/meta/tree/master/config/c-code
+environment:
+  # Currently the builds use @mgedmin's Appveyor account.  The PyPI token
+  # belongs to zope.wheelbuilder, which is managed by @mgedmin and @dataflake.
+  
+  global:
+    TWINE_USERNAME: __token__
+    TWINE_PASSWORD:
+      secure: aoZC/+rvJKg8B5GMGIxd1X2q2bz7SMl8G3810BID9U8PXFqM0FbWaK9fZ9qcU0UyG2xJsK56Fb6+L6g27I0Lg8UFNhlU1zLAuMSgJQbHsqawFgSY067IdJB68pp34d/oEyxMrJvAKENHH77Fe4KGDssLlk5WnnYS3DA9b66p5imP+1DTtkq5/gMtoG4nZTBtVos7J2kkYTQ5t4BjzTQxPMC3bStNnvuuB0orX4AoCyTrOR1wdZFiNKLzbVnrJCNn24t/n3kG9WrxbnKlrbOm4A==
+
+  matrix:
+    - python: 27-x64
+    - python: 35-x64
+    - python: 36-x64
+    - python: 37-x64
+    - python: 38-x64
+    - python: 39-x64
+    - python: 310-x64
+    - python: 311-x64
+
+install:
+  - "SET PYTHONVERSION=%PYTHON%"
+  - "SET PATH=C:\\Python%PYTHON%;c:\\Python%PYTHON%\\scripts;%PATH%"
+  - ps: |
+      $env:PYTHON = "C:\\Python${env:PYTHON}"
+      if (-not (Test-Path $env:PYTHON)) {
+        curl -o install_python.ps1 https://raw.githubusercontent.com/matthew-brett/multibuild/11a389d78892cf90addac8f69433d5e22bfa422a/install_python.ps1
+        .\install_python.ps1
+      }
+  - ps: if (-not (Test-Path $env:PYTHON)) { throw "No $env:PYTHON" }
+  - echo "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64 > "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\amd64\vcvars64.bat"
+  - python -m pip install -U pip
+  - pip install -U setuptools wheel
+  - pip install -U -e .test
+
+matrix:
+  fast_finish: true
+
+build_script:
+  - python -W ignore setup.py -q bdist_wheel
+
+test_script:
+  - python -m unittest discover -s src
+artifacts:
+  - path: 'dist\*.whl'
+    name: wheel
+
+deploy_script:
+  - ps: if ($env:APPVEYOR_REPO_TAG -eq $TRUE) { pip install twine; twine upload --skip-existing dist\*.whl }
+
+deploy: on

_service:tar_scm:zope.interface-5.5.2.tar.gz/benchmarks Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/benchmarks/micro.py Added

@@ -0,0 +1,348 @@
+import pyperf
+
+from zope.interface import Interface
+from zope.interface import classImplements
+from zope.interface import implementedBy
+from zope.interface.interface import InterfaceClass
+from zope.interface.registry import Components
+
+# Long, mostly similar names are a worst case for equality
+# comparisons.
+ifaces = 
+    InterfaceClass('I' + ('0' * 20) + str(i), (Interface,), {})
+    for i in range(100)
+
+
+class IWideInheritance(*ifaces):
+    """
+    Inherits from 100 unrelated interfaces.
+    """
+
+class WideInheritance(object):
+    pass
+classImplements(WideInheritance, IWideInheritance)
+
+def make_deep_inheritance():
+    children = 
+    base = Interface
+    for iface in ifaces:
+        child = InterfaceClass('IDerived' + base.__name__, (iface, base,), {})
+        base = child
+        children.append(child)
+    return children
+
+deep_ifaces = make_deep_inheritance()
+
+class DeepestInheritance(object):
+    pass
+classImplements(DeepestInheritance, deep_ifaces-1)
+
+
+class ImplementsNothing(object):
+    pass
+
+
+class HasConformReturnNone(object):
+    def __conform__(self, iface):
+        return None
+
+
+class HasConformReturnObject(object):
+    def __conform__(self, iface):
+        return self
+
+
+def make_implementer(iface):
+    c = type('Implementer' + iface.__name__, (object,), {})
+    classImplements(c, iface)
+    return c
+
+implementers = 
+    make_implementer(iface)
+    for iface in ifaces
+
+
+providers = 
+    implementer()
+    for implementer in implementers
+
+
+INNER = 100
+
+def bench_in(loops, o):
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            o.__contains__(Interface)
+
+    return pyperf.perf_counter() - t0
+
+def bench_sort(loops, objs):
+    import random
+    rand = random.Random(8675309)
+
+    shuffled = list(objs)
+    rand.shuffle(shuffled)
+
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            sorted(shuffled)
+
+    return pyperf.perf_counter() - t0
+
+def bench_query_adapter(loops, components, objs=providers):
+    components_queryAdapter = components.queryAdapter
+    # One time through to prime the caches
+    for iface in ifaces:
+        for provider in providers:
+            components_queryAdapter(provider, iface)
+
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for iface in ifaces:
+            for provider in objs:
+                components_queryAdapter(provider, iface)
+    return pyperf.perf_counter() - t0
+
+
+def bench_getattr(loops, name, get=getattr):
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            get(Interface, name) # 1
+            get(Interface, name) # 2
+            get(Interface, name) # 3
+            get(Interface, name) # 4
+            get(Interface, name) # 5
+            get(Interface, name) # 6
+            get(Interface, name) # 7
+            get(Interface, name) # 8
+            get(Interface, name) # 9
+            get(Interface, name) # 10
+    return pyperf.perf_counter() - t0
+
+
+def bench_iface_call_no_conform_no_alternate_not_provided(loops):
+    inst = ImplementsNothing()
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            for iface in ifaces:
+                try:
+                    iface(inst)
+                except TypeError:
+                    pass
+                else:
+                    raise TypeError("Should have failed")
+    return pyperf.perf_counter() - t0
+
+
+def bench_iface_call_no_conform_w_alternate_not_provided(loops):
+    inst = ImplementsNothing()
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            for iface in ifaces:
+                iface(inst, 42)
+    return pyperf.perf_counter() - t0
+
+
+def bench_iface_call_w_conform_return_none_not_provided(loops):
+    inst = HasConformReturnNone()
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            for iface in ifaces:
+                iface(inst, 42)
+    return pyperf.perf_counter() - t0
+
+
+def bench_iface_call_w_conform_return_non_none_not_provided(loops):
+    inst = HasConformReturnObject()
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            for iface in ifaces:
+                iface(inst)
+    return pyperf.perf_counter() - t0
+
+def _bench_iface_call_simple(loops, inst):
+    t0 = pyperf.perf_counter()
+    for _ in range(loops):
+        for _ in range(INNER):
+            for iface in ifaces:
+                iface(inst)
+    return pyperf.perf_counter() - t0
+
+
+def bench_iface_call_no_conform_provided_wide(loops):
+    return _bench_iface_call_simple(loops, WideInheritance())
+
+
+def bench_iface_call_no_conform_provided_deep(loops):
+    return _bench_iface_call_simple(loops, DeepestInheritance())
+
+
+runner = pyperf.Runner()
+
+runner.bench_time_func(
+    'call interface (provides; deep)',
+    bench_iface_call_no_conform_provided_deep,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'call interface (provides; wide)',
+    bench_iface_call_no_conform_provided_wide,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'call interface (no alternate, no conform, not provided)',
+    bench_iface_call_no_conform_no_alternate_not_provided,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'call interface (alternate, no conform, not provided)',
+    bench_iface_call_no_conform_w_alternate_not_provided,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'call interface (no alternate, valid conform, not provided)',
+    bench_iface_call_w_conform_return_non_none_not_provided,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'call interface (alternate, invalid conform, not provided)',
+    bench_iface_call_w_conform_return_none_not_provided,
+    inner_loops=INNER * len(ifaces)
+)
+
+runner.bench_time_func(
+    'read __module__', # stored in C, accessed through __getattribute__
+    bench_getattr,
+    '__module__',
+    inner_loops=INNER * 10
+)
+
+runner.bench_time_func(
+    'read __name__', # stored in C, accessed through PyMemberDef
+    bench_getattr,
+    '__name__',
+    inner_loops=INNER * 10
+)
+
+runner.bench_time_func(
+    'read __doc__', # stored in Python instance dictionary directly
+    bench_getattr,
+    '__doc__',
+    inner_loops=INNER * 10
+)
+
+runner.bench_time_func(
+    'read providedBy', # from the class, wrapped into a method object.
+    bench_getattr,
+    'providedBy',
+    inner_loops=INNER * 10
+)
+
+runner.bench_time_func(
+    'query adapter (no registrations)',
+    bench_query_adapter,
+    Components(),
+    inner_loops=1
+)
+
+def populate_components():
+    def factory(o):
+        return 42
+
+    pop_components = Components()
+    for iface in ifaces:
+        for other_iface in ifaces:
+            pop_components.registerAdapter(factory, (iface,), other_iface, event=False)
+
+    return pop_components
+
+runner.bench_time_func(
+    'query adapter (all trivial registrations)',
+    bench_query_adapter,
+    populate_components(),
+    inner_loops=1
+)
+
+runner.bench_time_func(
+    'query adapter (all trivial registrations, wide inheritance)',
+    bench_query_adapter,
+    populate_components(),
+    WideInheritance(),
+    inner_loops=1
+)
+
+runner.bench_time_func(
+    'query adapter (all trivial registrations, deep inheritance)',
+    bench_query_adapter,
+    populate_components(),
+    DeepestInheritance(),
+    inner_loops=1
+)
+
+runner.bench_time_func(
+    'sort interfaces',
+    bench_sort,
+    ifaces,
+    inner_loops=INNER,
+)
+
+runner.bench_time_func(
+    'sort implementedBy',
+    bench_sort,
+    implementedBy(p) for p in implementers,
+    inner_loops=INNER,
+)
+
+runner.bench_time_func(
+    'sort mixed',
+    bench_sort,
+    implementedBy(p) for p in implementers + ifaces,
+    inner_loops=INNER,
+)
+
+runner.bench_time_func(
+    'contains (empty dict)',
+    bench_in,
+    {},
+    inner_loops=INNER
+)
+
+runner.bench_time_func(
+    'contains (populated dict: interfaces)',
+    bench_in,
+    {k: k for k in ifaces},
+    inner_loops=INNER
+)
+
+runner.bench_time_func(
+    'contains (populated list: interfaces)',
+    bench_in,
+    ifaces,
+    inner_loops=INNER
+)
+
+runner.bench_time_func(
+    'contains (populated dict: implementedBy)',
+    bench_in,
+    {implementedBy(p): 1 for p in implementers},
+    inner_loops=INNER
+)
+
+runner.bench_time_func(
+    'contains (populated list: implementedBy)',
+    bench_in,
+    implementedBy(p) for p in implementers,
+    inner_loops=INNER
+)

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/doctest Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/doctest/output.txt Added

@@ -0,0 +1,65 @@
+Results of doctest builder run on 2022-11-03 13:55:30
+=====================================================
+
+Document: api/specifications
+----------------------------
+1 items passed all tests:
+ 109 tests in default
+109 tests in 1 items.
+109 passed and 0 failed.
+Test passed.
+
+Document: verify
+----------------
+1 items passed all tests:
+  78 tests in default
+78 tests in 1 items.
+78 passed and 0 failed.
+Test passed.
+
+Document: human
+---------------
+1 items passed all tests:
+  18 tests in default
+18 tests in 1 items.
+18 passed and 0 failed.
+Test passed.
+
+Document: api/declarations
+--------------------------
+1 items passed all tests:
+ 302 tests in default
+302 tests in 1 items.
+302 passed and 0 failed.
+Test passed.
+
+Document: adapter
+-----------------
+1 items passed all tests:
+ 164 tests in default
+164 tests in 1 items.
+164 passed and 0 failed.
+Test passed.
+
+Document: README
+----------------
+1 items passed all tests:
+ 218 tests in default
+218 tests in 1 items.
+218 passed and 0 failed.
+Test passed.
+
+Document: foodforthought
+------------------------
+1 items passed all tests:
+  25 tests in default
+25 tests in 1 items.
+25 passed and 0 failed.
+Test passed.
+
+Doctest summary
+===============
+  914 tests
+    0 failures in tests
+    0 failures in setup code
+    0 failures in cleanup code

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/README.rst.txt Added

@@ -0,0 +1,1357 @@
+============
+ Interfaces
+============
+
+.. currentmodule:: zope.interface
+
+Interfaces are objects that specify (document) the external behavior
+of objects that "provide" them.  An interface specifies behavior
+through:
+
+- Informal documentation in a doc string
+
+- Attribute definitions
+
+- Invariants, which are conditions that must hold for objects that
+  provide the interface
+
+Attribute definitions specify specific attributes. They define the
+attribute name and provide documentation and constraints of attribute
+values.  Attribute definitions can take a number of forms, as we'll
+see below.
+
+Defining interfaces
+===================
+
+Interfaces are defined using Python ``class`` statements:
+
+.. doctest::
+
+  >>> import zope.interface
+  >>> class IFoo(zope.interface.Interface):
+  ...    """Foo blah blah"""
+  ...
+  ...    x = zope.interface.Attribute("""X blah blah""")
+  ...
+  ...    def bar(q, r=None):
+  ...        """bar blah blah"""
+
+In the example above, we've created an interface, :class:`IFoo`.  We
+subclassed :class:`zope.interface.Interface`, which is an ancestor interface for
+all interfaces, much as ``object`` is an ancestor of all new-style
+classes #create_.   The interface is not a class, it's an Interface,
+an instance of :class:`zope.interface.interface.InterfaceClass`:
+
+.. doctest::
+
+  >>> type(IFoo)
+  <class 'zope.interface.interface.InterfaceClass'>
+
+We can ask for the interface's documentation:
+
+.. doctest::
+
+  >>> IFoo.__doc__
+  'Foo blah blah'
+
+and its name:
+
+.. doctest::
+
+  >>> IFoo.__name__
+  'IFoo'
+
+and even its module:
+
+.. doctest::
+
+  >>> IFoo.__module__
+  'builtins'
+
+The interface defined two attributes:
+
+``x``
+  This is the simplest form of attribute definition.  It has a name
+  and a doc string.  It doesn't formally specify anything else.
+
+``bar``
+  This is a method.  A method is defined via a function definition.  A
+  method is simply an attribute constrained to be a callable with a
+  particular signature, as provided by the function definition.
+
+  Note that ``bar`` doesn't take a ``self`` argument.  Interfaces document
+  how an object is *used*.  When calling instance methods, you don't
+  pass a ``self`` argument, so a ``self`` argument isn't included in the
+  interface signature.  The ``self`` argument in instance methods is
+  really an implementation detail of Python instances. Other objects,
+  besides instances can provide interfaces and their methods might not
+  be instance methods. For example, modules can provide interfaces and
+  their methods are usually just functions.  Even instances can have
+  methods that are not instance methods.
+
+You can access the attributes defined by an interface using mapping
+syntax:
+
+.. doctest::
+
+  >>> x = IFoo'x'
+  >>> type(x)
+  <class 'zope.interface.interface.Attribute'>
+  >>> x.__name__
+  'x'
+  >>> x.__doc__
+  'X blah blah'
+
+  >>> IFoo.get('x').__name__
+  'x'
+
+  >>> IFoo.get('y')
+
+You can use ``in`` to determine if an interface defines a name:
+
+.. doctest::
+
+  >>> 'x' in IFoo
+  True
+
+You can iterate over interfaces to get the names they define:
+
+.. doctest::
+
+  >>> names = list(IFoo)
+  >>> names.sort()
+  >>> names
+  'bar', 'x'
+
+Remember that interfaces aren't classes. You can't access attribute
+definitions as attributes of interfaces:
+
+.. doctest::
+
+  >>> IFoo.x
+  Traceback (most recent call last):
+    File "<stdin>", line 1, in ?
+  AttributeError: 'InterfaceClass' object has no attribute 'x'
+
+Methods provide access to the method signature:
+
+.. doctest::
+
+  >>> bar = IFoo'bar'
+  >>> bar.getSignatureString()
+  '(q, r=None)'
+
+TODO
+  Methods really should have a better API.  This is something that
+  needs to be improved.
+
+Declaring interfaces
+====================
+
+Having defined interfaces, we can *declare* that objects provide
+them.  Before we describe the details, lets define some terms:
+
+*provide*
+   We say that objects *provide* interfaces.  If an object provides an
+   interface, then the interface specifies the behavior of the
+   object. In other words, interfaces specify the behavior of the
+   objects that provide them.
+
+*implement*
+   We normally say that classes *implement* interfaces.  If a class
+   implements an interface, then the instances of the class provide
+   the interface.  Objects provide interfaces that their classes
+   implement #factory_.  (Objects can provide interfaces directly,
+   in addition to what their classes implement.)
+
+   It is important to note that classes don't usually provide the
+   interfaces that they implement.
+
+   We can generalize this to factories.  For any callable object we
+   can declare that it produces objects that provide some interfaces
+   by saying that the factory implements the interfaces.
+
+Now that we've defined these terms, we can talk about the API for
+declaring interfaces.
+
+Declaring implemented interfaces
+--------------------------------
+
+The most common way to declare interfaces is using the `implementer`
+decorator on a class:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IFoo)
+  ... class Foo:
+  ...
+  ...     def __init__(self, x=None):
+  ...         self.x = x
+  ...
+  ...     def bar(self, q, r=None):
+  ...         return q, r, self.x
+  ...
+  ...     def __repr__(self):
+  ...         return "Foo(%s)" % self.x
+
+
+In this example, we declared that ``Foo`` implements ``IFoo``. This means
+that instances of ``Foo`` provide ``IFoo``.  Having made this declaration,
+there are several ways we can introspect the declarations.  First, we
+can ask an interface whether it is implemented by a class:
+
+.. doctest::
+
+  >>> IFoo.implementedBy(Foo)
+  True
+
+And we can ask whether an interface is provided by an object:
+
+.. doctest::
+
+  >>> foo = Foo()
+  >>> IFoo.providedBy(foo)
+  True
+
+Of course, ``Foo`` doesn't *provide* ``IFoo``, it *implements* it:
+
+.. doctest::
+
+  >>> IFoo.providedBy(Foo)
+  False
+
+We can also ask what interfaces are implemented by a class:
+
+.. doctest::
+
+  >>> list(zope.interface.implementedBy(Foo))
+  <InterfaceClass builtins.IFoo>
+
+It's an error to ask for interfaces implemented by a non-callable
+object:
+
+.. doctest::
+
+  >>> IFoo.implementedBy(foo)
+  Traceback (most recent call last):
+  ...
+  TypeError: ('ImplementedBy called for non-factory', Foo(None))
+
+  >>> list(zope.interface.implementedBy(foo))
+  Traceback (most recent call last):
+  ...
+  TypeError: ('ImplementedBy called for non-factory', Foo(None))
+
+Similarly, we can ask what interfaces are provided by an object:
+
+.. doctest::
+
+  >>> list(zope.interface.providedBy(foo))
+  <InterfaceClass builtins.IFoo>
+  >>> list(zope.interface.providedBy(Foo))
+  
+
+We can declare interfaces implemented by other factories (besides
+classes).  We do this using the same `implementer` decorator.
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IFoo)
+  ... def yfoo(y):
+  ...     foo = Foo()
+  ...     foo.y = y
+  ...     return foo
+
+  >>> list(zope.interface.implementedBy(yfoo))
+  <InterfaceClass builtins.IFoo>
+
+Note that the implementer decorator may modify its argument. Callers
+should not assume that a new object is created.
+
+Using implementer also works on callable objects. This is used by
+:py:mod:`zope.formlib`, as an example:
+
+.. doctest::
+
+  >>> class yfactory:
+  ...     def __call__(self, y):
+  ...         foo = Foo()
+  ...         foo.y = y
+  ...         return foo
+  >>> yfoo = yfactory()
+  >>> yfoo = zope.interface.implementer(IFoo)(yfoo)
+
+  >>> list(zope.interface.implementedBy(yfoo))
+  <InterfaceClass builtins.IFoo>
+
+XXX: Double check and update these version numbers:
+
+In :py:mod:`zope.interface` 3.5.2 and lower, the implementer decorator can not
+be used for classes, but in 3.6.0 and higher it can:
+
+.. doctest::
+
+  >>> Foo = zope.interface.implementer(IFoo)(Foo)
+  >>> list(zope.interface.providedBy(Foo()))
+  <InterfaceClass builtins.IFoo>
+
+Note that class decorators using the ``@implementer(IFoo)`` syntax are only
+supported in Python 2.6 and later.
+
+.. autofunction:: implementer
+   :noindex:
+
+   .. XXX: Duplicate description.
+
+Declaring provided interfaces
+-----------------------------
+
+We can declare interfaces directly provided by objects.  Suppose that
+we want to document what the ``__init__`` method of the ``Foo`` class
+does.  It's not *really* part of ``IFoo``.  You wouldn't normally call
+the ``__init__`` method on Foo instances.  Rather, the ``__init__`` method
+is part of ``Foo``'s ``__call__`` method:
+
+.. doctest::
+
+  >>> class IFooFactory(zope.interface.Interface):
+  ...     """Create foos"""
+  ...
+  ...     def __call__(x=None):
+  ...         """Create a foo
+  ...
+  ...         The argument provides the initial value for x ...
+  ...         """
+
+It's the class that provides this interface, so we declare the
+interface on the class:
+
+.. doctest::
+
+  >>> zope.interface.directlyProvides(Foo, IFooFactory)
+
+And then, we'll see that Foo provides some interfaces:
+
+.. doctest::
+
+  >>> list(zope.interface.providedBy(Foo))
+  <InterfaceClass builtins.IFooFactory>
+  >>> IFooFactory.providedBy(Foo)
+  True
+
+Declaring class interfaces is common enough that there's a special
+decorator for it, `provider`:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IFoo)
+  ... @zope.interface.provider(IFooFactory)
+  ... class Foo2:
+  ...
+  ...     def __init__(self, x=None):
+  ...         self.x = x
+  ...
+  ...     def bar(self, q, r=None):
+  ...         return q, r, self.x
+  ...
+  ...     def __repr__(self):
+  ...         return "Foo(%s)" % self.x
+
+  >>> list(zope.interface.providedBy(Foo2))
+  <InterfaceClass builtins.IFooFactory>
+  >>> IFooFactory.providedBy(Foo2)
+  True
+
+There's a similar function, ``moduleProvides``, that supports interface
+declarations from within module definitions.  For example, see the use
+of ``moduleProvides`` call in ``zope.interface.__init__``, which declares that
+the package ``zope.interface`` provides ``IInterfaceDeclaration``.
+
+Sometimes, we want to declare interfaces on instances, even though
+those instances get interfaces from their classes.  Suppose we create
+a new interface, ``ISpecial``:
+
+.. doctest::
+
+  >>> class ISpecial(zope.interface.Interface):
+  ...     reason = zope.interface.Attribute("Reason why we're special")
+  ...     def brag():
+  ...         "Brag about being special"
+
+We can make an existing foo instance special by providing ``reason``
+and ``brag`` attributes:
+
+.. doctest::
+
+  >>> foo.reason = 'I just am'
+  >>> def brag():
+  ...      return "I'm special!"
+  >>> foo.brag = brag
+  >>> foo.reason
+  'I just am'
+  >>> foo.brag()
+  "I'm special!"
+
+and by declaring the interface:
+
+.. doctest::
+
+  >>> zope.interface.directlyProvides(foo, ISpecial)
+
+then the new interface is included in the provided interfaces:
+
+.. doctest::
+
+  >>> ISpecial.providedBy(foo)
+  True
+  >>> list(zope.interface.providedBy(foo))
+  <InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>
+
+We can find out what interfaces are directly provided by an object:
+
+.. doctest::
+
+  >>> list(zope.interface.directlyProvidedBy(foo))
+  <InterfaceClass builtins.ISpecial>
+
+  >>> newfoo = Foo()
+  >>> list(zope.interface.directlyProvidedBy(newfoo))
+  
+
+.. autofunction:: provider
+   :noindex:
+
+   .. XXX: Duplicate description.
+
+Inherited declarations
+----------------------
+
+Normally, declarations are inherited:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ISpecial)
+  ... class SpecialFoo(Foo):
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+  >>> list(zope.interface.implementedBy(SpecialFoo))
+  <InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>
+
+  >>> list(zope.interface.providedBy(SpecialFoo()))
+  <InterfaceClass builtins.ISpecial>, <InterfaceClass builtins.IFoo>
+
+Sometimes, you don't want to inherit declarations.  In that case, you
+can use ``implementer_only``, instead of ``implementer``:
+
+.. doctest::
+
+  >>> @zope.interface.implementer_only(ISpecial)
+  ... class Special(Foo):
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+  >>> list(zope.interface.implementedBy(Special))
+  <InterfaceClass builtins.ISpecial>
+
+  >>> list(zope.interface.providedBy(Special()))
+  <InterfaceClass builtins.ISpecial>
+
+External declarations
+---------------------
+
+Normally, we make implementation declarations as part of a class
+definition. Sometimes, we may want to make declarations from outside
+the class definition. For example, we might want to declare interfaces
+for classes that we didn't write.  The function ``classImplements`` can
+be used for this purpose:
+
+.. doctest::
+
+  >>> class C:
+  ...     pass
+
+  >>> zope.interface.classImplements(C, IFoo)
+  >>> list(zope.interface.implementedBy(C))
+  <InterfaceClass builtins.IFoo>
+
+.. autofunction:: classImplements
+   :noindex:
+
+We can use ``classImplementsOnly`` to exclude inherited interfaces:
+
+.. doctest::
+
+  >>> class C(Foo):
+  ...     pass
+
+  >>> zope.interface.classImplementsOnly(C, ISpecial)
+  >>> list(zope.interface.implementedBy(C))
+  <InterfaceClass builtins.ISpecial>
+
+.. autofunction:: classImplementsOnly
+   :noindex:
+
+   .. XXX: Duplicate description.
+
+Declaration Objects
+-------------------
+
+When we declare interfaces, we create *declaration* objects.  When we
+query declarations, declaration objects are returned:
+
+.. doctest::
+
+  >>> type(zope.interface.implementedBy(Special))
+  <class 'zope.interface.declarations.Implements'>
+
+Declaration objects and interface objects are similar in many ways. In
+fact, they share a common base class.  The important thing to realize
+about them is that they can be used where interfaces are expected in
+declarations. Here's a silly example:
+
+.. doctest::
+
+  >>> @zope.interface.implementer_only(
+  ...     zope.interface.implementedBy(Foo),
+  ...     ISpecial,
+  ... )
+  ... class Special2(object):
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+The declaration here is almost the same as
+``zope.interface.implementer(ISpecial)``, except that the order of
+interfaces in the resulting declaration is different:
+
+.. doctest::
+
+  >>> list(zope.interface.implementedBy(Special2))
+  <InterfaceClass builtins.IFoo>, <InterfaceClass builtins.ISpecial>
+
+
+Interface Inheritance
+=====================
+
+Interfaces can extend other interfaces. They do this simply by listing
+the other interfaces as base interfaces:
+
+.. doctest::
+
+  >>> class IBlat(zope.interface.Interface):
+  ...     """Blat blah blah"""
+  ...
+  ...     y = zope.interface.Attribute("y blah blah")
+  ...     def eek():
+  ...         """eek blah blah"""
+
+  >>> IBlat.__bases__
+  (<InterfaceClass zope.interface.Interface>,)
+
+  >>> class IBaz(IFoo, IBlat):
+  ...     """Baz blah"""
+  ...     def eek(a=1):
+  ...         """eek in baz blah"""
+  ...
+
+  >>> IBaz.__bases__
+  (<InterfaceClass builtins.IFoo>, <InterfaceClass builtins.IBlat>)
+
+  >>> names = list(IBaz)
+  >>> names.sort()
+  >>> names
+  'bar', 'eek', 'x', 'y'
+
+Note that ``IBaz`` overrides ``eek``:
+
+.. doctest::
+
+  >>> IBlat'eek'.__doc__
+  'eek blah blah'
+  >>> IBaz'eek'.__doc__
+  'eek in baz blah'
+
+We were careful to override ``eek`` in a compatible way.  When extending
+an interface, the extending interface should be compatible #compat_
+with the extended interfaces.
+
+We can ask whether one interface extends another:
+
+.. doctest::
+
+  >>> IBaz.extends(IFoo)
+  True
+  >>> IBlat.extends(IFoo)
+  False
+
+Note that interfaces don't extend themselves:
+
+.. doctest::
+
+  >>> IBaz.extends(IBaz)
+  False
+
+Sometimes we wish they did, but we can instead use ``isOrExtends``:
+
+.. doctest::
+
+  >>> IBaz.isOrExtends(IBaz)
+  True
+  >>> IBaz.isOrExtends(IFoo)
+  True
+  >>> IFoo.isOrExtends(IBaz)
+  False
+
+When we iterate over an interface, we get all of the names it defines,
+including names defined by base interfaces. Sometimes, we want *just*
+the names defined by the interface directly. We can use the ``names``
+method for that:
+
+.. doctest::
+
+  >>> list(IBaz.names())
+  'eek'
+
+Inheritance of attribute specifications
+---------------------------------------
+
+An interface may override attribute definitions from base interfaces.
+If two base interfaces define the same attribute, the attribute is
+inherited from the most specific interface. For example, with:
+
+.. doctest::
+
+  >>> class IBase(zope.interface.Interface):
+  ...
+  ...     def foo():
+  ...         "base foo doc"
+
+  >>> class IBase1(IBase):
+  ...     pass
+
+  >>> class IBase2(IBase):
+  ...
+  ...     def foo():
+  ...         "base2 foo doc"
+
+  >>> class ISub(IBase1, IBase2):
+  ...     pass
+
+``ISub``'s definition of ``foo`` is the one from ``IBase2``, since ``IBase2`` is more
+specific than ``IBase``:
+
+.. doctest::
+
+  >>> ISub'foo'.__doc__
+  'base2 foo doc'
+
+Note that this differs from a depth-first search.
+
+Sometimes, it's useful to ask whether an interface defines an
+attribute directly.  You can use the direct method to get a directly
+defined definitions:
+
+.. doctest::
+
+  >>> IBase.direct('foo').__doc__
+  'base foo doc'
+
+  >>> ISub.direct('foo')
+
+Specifications
+--------------
+
+Interfaces and declarations are both special cases of specifications.
+What we described above for interface inheritance applies to both
+declarations and specifications.  Declarations actually extend the
+interfaces that they declare:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IBaz)
+  ... class Baz(object):
+  ...     pass
+
+  >>> baz_implements = zope.interface.implementedBy(Baz)
+  >>> baz_implements.__bases__
+  (<InterfaceClass builtins.IBaz>, classImplements(object))
+
+  >>> baz_implements.extends(IFoo)
+  True
+
+  >>> baz_implements.isOrExtends(IFoo)
+  True
+  >>> baz_implements.isOrExtends(baz_implements)
+  True
+
+Specifications (interfaces and declarations) provide an ``__sro__``
+that lists the specification and all of it's ancestors:
+
+.. doctest::
+
+  >>> from pprint import pprint
+  >>> pprint(baz_implements.__sro__)
+  (classImplements(Baz, IBaz),
+   <InterfaceClass builtins.IBaz>,
+   <InterfaceClass builtins.IFoo>,
+   <InterfaceClass builtins.IBlat>,
+   classImplements(object),
+   <InterfaceClass zope.interface.Interface>)
+  >>> class IBiz(zope.interface.Interface):
+  ...    pass
+  >>> @zope.interface.implementer(IBiz)
+  ... class Biz(Baz):
+  ...    pass
+  >>> pprint(zope.interface.implementedBy(Biz).__sro__)
+  (classImplements(Biz, IBiz),
+   <InterfaceClass builtins.IBiz>,
+   classImplements(Baz, IBaz),
+   <InterfaceClass builtins.IBaz>,
+   <InterfaceClass builtins.IFoo>,
+   <InterfaceClass builtins.IBlat>,
+   classImplements(object),
+   <InterfaceClass zope.interface.Interface>)
+
+Tagged Values
+=============
+
+.. autofunction:: taggedValue
+
+Interfaces and attribute descriptions support an extension mechanism,
+borrowed from UML, called "tagged values" that lets us store extra
+data:
+
+.. doctest::
+
+  >>> IFoo.setTaggedValue('date-modified', '2004-04-01')
+  >>> IFoo.setTaggedValue('author', 'Jim Fulton')
+  >>> IFoo.getTaggedValue('date-modified')
+  '2004-04-01'
+  >>> IFoo.queryTaggedValue('date-modified')
+  '2004-04-01'
+  >>> IFoo.queryTaggedValue('datemodified')
+  >>> tags = list(IFoo.getTaggedValueTags())
+  >>> tags.sort()
+  >>> tags
+  'author', 'date-modified'
+
+Function attributes are converted to tagged values when method
+attribute definitions are created:
+
+.. doctest::
+
+  >>> class IBazFactory(zope.interface.Interface):
+  ...     def __call__():
+  ...         "create one"
+  ...     __call__.return_type = IBaz
+
+  >>> IBazFactory'__call__'.getTaggedValue('return_type')
+  <InterfaceClass builtins.IBaz>
+
+Tagged values can also be defined from within an interface definition:
+
+.. doctest::
+
+  >>> class IWithTaggedValues(zope.interface.Interface):
+  ...     zope.interface.taggedValue('squish', 'squash')
+  >>> IWithTaggedValues.getTaggedValue('squish')
+  'squash'
+
+Tagged values are inherited in the same way that attribute and method
+descriptions are. Inheritance can be ignored by using the "direct"
+versions of functions.
+
+.. doctest::
+
+   >>> class IExtendsIWithTaggedValues(IWithTaggedValues):
+   ...     zope.interface.taggedValue('child', True)
+   >>> IExtendsIWithTaggedValues.getTaggedValue('child')
+   True
+   >>> IExtendsIWithTaggedValues.getDirectTaggedValue('child')
+   True
+   >>> IExtendsIWithTaggedValues.getTaggedValue('squish')
+   'squash'
+   >>> print(IExtendsIWithTaggedValues.queryDirectTaggedValue('squish'))
+   None
+   >>> IExtendsIWithTaggedValues.setTaggedValue('squish', 'SQUASH')
+   >>> IExtendsIWithTaggedValues.getTaggedValue('squish')
+   'SQUASH'
+   >>> IExtendsIWithTaggedValues.getDirectTaggedValue('squish')
+   'SQUASH'
+
+
+Invariants
+==========
+
+.. autofunction:: invariant
+
+Interfaces can express conditions that must hold for objects that
+provide them. These conditions are expressed using one or more
+invariants.  Invariants are callable objects that will be called with
+an object that provides an interface. An invariant raises an ``Invalid``
+exception if the condition doesn't hold.  Here's an example:
+
+.. doctest::
+
+  >>> class RangeError(zope.interface.Invalid):
+  ...     """A range has invalid limits"""
+  ...     def __repr__(self):
+  ...         return "RangeError(%r)" % self.args
+
+  >>> def range_invariant(ob):
+  ...     if ob.max < ob.min:
+  ...         raise RangeError(ob)
+
+Given this invariant, we can use it in an interface definition:
+
+.. doctest::
+
+  >>> class IRange(zope.interface.Interface):
+  ...     min = zope.interface.Attribute("Lower bound")
+  ...     max = zope.interface.Attribute("Upper bound")
+  ...
+  ...     zope.interface.invariant(range_invariant)
+
+Interfaces have a method for checking their invariants:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IRange)
+  ... class Range(object):
+  ...     def __init__(self, min, max):
+  ...         self.min, self.max = min, max
+  ...
+  ...     def __repr__(self):
+  ...         return "Range(%s, %s)" % (self.min, self.max)
+
+  >>> IRange.validateInvariants(Range(1,2))
+  >>> IRange.validateInvariants(Range(1,1))
+  >>> IRange.validateInvariants(Range(2,1))
+  Traceback (most recent call last):
+  ...
+  RangeError: Range(2, 1)
+
+If you have multiple invariants, you may not want to stop checking
+after the first error.  If you pass a list to ``validateInvariants``,
+then a single ``Invalid`` exception will be raised with the list of
+exceptions as its argument:
+
+.. doctest::
+
+  >>> from zope.interface.exceptions import Invalid
+  >>> errors = 
+  >>> try:
+  ...     IRange.validateInvariants(Range(2,1), errors)
+  ... except Invalid as e:
+  ...     str(e)
+  'RangeError(Range(2, 1))'
+
+And the list will be filled with the individual exceptions:
+
+.. doctest::
+
+  >>> errors
+  RangeError(Range(2, 1))
+
+  >>> del errors:
+
+Adaptation
+==========
+
+Interfaces can be called to perform *adaptation*. Adaptation is the
+process of converting an object to an object implementing the
+interface. For example, in mathematics, to represent a point in space
+or on a graph there's the familiar Cartesian coordinate system using
+``CartesianPoint(x, y)``, and there's also the Polar coordinate system
+using ``PolarPoint(r, theta)``, plus several others (homogeneous,
+log-polar, etc). Polar points are most convenient for some types of
+operations, but cartesian points may make more intuitive sense to most
+people. Before printing an arbitrary point, we might want to *adapt* it
+to ``ICartesianPoint``, or before performing some mathematical
+operation you might want to adapt the arbitrary point to ``IPolarPoint``.
+
+The semantics are based on those of the  :pep:`246` ``adapt``
+function.
+
+If an object cannot be adapted, then a ``TypeError`` is raised:
+
+.. doctest::
+
+  >>> class ICartesianPoint(zope.interface.Interface):
+  ...     x = zope.interface.Attribute("Distance from origin along x axis")
+  ...     y = zope.interface.Attribute("Distance from origin along y axis")
+
+  >>> ICartesianPoint(0)
+  Traceback (most recent call last):
+  ...
+  TypeError: ('Could not adapt', 0, <InterfaceClass builtins.ICartesianPoint>)
+
+
+unless a default value is provided as a second positional argument;
+this value is not checked to see if it implements the interface:
+
+.. doctest::
+
+  >>> ICartesianPoint(0, 'bob')
+  'bob'
+
+If an object already implements the interface, then it will be returned:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ICartesianPoint)
+  ... class CartesianPoint(object):
+  ...     """The default cartesian point is the origin."""
+  ...     def __init__(self, x=0, y=0):
+  ...         self.x = x
+  ...         self.y = y
+  ...     def __repr__(self):
+  ...         return "CartesianPoint(%s, %s)" % (self.x, self.y)
+
+  >>> obj = CartesianPoint()
+  >>> ICartesianPoint(obj) is obj
+  True
+
+``__conform__``
+---------------
+
+:pep:`246` outlines a requirement:
+
+    When the object knows about the interface, and either considers
+    itself compliant, or knows how to wrap itself suitably.
+
+This is handled with ``__conform__``. If an object implements
+``__conform__``, then it will be used to give the object the chance to
+decide if it knows about the interface. This is true even if the class
+declares that it implements the interface.
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ICartesianPoint)
+  ... class C(object):
+  ...     def __conform__(self, proto):
+  ...          return "This could be anything."
+
+  >>> ICartesianPoint(C())
+  'This could be anything.'
+
+If ``__conform__`` returns ``None`` (because the object is unaware of
+the interface), then the rest of the adaptation process will continue.
+Here, we demonstrate that if the object already provides the
+interface, it is returned.
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ICartesianPoint)
+  ... class C(object):
+  ...     def __conform__(self, proto):
+  ...          return None
+
+  >>> c = C()
+  >>> ICartesianPoint(c) is c
+  True
+
+
+Adapter hooks (see :ref:`adapt_adapter_hooks`) will also be used, if present (after
+a ``__conform__`` method, if any, has been tried):
+
+.. doctest::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> def adapt_tuple_to_point(iface, obj):
+  ...     if isinstance(obj, tuple) and len(obj) == 2:
+  ...         return CartesianPoint(*obj)
+
+  >>> adapter_hooks.append(adapt_tuple_to_point)
+  >>> ICartesianPoint((1, 1))
+  CartesianPoint(1, 1)
+
+  >>> adapter_hooks.remove(adapt_tuple_to_point)
+  >>> ICartesianPoint((1, 1))
+  Traceback (most recent call last):
+  ...
+  TypeError: ('Could not adapt', (1, 1), <InterfaceClass builtins.ICartesianPoint>)
+
+.. _adapt_adapter_hooks:
+
+``__adapt__`` and adapter hooks
+-------------------------------
+
+Interfaces implement the :pep:`246` ``__adapt__`` method to satisfy
+the requirement:
+
+    When the interface knows about the object, and either the object
+    already complies or the interface knows how to suitably wrap the
+    object.
+
+This method is normally not called directly. It is called by the
+:pep:`246` adapt framework and by the interface ``__call__`` operator
+once ``__conform__`` (if any) has failed.
+
+The ``__adapt__`` method is responsible for adapting an object to the
+receiver.
+
+The default version returns ``None`` (because by default no interface
+"knows how to suitably wrap the object"):
+
+.. doctest::
+
+  >>> ICartesianPoint.__adapt__(0)
+
+unless the object given provides the interface ("the object already complies"):
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ICartesianPoint)
+  ... class C(object):
+  ...     pass
+
+  >>> obj = C()
+  >>> ICartesianPoint.__adapt__(obj) is obj
+  True
+
+.. rubric:: Customizing ``__adapt__`` in an interface
+
+It is possible to replace or customize the ``__adapt___``
+functionality for particular interfaces, if that interface "knows how
+to suitably wrap an object". This method should return the adapted
+object if it knows how, or call the super class to continue with the
+default adaptation process.
+
+.. doctest::
+
+   >>> import math
+   >>> class IPolarPoint(zope.interface.Interface):
+   ...     r = zope.interface.Attribute("Distance from center.")
+   ...     theta = zope.interface.Attribute("Angle from horizontal.")
+   ...     @zope.interface.interfacemethod
+   ...     def __adapt__(self, obj):
+   ...          if ICartesianPoint.providedBy(obj):
+   ...              # Convert to polar coordinates.
+   ...              r = math.sqrt(obj.x ** 2 + obj.y ** 2)
+   ...              theta = math.acos(obj.x / r)
+   ...              theta = math.degrees(theta)
+   ...              return PolarPoint(r, theta)
+   ...          return super(type(IPolarPoint), self).__adapt__(obj)
+
+   >>> @zope.interface.implementer(IPolarPoint)
+   ... class PolarPoint(object):
+   ...     def __init__(self, r=0, theta=0):
+   ...        self.r = r; self.theta = theta
+   ...     def __repr__(self):
+   ...        return "PolarPoint(%s, %s)" % (self.r, self.theta)
+   >>> IPolarPoint(CartesianPoint(0, 1))
+   PolarPoint(1.0, 90.0)
+   >>> IPolarPoint(PolarPoint())
+   PolarPoint(0, 0)
+
+.. seealso:: :func:`zope.interface.interfacemethod`, which explains
+   how to override functions in interface definitions and why, prior
+   to Python 3.6, the zero-argument version of `super` cannot be used.
+
+.. rubric:: Using adapter hooks for loose coupling
+
+Commonly, the author of the interface doesn't know how to wrap all
+possible objects, and neither does the author of an object know how to
+``__conform__`` to all possible interfaces. To support decoupling
+interfaces and objects, interfaces support the concept of "adapter
+hooks." Adapter hooks are a global sequence of callables
+``hook(interface, object)`` that are called, in order, from the
+default ``__adapt__`` method until one returns a non-``None`` result.
+
+.. note::
+   In many applications, a :doc:`adapter` is installed as
+   the first or only adapter hook.
+
+We'll install a hook that adapts from a 2D ``(x, y)`` Cartesian point
+on a plane to a three-dimensional point ``(x, y, z)`` by assuming the
+``z`` coordinate is 0. First, we'll define this new interface and an
+implementation:
+
+.. doctest::
+
+  >>> class ICartesianPoint3D(ICartesianPoint):
+  ...      z = zope.interface.Attribute("Depth.")
+  >>> @zope.interface.implementer(ICartesianPoint3D)
+  ... class CartesianPoint3D(CartesianPoint):
+  ...     def __init__(self, x=0, y=0, z=0):
+  ...        CartesianPoint.__init__(self, x, y)
+  ...        self.z = 0
+  ...     def __repr__(self):
+  ...        return "CartesianPoint3D(%s, %s, %s)" % (self.x, self.y, self.z)
+
+
+We install a hook by simply adding it to the ``adapter_hooks`` list:
+
+.. doctest::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> def returns_none(iface, obj):
+  ...     print("(First adapter hook returning None.)")
+  >>> def adapt_2d_to_3d(iface, obj):
+  ...     if iface == ICartesianPoint3D and ICartesianPoint.providedBy(obj):
+  ...         return CartesianPoint3D(obj.x, obj.y, 0)
+  >>> adapter_hooks.append(returns_none)
+  >>> adapter_hooks.append(adapt_2d_to_3d)
+  >>> ICartesianPoint3D.__adapt__(CartesianPoint())
+  (First adapter hook returning None.)
+  CartesianPoint3D(0, 0, 0)
+  >>> ICartesianPoint3D(CartesianPoint())
+  (First adapter hook returning None.)
+  CartesianPoint3D(0, 0, 0)
+
+Hooks can be uninstalled by removing them from the list:
+
+.. doctest::
+
+  >>> adapter_hooks.remove(returns_none)
+  >>> adapter_hooks.remove(adapt_2d_to_3d)
+  >>> ICartesianPoint3D.__adapt__(CartesianPoint())
+
+.. _global_persistence:
+
+Persistence, Sorting, Equality and Hashing
+==========================================
+
+.. tip:: For the practical implications of what's discussed below, and
+         some potential problems, see :ref:`spec_eq_hash`.
+
+Just like Python classes, interfaces are designed to inexpensively
+support persistence using Python's standard :mod:`pickle` module. This
+means that one process can send a *reference* to an interface to another
+process in the form of a byte string, and that other process can load
+that byte string and get the object that is that interface. The processes
+may be separated in time (one after the other), in space (running on
+different machines) or even be parts of the same process communicating
+with itself.
+
+We can demonstrate this. Observe how small the byte string needed to
+capture the reference is. Also note that since this is the same
+process, the identical object is found and returned:
+
+.. doctest::
+
+   >>> import sys
+   >>> import pickle
+   >>> class Foo(object):
+   ...    pass
+   >>> sys.modules__name__.Foo = Foo # XXX, see below
+   >>> pickled_byte_string = pickle.dumps(Foo, 0)
+   >>> len(pickled_byte_string)
+   21
+   >>> imported = pickle.loads(pickled_byte_string)
+   >>> imported == Foo
+   True
+   >>> imported is Foo
+   True
+   >>> class IFoo(zope.interface.Interface):
+   ...     pass
+   >>> sys.modules__name__.IFoo = IFoo # XXX, see below
+   >>> pickled_byte_string = pickle.dumps(IFoo, 0)
+   >>> len(pickled_byte_string)
+   22
+   >>> imported = pickle.loads(pickled_byte_string)
+   >>> imported is IFoo
+   True
+   >>> imported == IFoo
+   True
+
+.. rubric:: References to Global Objects
+
+The eagle-eyed reader will have noticed the two funny lines like
+``sys.modules__name__.Foo = Foo``. What's that for? To understand,
+we must know a bit about how Python "pickles" (``pickle.dump`` or
+``pickle.dumps``) classes or interfaces.
+
+When Python pickles a class or an interface, it does so as a "global
+object" #global_object_. Global objects are expected to already
+exist (contrast this with pickling a string or an object instance,
+which creates a new object in the receiving process) with all their
+necessary state information (for classes and interfaces, the state
+information would be things like the list of methods and defined
+attributes) in the receiving process, so the pickled byte string needs
+only contain enough data to look up that existing object; this data is a
+*reference*. Not only does this minimize the amount of data required
+to persist such an object, it also facilitates changing the definition
+of the object over time: if a class or interface gains or loses
+methods or attributes, loading a previously pickled reference will use
+the *current definition* of the object.
+
+The *reference* to a global object that's stored in the byte string
+consists only of the object's ``__name__`` and ``__module__``. Before
+a global object *obj* is pickled, Python makes sure that the object being
+pickled is the same one that can be found at
+``getattr(sys.modulesobj.__module__, obj.__name__)``; if there is no
+such object, or it refers to a different object, pickling fails. The
+two funny lines make sure that holds, no matter how this example is
+run (using some doctest runners, it doesn't hold by default, unlike it
+normally would).
+
+We can show some examples of what happens when that condition doesn't
+hold. First, what if we change the global object and try to pickle the
+old one?
+
+.. doctest::
+
+   >>> sys.modules__name__.Foo = 42
+   >>> pickle.dumps(Foo)
+   Traceback (most recent call last):
+   ...
+   _pickle.PicklingError: Can't pickle <class 'Foo'>: it's not the same object as builtins.Foo
+
+A consequence of this is that only one object of the given name can be
+defined and pickled at a time. If we were to try to define a new ``Foo``
+class (remembering that normally the ``sys.modules__name__.Foo =``
+line is automatic), we still cannot pickle the old one:
+
+.. doctest::
+
+   >>> orig_Foo = Foo
+   >>> class Foo(object):
+   ...    pass
+   >>> sys.modules__name__.Foo = Foo # XXX, usually automatic
+   >>> pickle.dumps(orig_Foo)
+   Traceback (most recent call last):
+   ...
+   _pickle.PicklingError: Can't pickle <class 'Foo'>: it's not the same object as builtins.Foo
+
+Or what if there simply is no global object?
+
+.. doctest::
+
+   >>> del sys.modules__name__.Foo
+   >>> pickle.dumps(Foo)
+   Traceback (most recent call last):
+   ...
+   _pickle.PicklingError: Can't pickle <class 'Foo'>: attribute lookup Foo on builtins failed
+
+Interfaces and classes behave the same in all those ways.
+
+.. rubric:: What's This Have To Do With Sorting, Equality and Hashing?
+
+Another important design consideration for interfaces is that they
+should be sortable. This permits them to be used, for example, as keys
+in a (persistent) `BTree <https://btrees.readthedocs.io>`_. As such,
+they define a total ordering, meaning that any given interface can
+definitively said to be greater than, less than, or equal to, any
+other interface. This relationship must be *stable* and hold the same
+across any two processes.
+
+An object becomes sortable by overriding the equality method
+``__eq__`` and at least one of the comparison methods (such as
+``__lt__``).
+
+Classes, on the other hand, are not sortable #class_sort_.
+Classes can only be tested for equality, and they implement this using
+object identity: ``class_a == class_b`` is equivalent to ``class_a is class_b``.
+
+In addition to being sortable, it's important for interfaces to be
+hashable so they can be used as keys in dictionaries or members of
+sets. This is done by implementing the ``__hash__`` method #hashable_.
+
+Classes are hashable, and they also implement this based on object
+identity, with the equivalent of ``id(class_a)``.
+
+To be both hashable and sortable, the hash method and the equality and
+comparison methods **must** `be consistent with each other
+<https://docs.python.org/3/reference/datamodel.html#object.__hash__>`_.
+That is, they must all be based on the same principle.
+
+Classes use the principle of identity to implement equality and
+hashing, but they don't implement sorting because identity isn't a
+stable sorting method (it is different in every process).
+
+Interfaces need to be sortable. In order for all three of hashing,
+equality and sorting to be consistent, interfaces implement them using
+the same principle as persistence. Interfaces are treated like "global
+objects" and sort and hash using the same information a *reference* to
+them would: their ``__name__`` and ``__module__``.
+
+In this way, hashing, equality and sorting are consistent with each
+other, and consistent with pickling:
+
+.. doctest::
+
+   >>> class IFoo(zope.interface.Interface):
+   ...     pass
+   >>> sys.modules__name__.IFoo = IFoo # XXX, usually automatic
+   >>> f1 = IFoo
+   >>> pickled_f1 = pickle.dumps(f1)
+   >>> class IFoo(zope.interface.Interface):
+   ...     pass
+   >>> sys.modules__name__.IFoo = IFoo # XXX, usually automatic
+   >>> IFoo == f1
+   True
+   >>> unpickled_f1 = pickle.loads(pickled_f1)
+   >>> unpickled_f1 == IFoo == f1
+   True
+
+This isn't quite the case for classes; note how ``f1`` wasn't equal to
+``Foo`` before pickling, but the unpickled value is:
+
+.. doctest::
+
+   >>> class Foo(object):
+   ...     pass
+   >>> sys.modules__name__.Foo = Foo # XXX, usually automatic
+   >>> f1 = Foo
+   >>> pickled_f1 = pickle.dumps(Foo)
+   >>> class Foo(object):
+   ...     pass
+   >>> sys.modules__name__.Foo = Foo # XXX, usually automatic
+   >>> f1 == Foo
+   False
+   >>> unpickled_f1 = pickle.loads(pickled_f1)
+   >>> unpickled_f1 == Foo # Surprise!
+   True
+   >>> unpickled_f1 == f1
+   False
+
+For more information, and some rare potential pitfalls, see
+:ref:`spec_eq_hash`.
+
+.. rubric:: Footnotes
+
+.. #create The main reason we subclass ``Interface`` is to cause the
+             Python class statement to create an interface, rather
+             than a class.
+
+             It's possible to create interfaces by calling a special
+             interface class directly.  Doing this, it's possible
+             (and, on rare occasions, useful) to create interfaces
+             that don't descend from ``Interface``.  Using this
+             technique is beyond the scope of this document.
+
+.. #factory Classes are factories.  They can be called to create
+              their instances.  We expect that we will eventually
+              extend the concept of implementation to other kinds of
+              factories, so that we can declare the interfaces
+              provided by the objects created.
+
+.. #compat The goal is substitutability.  An object that provides an
+             extending interface should be substitutable for an object
+             that provides the extended interface.  In our example, an
+             object that provides ``IBaz`` should be usable wherever an
+             object that provides ``IBlat`` is expected.
+
+             The interface implementation doesn't enforce this,
+             but maybe it should do some checks.
+
+.. #class_sort In Python 2, classes could be sorted, but the sort
+                 was not stable (it also used the identity principle)
+                 and not useful for persistence; this was considered a
+                 bug that was fixed in Python 3.
+
+.. #hashable In order to be hashable, you must implement both
+               ``__eq__``  and ``__hash__``. If you only implement
+               ``__eq__``, Python makes sure the type cannot be
+               used in a dictionary, set, or with :func:`hash`. In
+               Python 2, this wasn't the case, and forgetting to
+               override ``__hash__`` was a constant source of bugs.
+
+.. #global_object From the name of the pickle bytecode operator; it
+                    varies depending on the protocol but always
+                    includes "GLOBAL".

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/README.ru.rst.txt Added

@@ -0,0 +1,804 @@
+==========
+Интерфейсы
+==========
+
+.. contents::
+
+Интерфейсы - это объекты специфицирующие (документирующие) внешнее поведение
+объектов которые их "предоставляют". Интерфейсы определяют поведение через
+следующие составляющие:
+
+- Неформальную документацию в строках документации
+
+- Определения атрибутов
+
+- Инварианты - условия, которые должны соблюдаться для объектов предоставляющих
+  интерфейс
+
+Определения атрибутов описывают конкретные атрибуты. Они определяют
+имя атрибута и предоставляют документацию и ограничения для значений
+атрибута. Определения атрибутов могут быть заданы несколькими путями
+как мы увидим ниже.
+
+Определение интерфейсов
+=======================
+
+Интерфейсы определяются с использованием ключевого слова class::
+
+  >>> import zope.interface
+  >>> class IFoo(zope.interface.Interface):
+  ...    """Foo blah blah"""
+  ...
+  ...    x = zope.interface.Attribute("""X blah blah""")
+  ...
+  ...    def bar(q, r=None):
+  ...        """bar blah blah"""
+
+В примере выше мы создали интерфейс `IFoo`. Мы наследуем его от
+класса `zope.interface.Interface`, который является родительским интерфейсом
+для всех интерфейсов, как `object` - это родительский класс для всех новых
+классов #create_. Данный интерфейс не является классом, а является
+Интерфейсом, экземпляром `InterfaceClass`::
+
+  >>> type(IFoo)
+  <class 'zope.interface.interface.InterfaceClass'>
+
+Мы можем запросить у интерфейса его документацию::
+
+  >>> IFoo.__doc__
+  'Foo blah blah'
+
+и его имя::
+
+  >>> IFoo.__name__
+  'IFoo'
+
+и даже модуль в котором он определен::
+
+  >>> IFoo.__module__
+  '__main__'
+
+Наш интерфейс определяет два атрибута:
+
+`x`
+  Это простейшая форма определения атрибутов. Определяются имя
+  и строка документации. Формально здесь не определяется ничего более.
+
+`bar`
+  Это метод. Методы определяются как обычные функции. Метод - это просто
+  атрибут который должен быть вызываемым с указанием сигнатуры,
+  предоставляемой определением функции.
+
+  Надо отметить, что аргумент `self` не указывается для `bar`. Интерфейс
+  документирует как объект *используется*. Когда методы экземпляров классов
+  вызываются мы не передаем аргумент `self`, таким образом аргумент `self`
+  не включается и в сигнатуру интерфейса. Аргумент `self` в методах
+  экземпляров классов на самом деле деталь реализации экземпляров классов
+  в Python. Другие объекты кроме экземпляров классов могут предоставлять
+  интерфейсы и их методы могут не быть методами экземпляров классов. Для
+  примера модули могут предоставлять интерфейсы и их методы обычно просто
+  функции. Даже экземпляры могут иметь методы не являющиеся методами
+  экземпляров класса.
+
+Мы можем получить доступ к атрибутам определенным интерфейсом используя
+синтаксис доступа к элементам массива::
+
+  >>> x = IFoo'x'
+  >>> type(x)
+  <class 'zope.interface.interface.Attribute'>
+  >>> x.__name__
+  'x'
+  >>> x.__doc__
+  'X blah blah'
+
+  >>> IFoo.get('x').__name__
+  'x'
+
+  >>> IFoo.get('y')
+
+Можно использовать `in` для определения содержит ли интерфейс
+определенное имя::
+
+  >>> 'x' in IFoo
+  True
+
+Мы можем использовать итератор для интерфейсов чтобы получить все имена
+которые интерфейсы определяют::
+
+  >>> names = list(IFoo)
+  >>> names.sort()
+  >>> names
+  'bar', 'x'
+
+Надо помнить, что интерфейсы не являются классами. Мы не можем получить
+доступ к определениям атрибутов через доступ к атрибутам интерфейсов::
+
+  >>> IFoo.x
+  Traceback (most recent call last):
+    File "<stdin>", line 1, in ?
+  AttributeError: 'InterfaceClass' object has no attribute 'x'
+
+Методы также предоставляют доступ к сигнатуре метода::
+
+  >>> bar = IFoo'bar'
+  >>> bar.getSignatureString()
+  '(q, r=None)'
+
+Объявление интерфейсов
+======================
+
+Определив интерфейс мы можем теперь *объявить*, что объекты предоставляют их.
+Перед описанием деталей определим некоторые термины:
+
+*предоставлять*
+  Мы говорим, что объекты *предоставляют* интерфейсы. Если объект
+  предоставляет интерфейс, тогда интерфейс специфицирует поведение объекта.
+  Другими словами, интерфейсы специфицируют поведение объектов которые
+  предоставляют их.
+
+*реализовать*
+  Мы обычно говорим что классы *реализуют* интерфейсы. Если класс
+  реализует интерфейс, тогда экземпляры этого класса предоставляют
+  данный интерфейс. Объекты предоставляют интерфейсы которые их классы
+  реализуют #factory_. (Объекты также могут предоставлять интерфейсы напрямую
+  плюс к тем которые реализуют их классы.)
+
+  Важно помнить, что классы обычно не предоставляют интерфейсы которые
+  они реализуют.
+
+  Мы можем обобщить это до фабрик. Для любого вызываемого объекта мы можем
+  объявить что он производит объекты которые предоставляют какие-либо
+  интерфейсы сказав, что фабрика реализует данные интерфейсы.
+
+Теперь после того как мы определили эти термины мы можем поговорить об
+API для объявления интерфейсов.
+
+Объявление реализуемых интерфейсов
+----------------------------------
+
+Наиболее часто используемый путь для объявления интерфейсов - это использование
+функции implements в определении класса::
+
+  >>> class Foo:
+  ...     zope.interface.implements(IFoo)
+  ...
+  ...     def __init__(self, x=None):
+  ...         self.x = x
+  ...
+  ...     def bar(self, q, r=None):
+  ...         return q, r, self.x
+  ...
+  ...     def __repr__(self):
+  ...         return "Foo(%s)" % self.x
+
+В этом примере мы объявили, что `Foo` реализует `IFoo`. Это значит, что
+экземпляры `Foo` предоставляют `IFoo`. После данного объявления есть
+несколько путей для анализа объявлений. Во-первых мы можем спросить
+что интерфейс реализован классом::
+
+  >>> IFoo.implementedBy(Foo)
+  True
+
+Также мы можем спросить если интерфейс предоставляется объектами класса::
+
+  >>> foo = Foo()
+  >>> IFoo.providedBy(foo)
+  True
+
+Конечно `Foo` не предоставляет `IFoo`, он реализует его::
+
+  >>> IFoo.providedBy(Foo)
+  False
+
+Мы можем также узнать какие интерфейсы реализуются объектами::
+
+  >>> list(zope.interface.implementedBy(Foo))
+  <InterfaceClass __main__.IFoo>
+
+Это ошибка спрашивать про интерфейсы реализуемые не вызываемым объектом::
+
+  >>> IFoo.implementedBy(foo)
+  Traceback (most recent call last):
+  ...
+  TypeError: ('ImplementedBy called for non-factory', Foo(None))
+
+  >>> list(zope.interface.implementedBy(foo))
+  Traceback (most recent call last):
+  ...
+  TypeError: ('ImplementedBy called for non-factory', Foo(None))
+
+Также можно узнать какие интерфейсы предоставляются объектами::
+
+  >>> list(zope.interface.providedBy(foo))
+  <InterfaceClass __main__.IFoo>
+  >>> list(zope.interface.providedBy(Foo))
+  
+
+Мы можем объявить интерфейсы реализуемые другими фабриками (кроме классов).
+Это можно сделать используя декоратор `implementer` (в стиле Python 2.4).
+Для версий Python ниже 2.4 это будет выглядеть следующим образом::
+
+  >>> def yfoo(y):
+  ...     foo = Foo()
+  ...     foo.y = y
+  ...     return foo
+  >>> yfoo = zope.interface.implementer(IFoo)(yfoo)
+
+  >>> list(zope.interface.implementedBy(yfoo))
+  <InterfaceClass __main__.IFoo>
+
+Надо заметить, что декоратор implementer может модифицировать свои аргументы.
+Вызывающая сторона не должна предполагать, что всегда будет создаваться
+новый объект.
+
+XXX: Double check and update these version numbers, and translate to russian:
+
+In zope.interface 3.5.1 and lower, the implementer decorator can not
+be used for classes, but in 3.5.2 and higher it can::
+
+  >>> Foo = zope.interface.implementer(IFoo)(Foo)
+  >>> list(zope.interface.providedBy(Foo()))
+  <InterfaceClass __main__.IFoo>
+  
+Note that class decorators using the @implementer(IFoo) syntax are only 
+supported in Python 2.6 and later.
+
+
+Объявление предоставляемых интерфейсов
+--------------------------------------
+
+Мы можем объявлять интерфейсы напрямую предоставляемые объектами. Предположим
+что мы хотим документировать что делает метод `__init__` класса `Foo`. Это
+*точно* не часть `IFoo`. Обычно мы не должны напрямую вызывать метод `__init__`
+для экземпляров Foo. Скорее метод `__init__` является частью метода `__call__`
+класса `Foo`::
+
+  >>> class IFooFactory(zope.interface.Interface):
+  ...     """Create foos"""
+  ...
+  ...     def __call__(x=None):
+  ...         """Create a foo
+  ...
+  ...         The argument provides the initial value for x ...
+  ...         """
+
+У нас есть класс предоставляющий данный интерфейс, таким образом мы можем
+объявить интерфейс класса::
+
+  >>> zope.interface.directlyProvides(Foo, IFooFactory)
+
+Теперь мы видим, что Foo уже предоставляет интерфейсы::
+
+  >>> list(zope.interface.providedBy(Foo))
+  <InterfaceClass __main__.IFooFactory>
+  >>> IFooFactory.providedBy(Foo)
+  True
+
+Объявление интерфейсов класса достаточно частая операция и для нее есть
+специальная функция объявления `classProvides`, которая позволяет объявлять
+интерфейсы при определении класса::
+
+  >>> class Foo2:
+  ...     zope.interface.implements(IFoo)
+  ...     zope.interface.classProvides(IFooFactory)
+  ...
+  ...     def __init__(self, x=None):
+  ...         self.x = x
+  ...
+  ...     def bar(self, q, r=None):
+  ...         return q, r, self.x
+  ...
+  ...     def __repr__(self):
+  ...         return "Foo(%s)" % self.x
+
+  >>> list(zope.interface.providedBy(Foo2))
+  <InterfaceClass __main__.IFooFactory>
+  >>> IFooFactory.providedBy(Foo2)
+  True
+
+Похожая функция `moduleProvides` поддерживает объявление интерфейсов при
+определении модуля. Для примера смотрите использование вызова
+`moduleProvides` в `zope.interface.__init__`, который объявляет, что
+пакет `zope.interface` предоставляет `IInterfaceDeclaration`.
+
+Иногда мы хотим объявить интерфейсы экземпляров, даже если эти экземпляры
+уже берут интерфейсы от своих классов. Предположим, что мы создаем новый
+интерфейс `ISpecial`::
+
+  >>> class ISpecial(zope.interface.Interface):
+  ...     reason = zope.interface.Attribute("Reason why we're special")
+  ...     def brag():
+  ...         "Brag about being special"
+
+Мы можем сделать созданный экземпляр foo специальным, предоставив атрибуты
+`reason` и `brag`::
+
+  >>> foo.reason = 'I just am'
+  >>> def brag():
+  ...      return "I'm special!"
+  >>> foo.brag = brag
+  >>> foo.reason
+  'I just am'
+  >>> foo.brag()
+  "I'm special!"
+
+и объявив интерфейс::
+
+  >>> zope.interface.directlyProvides(foo, ISpecial)
+
+таким образом новый интерфейс включается в список предоставляемых интерфейсов::
+
+  >>> ISpecial.providedBy(foo)
+  True
+  >>> list(zope.interface.providedBy(foo))
+  <InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>
+
+Мы также можем определить, что интерфейсы напрямую предоставляются
+объектами::
+
+  >>> list(zope.interface.directlyProvidedBy(foo))
+  <InterfaceClass __main__.ISpecial>
+
+  >>> newfoo = Foo()
+  >>> list(zope.interface.directlyProvidedBy(newfoo))
+  
+
+Наследуемые объявления
+----------------------
+
+Обычно объявления наследуются::
+
+  >>> class SpecialFoo(Foo):
+  ...     zope.interface.implements(ISpecial)
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+  >>> list(zope.interface.implementedBy(SpecialFoo))
+  <InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>
+
+  >>> list(zope.interface.providedBy(SpecialFoo()))
+  <InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>
+
+Иногда мы не хотим наследовать объявления. В этом случае мы можем
+использовать `implementsOnly` вместо `implements`::
+
+  >>> class Special(Foo):
+  ...     zope.interface.implementsOnly(ISpecial)
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+  >>> list(zope.interface.implementedBy(Special))
+  <InterfaceClass __main__.ISpecial>
+
+  >>> list(zope.interface.providedBy(Special()))
+  <InterfaceClass __main__.ISpecial>
+
+Внешние объявления
+------------------
+
+Обычно мы создаем объявления реализации как часть объявления класса. Иногда
+мы можем захотеть создать объявления вне объявления класса. Для примера,
+мы можем хотеть объявить интерфейсы для классов которые писали не мы.
+Для этого может использоваться функция `classImplements`::
+
+  >>> class C:
+  ...     pass
+
+  >>> zope.interface.classImplements(C, IFoo)
+  >>> list(zope.interface.implementedBy(C))
+  <InterfaceClass __main__.IFoo>
+
+Мы можем использовать `classImplementsOnly` для исключения наследуемых
+интерфейсов::
+
+  >>> class C(Foo):
+  ...     pass
+
+  >>> zope.interface.classImplementsOnly(C, ISpecial)
+  >>> list(zope.interface.implementedBy(C))
+  <InterfaceClass __main__.ISpecial>
+
+Объекты объявлений
+------------------
+
+Когда мы объявляем интерфейсы, мы создаем объект *объявления*. Когда мы
+запрашиваем объявления возвращается объект объявления::
+
+  >>> type(zope.interface.implementedBy(Special))
+  <class 'zope.interface.declarations.Implements'>
+
+Объекты объявления и объекты интерфейсов во многом похожи друг на друга.
+На самом деле они даже имеют общий базовый класс. Важно понять, что они могут
+использоваться там, где в объявлениях ожидаются интерфейсы. Вот простой
+пример::
+
+  >>> class Special2(Foo):
+  ...     zope.interface.implementsOnly(
+  ...          zope.interface.implementedBy(Foo),
+  ...          ISpecial,
+  ...          )
+  ...     reason = 'I just am'
+  ...     def brag(self):
+  ...         return "I'm special because %s" % self.reason
+
+Объявление здесь практически такое же как
+``zope.interface.implements(ISpecial)``, отличие только в порядке
+интерфейсов в итоговом объявления::
+
+  >>> list(zope.interface.implementedBy(Special2))
+  <InterfaceClass __main__.IFoo>, <InterfaceClass __main__.ISpecial>
+
+Наследование интерфейсов
+========================
+
+Интерфейсы могут расширять другие интерфейсы. Они делают это просто
+показывая эти интерфейсы как базовые::
+
+  >>> class IBlat(zope.interface.Interface):
+  ...     """Blat blah blah"""
+  ...
+  ...     y = zope.interface.Attribute("y blah blah")
+  ...     def eek():
+  ...         """eek blah blah"""
+
+  >>> IBlat.__bases__
+  (<InterfaceClass zope.interface.Interface>,)
+
+  >>> class IBaz(IFoo, IBlat):
+  ...     """Baz blah"""
+  ...     def eek(a=1):
+  ...         """eek in baz blah"""
+  ...
+
+  >>> IBaz.__bases__
+  (<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.IBlat>)
+
+  >>> names = list(IBaz)
+  >>> names.sort()
+  >>> names
+  'bar', 'eek', 'x', 'y'
+
+Заметим, что `IBaz` переопределяет eek::
+
+  >>> IBlat'eek'.__doc__
+  'eek blah blah'
+  >>> IBaz'eek'.__doc__
+  'eek in baz blah'
+
+Мы были осторожны, переопределяя eek совместимым путем. Когда интерфейс
+расширяется, расширенный интерфейс должен быть совместимым #compat_ с
+расширяемыми интерфейсами.
+
+Мы можем запросить расширяет ли один из интерфейсов другой::
+
+  >>> IBaz.extends(IFoo)
+  True
+  >>> IBlat.extends(IFoo)
+  False
+
+Заметим, что интерфейсы не расширяют сами себя::
+
+  >>> IBaz.extends(IBaz)
+  False
+
+Если мы хотим видеть, что интерфейс расширяет сам себя,то мы можем использовать `isOrExtends`::
+
+  >>> IBaz.isOrExtends(IBaz)
+  True
+  >>> IBaz.isOrExtends(IFoo)
+  True
+  >>> IFoo.isOrExtends(IBaz)
+  False
+
+Когда мы применяем итерацию к интерфейсу мы получаем все имена которые он
+определяет, включая имена определенные для базовых интерфейсов. Иногда
+мы хотим получить *только* имена определенные интерфейсом напрямую.
+Для этого мы используем метод `names`::
+
+  >>> list(IBaz.names())
+  'eek'
+
+Наследование в случае определения атрибутов
+--------------------------------------------
+
+Интерфейс может переопределять определения атрибутов из базовых интерфейсов.
+Если два базовых интерфейса определяют один и тот же атрибут, то данный атрибут
+наследуется от более специфичного интерфейса. Для примера::
+
+  >>> class IBase(zope.interface.Interface):
+  ...
+  ...     def foo():
+  ...         "base foo doc"
+
+  >>> class IBase1(IBase):
+  ...     pass
+
+  >>> class IBase2(IBase):
+  ...
+  ...     def foo():
+  ...         "base2 foo doc"
+
+  >>> class ISub(IBase1, IBase2):
+  ...     pass
+
+Определение ISub для foo будет из IBase2 т.к. IBase2 более специфичен для
+IBase::
+
+  >>> ISub'foo'.__doc__
+  'base2 foo doc'
+
+Заметим, что это отличается от поиска в глубину.
+
+Иногда полезно узнать, что интерфейс определяет атрибут напрямую. Мы можем
+использовать метод `direct` для получения напрямую определенных атрибутов::
+
+  >>> IBase.direct('foo').__doc__
+  'base foo doc'
+
+  >>> ISub.direct('foo')
+
+Спецификации
+------------
+
+Интерфейсы и объявления - это специальные случаи спецификаций. Описание
+выше для наследования интерфейсов можно применить и к объявлениям и
+к спецификациям. Объявления фактически расширяют интерфейсы которые они
+объявляют::
+
+  >>> class Baz(object):
+  ...     zope.interface.implements(IBaz)
+
+  >>> baz_implements = zope.interface.implementedBy(Baz)
+  >>> baz_implements.__bases__
+  (<InterfaceClass __main__.IBaz>, <implementedBy ...object>)
+
+  >>> baz_implements.extends(IFoo)
+  True
+
+  >>> baz_implements.isOrExtends(IFoo)
+  True
+  >>> baz_implements.isOrExtends(baz_implements)
+  True
+
+Спецификации (интерфейсы и объявления) предоставляют атрибут `__sro__`
+который описывает спецификацию и всех ее предков::
+
+  >>> baz_implements.__sro__
+  (<implementedBy __main__.Baz>,
+   <InterfaceClass __main__.IBaz>,
+   <InterfaceClass __main__.IFoo>,
+   <InterfaceClass __main__.IBlat>,
+   <InterfaceClass zope.interface.Interface>,
+   <implementedBy ...object>)
+
+Помеченные значения
+===================
+
+Интерфейсы и описания атрибутов поддерживают механизм расширения,
+заимствованный из UML и называемый "помеченные значения", который позволяет
+сохранять дополнительные данные::
+
+  >>> IFoo.setTaggedValue('date-modified', '2004-04-01')
+  >>> IFoo.setTaggedValue('author', 'Jim Fulton')
+  >>> IFoo.getTaggedValue('date-modified')
+  '2004-04-01'
+  >>> IFoo.queryTaggedValue('date-modified')
+  '2004-04-01'
+  >>> IFoo.queryTaggedValue('datemodified')
+  >>> tags = list(IFoo.getTaggedValueTags())
+  >>> tags.sort()
+  >>> tags
+  'author', 'date-modified'
+
+Атрибуты функций конвертируются в помеченные значения, когда создаются
+определения атрибутов метода::
+
+  >>> class IBazFactory(zope.interface.Interface):
+  ...     def __call__():
+  ...         "create one"
+  ...     __call__.return_type = IBaz
+
+  >>> IBazFactory'__call__'.getTaggedValue('return_type')
+  <InterfaceClass __main__.IBaz>
+
+Помеченные значения также могут быть определены внутри определения
+интерфейса::
+
+  >>> class IWithTaggedValues(zope.interface.Interface):
+  ...     zope.interface.taggedValue('squish', 'squash')
+  >>> IWithTaggedValues.getTaggedValue('squish')
+  'squash'
+
+Инварианты
+==========
+
+Интерфейсы могут описывать условия, которые должны быть соблюдены для объектов,
+которые их предоставляют. Эти условия описываются одним или несколькими
+инвариантами. Инварианты - это вызываемые объекты, которые будут вызваны
+с объектом, предоставляющим интерфейс в качестве параметра. Инвариант
+должен выкинуть исключение `Invalid` если условие не соблюдено. Например::
+
+  >>> class RangeError(zope.interface.Invalid):
+  ...     """A range has invalid limits"""
+  ...     def __repr__(self):
+  ...         return "RangeError(%r)" % self.args
+
+  >>> def range_invariant(ob):
+  ...     if ob.max < ob.min:
+  ...         raise RangeError(ob)
+
+Определив этот инвариант, мы можем использовать его в определении интерфейсов::
+
+  >>> class IRange(zope.interface.Interface):
+  ...     min = zope.interface.Attribute("Lower bound")
+  ...     max = zope.interface.Attribute("Upper bound")
+  ...
+  ...     zope.interface.invariant(range_invariant)
+
+Интерфейсы имеют метод для проверки своих инвариантов::
+
+  >>> class Range(object):
+  ...     zope.interface.implements(IRange)
+  ...
+  ...     def __init__(self, min, max):
+  ...         self.min, self.max = min, max
+  ...
+  ...     def __repr__(self):
+  ...         return "Range(%s, %s)" % (self.min, self.max)
+
+  >>> IRange.validateInvariants(Range(1,2))
+  >>> IRange.validateInvariants(Range(1,1))
+  >>> IRange.validateInvariants(Range(2,1))
+  Traceback (most recent call last):
+  ...
+  RangeError: Range(2, 1)
+
+В случае нескольких инвариантов мы можем захотеть остановить проверку после
+первой ошибки. Если мы передадим в `validateInvariants` пустой список, тогда
+будет выкинуто единственное исключение `Invalid` со списком исключений
+как аргументом::
+
+  >>> from zope.interface.exceptions import Invalid
+  >>> errors = 
+  >>> try:
+  ...     IRange.validateInvariants(Range(2,1), errors)
+  ... except Invalid, e:
+  ...     str(e)
+  'RangeError(Range(2, 1))'
+
+И список будет заполнен индивидуальными исключениями::
+
+  >>> errors
+  RangeError(Range(2, 1))
+
+  >>> del errors:
+
+Адаптация
+=========
+
+Интерфейсы могут быть вызваны для осуществления адаптации. Эта семантика
+основана на функции adapt из PEP 246. Если объект не может быть адаптирован,
+будет выкинут TypeError::
+
+  >>> class I(zope.interface.Interface):
+  ...     pass
+
+  >>> I(0)
+  Traceback (most recent call last):
+  ...
+  TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)
+
+только если альтернативное значение не передано как второй аргумент::
+
+  >>> I(0, 'bob')
+  'bob'
+
+Если объект уже реализует нужный интерфейс, он будет возвращен::
+
+  >>> class C(object):
+  ...     zope.interface.implements(I)
+
+  >>> obj = C()
+  >>> I(obj) is obj
+  True
+
+Если объект реализует __conform__, тогда она будет использована::
+
+  >>> class C(object):
+  ...     zope.interface.implements(I)
+  ...     def __conform__(self, proto):
+  ...          return 0
+
+  >>> I(C())
+  0
+
+Также если присутствуют функции для вызова адаптации (см. __adapt__) они будут
+использованы::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> def adapt_0_to_42(iface, obj):
+  ...     if obj == 0:
+  ...         return 42
+
+  >>> adapter_hooks.append(adapt_0_to_42)
+  >>> I(0)
+  42
+
+  >>> adapter_hooks.remove(adapt_0_to_42)
+  >>> I(0)
+  Traceback (most recent call last):
+  ...
+  TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)
+
+
+__adapt__
+---------
+
+::
+
+  >>> class I(zope.interface.Interface):
+  ...     pass
+
+Интерфейсы реализуют метод __adapt__ из PEP 246. Этот метод обычно не
+вызывается напрямую. Он вызывается архитектурой адаптации из PEP 246 и методом
+__call__ интерфейсов. Метод адаптации отвечает за адаптацию объекта к
+получателю. Версия по умолчанию возвращает `None`::
+
+  >>> I.__adapt__(0)
+
+если только переданный объект не предоставляет нужный интерфейс::
+
+  >>> class C(object):
+  ...     zope.interface.implements(I)
+
+  >>> obj = C()
+  >>> I.__adapt__(obj) is obj
+  True
+
+Функции для вызова адаптации могут быть добавлены (или удалены) для
+предоставления адаптации "на заказ". Мы установим глупую функцию которая
+адаптирует 0 к 42. Мы устанавливаем функцию просто добавляя ее к списку
+`adapter_hooks`::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> def adapt_0_to_42(iface, obj):
+  ...     if obj == 0:
+  ...         return 42
+
+  >>> adapter_hooks.append(adapt_0_to_42)
+  >>> I.__adapt__(0)
+  42
+
+Функции должны возвращать либо адаптер, либо `None`, если адаптер не найден.
+Функции могут быть удалены удалением их из списка::
+
+  >>> adapter_hooks.remove(adapt_0_to_42)
+  >>> I.__adapt__(0)
+
+
+.. #create Основная причина по которой мы наследуемся от `Interface` - это
+             что бы быть уверенными в том, что ключевое слово class будет
+             создавать интерфейс, а не класс.
+
+             Есть возможность создать интерфейсы вызвав специальный
+             класс интерфейса напрямую. Делая это, возможно (и в редких
+             случаях полезно) создать интерфейсы которые не наследуются
+             от `Interface`. Однако использование этой техники выходит
+	     за рамки данного документа.
+
+.. #factory Классы - это фабрики. Они могут быть вызваны для создания
+              своих экземпляров. Мы ожидаем что в итоге мы расширим
+              концепцию реализации на другие типы фабрик, таким образом
+              мы сможем объявлять интерфейсы предоставляемые созданными
+              фабриками объектами.
+
+.. #compat Цель - заменяемость. Объект который предоставляет расширенный
+             интерфейс должен быть заменяем в качестве объектов которые
+             предоставляют расширяемый интерфейс. В нашем примере объект
+             который предоставляет IBaz должен быть используемым и
+             в случае если ожидается объект который предоставляет IBlat.
+
+             Реализация интерфейса не требует этого. Но возможно в дальнейшем
+             она должна будет делать какие-либо проверки.

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/adapter.rst.txt Added

@@ -0,0 +1,690 @@
+.. _adapter-registry:
+
+==================
+ Adapter Registry
+==================
+
+Adapter registries provide a way to register objects that depend on
+one or more interface specifications and provide (perhaps indirectly)
+some interface.  In addition, the registrations have names. (You can
+think of the names as qualifiers of the provided interfaces.)
+
+The term "interface specification" refers both to interfaces and to
+interface declarations, such as declarations of interfaces implemented
+by a class.
+
+
+Single Adapters
+===============
+
+Let's look at a simple example, using a single required specification:
+
+.. doctest::
+
+  >>> from zope.interface.adapter import AdapterRegistry
+  >>> import zope.interface
+
+  >>> class IRequireBase(zope.interface.Interface):
+  ...     pass
+  >>> class IProvideBase(zope.interface.Interface):
+  ...     pass
+  >>> class IProvideChild(IProvideBase):
+  ...     pass
+
+  >>> registry = AdapterRegistry()
+
+We'll register an object that depends on ``IRequireBase`` and "provides" ``IProvideChild``:
+
+.. doctest::
+
+  >>> registry.register(IRequireBase, IProvideChild, '', 'Base->Child')
+
+Given the registration, we can look it up again:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireBase, IProvideChild, '')
+  'Base->Child'
+
+Note that we used an integer in the example.  In real applications,
+one would use some objects that actually depend on or provide
+interfaces. The registry doesn't care about what gets registered, so
+we'll use integers and strings to keep the examples simple. There is
+one exception.  Registering a value of ``None`` unregisters any
+previously-registered value.
+
+If an object depends on a specification, it can be looked up with a
+specification that extends the specification that it depends on:
+
+.. doctest::
+
+  >>> class IRequireChild(IRequireBase):
+  ...     pass
+  >>> registry.lookup(IRequireChild, IProvideChild, '')
+  'Base->Child'
+
+We can use a class implementation specification to look up the object:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IRequireChild)
+  ... class C2:
+  ...     pass
+
+  >>> registry.lookup(zope.interface.implementedBy(C2), IProvideChild, '')
+  'Base->Child'
+
+
+and it can be looked up for interfaces that its provided interface
+extends:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireBase, IProvideBase, '')
+  'Base->Child'
+  >>> registry.lookup(IRequireChild, IProvideBase, '')
+  'Base->Child'
+
+But if you require a specification that doesn't extend the specification the
+object depends on, you won't get anything:
+
+.. doctest::
+
+  >>> registry.lookup(zope.interface.Interface, IProvideBase, '')
+
+By the way, you can pass a default value to lookup:
+
+.. doctest::
+
+  >>> registry.lookup(zope.interface.Interface, IProvideBase, '', 42)
+  42
+
+If you try to get an interface the object doesn't provide, you also
+won't get anything:
+
+.. doctest::
+
+  >>> class IProvideGrandchild(IProvideChild):
+  ...     pass
+  >>> registry.lookup(IRequireBase, IProvideGrandchild, '')
+
+You also won't get anything if you use the wrong name:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireBase, IProvideBase, 'bob')
+  >>> registry.register(IRequireBase, IProvideChild, 'bob', "Bob's 12")
+  >>> registry.lookup(IRequireBase, IProvideBase, 'bob')
+  "Bob's 12"
+
+You can leave the name off when doing a lookup:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireBase, IProvideBase)
+  'Base->Child'
+
+If we register an object that provides ``IProvideBase``:
+
+.. doctest::
+
+  >>> registry.register(IRequireBase, IProvideBase, '', 'Base->Base')
+
+then that object will be preferred over ``O('Base->Child')``:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireBase, IProvideBase, '')
+  'Base->Base'
+
+Also, if we register an object for ``IRequireChild``, then that will be preferred
+when using ``IRequireChild``:
+
+.. doctest::
+
+  >>> registry.register(IRequireChild, IProvideBase, '', 'Child->Base')
+  >>> registry.lookup(IRequireChild, IProvideBase, '')
+  'Child->Base'
+
+Finding out what, if anything, is registered
+--------------------------------------------
+
+We can ask if there is an adapter registered for a collection of
+interfaces. This is different than lookup, because it looks for an
+exact match:
+
+.. doctest::
+
+  >>> print(registry.registered(IRequireBase, IProvideBase))
+  Base->Base
+
+  >>> print(registry.registered(IRequireBase, IProvideChild))
+  Base->Child
+
+  >>> print(registry.registered(IRequireBase, IProvideChild, 'bob'))
+  Bob's 12
+
+
+  >>> print(registry.registered(IRequireChild, IProvideBase))
+  Child->Base
+
+  >>> print(registry.registered(IRequireChild, IProvideChild))
+  None
+
+In the last example, ``None`` was returned because nothing was registered
+exactly for the given interfaces.
+
+lookup1
+-------
+
+Lookup of single adapters is common enough that there is a specialized
+version of lookup that takes a single required interface:
+
+.. doctest::
+
+  >>> registry.lookup1(IRequireChild, IProvideBase, '')
+  'Child->Base'
+  >>> registry.lookup1(IRequireChild, IProvideBase)
+  'Child->Base'
+
+Actual Adaptation
+-----------------
+
+The adapter registry is intended to support adaptation, where one
+object that implements an interface is adapted to another object that
+supports a different interface.  The adapter registry supports the
+computation of adapters. In this case, we have to register adapter
+factories:
+
+.. doctest::
+
+   >>> class IR(zope.interface.Interface):
+   ...     pass
+
+   >>> @zope.interface.implementer(IR)
+   ... class X(object):
+   ...     pass
+
+   >>> @zope.interface.implementer(IProvideBase)
+   ... class Y(object):
+   ...     def __init__(self, context):
+   ...         self.context = context
+
+  >>> registry.register(IR, IProvideBase, '', Y)
+
+In this case, we registered a class as the factory. Now we can call
+``queryAdapter`` to get the adapted object:
+
+.. doctest::
+
+  >>> x = X()
+  >>> y = registry.queryAdapter(x, IProvideBase)
+  >>> y.__class__.__name__
+  'Y'
+  >>> y.context is x
+  True
+
+We can register and lookup by name too:
+
+.. doctest::
+
+  >>> class Y2(Y):
+  ...     pass
+
+  >>> registry.register(IR, IProvideBase, 'bob', Y2)
+  >>> y = registry.queryAdapter(x, IProvideBase, 'bob')
+  >>> y.__class__.__name__
+  'Y2'
+  >>> y.context is x
+  True
+
+Passing ``super`` objects works as expected to find less specific adapters:
+
+.. doctest::
+
+  >>> class IDerived(IR):
+  ...     pass
+  >>> @zope.interface.implementer(IDerived)
+  ... class Derived(X):
+  ...     pass
+  >>> class DerivedAdapter(Y):
+  ...     def query_next(self):
+  ...        return registry.queryAdapter(
+  ...            super(type(self.context), self.context),
+  ...            IProvideBase)
+  >>> registry.register(IDerived, IProvideBase, '', DerivedAdapter)
+  >>> derived = Derived()
+  >>> adapter = registry.queryAdapter(derived, IProvideBase)
+  >>> adapter.__class__.__name__
+  'DerivedAdapter'
+  >>> adapter = adapter.query_next()
+  >>> adapter.__class__.__name__
+  'Y'
+
+When the adapter factory produces ``None``, then this is treated as if no
+adapter has been found. This allows us to prevent adaptation (when desired)
+and let the adapter factory determine whether adaptation is possible based on
+the state of the object being adapted:
+
+.. doctest::
+
+  >>> def factory(context):
+  ...     if context.name == 'object':
+  ...         return 'adapter'
+  ...     return None
+
+  >>> @zope.interface.implementer(IR)
+  ... class Object(object):
+  ...     name = 'object'
+
+  >>> registry.register(IR, IProvideBase, 'conditional', factory)
+  >>> obj = Object()
+  >>> registry.queryAdapter(obj, IProvideBase, 'conditional')
+  'adapter'
+  >>> obj.name = 'no object'
+  >>> registry.queryAdapter(obj, IProvideBase, 'conditional') is None
+  True
+  >>> registry.queryAdapter(obj, IProvideBase, 'conditional', 'default')
+  'default'
+
+An alternate method that provides the same function as ``queryAdapter()`` is
+`adapter_hook()`:
+
+.. doctest::
+
+  >>> y = registry.adapter_hook(IProvideBase, x)
+  >>> y.__class__.__name__
+  'Y'
+  >>> y.context is x
+  True
+  >>> y = registry.adapter_hook(IProvideBase, x, 'bob')
+  >>> y.__class__.__name__
+  'Y2'
+  >>> y.context is x
+  True
+
+The ``adapter_hook()`` simply switches the order of the object and
+interface arguments.  It is used to hook into the interface call
+mechanism.
+
+
+Default Adapters
+----------------
+
+Sometimes, you want to provide an adapter that will adapt anything.
+For that, provide ``None`` as the required interface:
+
+.. doctest::
+
+  >>> registry.register(None, IProvideBase, '', 1)
+
+then we can use that adapter for interfaces we don't have specific
+adapters for:
+
+.. doctest::
+
+  >>> class IQ(zope.interface.Interface):
+  ...     pass
+  >>> registry.lookup(IQ, IProvideBase, '')
+  1
+
+Of course, specific adapters are still used when applicable:
+
+.. doctest::
+
+  >>> registry.lookup(IRequireChild, IProvideBase, '')
+  'Child->Base'
+
+
+Class adapters
+--------------
+
+You can register adapters for class declarations, which is almost the
+same as registering them for a class:
+
+.. doctest::
+
+  >>> registry.register(zope.interface.implementedBy(C2), IProvideBase, '', 'C21')
+  >>> registry.lookup(zope.interface.implementedBy(C2), IProvideBase, '')
+  'C21'
+
+Dict adapters
+-------------
+
+At some point it was impossible to register dictionary-based adapters due a
+bug. Let's make sure this works now:
+
+.. doctest::
+
+  >>> adapter = {}
+  >>> registry.register((), IQ, '', adapter)
+  >>> registry.lookup((), IQ, '') is adapter
+  True
+
+Unregistering
+-------------
+
+You can unregister by registering ``None``, rather than an object:
+
+.. doctest::
+
+  >>> registry.register(zope.interface.implementedBy(C2), IProvideBase, '', None)
+  >>> registry.lookup(zope.interface.implementedBy(C2), IProvideBase, '')
+  'Child->Base'
+
+Of course, this means that ``None`` can't be registered. This is an
+exception to the statement, made earlier, that the registry doesn't
+care what gets registered.
+
+Multi-adapters
+==============
+
+You can adapt multiple specifications:
+
+.. doctest::
+
+  >>> registry.register(IRequireBase, IQ, IProvideChild, '', '1q2')
+  >>> registry.lookup(IRequireBase, IQ, IProvideChild, '')
+  '1q2'
+  >>> registry.lookup(IRequireChild, IQ, IProvideBase, '')
+  '1q2'
+
+  >>> class IS(zope.interface.Interface):
+  ...     pass
+  >>> registry.lookup(IRequireChild, IS, IProvideBase, '')
+
+  >>> class IQ2(IQ):
+  ...     pass
+
+  >>> registry.lookup(IRequireChild, IQ2, IProvideBase, '')
+  '1q2'
+
+  >>> registry.register(IRequireBase, IQ2, IProvideChild, '', '(Base,Q2)->Child')
+  >>> registry.lookup(IRequireChild, IQ2, IProvideBase, '')
+  '(Base,Q2)->Child'
+
+Multi-adaptation
+----------------
+
+You can adapt multiple objects:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IQ)
+  ... class Q:
+  ...     pass
+
+As with single adapters, we register a factory, which is often a class:
+
+.. doctest::
+
+  >>> class IM(zope.interface.Interface):
+  ...     pass
+  >>> @zope.interface.implementer(IM)
+  ... class M:
+  ...     def __init__(self, x, q):
+  ...         self.x, self.q = x, q
+  >>> registry.register(IR, IQ, IM, '', M)
+
+And then we can call ``queryMultiAdapter`` to compute an adapter:
+
+.. doctest::
+
+  >>> q = Q()
+  >>> m = registry.queryMultiAdapter((x, q), IM)
+  >>> m.__class__.__name__
+  'M'
+  >>> m.x is x and m.q is q
+  True
+
+and, of course, we can use names:
+
+.. doctest::
+
+  >>> class M2(M):
+  ...     pass
+  >>> registry.register(IR, IQ, IM, 'bob', M2)
+  >>> m = registry.queryMultiAdapter((x, q), IM, 'bob')
+  >>> m.__class__.__name__
+  'M2'
+  >>> m.x is x and m.q is q
+  True
+
+Default Adapters
+----------------
+
+As with single adapters, you can define default adapters by specifying
+``None`` for the *first* specification:
+
+.. doctest::
+
+  >>> registry.register(None, IQ, IProvideChild, '', '(None,Q)->Child')
+  >>> registry.lookup(IS, IQ, IProvideChild, '')
+  '(None,Q)->Child'
+
+Null Adapters
+=============
+
+You can also adapt **no** specification:
+
+.. doctest::
+
+  >>> registry.register(, IProvideChild, '', '->Child')
+  >>> registry.lookup(, IProvideChild, '')
+  '->Child'
+  >>> registry.lookup(, IProvideBase, '')
+  '->Child'
+
+Listing named adapters
+----------------------
+
+Adapters are named. Sometimes, it's useful to get all of the named
+adapters for given interfaces:
+
+.. doctest::
+
+  >>> adapters = list(registry.lookupAll(IRequireBase, IProvideBase))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', 'Base->Base'), (u'bob', "Bob's 12")
+
+This works for multi-adapters too:
+
+.. doctest::
+
+  >>> registry.register(IRequireBase, IQ2, IProvideChild, 'bob', '(Base,Q2)->Child for bob')
+  >>> adapters = list(registry.lookupAll(IRequireChild, IQ2, IProvideBase))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', '(Base,Q2)->Child'), (u'bob', '(Base,Q2)->Child for bob')
+
+And even null adapters:
+
+.. doctest::
+
+  >>> registry.register(, IProvideChild, 'bob', 3)
+  >>> adapters = list(registry.lookupAll(, IProvideBase))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', '->Child'), (u'bob', 3)
+
+Subscriptions
+=============
+
+Normally, we want to look up an object that most closely matches a
+specification.  Sometimes, we want to get all of the objects that
+match some specification.  We use *subscriptions* for this.  We
+subscribe objects against specifications and then later find all of
+the subscribed objects:
+
+.. doctest::
+
+  >>> registry.subscribe(IRequireBase, IProvideChild, 'Base->Child (1)')
+  >>> registry.subscriptions(IRequireBase, IProvideChild)
+  'Base->Child (1)'
+
+Note that, unlike regular adapters, subscriptions are unnamed.
+
+You can have multiple subscribers for the same specification:
+
+.. doctest::
+
+  >>> registry.subscribe(IRequireBase, IProvideChild, 'Base->Child (2)')
+  >>> registry.subscriptions(IRequireBase, IProvideChild)
+  'Base->Child (1)', 'Base->Child (2)'
+
+If subscribers are registered for the same required interfaces, they
+are returned in the order of definition.
+
+You can register subscribers for all specifications using ``None``:
+
+.. doctest::
+
+  >>> registry.subscribe(None, IProvideBase, 'None->Base')
+  >>> registry.subscriptions(IRequireChild, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)'
+
+Note that the new subscriber is returned first.
+
+Subscribers defined for less specific required interfaces are returned
+before subscribers for more specific interfaces:
+
+.. doctest::
+
+  >>> class IRequireGrandchild(IRequireChild):
+  ...     pass
+  >>> registry.subscribe(IRequireChild, IProvideBase, 'Child->Base')
+  >>> registry.subscribe(IRequireGrandchild, IProvideBase, 'Grandchild->Base')
+  >>> registry.subscriptions(IRequireGrandchild, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)', 'Child->Base', 'Grandchild->Base'
+
+Subscriptions may be combined over multiple compatible specifications:
+
+.. doctest::
+
+  >>> registry.subscriptions(IRequireChild, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)', 'Child->Base'
+  >>> registry.subscribe(IRequireBase, IProvideBase, 'Base->Base')
+  >>> registry.subscriptions(IRequireChild, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)', 'Base->Base', 'Child->Base'
+  >>> registry.subscribe(IRequireChild, IProvideChild, 'Child->Child')
+  >>> registry.subscriptions(IRequireChild, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)', 'Base->Base', 'Child->Child', 'Child->Base'
+  >>> registry.subscriptions(IRequireChild, IProvideChild)
+  'Base->Child (1)', 'Base->Child (2)', 'Child->Child'
+
+Subscriptions can be on multiple specifications:
+
+.. doctest::
+
+  >>> registry.subscribe(IRequireBase, IQ, IProvideChild, '(Base,Q)->Child')
+  >>> registry.subscriptions(IRequireBase, IQ, IProvideChild)
+  '(Base,Q)->Child'
+
+As with single subscriptions and non-subscription adapters, you can
+specify ``None`` for the first required interface, to specify a default:
+
+.. doctest::
+
+  >>> registry.subscribe(None, IQ, IProvideChild, '(None,Q)->Child')
+  >>> registry.subscriptions(IS, IQ, IProvideChild)
+  '(None,Q)->Child'
+  >>> registry.subscriptions(IRequireBase, IQ, IProvideChild)
+  '(None,Q)->Child', '(Base,Q)->Child'
+
+You can have subscriptions that are independent of any specifications:
+
+.. doctest::
+
+  >>> list(registry.subscriptions(, IProvideBase))
+  
+
+  >>> registry.subscribe(, IProvideChild, 'sub2')
+  >>> registry.subscriptions(, IProvideBase)
+  'sub2'
+  >>> registry.subscribe(, IProvideBase, 'sub1')
+  >>> registry.subscriptions(, IProvideBase)
+  'sub2', 'sub1'
+  >>> registry.subscriptions(, IProvideChild)
+  'sub2'
+
+Unregistering subscribers
+-------------------------
+
+We can unregister subscribers.  When unregistering a subscriber, we
+can unregister a *specific* subscriber:
+
+.. doctest::
+
+  >>> registry.unsubscribe(IRequireBase, IProvideBase, 'Base->Base')
+  >>> registry.subscriptions(IRequireBase, IProvideBase)
+  'None->Base', 'Base->Child (1)', 'Base->Child (2)'
+
+If we don't specify a value, then *all* subscribers matching the given
+interfaces will be unsubscribed:
+
+.. doctest::
+
+  >>> registry.unsubscribe(IRequireBase, IProvideChild)
+  >>> registry.subscriptions(IRequireBase, IProvideBase)
+  'None->Base'
+
+
+Subscription adapters
+---------------------
+
+We normally register adapter factories, which then allow us to compute
+adapters, but with subscriptions, we get multiple adapters.  Here's an
+example of multiple-object subscribers:
+
+.. doctest::
+
+  >>> registry.subscribe(IR, IQ, IM, M)
+  >>> registry.subscribe(IR, IQ, IM, M2)
+
+  >>> subscribers = registry.subscribers((x, q), IM)
+  >>> len(subscribers)
+  2
+  >>> class_names = s.__class__.__name__ for s in subscribers
+  >>> class_names.sort()
+  >>> class_names
+  'M', 'M2'
+  >>> (s.x is x and s.q is q) for s in subscribers
+  True, True
+
+Adapter factory subscribers can't return ``None`` values:
+
+.. doctest::
+
+  >>> def M3(x, y):
+  ...     return None
+
+  >>> registry.subscribe(IR, IQ, IM, M3)
+  >>> subscribers = registry.subscribers((x, q), IM)
+  >>> len(subscribers)
+  2
+
+Handlers
+--------
+
+A handler is a subscriber factory that doesn't produce any normal
+output.  It returns ``None``.  A handler is unlike adapters in that it does
+all of its work when the factory is called.
+
+To register a handler, simply provide ``None`` as the provided interface:
+
+.. doctest::
+
+  >>> def handler(event):
+  ...     print('handler', event)
+
+  >>> registry.subscribe(IRequireBase, None, handler)
+  >>> registry.subscriptions(IRequireBase, None) == handler
+  True
+
+
+Components
+==========
+
+A :class:`zope.interface.registry.Components` object implements the
+:class:`zope.interface.interfaces.IComponents` interface. This
+interface uses multiple adapter registries to implement multiple
+higher-level concerns (utilities, adapters and handlers), while also
+providing event notifications and query capabilities.

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/adapter.ru.rst.txt Added

@@ -0,0 +1,540 @@
+================
+Реестр адаптеров
+================
+
+.. contents::
+
+Реестры адаптеров предоставляют возможность для регистрации объектов которые
+зависят от одной, или нескольких спецификаций интерфейсов и предоставляют
+(возможно не напрямую) какой-либо интерфейс. В дополнение, регистрации имеют
+имена. (Можно думать об именах как о спецификаторах предоставляемого
+интерфейса.)
+
+Термин "спецификация интерфейса" ссылается и на интерфейсы и на определения
+интерфейсов, такие как определения интерфейсов реализованных некоторым классом.
+
+Одиночные адаптеры
+==================
+
+Давайте рассмотрим простой пример использующий единственную требуемую
+спецификацию::
+
+  >>> from zope.interface.adapter import AdapterRegistry
+  >>> import zope.interface
+
+  >>> class IR1(zope.interface.Interface):
+  ...     pass
+  >>> class IP1(zope.interface.Interface):
+  ...     pass
+  >>> class IP2(IP1):
+  ...     pass
+
+  >>> registry = AdapterRegistry()
+
+Мы зарегистрируем объект который зависит от IR1 и "предоставляет" IP2::
+
+  >>> registry.register(IR1, IP2, '', 12)
+
+После регистрации мы можем запросить объект снова::
+
+  >>> registry.lookup(IR1, IP2, '')
+  12
+
+Заметьте, что мы используем целое в этом примере. В реальных приложениях вы
+можете использовать объекты которые на самом деле зависят или предоставляют
+интерфейсы. Реестр не заботиться о том, что регистрируется и таким образом мы
+можем использовать целые, или строки что бы упростить наши примеры. Здесь есть
+одно исключение. Регистрация значения None удаляет регистрацию для любого
+зарегистрированного прежде значения.
+
+Если объект зависит от спецификации он может быть запрошен с помощью
+спецификации которая расширяет спецификацию от которой он зависит::
+
+  >>> class IR2(IR1):
+  ...     pass
+  >>> registry.lookup(IR2, IP2, '')
+  12
+
+Мы можем использовать класс реализующий спецификацию для запроса объекта::
+
+  >>> class C2:
+  ...     zope.interface.implements(IR2)
+
+  >>> registry.lookup(zope.interface.implementedBy(C2), IP2, '')
+  12
+
+и объект может быть запрошен для интерфейсов которые предоставляемый объектом
+интерфейс расширяет::
+
+  >>> registry.lookup(IR1, IP1, '')
+  12
+  >>> registry.lookup(IR2, IP1, '')
+  12
+
+Но если вы требуете спецификацию которая не расширяет спецификацию от которой
+зависит объект, вы не получите ничего::
+
+  >>> registry.lookup(zope.interface.Interface, IP1, '')
+
+Между прочим, вы можете передать значение по умолчанию при запросе::
+
+  >>> registry.lookup(zope.interface.Interface, IP1, '', 42)
+  42
+
+Если вы пробуете получить интерфейс который объект не предоставляет вы также
+не получите ничего::
+
+  >>> class IP3(IP2):
+  ...     pass
+  >>> registry.lookup(IR1, IP3, '')
+
+Вы также не получите ничего если вы используете неверное имя::
+
+  >>> registry.lookup(IR1, IP1, 'bob')
+  >>> registry.register(IR1, IP2, 'bob', "Bob's 12")
+  >>> registry.lookup(IR1, IP1, 'bob')
+  "Bob's 12"
+
+Вы можете не использовать имя при запросе::
+
+  >>> registry.lookup(IR1, IP1)
+  12
+
+Если мы регистрируем объект который предоставляет IP1::
+
+  >>> registry.register(IR1, IP1, '', 11)
+
+тогда этот объект будет иметь преимущество перед O(12)::
+
+  >>> registry.lookup(IR1, IP1, '')
+  11
+
+Также, если мы регистрируем объект для IR2 тогда он будет иметь преимущество
+когда используется IR2::
+
+  >>> registry.register(IR2, IP1, '', 21)
+  >>> registry.lookup(IR2, IP1, '')
+  21
+
+Поиск того, что (если вообще что-то) зарегистрировано
+-----------------------------------------------------
+
+Мы можем спросить есть-ли адаптер зарегистрированный для набора интерфейсов.
+Это отличается от обычного запроса так как здесь мы ищем точное совпадение::
+
+  >>> print registry.registered(IR1, IP1)
+  11
+
+  >>> print registry.registered(IR1, IP2)
+  12
+
+  >>> print registry.registered(IR1, IP2, 'bob')
+  Bob's 12
+  
+
+  >>> print registry.registered(IR2, IP1)
+  21
+
+  >>> print registry.registered(IR2, IP2)
+  None
+
+В последнем примере, None был возвращен потому, что для данного интерфейса
+ничего не было зарегистрировано.
+
+lookup1
+-------
+
+Запрос одиночного адаптера - это наиболее частая операция и для нее есть
+специализированная версия запроса которая получает на вход единственный
+требуемый интерфейс::
+
+  >>> registry.lookup1(IR2, IP1, '')
+  21
+  >>> registry.lookup1(IR2, IP1)
+  21
+
+Адаптация на практике
+---------------------
+
+Реестр адаптеров предназначен для поддержки адаптации когда один объект
+реализующий интерфейс адаптируется к другому объекту который поддерживает
+другой интерфейс. Реестр адаптеров также поддерживает вычисление адаптеров. В
+этом случае мы должны регистрировать фабрики для адаптеров::
+
+   >>> class IR(zope.interface.Interface):
+   ...     pass
+
+   >>> class X:
+   ...     zope.interface.implements(IR)
+           
+   >>> class Y:
+   ...     zope.interface.implements(IP1)
+   ...     def __init__(self, context):
+   ...         self.context = context
+
+  >>> registry.register(IR, IP1, '', Y)
+
+В этом случае мы регистрируем класс как фабрику. Теперь мы можем вызвать
+`queryAdapter` для получения адаптированного объекта::
+
+  >>> x = X()
+  >>> y = registry.queryAdapter(x, IP1)
+  >>> y.__class__.__name__
+  'Y'
+  >>> y.context is x
+  True
+
+Мы также можем регистрировать и запрашивать по имени::
+
+  >>> class Y2(Y):
+  ...     pass
+
+  >>> registry.register(IR, IP1, 'bob', Y2)
+  >>> y = registry.queryAdapter(x, IP1, 'bob')
+  >>> y.__class__.__name__
+  'Y2'
+  >>> y.context is x
+  True
+
+Когда фабрика для адаптера возвращает `None` - это рассматривается как если бы
+адаптер не был найден. Это позволяет нам избежать адаптации (по желанию) и дает
+возможность фабрике адаптера определить возможна ли адаптация основываясь на
+состоянии объекта который адаптируется::
+
+  >>> def factory(context):
+  ...     if context.name == 'object':
+  ...         return 'adapter'
+  ...     return None
+
+  >>> class Object(object):
+  ...     zope.interface.implements(IR)
+  ...     name = 'object'
+
+  >>> registry.register(IR, IP1, 'conditional', factory) 
+  >>> obj = Object()
+  >>> registry.queryAdapter(obj, IP1, 'conditional')
+  'adapter'
+  >>> obj.name = 'no object'
+  >>> registry.queryAdapter(obj, IP1, 'conditional') is None
+  True
+  >>> registry.queryAdapter(obj, IP1, 'conditional', 'default')
+  'default'
+
+Альтернативный метод для предоставления такой же функциональности как и
+`queryAdapter()` - это `adapter_hook()`::
+
+  >>> y = registry.adapter_hook(IP1, x)
+  >>> y.__class__.__name__
+  'Y'
+  >>> y.context is x
+  True
+  >>> y = registry.adapter_hook(IP1, x, 'bob')
+  >>> y.__class__.__name__
+  'Y2'
+  >>> y.context is x
+  True
+
+`adapter_hook()` просто меняет порядок аргументов для объекта и интерфейса. Это
+используется для встраивания в механизм вызовов интерфейсов.
+
+Адаптеры по умолчанию
+---------------------
+
+Иногда вы можете захотеть предоставить адаптер который не будет ничего
+адаптировать. Для этого нужно передать None как требуемый интерфейс::
+
+  >>> registry.register(None, IP1, '', 1)
+
+после этого вы можете использовать этот адаптер для интерфейсов для которых у
+вас нет конкретного адаптера::
+
+  >>> class IQ(zope.interface.Interface):
+  ...     pass
+  >>> registry.lookup(IQ, IP1, '')
+  1
+
+Конечно, конкретные адаптеры все еще используются когда необходимо::
+
+  >>> registry.lookup(IR2, IP1, '')
+  21
+
+Адаптеры классов
+----------------
+
+Вы можете регистрировать адаптеры для определений классов, что будет похоже на
+регистрацию их для классов::
+
+  >>> registry.register(zope.interface.implementedBy(C2), IP1, '', 'C21')
+  >>> registry.lookup(zope.interface.implementedBy(C2), IP1, '')
+  'C21'
+
+Адаптеры для словарей
+---------------------
+
+В какой-то момент было невозможно регистрировать адаптеры основанные на
+словарях из-за ошибки. Давайте удостоверимся что это теперь работает::
+
+  >>> adapter = {}
+  >>> registry.register((), IQ, '', adapter)
+  >>> registry.lookup((), IQ, '') is adapter
+  True
+
+Удаление регистрации
+--------------------
+
+Вы можете удалить регистрацию регистрируя None вместо объекта::
+
+  >>> registry.register(zope.interface.implementedBy(C2), IP1, '', None)
+  >>> registry.lookup(zope.interface.implementedBy(C2), IP1, '')
+  21
+
+Конечно это значит, что None не может быть зарегистрирован. Это исключение к
+утверждению выше о том, что реестр не заботиться о том, что регистрируется.
+
+Мульти-адаптеры
+===============
+
+Вы можете адаптировать несколько спецификаций::
+
+  >>> registry.register(IR1, IQ, IP2, '', '1q2')
+  >>> registry.lookup(IR1, IQ, IP2, '')
+  '1q2'
+  >>> registry.lookup(IR2, IQ, IP1, '')
+  '1q2'
+
+  >>> class IS(zope.interface.Interface):
+  ...     pass
+  >>> registry.lookup(IR2, IS, IP1, '')
+
+  >>> class IQ2(IQ):
+  ...     pass
+
+  >>> registry.lookup(IR2, IQ2, IP1, '')
+  '1q2'
+
+  >>> registry.register(IR1, IQ2, IP2, '', '1q22')
+  >>> registry.lookup(IR2, IQ2, IP1, '')
+  '1q22'
+
+Мульти-адаптация
+----------------
+
+Вы можете адаптировать несколько объектов::
+
+  >>> class Q:
+  ...     zope.interface.implements(IQ)
+
+Как и с одиночными адаптерами, мы регистрируем фабрику которая возвращает
+класс::
+
+  >>> class IM(zope.interface.Interface):
+  ...     pass
+  >>> class M:
+  ...     zope.interface.implements(IM)
+  ...     def __init__(self, x, q):
+  ...         self.x, self.q = x, q
+  >>> registry.register(IR, IQ, IM, '', M)
+
+И затем мы можем вызвать `queryMultiAdapter` для вычисления адаптера::
+
+  >>> q = Q()
+  >>> m = registry.queryMultiAdapter((x, q), IM)
+  >>> m.__class__.__name__
+  'M'
+  >>> m.x is x and m.q is q
+  True
+
+и, конечно, мы можем использовать имена::
+
+  >>> class M2(M):
+  ...     pass
+  >>> registry.register(IR, IQ, IM, 'bob', M2)
+  >>> m = registry.queryMultiAdapter((x, q), IM, 'bob')
+  >>> m.__class__.__name__
+  'M2'
+  >>> m.x is x and m.q is q
+  True
+
+Адаптеры по умолчанию
+---------------------
+
+Как и для одиночных адаптеров вы можете определить адаптер по умолчанию передав
+None вместо *первой* спецификации::
+
+  >>> registry.register(None, IQ, IP2, '', 'q2')
+  >>> registry.lookup(IS, IQ, IP2, '')
+  'q2'
+
+Нулевые адаптеры
+================
+
+Вы можете также адаптировать без спецификации::
+
+  >>> registry.register(, IP2, '', 2)
+  >>> registry.lookup(, IP2, '')
+  2
+  >>> registry.lookup(, IP1, '')
+  2
+
+Перечисление именованных адаптеров
+----------------------------------
+
+Адаптеры имеют имена. Иногда это полезно для получения всех именованных
+адаптеров для заданного интерфейса::
+
+  >>> adapters = list(registry.lookupAll(IR1, IP1))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', 11), (u'bob', "Bob's 12")
+
+Это работает также и для мульти-адаптеров::
+
+  >>> registry.register(IR1, IQ2, IP2, 'bob', '1q2 for bob')
+  >>> adapters = list(registry.lookupAll(IR2, IQ2, IP1))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', '1q22'), (u'bob', '1q2 for bob')
+
+И даже для нулевых адаптеров::
+
+  >>> registry.register(, IP2, 'bob', 3)
+  >>> adapters = list(registry.lookupAll(, IP1))
+  >>> adapters.sort()
+  >>> assert adapters == (u'', 2), (u'bob', 3)
+
+Подписки
+========
+
+Обычно мы хотим запросить объект который наиболее близко соответствует
+спецификации. Иногда мы хотим получить все объекты которые соответствуют
+какой-либо спецификации. Мы используем подписки для этого. Мы подписываем
+объекты для спецификаций и затем позже находим все подписанные объекты::
+
+  >>> registry.subscribe(IR1, IP2, 'sub12 1')
+  >>> registry.subscriptions(IR1, IP2)
+  'sub12 1'
+
+Заметьте, что в отличие от обычных адаптеров подписки не имеют имен.
+
+Вы можете иметь несколько подписчиков для одной спецификации::
+
+  >>> registry.subscribe(IR1, IP2, 'sub12 2')
+  >>> registry.subscriptions(IR1, IP2)
+  'sub12 1', 'sub12 2'
+
+Если подписчики зарегистрированы для одних и тех же требуемых интерфейсов, они
+возвращаются в порядке определения.
+
+Вы можете зарегистрировать подписчики для всех спецификаций используя None::
+
+  >>> registry.subscribe(None, IP1, 'sub_1')
+  >>> registry.subscriptions(IR2, IP1)
+  'sub_1', 'sub12 1', 'sub12 2'
+
+Заметьте, что новый подписчик возвращается первым. Подписчики определенные
+для менее общих требуемых интерфейсов возвращаются перед подписчиками
+для более общих интерфейсов.
+
+Подписки могут смешиваться между несколькими совместимыми спецификациями::
+
+  >>> registry.subscriptions(IR2, IP1)
+  'sub_1', 'sub12 1', 'sub12 2'
+  >>> registry.subscribe(IR1, IP1, 'sub11')
+  >>> registry.subscriptions(IR2, IP1)
+  'sub_1', 'sub12 1', 'sub12 2', 'sub11'
+  >>> registry.subscribe(IR2, IP2, 'sub22')
+  >>> registry.subscriptions(IR2, IP1)
+  'sub_1', 'sub12 1', 'sub12 2', 'sub11', 'sub22'
+  >>> registry.subscriptions(IR2, IP2)
+  'sub12 1', 'sub12 2', 'sub22'
+
+Подписки могут существовать для нескольких спецификаций::
+
+  >>> registry.subscribe(IR1, IQ, IP2, 'sub1q2')
+  >>> registry.subscriptions(IR1, IQ, IP2)
+  'sub1q2'
+
+Как и с одиночными подписчиками и адаптерами без подписок, вы можете определить
+None для первого требуемого интерфейса, что бы задать значение по умолчанию::
+
+  >>> registry.subscribe(None, IQ, IP2, 'sub_q2')
+  >>> registry.subscriptions(IS, IQ, IP2)
+  'sub_q2'
+  >>> registry.subscriptions(IR1, IQ, IP2)
+  'sub_q2', 'sub1q2'
+
+Вы можете создать подписки которые независимы от любых спецификаций::
+
+  >>> list(registry.subscriptions(, IP1))
+  
+
+  >>> registry.subscribe(, IP2, 'sub2')
+  >>> registry.subscriptions(, IP1)
+  'sub2'
+  >>> registry.subscribe(, IP1, 'sub1')
+  >>> registry.subscriptions(, IP1)
+  'sub2', 'sub1'
+  >>> registry.subscriptions(, IP2)
+  'sub2'
+
+Удаление регистрации подписчиков
+--------------------------------
+
+Мы можем удалять регистрацию подписчиков. При удалении регистрации подписчика
+мы можем удалить регистрацию заданного адаптера::
+
+  >>> registry.unsubscribe(IR1, IP1, 'sub11')
+  >>> registry.subscriptions(IR1, IP1)
+  'sub_1', 'sub12 1', 'sub12 2'
+
+Если мы не задаем никакого значения тогда подписки будут удалены для всех
+подписчиков совпадающих с заданным интерфейсом::
+
+  >>> registry.unsubscribe(IR1, IP2)
+  >>> registry.subscriptions(IR1, IP1)
+  'sub_1'
+
+Адаптеры подписки
+-----------------
+
+Обычно мы регистрируем фабрики для адаптеров которые затем позволяют нам
+вычислять адаптеры, но с подписками мы получаем несколько адаптеров. Это пример
+подписчика для нескольких объектов::
+
+  >>> registry.subscribe(IR, IQ, IM, M)
+  >>> registry.subscribe(IR, IQ, IM, M2)
+
+  >>> subscribers = registry.subscribers((x, q), IM)
+  >>> len(subscribers)
+  2
+  >>> class_names = s.__class__.__name__ for s in subscribers
+  >>> class_names.sort()
+  >>> class_names
+  'M', 'M2'
+  >>> (s.x is x and s.q is q) for s in subscribers
+  True, True
+
+подписчики фабрик адаптеров не могут возвращать None::
+
+  >>> def M3(x, y):
+  ...     return None
+
+  >>> registry.subscribe(IR, IQ, IM, M3)
+  >>> subscribers = registry.subscribers((x, q), IM)
+  >>> len(subscribers)
+  2
+
+Обработчики
+-----------
+
+Обработчик - это подписанная фабрика которая не возвращает нормального
+значения. Она возвращает None. Обработчик отличается от адаптеров тем, что он
+делает всю работу когда вызывается фабрика.
+
+Для регистрации обработчика надо просто передать None как предоставляемый
+интерфейс::
+
+  >>> def handler(event):
+  ...     print 'handler', event
+
+  >>> registry.subscribe(IR1, None, handler)
+  >>> registry.subscriptions(IR1, None) == handler
+  True

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/adapters.rst.txt Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/common.rst.txt Added

@@ -0,0 +1,50 @@
+====================================
+ Python Standard Library Interfaces
+====================================
+
+The ``zope.interface.common`` package provides interfaces for objects
+distributed as part of the Python standard library. Importing these
+modules (usually) has the effect of making the standard library objects
+implement the correct interface.
+
+zope.interface.common.interface
+===============================
+
+.. automodule:: zope.interface.common.interfaces
+
+zope.interface.common.idatetime
+===============================
+
+.. automodule:: zope.interface.common.idatetime
+
+zope.interface.common.collections
+=================================
+
+.. automodule:: zope.interface.common.collections
+
+zope.interface.common.numbers
+=============================
+
+.. automodule:: zope.interface.common.numbers
+
+zope.interface.common.builtins
+==============================
+
+.. automodule:: zope.interface.common.builtins
+
+zope.interface.common.io
+========================
+
+.. automodule:: zope.interface.common.io
+
+.. Deprecated or discouraged modules below this
+
+zope.interface.common.mapping
+=============================
+
+.. automodule:: zope.interface.common.mapping
+
+zope.interface.common.sequence
+==============================
+
+.. automodule:: zope.interface.common.sequence

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/components.rst.txt Added

@@ -0,0 +1,84 @@
+======================
+ Component Registries
+======================
+
+The component registry's API is defined by
+``zope.interface.interfaces.IComponents``:
+
+.. autointerface:: zope.interface.interfaces.IComponentLookup
+   :members:
+   :member-order: bysource
+
+
+.. autointerface:: zope.interface.interfaces.IComponentRegistry
+   :members:
+   :member-order: bysource
+
+.. autointerface:: zope.interface.interfaces.IComponents
+   :members:
+   :member-order: bysource
+
+One default implementation of `~zope.interface.interfaces.IComponents` is provided.
+
+.. autoclass:: zope.interface.registry.Components
+
+Events
+======
+
+Adding and removing components from the component registry create
+registration and unregistration events. Like most things, they are
+defined by an interface and a default implementation is provided.
+
+Registration
+------------
+
+.. autointerface:: zope.interface.interfaces.IObjectEvent
+.. autointerface:: zope.interface.interfaces.IRegistrationEvent
+
+.. autointerface:: zope.interface.interfaces.IRegistered
+.. autoclass:: zope.interface.interfaces.Registered
+
+.. autointerface:: zope.interface.interfaces.IUnregistered
+.. autoclass:: zope.interface.interfaces.Unregistered
+
+
+Details
+-------
+
+These are all types of ``IObjectEvent``, meaning they have an object
+that provides specific details about the event. Component registries
+create detail objects for four types of components they manage.
+
+All four share a common base interface.
+
+.. autointerface:: zope.interface.interfaces.IRegistration
+
+* Utilities
+
+  .. autointerface:: zope.interface.interfaces.IUtilityRegistration
+  .. autoclass:: zope.interface.registry.UtilityRegistration
+
+* Handlers
+
+  .. autointerface:: zope.interface.interfaces.IHandlerRegistration
+  .. autoclass:: zope.interface.registry.HandlerRegistration
+
+* Adapters
+
+  For ease of implementation, a shared base class is used for these
+  events. It should not be referenced by clients, but it is documented
+  to show the common attributes.
+
+  .. autointerface:: zope.interface.interfaces._IBaseAdapterRegistration
+
+  .. autointerface:: zope.interface.interfaces.IAdapterRegistration
+  .. autoclass:: zope.interface.registry.AdapterRegistration
+
+  .. autointerface:: zope.interface.interfaces.ISubscriptionAdapterRegistration
+  .. autoclass:: zope.interface.registry.SubscriptionRegistration
+
+Exceptions
+==========
+
+.. autoclass:: zope.interface.interfaces.ComponentLookupError
+.. autoclass:: zope.interface.interfaces.Invalid

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/declarations.rst.txt Added

@@ -0,0 +1,975 @@
+==================================================
+ Declaring and Checking The Interfaces of Objects
+==================================================
+
+Declaring what interfaces an object implements or provides, and later
+being able to check those, is an important part of this package.
+Declaring interfaces, in particular, can be done both statically at
+object definition time and dynamically later on.
+
+The functionality that allows declaring and checking interfaces is
+provided directly in the ``zope.interface`` module. It is described by
+the interface ``zope.interface.interfaces.IInterfaceDeclaration``. We
+will first look at that interface, and then we will look more
+carefully at each object it documents, including providing examples.
+
+.. autointerface:: zope.interface.interfaces.IInterfaceDeclaration
+
+
+.. currentmodule:: zope.interface
+
+Declaring Interfaces
+====================
+
+To declare an interface itself, extend the ``Interface`` base class.
+
+.. autointerface:: Interface
+   :noindex:
+
+.. autofunction:: taggedValue
+   :noindex:
+
+   .. documented more thoroughly in README.rst
+
+.. autofunction:: invariant
+   :noindex:
+
+   .. documented in README.rst
+
+.. autofunction:: interfacemethod
+
+Declaring The Interfaces of Objects
+===================================
+
+
+implementer
+-----------
+
+.. autoclass:: implementer
+
+
+implementer_only
+----------------
+
+.. autoclass:: implementer_only
+
+
+classImplementsOnly
+-------------------
+
+.. autofunction:: classImplementsOnly
+
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import implementedBy
+   >>> from zope.interface import implementer
+   >>> from zope.interface import classImplementsOnly
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(Interface): pass
+   ...
+   >>> @implementer(I3)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(I4)
+   ... class B(object):
+   ...     pass
+   >>> class C(A, B):
+   ...   pass
+   >>> classImplementsOnly(C, I1, I2)
+   >>> i.getName() for i in implementedBy(C)
+   'I1', 'I2'
+
+Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
+whatever interfaces instances of ``A`` and ``B`` implement.
+
+
+classImplements
+---------------
+
+.. autofunction:: classImplements
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import classImplements
+   >>> from zope.interface.ro import is_consistent
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class IA(Interface): pass
+   ...
+   >>> class IB(Interface): pass
+   ...
+   >>> class I5(Interface): pass
+   ...
+   >>> @implementer(IA)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> class C(A, B):
+   ...   pass
+   >>> classImplements(C, I1, I2)
+   >>> i.getName() for i in implementedBy(C)
+   'I1', 'I2', 'IA', 'IB'
+
+Instances of ``C`` provide ``I1`` and ``I2``, plus whatever
+instances of ``A`` and ``B`` provide.
+
+.. doctest::
+
+   >>> classImplements(C, I5)
+   >>> i.getName() for i in implementedBy(C)
+   'I1', 'I2', 'I5', 'IA', 'IB'
+
+Instances of ``C`` now also provide ``I5``. Notice how ``I5`` was
+added to the *end* of the list of things provided directly by ``C``.
+
+If we ask a class to implement an interface that extends
+an interface it already implements, that interface will go at the
+*beginning* of the list, in order to preserve a consistent resolution
+order.
+
+.. doctest::
+
+   >>> class I6(I5): pass
+   >>> class I7(IA): pass
+   >>> classImplements(C, I6, I7)
+   >>> i.getName() for i in implementedBy(C)
+   'I6', 'I1', 'I2', 'I5', 'I7', 'IA', 'IB'
+   >>> is_consistent(implementedBy(C))
+   True
+
+This cannot be used to introduce duplicates.
+
+.. doctest::
+
+   >>> classImplements(C, IA, IB, I1, I2)
+   >>> i.getName() for i in implementedBy(C)
+   'I6', 'I1', 'I2', 'I5', 'I7', 'IA', 'IB'
+
+
+classImplementsFirst
+--------------------
+
+.. autofunction:: classImplementsFirst
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import classImplements
+   >>> from zope.interface import classImplementsFirst
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class IA(Interface): pass
+   ...
+   >>> class IB(Interface): pass
+   ...
+   >>> class I5(Interface): pass
+   ...
+   >>> @implementer(IA)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> class C(A, B):
+   ...   pass
+   >>> classImplementsFirst(C, I2)
+   >>> classImplementsFirst(C, I1)
+   >>> i.getName() for i in implementedBy(C)
+   'I1', 'I2', 'IA', 'IB'
+
+Instances of ``C`` provide ``I1``, ``I2``, ``I5``, and whatever
+interfaces instances of ``A`` and ``B`` provide.
+
+.. doctest::
+
+   >>> classImplementsFirst(C, I5)
+   >>> i.getName() for i in implementedBy(C)
+   'I5', 'I1', 'I2', 'IA', 'IB'
+
+Instances of ``C`` now also provide ``I5``. Notice how ``I5`` was
+added to the *beginning* of the list of things provided directly by
+``C``. Unlike `classImplements`, this ignores interface inheritance
+and does not attempt to ensure a consistent resolution order (except
+that it continues to elide interfaces already implemented through
+class inheritance)::
+
+.. doctest::
+
+   >>> class IBA(IB, IA):
+   ...     pass
+   >>> classImplementsFirst(C, IBA)
+   >>> classImplementsFirst(C, IA)
+   >>> i.getName() for i in implementedBy(C)
+   'IBA', 'I5', 'I1', 'I2', 'IA', 'IB'
+
+This cannot be used to introduce duplicates.
+
+.. doctest::
+
+   >>> len(implementedBy(C).declared)
+   4
+   >>> classImplementsFirst(C, IA)
+   >>> classImplementsFirst(C, IBA)
+   >>> classImplementsFirst(C, IA)
+   >>> classImplementsFirst(C, IBA)
+   >>> i.getName() for i in implementedBy(C)
+   'IBA', 'I5', 'I1', 'I2', 'IA', 'IB'
+   >>> len(implementedBy(C).declared)
+   4
+
+
+directlyProvides
+----------------
+
+.. autofunction:: directlyProvides
+
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import providedBy
+   >>> from zope.interface import directlyProvides
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class IA1(Interface): pass
+   ...
+   >>> class IA2(Interface): pass
+   ...
+   >>> class IB(Interface): pass
+   ...
+   >>> class IC(Interface): pass
+   ...
+   >>> @implementer(IA1, IA2)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> @implementer(IC)
+   ... class C(A, B):
+   ...     pass
+   >>> ob = C()
+   >>> directlyProvides(ob, I1, I2)
+   >>> int(I1 in providedBy(ob))
+   1
+   >>> int(I2 in providedBy(ob))
+   1
+   >>> int(IA1 in providedBy(ob))
+   1
+   >>> int(IA2 in providedBy(ob))
+   1
+   >>> int(IB in providedBy(ob))
+   1
+   >>> int(IC in providedBy(ob))
+   1
+
+The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
+instances have been declared for instances of ``C``.
+
+To remove directly provided interfaces, use ``directlyProvidedBy`` and
+subtract the unwanted interfaces. For example:
+
+.. doctest::
+
+   >>> from zope.interface import directlyProvidedBy
+   >>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
+   >>> int(I1 in providedBy(ob))
+   1
+   >>> int(I2 in providedBy(ob))
+   0
+
+removes ``I2`` from the interfaces directly provided by ``ob``. The object,
+``ob`` no longer directly provides ``I2``, although it might still
+provide ``I2`` if its class implements ``I2``.
+
+To add directly provided interfaces, use ``directlyProvidedBy`` and
+include additional interfaces.  For example:
+
+.. doctest::
+
+   >>> int(I2 in providedBy(ob))
+   0
+   >>> from zope.interface import directlyProvidedBy
+   >>> directlyProvides(ob, directlyProvidedBy(ob), I2)
+
+adds ``I2`` to the interfaces directly provided by ``ob``:
+
+.. doctest::
+
+   >>> int(I2 in providedBy(ob))
+   1
+
+We need to avoid setting this attribute on meta classes that
+don't support descriptors.
+
+We can do away with this check when we get rid of the old EC
+
+
+alsoProvides
+------------
+
+.. autofunction:: alsoProvides
+
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import alsoProvides
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class IA1(Interface): pass
+   ...
+   >>> class IA2(Interface): pass
+   ...
+   >>> class IB(Interface): pass
+   ...
+   >>> class IC(Interface): pass
+   ...
+   >>> @implementer(IA1, IA2)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(IB)
+   ... class B(object):
+   ...     pass
+   >>> @implementer(IC)
+   ... class C(A, B):
+   ...     pass
+   >>> ob = C()
+   >>> directlyProvides(ob, I1)
+   >>> int(I1 in providedBy(ob))
+   1
+   >>> int(I2 in providedBy(ob))
+   0
+   >>> int(IA1 in providedBy(ob))
+   1
+   >>> int(IA2 in providedBy(ob))
+   1
+   >>> int(IB in providedBy(ob))
+   1
+   >>> int(IC in providedBy(ob))
+   1
+   >>> alsoProvides(ob, I2)
+   >>> int(I1 in providedBy(ob))
+   1
+   >>> int(I2 in providedBy(ob))
+   1
+   >>> int(IA1 in providedBy(ob))
+   1
+   >>> int(IA2 in providedBy(ob))
+   1
+   >>> int(IB in providedBy(ob))
+   1
+   >>> int(IC in providedBy(ob))
+   1
+
+The object, ``ob`` provides ``I1``, ``I2``, and whatever interfaces
+instances have been declared for instances of ``C``. Notice that the
+``alsoProvides`` just extends the provided interfaces.
+
+
+noLongerProvides
+----------------
+
+.. autofunction:: noLongerProvides
+
+Consider the following two interfaces:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+
+``I1`` is provided through the class, ``I2`` is directly provided
+by the object:
+
+.. doctest::
+
+   >>> @implementer(I1)
+   ... class C(object):
+   ...     pass
+   >>> c = C()
+   >>> alsoProvides(c, I2)
+   >>> I2.providedBy(c)
+   True
+
+Remove ``I2`` from ``c`` again:
+
+.. doctest::
+
+   >>> from zope.interface import noLongerProvides
+   >>> noLongerProvides(c, I2)
+   >>> I2.providedBy(c)
+   False
+
+Removing an interface that is provided through the class is not possible:
+
+.. doctest::
+
+   >>> noLongerProvides(c, I1)
+   Traceback (most recent call last):
+   ...
+   ValueError: Can only remove directly provided interfaces.
+
+
+provider
+--------
+
+.. autoclass:: provider
+
+For example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import implementer
+   >>> from zope.interface import provider
+   >>> class IFooFactory(Interface):
+   ...     pass
+   >>> class IFoo(Interface):
+   ...     pass
+   >>> @implementer(IFoo)
+   ... @provider(IFooFactory)
+   ... class C(object):
+   ...     pass
+   >>> i.getName() for i in C.__provides__
+   'IFooFactory'
+   >>> i.getName() for i in C().__provides__
+   'IFoo'
+
+Which is equivalent to:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class IFoo(Interface): pass
+   ...
+   >>> class IFooFactory(Interface): pass
+   ...
+   >>> @implementer(IFoo)
+   ... class C(object):
+   ...   pass
+   >>> directlyProvides(C, IFooFactory)
+   >>> i.getName() for i in C.__providedBy__
+   'IFooFactory'
+   >>> i.getName() for i in C().__providedBy__
+   'IFoo'
+
+
+moduleProvides
+--------------
+
+.. autofunction:: moduleProvides
+
+
+named
+-----
+
+.. autoclass:: zope.interface.declarations.named
+
+For example:
+
+.. doctest::
+
+   >>> from zope.interface.declarations import named
+
+   >>> @named('foo')
+   ... class Foo(object):
+   ...     pass
+
+   >>> Foo.__component_name__
+   'foo'
+
+When registering an adapter or utility component, the registry looks for the
+``__component_name__`` attribute and uses it, if no name was explicitly
+provided.
+
+
+Deprecated Functions
+--------------------
+
+implements
+~~~~~~~~~~
+
+.. caution:: Does not work on Python 3.  Use the `implementer` decorator instead.
+
+.. autofunction:: implements
+
+
+implementsOnly
+~~~~~~~~~~~~~~
+
+.. caution:: Does not work on Python 3.  Use the `implementer_only` decorator instead.
+
+.. autofunction:: implementsOnly
+
+
+classProvides
+~~~~~~~~~~~~~
+
+.. caution:: Does not work on Python 3.  Use the `provider` decorator instead.
+
+.. autofunction:: classProvides
+
+
+Querying The Interfaces Of Objects
+==================================
+
+All of these functions return an
+`~zope.interface.interfaces.IDeclaration`.
+You'll notice that an ``IDeclaration`` is a type of
+`~zope.interface.interfaces.ISpecification`, as is
+``zope.interface.Interface``, so they share some common behaviour.
+
+.. autointerface:: zope.interface.interfaces.IDeclaration
+   :members:
+   :member-order: bysource
+
+
+implementedBy
+-------------
+
+.. autofunction:: implementedBy
+
+
+Consider the following example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import implementer
+   >>> from zope.interface import classImplementsOnly
+   >>> from zope.interface import implementedBy
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(Interface): pass
+   ...
+   >>> @implementer(I3)
+   ... class A(object):
+   ...     pass
+   >>> @implementer(I4)
+   ... class B(object):
+   ...     pass
+   >>> class C(A, B):
+   ...   pass
+   >>> classImplementsOnly(C, I1, I2)
+   >>> i.getName() for i in implementedBy(C)
+   'I1', 'I2'
+
+Instances of ``C`` provide only ``I1``, ``I2``, and regardless of
+whatever interfaces instances of ``A`` and ``B`` implement.
+
+Another example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> @implementer(I2)
+   ... class C1(object):
+   ...     pass
+   >>> @implementer(I3)
+   ... class C2(C1):
+   ...     pass
+   >>> i.getName() for i in implementedBy(C2)
+   'I3', 'I2'
+
+Really, any object should be able to receive a successful answer, even
+an instance:
+
+.. doctest::
+
+   >>> class Callable(object):
+   ...     def __call__(self):
+   ...         return self
+   >>> implementedBy(Callable())
+   classImplements(builtins.?)
+
+Note that the name of the spec ends with a '?', because the ``Callable``
+instance does not have a ``__name__`` attribute.
+
+This also manages storage of implementation specifications.
+
+
+providedBy
+----------
+
+.. autofunction:: providedBy
+
+
+directlyProvidedBy
+------------------
+
+.. autofunction:: directlyProvidedBy
+
+
+Classes
+=======
+
+
+Declarations
+------------
+
+Declaration objects implement the API defined by
+:class:`~zope.interface.interfaces.IDeclaration`.
+
+
+.. autoclass:: Declaration
+
+
+Exmples for :meth:`Declaration.__contains__`:
+
+.. doctest::
+
+   >>> from zope.interface.declarations import Declaration
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration(I2, I3)
+   >>> spec = Declaration(I4, spec)
+   >>> int(I1 in spec)
+   0
+   >>> int(I2 in spec)
+   1
+   >>> int(I3 in spec)
+   1
+   >>> int(I4 in spec)
+   1
+
+Exmples for :meth:`Declaration.__iter__`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration(I2, I3)
+   >>> spec = Declaration(I4, spec)
+   >>> i = iter(spec)
+   >>> x.getName() for x in i
+   'I4', 'I2', 'I3'
+   >>> list(i)
+   
+
+Exmples for :meth:`Declaration.flattened`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration(I2, I3)
+   >>> spec = Declaration(I4, spec)
+   >>> i = spec.flattened()
+   >>> x.getName() for x in i
+   'I4', 'I2', 'I3', 'I1', 'Interface'
+   >>> list(i)
+   
+
+Exmples for :meth:`Declaration.__sub__`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration()
+   >>> iface.getName() for iface in spec
+   
+   >>> spec -= I1
+   >>> iface.getName() for iface in spec
+   
+   >>> spec -= Declaration(I2)
+   >>> iface.getName() for iface in spec
+   
+   >>> spec = Declaration(I2, I4)
+   >>> iface.getName() for iface in spec
+   'I2', 'I4'
+   >>> iface.getName() for iface in spec - I4
+   'I2'
+   >>> iface.getName() for iface in spec - I1
+   'I4'
+   >>> iface.getName() for iface
+   ...  in spec - Declaration(I4)
+   'I2'
+
+Exmples for :meth:`Declaration.__add__`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class IRoot1(Interface): pass
+   ...
+   >>> class IDerived1(IRoot1): pass
+   ...
+   >>> class IRoot2(Interface): pass
+   ...
+   >>> class IDerived2(IRoot2): pass
+   ...
+   >>> spec = Declaration()
+   >>> iface.getName() for iface in spec
+   
+   >>> iface.getName() for iface in spec+IRoot1
+   'IRoot1'
+   >>> iface.getName() for iface in IRoot1+spec
+   'IRoot1'
+   >>> spec2 = spec
+   >>> spec += IRoot1
+   >>> iface.getName() for iface in spec
+   'IRoot1'
+   >>> iface.getName() for iface in spec2
+   
+   >>> spec2 += Declaration(IDerived2, IRoot2)
+   >>> iface.getName() for iface in spec2
+   'IDerived2', 'IRoot2'
+   >>> iface.getName() for iface in spec+spec2
+   'IRoot1', 'IDerived2', 'IRoot2'
+   >>> iface.getName() for iface in spec2+spec
+   'IDerived2', 'IRoot2', 'IRoot1'
+   >>> iface.getName() for iface in (spec+spec2).__bases__
+   'IRoot1', 'IDerived2', 'IRoot2'
+   >>> iface.getName() for iface in (spec2+spec).__bases__
+   'IDerived2', 'IRoot2', 'IRoot1'
+
+
+
+ProvidesClass
+-------------
+
+.. autoclass:: zope.interface.declarations.ProvidesClass
+
+
+Descriptor semantics (via ``Provides.__get__``):
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class IFooFactory(Interface):
+   ...     pass
+   >>> class C(object):
+   ...     pass
+   >>> from zope.interface.declarations import ProvidesClass
+   >>> C.__provides__ = ProvidesClass(C, IFooFactory)
+   >>> i.getName() for i in C.__provides__
+   'IFooFactory'
+   >>> getattr(C(), '__provides__', 0)
+   0
+
+
+Implementation Details
+======================
+
+The following section discusses some implementation details and
+demonstrates their use. You'll notice that they are all demonstrated
+using the previously-defined functions.
+
+Provides
+--------
+
+.. autofunction:: Provides
+
+In the examples below, we are going to make assertions about
+the size of the weakvalue dictionary.  For the assertions to be
+meaningful, we need to force garbage collection to make sure garbage
+objects are, indeed, removed from the system. Depending on how Python
+is run, we may need to make multiple calls to be sure.  We provide a
+collect function to help with this:
+
+.. doctest::
+
+   >>> import gc
+   >>> def collect():
+   ...     for i in range(4):
+   ...         gc.collect()
+   >>> collect()
+   >>> from zope.interface import directlyProvides
+   >>> from zope.interface.declarations import InstanceDeclarations
+   >>> before = len(InstanceDeclarations)
+   >>> class C(object):
+   ...     pass
+   >>> from zope.interface import Interface
+   >>> class I(Interface):
+   ...     pass
+   >>> c1 = C()
+   >>> c2 = C()
+   >>> len(InstanceDeclarations) == before
+   True
+   >>> directlyProvides(c1, I)
+   >>> len(InstanceDeclarations) == before + 1
+   True
+   >>> directlyProvides(c2, I)
+   >>> len(InstanceDeclarations) == before + 1
+   True
+   >>> del c1
+   >>> collect()
+   >>> len(InstanceDeclarations) == before + 1
+   True
+   >>> del c2
+   >>> collect()
+   >>> len(InstanceDeclarations) == before
+   True
+
+
+ObjectSpecification
+-------------------
+
+.. autofunction:: zope.interface.declarations.ObjectSpecification
+
+
+For example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import implementer_only
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(Interface): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I31(I3): pass
+   ...
+   >>> class I4(Interface): pass
+   ...
+   >>> class I5(Interface): pass
+   ...
+   >>> @implementer(I1)
+   ... class A(object):
+   ...     pass
+   >>> class B(object):
+   ...     __implemented__ = I2
+   >>> @implementer(I31)
+   ... class C(A, B):
+   ...     pass
+   >>> c = C()
+   >>> directlyProvides(c, I4)
+   >>> i.getName() for i in providedBy(c)
+   'I4', 'I31', 'I1', 'I2'
+   >>> i.getName() for i in providedBy(c).flattened()
+   'I4', 'I31', 'I3', 'I1', 'I2', 'Interface'
+   >>> int(I1 in providedBy(c))
+   1
+   >>> int(I3 in providedBy(c))
+   0
+   >>> int(providedBy(c).extends(I3))
+   1
+   >>> int(providedBy(c).extends(I31))
+   1
+   >>> int(providedBy(c).extends(I5))
+   0
+   >>> @implementer_only(I31)
+   ... class COnly(A, B):
+   ...     pass
+   >>> @implementer(I5)
+   ... class D(COnly):
+   ...     pass
+   >>> c = D()
+   >>> directlyProvides(c, I4)
+   >>> i.getName() for i in providedBy(c)
+   'I4', 'I5', 'I31'
+   >>> i.getName() for i in providedBy(c).flattened()
+   'I4', 'I5', 'I31', 'I3', 'Interface'
+   >>> int(I1 in providedBy(c))
+   0
+   >>> int(I3 in providedBy(c))
+   0
+   >>> int(providedBy(c).extends(I3))
+   1
+   >>> int(providedBy(c).extends(I1))
+   0
+   >>> int(providedBy(c).extends(I31))
+   1
+   >>> int(providedBy(c).extends(I5))
+   1
+
+ObjectSpecificationDescriptor
+-----------------------------
+
+.. autoclass:: zope.interface.declarations.ObjectSpecificationDescriptor
+
+For example:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class IFoo(Interface): pass
+   ...
+   >>> class IFooFactory(Interface): pass
+   ...
+   >>> @implementer(IFoo)
+   ... @provider(IFooFactory)
+   ... class C(object):
+   ...     pass
+   >>> i.getName() for i in C.__providedBy__
+   'IFooFactory'
+   >>> i.getName() for i in C().__providedBy__
+   'IFoo'
+
+Get an ObjectSpecification bound to either an instance or a class,
+depending on how we were accessed.

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/index.rst.txt Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/ro.rst.txt Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/api/specifications.rst.txt Added

@@ -0,0 +1,380 @@
+==========================
+ Interface Specifications
+==========================
+
+.. currentmodule:: zope.interface.interfaces
+
+
+This document discusses the actual interface objects themselves. We
+begin with a basic concept of specifying an object's behaviour (with
+an `ISpecification`), and then we describe the way we write such a
+specification (`IInterface`). Combinations of specifications (e.g., an
+object that provides multiple interfaces) are covered by
+`IDeclaration`.
+
+Specification
+=============
+
+Specification objects implement the API defined by
+:class:`ISpecification`:
+
+.. autointerface:: ISpecification
+   :members:
+   :member-order: bysource
+
+.. autoclass:: zope.interface.interface.Specification
+   :no-members:
+
+For example:
+
+.. doctest::
+
+   >>> from zope.interface.interface import Specification
+   >>> from zope.interface import Interface
+   >>> class I1(Interface):
+   ...     pass
+   >>> class I2(I1):
+   ...     pass
+   >>> class I3(I2):
+   ...     pass
+   >>> i.__name__ for i in I1.__bases__
+   'Interface'
+   >>> i.__name__ for i in I2.__bases__
+   'I1'
+   >>> I3.extends(I1)
+   True
+   >>> I2.__bases__ = (Interface, )
+   >>> i.__name__ for i in I2.__bases__
+   'Interface'
+   >>> I3.extends(I1)
+   False
+
+Exmples for :meth:`.Specification.providedBy`:
+
+.. doctest::
+
+   >>> from zope.interface import *
+   >>> class I1(Interface):
+   ...     pass
+   >>> @implementer(I1)
+   ... class C(object):
+   ...     pass
+   >>> c = C()
+   >>> class X(object):
+   ...     pass
+   >>> x = X()
+   >>> I1.providedBy(x)
+   False
+   >>> I1.providedBy(C)
+   False
+   >>> I1.providedBy(c)
+   True
+   >>> directlyProvides(x, I1)
+   >>> I1.providedBy(x)
+   True
+   >>> directlyProvides(C, I1)
+   >>> I1.providedBy(C)
+   True
+
+Examples for :meth:`.Specification.isOrExtends`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface.declarations import Declaration
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration()
+   >>> int(spec.extends(Interface))
+   1
+   >>> spec = Declaration(I2)
+   >>> int(spec.extends(Interface))
+   1
+   >>> int(spec.extends(I1))
+   1
+   >>> int(spec.extends(I2))
+   1
+   >>> int(spec.extends(I3))
+   0
+   >>> int(spec.extends(I4))
+   0
+
+Examples for :meth:`.Specification.interfaces`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Specification((I2, I3))
+   >>> spec = Specification((I4, spec))
+   >>> i = spec.interfaces()
+   >>> x.getName() for x in i
+   'I4', 'I2', 'I3'
+   >>> list(i)
+   
+
+Exmples for :meth:`.Specification.extends`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface.declarations import Declaration
+   >>> class I1(Interface): pass
+   ...
+   >>> class I2(I1): pass
+   ...
+   >>> class I3(Interface): pass
+   ...
+   >>> class I4(I3): pass
+   ...
+   >>> spec = Declaration()
+   >>> int(spec.extends(Interface))
+   1
+   >>> spec = Declaration(I2)
+   >>> int(spec.extends(Interface))
+   1
+   >>> int(spec.extends(I1))
+   1
+   >>> int(spec.extends(I2))
+   1
+   >>> int(spec.extends(I3))
+   0
+   >>> int(spec.extends(I4))
+   0
+   >>> I2.extends(I2)
+   False
+   >>> I2.extends(I2, False)
+   True
+   >>> I2.extends(I2, strict=False)
+   True
+
+.. _spec_eq_hash:
+
+Equality, Hashing, and Comparisons
+----------------------------------
+
+Specifications (including their notable subclass `Interface`), are
+hashed and compared (sorted) based solely on their ``__name__`` and
+``__module__``, not including any information about their enclosing
+scope, if any (e.g., their ``__qualname__``). This means that any two
+objects created with the same name and module are considered equal and
+map to the same value in a dictionary.
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   >>> orig_I1 = I1
+   >>> class I1(Interface): pass
+   >>> I1 is orig_I1
+   False
+   >>> I1 == orig_I1
+   True
+   >>> d = {I1: 42}
+   >>> dorig_I1
+   42
+   >>> def make_nested():
+   ...     class I1(Interface): pass
+   ...     return I1
+   >>> nested_I1 = make_nested()
+   >>> I1 == orig_I1 == nested_I1
+   True
+
+Caveats
+~~~~~~~
+
+While this behaviour works well with :ref:`pickling (persistence)
+<global_persistence>`, it has some potential downsides to be aware of.
+
+.. rubric:: Weak References
+
+The first downside involves weak references. Because weak references
+hash the same as their underlying object, this can lead to surprising
+results when weak references are involved, especially if there are
+cycles involved or if the garbage collector is not based on reference
+counting (e.g., PyPy). For example, if you redefine an interface named
+the same as an interface being used in a ``WeakKeyDictionary``, you
+can get a ``KeyError``, even if you put the new interface into the
+dictionary.
+
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> import gc
+   >>> from weakref import WeakKeyDictionary
+   >>> wr_dict = WeakKeyDictionary()
+   >>> class I1(Interface): pass
+   >>> wr_dictI1 = 42
+   >>> orig_I1 = I1 # Make sure it stays alive
+   >>> class I1(Interface): pass
+   >>> wr_dictI1 = 2020
+   >>> del orig_I1
+   >>> _ = gc.collect() # Sometime later, gc runs and makes sure the original is gone
+   >>> wr_dictI1 # Cleaning up the original weakref removed the new one
+   Traceback (most recent call last):
+   ...
+   KeyError: ...
+
+This is mostly likely a problem in test cases where it is tempting to
+use the same named interfaces in different test methods. If references
+to them escape, especially if they are used as the bases of other
+interfaces, you may find surprising ``KeyError`` exceptions. For this
+reason, it is best to use distinct names for local interfaces within
+the same test module.
+
+.. rubric:: Providing Dynamic Interfaces
+
+If you return an interface created inside a function or method, or
+otherwise let it escape outside the bounds of that function (such as
+by having an object provide it), it's important to be aware that it
+will compare and hash equal to *any* other interface defined in that
+same module with the same name. This includes interface objects
+created by other invocations of that function.
+
+This can lead to surprising results when querying against those
+interfaces. We can demonstrate by creating a module-level interface
+with a common name, and checking that it is provided by an object:
+
+.. doctest::
+
+   >>> from zope.interface import Interface, alsoProvides, providedBy
+   >>> class ICommon(Interface):
+   ...     pass
+   >>> class Obj(object):
+   ...     pass
+   >>> obj = Obj()
+   >>> alsoProvides(obj, ICommon)
+   >>> len(list(providedBy(obj)))
+   1
+   >>> ICommon.providedBy(obj)
+   True
+
+Next, in the same module, we will define a function that dynamically
+creates an interface of the same name and adds it to an object.
+
+.. doctest::
+
+   >>> def add_interfaces(obj):
+   ...     class ICommon(Interface):
+   ...         pass
+   ...     class I2(Interface):
+   ...         pass
+   ...     alsoProvides(obj, ICommon, I2)
+   ...     return ICommon
+   ...
+   >>> dynamic_ICommon = add_interfaces(obj)
+
+The two instances are *not* identical, but they are equal, and *obj*
+provides them both:
+
+.. doctest::
+
+   >>> ICommon is dynamic_ICommon
+   False
+   >>> ICommon == dynamic_ICommon
+   True
+   >>> ICommon.providedBy(obj)
+   True
+   >>> dynamic_ICommon.providedBy(obj)
+   True
+
+At this point, we've effectively called ``alsoProvides(obj, ICommon,
+dynamic_ICommon, I2)``, where the last two interfaces were locally
+defined in the function. So checking how many interfaces *obj* now
+provides should return three, right?
+
+.. doctest::
+
+   >>> len(list(providedBy(obj)))
+   2
+
+Because ``ICommon == dynamic_ICommon`` due to having the same
+``__name__`` and ``__module__``, only one of them is actually provided
+by the object, for a total of two provided interfaces. (Exactly which
+one is undefined.) Likewise, if we run the same function again, *obj*
+will still only provide two interfaces
+
+.. doctest::
+
+   >>> _ = add_interfaces(obj)
+   >>> len(list(providedBy(obj)))
+   2
+
+
+Interface
+=========
+
+Interfaces are a particular type of `ISpecification` and implement the
+API defined by :class:`IInterface`.
+
+Before we get there, we need to discuss two related concepts. The
+first is that of an "element", which provides us a simple way to query
+for information generically (this is important because we'll see that
+``IInterface`` implements this interface):
+
+..
+  IElement defines __doc__ to be an Attribute, so the docstring
+  in the class isn't used._
+
+.. autointerface:: IElement
+
+   Objects that have basic documentation and tagged values.
+
+   Known derivatives include :class:`IAttribute` and its derivative
+   :class:`IMethod`; these have no notion of inheritance.
+   :class:`IInterface` is also a derivative, and it does have a
+   notion of inheritance, expressed through its ``__bases__`` and
+   ordered in its ``__iro__`` (both defined by
+   :class:`ISpecification`).
+
+
+.. autoclass:: zope.interface.interface.Element
+   :no-members:
+
+Next, we look at ``IAttribute`` and ``IMethod``. These make up the
+content, or body, of an ``Interface``.
+
+.. autointerface:: zope.interface.interfaces.IAttribute
+.. autoclass:: zope.interface.interface.Attribute
+   :no-members:
+
+.. autointerface:: IMethod
+.. autoclass:: zope.interface.interface.Method
+   :no-members:
+
+Finally we can look at the definition of ``IInterface``.
+
+.. autointerface:: IInterface
+
+.. autointerface:: zope.interface.Interface
+
+Usage
+-----
+
+Exmples for :meth:`InterfaceClass.extends`:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> class I1(Interface): pass
+   ...
+   >>>
+   >>> i = I1.interfaces()
+   >>> x.getName() for x in i
+   'I1'
+   >>> list(i)
+

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/changes.rst.txt Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/foodforthought.rst.txt Added

@@ -0,0 +1,71 @@
+================================
+Food-based subscription examples
+================================
+
+
+This file gives more subscription examples using a cooking-based example:
+
+.. doctest::
+
+    >>> from zope.interface.adapter import AdapterRegistry
+    >>> registry = AdapterRegistry()
+
+    >>> import zope.interface
+    >>> class IAnimal(zope.interface.Interface):
+    ...     pass
+    >>> class IPoultry(IAnimal):
+    ...     pass
+    >>> class IChicken(IPoultry):
+    ...     pass
+    >>> class ISeafood(IAnimal):
+    ...     pass
+
+Adapting to some other interface for which there is no
+subscription adapter returns an empty sequence:
+
+.. doctest::
+
+    >>> class IRecipe(zope.interface.Interface):
+    ...     pass
+    >>> class ISausages(IRecipe):
+    ...     pass
+    >>> class INoodles(IRecipe):
+    ...     pass
+    >>> class IKFC(IRecipe):
+    ...     pass
+
+    >>> list(registry.subscriptions(IPoultry, IRecipe))
+    
+
+unless we define a subscription:
+
+.. doctest::
+
+    >>> registry.subscribe(IAnimal, ISausages, 'sausages')
+    >>> list(registry.subscriptions(IPoultry, ISausages))
+    'sausages'
+
+And define another subscription adapter:
+
+.. doctest::
+
+    >>> registry.subscribe(IPoultry, INoodles, 'noodles')
+    >>> meals = list(registry.subscriptions(IPoultry, IRecipe))
+    >>> meals.sort()
+    >>> meals
+    'noodles', 'sausages'
+
+    >>> registry.subscribe(IChicken, IKFC, 'kfc')
+    >>> meals = list(registry.subscriptions(IChicken, IRecipe))
+    >>> meals.sort()
+    >>> meals
+    'kfc', 'noodles', 'sausages'
+
+And the answer for poultry hasn't changed:
+
+.. doctest::
+
+    >>> meals = list(registry.subscriptions(IPoultry, IRecipe))
+    >>> meals.sort()
+    >>> meals
+    'noodles', 'sausages'

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/hacking.rst.txt Added

@@ -0,0 +1,312 @@
+Hacking on :mod:`zope.interface`
+================================
+
+
+Getting the Code
+################
+
+The main repository for :mod:`zope.interface` is in the Zope Foundation
+Github repository:
+
+  https://github.com/zopefoundation/zope.interface
+
+You can get a read-only checkout from there:
+
+.. code-block:: sh
+
+   $ git clone https://github.com/zopefoundation/zope.interface.git
+
+or fork it and get a writeable checkout of your fork:
+
+.. code-block:: sh
+
+   $ git clone git@github.com/jrandom/zope.interface.git
+
+The project also mirrors the trunk from the Github repository as a
+Bazaar branch on Launchpad:
+
+https://code.launchpad.net/zope.interface
+
+You can branch the trunk from there using Bazaar:
+
+.. code-block:: sh
+
+   $ bzr branch lp:zope.interface
+
+
+Working in a ``virtualenv``
+###########################
+
+Running the tests
+-----------------
+
+If you use the ``virtualenv`` package to create lightweight Python
+development environments, you can run the tests using nothing more
+than the ``python`` binary in a virtualenv.  First, create a scratch
+environment:
+
+.. code-block:: sh
+
+   $ /path/to/virtualenv --no-site-packages /tmp/hack-zope.interface
+
+Next, get this package registered as a "development egg" in the
+environment:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.interface/bin/python setup.py develop
+
+Finally, run the tests using the built-in ``setuptools`` testrunner:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.interface/bin/python setup.py test -q
+   running test
+   ...
+   ----------------------------------------------------------------------
+   Ran 2 tests in 0.000s
+
+   OK
+
+The ``dev`` command alias downloads and installs extra tools, like the
+:mod:`nose` testrunner and the :mod:`coverage` coverage analyzer:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.interface/bin/python setup.py dev
+   $ /tmp/hack-zope.interface/bin/nosetests
+   running nosetests
+   .................................... (lots more dots)
+   ----------------------------------------------------------------------
+   Ran 707 tests in 2.166s
+
+   OK
+
+If you have the :mod:`coverage` package installed in the virtualenv,
+you can see how well the tests cover the code:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.interface/bin/nosetests --with coverage
+   running nosetests
+   .................................... (lots more dots)
+   Name                               Stmts   Miss  Cover   Missing
+   ----------------------------------------------------------------
+   zope.interface                        30      0   100%   
+   zope.interface.adapter               440      0   100%   
+   zope.interface.advice                 69      0   100%   
+   zope.interface.common                  0      0   100%   
+   zope.interface.common.idatetime       98      0   100%   
+   zope.interface.common.interfaces      81      0   100%   
+   zope.interface.common.mapping         32      0   100%   
+   zope.interface.common.sequence        38      0   100%   
+   zope.interface.declarations          312      0   100%   
+   zope.interface.document               54      0   100%   
+   zope.interface.exceptions             21      0   100%   
+   zope.interface.interface             378      0   100%   
+   zope.interface.interfaces            137      0   100%   
+   zope.interface.registry              300      0   100%   
+   zope.interface.ro                     25      0   100%   
+   zope.interface.verify                 48      0   100%   
+   ----------------------------------------------------------------
+   TOTAL                               2063      0   100%   
+   ----------------------------------------------------------------------
+   Ran 707 tests in 2.166s
+
+   OK
+
+
+Building the documentation
+--------------------------
+
+:mod:`zope.interface` uses the nifty :mod:`Sphinx` documentation system
+for building its docs.  Using the same virtualenv you set up to run the
+tests, you can build the docs:
+
+The ``docs`` command alias downloads and installs Sphinx and its dependencies:
+
+.. code-block:: sh
+
+   $ /tmp/hack-zope.interface/bin/python setup.py docs
+   ...
+   $ bin/sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
+   ...
+   build succeeded.
+
+   Build finished. The HTML pages are in docs/_build/html.
+
+You can also test the code snippets in the documentation:
+
+.. code-block:: sh
+
+   $ bin/sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
+   ...
+   running tests...
+
+   Document: index
+   ---------------
+   1 items passed all tests:
+     17 tests in default
+   17 tests in 1 items.
+   17 passed and 0 failed.
+   Test passed.
+
+   Doctest summary
+   ===============
+      17 tests
+       0 failures in tests
+       0 failures in setup code
+   build succeeded.
+   Testing of doctests in the sources finished, look at the  \
+       results in docs/_build/doctest/output.txt.
+
+
+
+Using :mod:`zc.buildout`
+########################
+
+Setting up the buildout
+-----------------------
+
+:mod:`zope.interface` ships with its own :file:`buildout.cfg` file and
+:file:`bootstrap.py` for setting up a development buildout:
+
+.. code-block:: sh
+
+   $ /path/to/python2.7 bootstrap.py
+   ...
+   Generated script '.../bin/buildout'
+   $ bin/buildout
+   Develop: '/home/jrandom/projects/Zope/BTK/interface/.'
+   ...
+   Generated script '.../bin/sphinx-quickstart'.
+   Generated script '.../bin/sphinx-build'.
+
+Running the tests
+-----------------
+
+You can now run the tests:
+
+.. code-block:: sh
+
+   $ bin/test --all
+   Running zope.testing.testrunner.layer.UnitTests tests:
+     Set up zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+     Ran 702 tests with 0 failures and 0 errors in 0.000 seconds.
+   Tearing down left over layers:
+     Tear down zope.testing.testrunner.layer.UnitTests in 0.000 seconds.
+
+
+Using :mod:`tox`
+################
+
+Running Tests on Multiple Python Versions
+-----------------------------------------
+
+`tox <http://tox.testrun.org/latest/>`_ is a Python-based test automation
+tool designed to run tests against multiple Python versions.  It creates
+a ``virtualenv`` for each configured version, installs the current package
+and configured dependencies into each ``virtualenv``, and then runs the
+configured commands.
+   
+:mod:`zope.interface` configures the following :mod:`tox` environments via
+its ``tox.ini`` file:
+
+- The defined Python environments build a ``virtualenv`` with various Python 2,
+  Python 3, PyPy 2 and PyPy 3 versions, install :mod:`zope.interface` and
+  dependencies, and run the tests via ``python setup.py test -q``.
+
+- The ``coverage`` environment builds a ``virtualenv`` with ``python2.7``,
+  installs :mod:`zope.interface` and dependencies, installs
+  :mod:`nose` and :mod:`coverage`, and runs ``nosetests`` with statement
+  coverage.
+
+- The ``docs`` environment builds a virtualenv with ``python2.7``, installs
+  :mod:`zope.interface` and dependencies, installs ``Sphinx`` and
+  dependencies, and then builds the docs and exercises the doctest snippets.
+
+This example requires that you have a working ``python2.7`` on your path,
+as well as installing ``tox``:
+
+.. code-block:: sh
+
+   $ tox -e py26
+   GLOB sdist-make: .../zope.interface/setup.py
+   py26 sdist-reinst: .../zope.interface/.tox/dist/zope.interface-4.0.2dev.zip
+   py26 runtests: commands0
+   ...
+   ----------------------------------------------------------------------
+   Ran 1341 tests in 0.477s
+
+   OK
+   ___________________________________ summary ____________________________________
+   py26: commands succeeded
+   congratulations :)
+
+Running ``tox`` with no arguments runs all the configured environments,
+including building the docs and testing their snippets:
+
+.. code-block:: sh
+
+   $ tox
+   GLOB sdist-make: .../zope.interface/setup.py
+   py26 sdist-reinst: .../zope.interface/.tox/dist/zope.interface-4.0.2dev.zip
+   py26 runtests: commands0
+   ...
+   Doctest summary
+   ===============
+   678 tests
+      0 failures in tests
+      0 failures in setup code
+      0 failures in cleanup code
+   build succeeded.
+   ___________________________________ summary ____________________________________
+   py26: commands succeeded
+   py27: commands succeeded
+   py32: commands succeeded
+   pypy: commands succeeded
+   coverage: commands succeeded
+   docs: commands succeeded
+   congratulations :)
+
+
+Contributing to :mod:`zope.interface`
+#####################################
+
+Submitting a Bug Report
+-----------------------
+
+:mod:`zope.interface` tracks its bugs on Github:
+
+  https://github.com/zopefoundation/zope.interface/issues
+
+Please submit bug reports and feature requests there.
+
+
+Sharing Your Changes
+--------------------
+
+.. note::
+
+   Please ensure that all tests are passing before you submit your code.
+   If possible, your submission should include new tests for new features
+   or bug fixes, although it is possible that you may have tested your
+   new code by updating existing tests.
+
+If have made a change you would like to share, the best route is to fork
+the Githb repository, check out your fork, make your changes on a branch
+in your fork, and push it.  You can then submit a pull request from your
+branch:
+
+  https://github.com/zopefoundation/zope.interface/pulls
+
+If you branched the code from Launchpad using Bazaar, you have another
+option:  you can "push" your branch to Launchpad:
+
+.. code-block:: sh
+
+   $ bzr push lp:~jrandom/zope.interface/cool_feature
+
+After pushing your branch, you can link it to a bug report on Launchpad,
+or request that the maintainers merge your branch using the Launchpad
+"merge request" feature.

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/human.rst.txt Added

@@ -0,0 +1,180 @@
+==========================
+Using the Adapter Registry
+==========================
+
+This is a small demonstration of the :mod:`zope.interface` package including its
+adapter registry. It is intended to provide a concrete but narrow example on
+how to use interfaces and adapters outside of Zope 3.
+
+First we have to import the interface package:
+
+.. doctest::
+
+  >>> import zope.interface
+
+We now develop an interface for our object, which is a simple file in this
+case. For now we simply support one attribute, the body, which contains the
+actual file contents:
+
+.. doctest::
+
+  >>> class IFile(zope.interface.Interface):
+  ...
+  ...     body = zope.interface.Attribute('Contents of the file.')
+  ...
+
+For statistical reasons we often want to know the size of a file. However, it
+would be clumsy to implement the size directly in the file object, since the
+size really represents meta-data. Thus we create another interface that
+provides the size of something:
+
+.. doctest::
+
+  >>> class ISize(zope.interface.Interface):
+  ...
+  ...     def getSize():
+  ...         'Return the size of an object.'
+  ...
+
+Now we need to implement the file interface. It is essential that the object states
+that it implements the ``IFile`` interface. We also provide a default body
+value (just to make things simpler for this example):
+
+.. doctest::
+
+  >>> @zope.interface.implementer(IFile)
+  ... class File(object):
+  ...
+  ...      body = 'foo bar'
+  ...
+
+Next we implement an adapter that can provide the ``ISize`` interface given any
+object providing ``IFile``. By convention we use ``__used_for__`` to specify the
+interface that we expect the adapted object to provide, in our case
+``IFile``. However, this attribute is not used for anything. If you have
+multiple interfaces for which an adapter is used, just specify the interfaces
+via a tuple.
+
+Again by convention, the constructor of an adapter takes one argument, the
+context. The context in this case is an instance of ``File`` (providing ``IFile``)
+that is used to extract the size from. Also by convention the context is
+stored in an attribute named ``context`` on the adapter. The `twisted`_ community
+refers to the context as the ``original`` object. However, you may feel free to
+use a specific argument name, such as ``file``:
+
+.. doctest::
+
+  >>> @zope.interface.implementer(ISize)
+  ... class FileSize(object):
+  ...
+  ...      __used_for__ = IFile
+  ...
+  ...      def __init__(self, context):
+  ...          self.context = context
+  ...
+  ...      def getSize(self):
+  ...          return len(self.context.body)
+  ...
+
+Now that we have written our adapter, we have to register it with an adapter
+registry, so that it can be looked up when needed. There is no such thing as a
+global registry; thus we have to instantiate one for our example manually:
+
+.. doctest::
+
+  >>> from zope.interface.adapter import AdapterRegistry
+  >>> registry = AdapterRegistry()
+
+
+The registry keeps a map of what adapters implement based on another
+interface the object already provides. Therefore, we next have to register an
+adapter that adapts from ``IFile`` to ``ISize``. The first argument to
+the registry's ``register()`` method is a list of original interfaces.In our
+cause we have only one original interface, ``IFile``. A list makes sense, since
+the interface package has the concept of multi-adapters, which are adapters
+that require multiple objects to adapt to a new interface. In these
+situations, your adapter constructor will require an argument for each
+specified interface.
+
+The second argument is the interface the adapter provides, in our case
+``ISize``. The third argument is the name of the adapter. Since we do not care
+about names, we simply leave it as an empty string. Names are commonly useful,
+if you have adapters for the same set of interfaces, but they are useful in
+different situations. The last argument is simply the adapter class:
+
+.. doctest::
+
+  >>> registry.register(IFile, ISize, '', FileSize)
+
+You can now use the the registry to lookup the adapter:
+
+.. doctest::
+
+  >>> registry.lookup1(IFile, ISize, '')
+  <class 'FileSize'>
+
+Let's get a little bit more practical. Let's create a ``File`` instance and
+create the adapter using a registry lookup. Then we see whether the adapter
+returns the correct size by calling ``getSize()``:
+
+.. doctest::
+
+  >>> file = File()
+  >>> size = registry.lookup1(IFile, ISize, '')(file)
+  >>> size.getSize()
+  7
+
+However, this is not very practical, since I have to manually pass in the
+arguments to the lookup method. There is some syntactic candy that will allow
+us to get an adapter instance by simply calling ``ISize(file)``. To make use of
+this functionality, we need to add our registry to the ``adapter_hooks`` list,
+which is a member of the adapters module. This list stores a collection of
+callables that are automatically invoked when ``IFoo(obj)`` is called; their
+purpose is to locate adapters that implement an interface for a certain
+context instance.
+
+You are required to implement your own adapter hook; this example covers one
+of the simplest hooks that use the registry, but you could implement one that
+used an adapter cache or persistent adapters, for instance. The helper hook is
+required to expect as first argument the desired output interface (for us
+``ISize``) and as the second argument the context of the adapter (here
+``file``). The function returns an adapter, i.e. a ``FileSize`` instance:
+
+.. doctest::
+
+  >>> def hook(provided, object):
+  ...     adapter = registry.lookup1(zope.interface.providedBy(object),
+  ...                                provided, '')
+  ...     return adapter(object)
+  ...
+
+We now just add the hook to an ``adapter_hooks`` list:
+
+.. doctest::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> adapter_hooks.append(hook)
+
+Once the hook is registered, you can use the desired syntax:
+
+.. doctest::
+
+  >>> size = ISize(file)
+  >>> size.getSize()
+  7
+
+Now we have to clean up after ourselves, so that others after us have a clean
+``adapter_hooks`` list:
+
+.. doctest::
+
+  >>> adapter_hooks.remove(hook)
+
+That's it. I have intentionally left out a discussion of named adapters and
+multi-adapters, since this text is intended as a practical and simple
+introduction to Zope 3 interfaces and adapters. You might want to read the
+``adapter.txt`` in the ``zope.interface`` package for a more formal, referential
+and complete treatment of the package. Warning: People have reported that
+``adapter.txt`` makes their brain feel soft!
+
+.. _twisted: https://twistedmatrix.com/

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/human.ru.rst.txt Added

@@ -0,0 +1,156 @@
+===============================
+Использование реестра адаптеров
+===============================
+
+Данный документ содержит небольшую демонстрацию пакета ``zope.interface`` и его
+реестра адаптеров. Документ рассчитывался как конкретный, но более узкий пример
+того как использовать интерфейсы и адаптеры вне Zope 3.
+
+Сначала нам необходимо импортировать пакет для работы с интерфейсами::
+
+  >>> import zope.interface
+
+Теперь мы разработаем интерфейс для нашего объекта - простого файла. Наш файл
+будет содержать всего один атрибут - body, в котором фактически будет сохранено
+содержимое файла::
+
+  >>> class IFile(zope.interface.Interface):
+  ...
+  ...     body = zope.interface.Attribute(u'Содержимое файла.')
+  ...
+
+Для статистики нам часто необходимо знать размер файла. Но было бы несколько
+топорно реализовывать определение размера прямо для объекта файла, т.к. размер
+больше относится к мета-данным. Таким образом мы создаем еще один интерфейс для
+представления размера какого-либо объекта::
+
+  >>> class ISize(zope.interface.Interface):
+  ...
+  ...     def getSize():
+  ...         'Return the size of an object.'
+  ...
+
+Теперь мы должны создать класс реализующий наш файл. Необходимо что бы наш
+объект хранил информацию о том, что он реализует интерфейс `IFile`. Мы также
+создаем атрибут с содержимым файла по умолчанию (для упрощения нашего
+примера)::
+
+  >>> class File(object):
+  ...
+  ...      zope.interface.implements(IFile)
+  ...      body = 'foo bar'
+  ...
+
+Дальше мы создаем адаптер, который будет предоставлять интерфейс `ISize`
+получая любой объект предоставляющий интерфейс `IFile`. По соглашению мы
+используем атрибут `__used_for__` для указания интерфейса который как мы
+ожидаем предоставляет адаптируемый объект, `IFile` в нашем случае. На самом
+деле этот атрибут используется только для документирования. В случае если
+адаптер используется для нескольких интерфейсов можно указать их все в виде
+кортежа.
+
+Опять же по соглашению конструктор адаптера получает один аргумент - context
+(контекст). В нашем случае контекст - это экземпляр `IFile` (объект,
+предоставляющий `IFile`) который используется для получения из него размера.
+Так же по соглашению контекст сохраняется а адаптере в атрибуте с именем
+`context`. Twisted комьюнити ссылается на контекст как на объект `original`.
+Таким образом можно также дать аргументу любое подходящее имя, например
+`file`::
+
+  >>> class FileSize(object):
+  ...
+  ...      zope.interface.implements(ISize)
+  ...      __used_for__ = IFile
+  ...
+  ...      def __init__(self, context):
+  ...          self.context = context
+  ...
+  ...      def getSize(self):
+  ...          return len(self.context.body)
+  ...
+
+Теперь когда мы написали наш адаптер мы должны зарегистрировать его в реестре
+адаптеров, что бы его можно было запросить когда он понадобится. Здесь нет
+какого-либо глобального реестра адаптеров, таким образом мы должны
+самостоятельно создать для нашего примера реестр::
+
+  >>> from zope.interface.adapter import AdapterRegistry
+  >>> registry = AdapterRegistry()
+
+Реестр содержит отображение того, что адаптер реализует на основе другого
+интерфейса который предоставляет объект. Поэтому дальше мы регистрируем адаптер
+который адаптирует интерфейс `IFile` к интерфейсу `ISize`. Первый аргумент к
+методу `register()` реестра - это список адаптируемых интерфейсов. В нашем
+случае мы имеем только один адаптируемый интерфейс - `IFile`. Список
+интерфейсов имеет смысл для использования концепции мульти-адаптеров, которые
+требуют нескольких оригинальных объектов для адаптации к новому интерфейсу. В
+этой ситуации конструктор адаптера будет требовать новый аргумент для каждого
+оригинального интерфейса.
+
+Второй аргумент метода `register()` - это интерфейс который предоставляет
+адаптер, в нашем случае `ISize`. Третий аргумент - имя адаптера. Сейчас нам не
+важно имя адаптера и мы передаем его как пустую строку. Обычно имена полезны
+если используются адаптеры для одинакового набора интерфейсов, но в различных
+ситуациях. Последний аргумент - это класс адаптера::
+
+  >>> registry.register(IFile, ISize, '', FileSize)
+
+Теперь мы можем использовать реестр для запроса адаптера::
+
+  >>> registry.lookup1(IFile, ISize, '')
+  <class '__main__.FileSize'>
+
+Попробуем более практичный пример. Создадим экземпляр `File` и создадим адаптер
+использующий запрос реестра. Затем мы увидим возвращает ли адаптер корректный
+размер при вызове `getSize()`::
+
+  >>> file = File()
+  >>> size = registry.lookup1(IFile, ISize, '')(file)
+  >>> size.getSize()
+  7
+
+На самом деле это не очень практично, т.к. нам нужно самим передавать все
+аргументы методу запроса. Существует некоторый синтаксический леденец который
+позволяет нам получить экземпляр адаптера просто вызвав `ISize(file)`. Что бы
+использовать эту функциональность нам понадобится добавить наш реестр к списку
+adapter_hooks, который находится в модуле с адаптерами. Этот список хранит
+коллекцию вызываемых объектов которые вызываются автоматически когда вызывается
+IFoo(obj); их предназначение - найти адаптеры которые реализуют интерфейс для
+определенного экземпляра контекста.
+
+Необходимо реализовать свою собственную функцию для поиска адаптера; данный
+пример описывает одну из простейших функций для использования с реестром, но
+также можно реализовать поисковые функции которые, например, используют
+кэширование, или адаптеры сохраняемые в базе. Функция поиска должна принимать
+желаемый на выходе интерфейс (в нашем случае `ISize`) как первый аргумент и
+контекст для адаптации (`file`) как второй. Функция должна вернуть адаптер,
+т.е. экземпляр `FileSize`::
+
+  >>> def hook(provided, object):
+  ...     adapter = registry.lookup1(zope.interface.providedBy(object),
+  ...                                provided, '')
+  ...     return adapter(object)
+  ...
+
+Теперь мы просто добавляем нашу функцию к списку `adapter_hooks`::
+
+  >>> from zope.interface.interface import adapter_hooks
+  >>> adapter_hooks.append(hook)
+
+Как только функция зарегистрирована мы можем использовать желаемый синтаксис::
+
+  >>> size = ISize(file)
+  >>> size.getSize()
+  7
+
+После нам нужно прибраться за собой, что бы другие получили чистый список
+`adaper_hooks` после нас::
+
+  >>> adapter_hooks.remove(hook)
+
+Это все. Здесь намеренно отложена дискуссия об именованных и мульти-адаптерах,
+т.к. данный текст рассчитан как практическое и простое введение в интерфейсы и
+адаптеры Zope 3. Для более подробной информации имеет смысл прочитать
+`adapter.txt` из пакета `zope.interface`, что бы получить более формальное,
+справочное и полное трактование пакета. Внимание: многие жаловались, что
+`adapter.txt` приводит их мозг к расплавленному состоянию!

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/index.rst.txt Added

_service:tar_scm:zope.interface-5.5.2.tar.gz/docs/_build/html/_sources/verify.rst.txt Added

@@ -0,0 +1,322 @@
+=====================================
+ Verifying interface implementations
+=====================================
+
+The ``zope.interface.verify`` module provides functions that test whether a
+given interface is implemented by a class or provided by an object.
+
+.. currentmodule:: zope.interface.verify
+
+Verifying objects
+=================
+
+.. autofunction:: verifyObject
+
+.. autoexception:: zope.interface.Invalid
+
+Let's demonstrate. We'll begin by defining a simple interface hierarchy
+requiring two attributes, and a helper method that will instantiate and verify
+that an object provides this interface.
+
+.. doctest::
+
+   >>> from zope.interface import Interface, Attribute, implementer
+   >>> from zope.interface import Invalid
+   >>> from zope.interface.verify import verifyObject
+   >>> oname, __name__ = __name__, 'base' # Pretend we're in a module, not a doctest
+   >>> class IBase(Interface):
+   ...     x = Attribute("The X attribute")
+   >>> __name__ = 'module' # Pretend to be a different module.
+   >>> class IFoo(IBase):
+   ...     y = Attribute("The Y attribute")
+   >>> __name__ = oname; del oname
+   >>> class Foo(object):
+   ...     pass
+   >>> def verify_foo(**kwargs):
+   ...    foo = Foo()
+   ...    try:
+   ...        return verifyObject(IFoo, foo, **kwargs)
+   ...    except Invalid as e:
+   ...        print(e)
+
+If we try to verify an instance of this ``Foo`` class, three errors
+will be reported. The declarations (does the object provide ``IFoo``)
+are checked, as are the attributes specified in the interface being
+validated (and its ancestors). Notice that the interface being
+verified is shown, as is the interface where the attribute was
+defined.
+
+.. doctest::
+
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo:
+       Does not declaratively implement the interface
+       The base.IBase.x attribute was not provided
+       The module.IFoo.y attribute was not provided
+
+If we add the two missing attributes, we still have the error about not
+declaring the correct interface.
+
+.. doctest::
+
+   >>> Foo.x = Foo.y = 42
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: Does not declaratively implement the interface.
+
+If we want to only check the structure of the object, without examining
+its declarations, we can use the ``tentative`` argument.
+
+.. doctest::
+
+   >>> verify_foo(tentative=True)
+   True
+
+Of course, we can always mark a particular instance as providing the
+desired interface.
+
+.. doctest::
+
+   >>> from zope.interface import alsoProvides
+   >>> foo = Foo()
+   >>> alsoProvides(foo, IFoo)
+   >>> verifyObject(IFoo, foo)
+   True
+
+If all instances will provide the interface, we can
+mark a class as implementing it. But we have to remove the interface from the
+instance first so a consistent interface resolution order can be achieved.
+(Calling ``gc.collect()`` is also necessary because we use weakrefs.)
+
+.. doctest::
+
+   >>> from zope.interface import classImplements
+   >>> from zope.interface import noLongerProvides
+   >>> import gc
+   >>> noLongerProvides(foo, IFoo)
+   >>> _ = gc.collect()
+   >>> classImplements(Foo, IFoo)
+   >>> verify_foo()
+   True
+
+
+Testing for attributes
+----------------------
+
+Attributes of the object, be they defined by its class or added by its
+``__init__`` method, will be recognized:
+
+.. doctest::
+
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     x = 1
+   ...     def __init__(self):
+   ...         self.y = 2
+
+   >>> verifyObject(IFoo, Foo())
+   True
+
+If either attribute is missing, verification will fail by raising an
+exception.
+
+.. doctest::
+
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     x = 1
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.y attribute was not provided.
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     def __init__(self):
+   ...         self.y = 2
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The base.IBase.x attribute was not provided.
+
+If both attributes are missing, an exception is raised reporting
+both errors.
+
+.. doctest::
+
+    >>> @implementer(IFoo)
+    ... class Foo(object):
+    ...     pass
+    >>> verify_foo()
+    The object <Foo ...> has failed to implement interface ...IFoo:
+        The base.IBase.x attribute was not provided
+        The module.IFoo.y attribute was not provided
+
+If an attribute is implemented as a property that raises an ``AttributeError``
+when trying to get its value, the attribute is considered missing:
+
+.. doctest::
+
+   >>> oname, __name__ = __name__, 'module'
+   >>> class IFoo(Interface):
+   ...     x = Attribute('The X attribute')
+   >>> __name__ = oname; del oname
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     @property
+   ...     def x(self):
+   ...         raise AttributeError
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.x attribute was not provided.
+
+
+Any other exception raised by a property will propagate to the caller of
+``verifyObject``:
+
+.. doctest::
+
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     @property
+   ...     def x(self):
+   ...         raise Exception
+   >>> verify_foo()
+   Traceback (most recent call last):
+   Exception
+
+Of course, broken properties that are not required by the interface don't do
+any harm:
+
+.. doctest::
+
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     x = 1
+   ...     @property
+   ...     def y(self):
+   ...         raise Exception
+   >>> verify_foo()
+   True
+
+
+Testing For Methods
+-------------------
+
+Methods are also validated to exist. We'll start by defining a method
+that takes one argument. If we don't provide it, we get an error.
+
+.. doctest::
+
+   >>> oname, __name__ = __name__, 'module'
+   >>> class IFoo(Interface):
+   ...    def simple(arg1): "Takes one positional argument"
+   >>> __name__ = oname; del oname
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...    pass
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.simple(arg1) attribute was not provided.
+
+Once they exist, they are checked to be callable, and for compatible signatures.
+
+Not being callable is an error.
+
+.. doctest::
+
+   >>> Foo.simple = 42
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '42' is not a method.
+
+Taking too few arguments is an error. (Recall that the ``self``
+argument is implicit.)
+
+.. doctest::
+
+   >>> Foo.simple = lambda self: "I take no arguments"
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '<lambda>()' doesn't allow enough arguments.
+
+Requiring too many arguments is an error.
+
+.. doctest::
+
+   >>> Foo.simple = lambda self, a, b: "I require two arguments"
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '<lambda>(a, b)' requires too many arguments.
+
+Variable arguments can be used to implement the required number, as
+can arguments with defaults.
+
+.. doctest::
+
+   >>> Foo.simple = lambda self, *args: "Varargs work."
+   >>> verify_foo()
+   True
+   >>> Foo.simple = lambda self, a=1, b=2: "Default args work."
+   >>> verify_foo()
+   True
+
+If our interface defines a method that uses variable positional or
+variable keyword arguments, the implementation must also accept them.
+
+.. doctest::
+
+   >>> oname, __name__ = __name__, 'module'
+   >>> class IFoo(Interface):
+   ...    def needs_kwargs(**kwargs): pass
+   >>> __name__ = oname; del oname
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     def needs_kwargs(self, a=1, b=2): pass
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.needs_kwargs(**kwargs) is violated because 'Foo.needs_kwargs(a=1, b=2)' doesn't support keyword arguments.
+
+   >>> oname, __name__ = __name__, 'module'
+   >>> class IFoo(Interface):
+   ...    def needs_varargs(*args): pass
+   >>> __name__ = oname; del oname
+   >>> @implementer(IFoo)
+   ... class Foo(object):
+   ...     def needs_varargs(self, **kwargs): pass
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.needs_varargs(*args) is violated because 'Foo.needs_varargs(**kwargs)' doesn't support variable arguments.
+
+Of course, missing attributes are also found and reported, and the
+source interface of the missing attribute is included. Similarly, when
+the failing method is from a parent class, that is also reported.
+
+.. doctest::
+
+   >>> oname, __name__ = __name__, 'base'
+   >>> class IBase(Interface):
+   ...    def method(arg1): "Takes one positional argument"
+   >>> __name__ = 'module'
+   >>> class IFoo(IBase):
+   ...    x = Attribute('The X attribute')
+   >>> __name__ = oname; del oname
+   >>> class Base(object):
+   ...    def method(self): "I don't have enough arguments"
+   >>> @implementer(IFoo)
+   ... class Foo(Base):
+   ...    pass
+   >>> verify_foo()
+   The object <Foo...> has failed to implement interface ...IFoo:
+       The contract of base.IBase.method(arg1) is violated because 'Base.method()' doesn't allow enough arguments
+       The module.IFoo.x attribute was not provided
+
+Verifying Classes
+=================
+
+The function `verifyClass` is used to check that a class implements
+an interface properly, meaning that its instances properly provide the
+interface. Many of the same things that `verifyObject` checks can be
+checked for classes, but certain conditions, such as the presence of
+attributes, cannot be verified.
+
+.. autofunction:: verifyClass
+
+.. doctest::
+
+    >>> from zope.interface.verify import verifyClass
+    >>> def verify_foo_class():
+    ...    try:
+    ...        return verifyClass(IFoo, Foo)
+    ...    except Invalid as e:
+    ...        print(e)
+
+    >>> verify_foo_class()
+    The object <class 'Foo'> has failed to implement interface ...IFoo: The contract of base.IBase.method(arg1) is violated because 'Base.method(self)' doesn't allow enough arguments.

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/adapter.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/docs/adapter.rst Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/api/components.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/docs/api/components.rst Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/api/declarations.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/docs/api/declarations.rst Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/hacking.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/docs/hacking.rst Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/docs/verify.rst -> _service:tar_scm:zope.interface-5.5.2.tar.gz/docs/verify.rst Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/setup.cfg -> _service:tar_scm:zope.interface-5.5.2.tar.gz/setup.cfg Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/setup.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/setup.py Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope.interface.egg-info/PKG-INFO -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope.interface.egg-info/PKG-INFO Changed

@@ -1,1040 +1,12 @@
 Metadata-Version: 2.1
 Name: zope.interface
-Version: 5.4.0
+Version: 5.5.2
 Summary: Interfaces for Python
 Home-page: https://github.com/zopefoundation/zope.interface
 Author: Zope Foundation and Contributors
 Author-email: zope-dev@zope.org
 License: ZPL 2.1
-Description: ====================
-         ``zope.interface``
-        ====================
-        
-        .. image:: https://img.shields.io/pypi/v/zope.interface.svg
-            :target: https://pypi.python.org/pypi/zope.interface/
-            :alt: Latest Version
-        
-        .. image:: https://img.shields.io/pypi/pyversions/zope.interface.svg
-                :target: https://pypi.org/project/zope.interface/
-                :alt: Supported Python versions
-        
-        .. image:: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml/badge.svg
-                :target: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml
-        
-        .. image:: https://readthedocs.org/projects/zopeinterface/badge/?version=latest
-                :target: https://zopeinterface.readthedocs.io/en/latest/
-                :alt: Documentation Status
-        
-        This package is intended to be independently reusable in any Python
-        project. It is maintained by the `Zope Toolkit project
-        <https://zopetoolkit.readthedocs.io/>`_.
-        
-        This package provides an implementation of "object interfaces" for Python.
-        Interfaces are a mechanism for labeling objects as conforming to a given
-        API or contract. So, this package can be considered as implementation of
-        the `Design By Contract`_ methodology support in Python.
-        
-        .. _Design By Contract: http://en.wikipedia.org/wiki/Design_by_contract
-        
-        For detailed documentation, please see https://zopeinterface.readthedocs.io/en/latest/
-        
-        =========
-         Changes
-        =========
-        
-        5.4.0 (2021-04-15)
-        ==================
-        
-        - Make the C implementation of the ``__providedBy__`` descriptor stop
-          ignoring all errors raised when accessing the instance's
-          ``__provides__``. Now it behaves like the Python version and only
-          catches ``AttributeError``. The previous behaviour could lead to
-          crashing the interpreter in cases of recursion and errors. See
-          `issue 239 <https://github.com/zopefoundation/zope.interface/issues>`_.
-        
-        - Update the ``repr()`` and ``str()`` of various objects to be shorter
-          and more informative. In many cases, the ``repr()`` is now something
-          that can be evaluated to produce an equal object. For example, what
-          was previously printed as ``<implementedBy builtins.list>`` is now
-          shown as ``classImplements(list, IMutableSequence, IIterable)``. See
-          `issue 236 <https://github.com/zopefoundation/zope.interface/issues/236>`_.
-        
-        - Make ``Declaration.__add__`` (as in ``implementedBy(Cls) +
-          ISomething``) try harder to preserve a consistent resolution order
-          when the two arguments share overlapping pieces of the interface
-          inheritance hierarchy. Previously, the right hand side was always
-          put at the end of the resolution order, which could easily produce
-          invalid orders. See `issue 193
-          <https://github.com/zopefoundation/zope.interface/issues/193>`_.
-        
-        5.3.0 (2020-03-21)
-        ==================
-        
-        - No changes from 5.3.0a1
-        
-        
-        5.3.0a1 (2021-03-18)
-        ====================
-        
-        - Improve the repr of ``zope.interface.Provides`` to remove ambiguity
-          about what is being provided. This is especially helpful diagnosing
-          IRO issues.
-        
-        - Allow subclasses of ``BaseAdapterRegistry`` (including
-          ``AdapterRegistry`` and ``VerifyingAdapterRegistry``) to have
-          control over the data structures. This allows persistent
-          implementations such as those based on ZODB to choose more scalable
-          options (e.g., BTrees instead of dicts). See `issue 224
-          <https://github.com/zopefoundation/zope.interface/issues/224>`_.
-        
-        - Fix a reference counting issue in ``BaseAdapterRegistry`` that could
-          lead to references to interfaces being kept around even when all
-          utilities/adapters/subscribers providing that interface have been
-          removed. This is mostly an issue for persistent implementations.
-          Note that this only corrects the issue moving forward, it does not
-          solve any already corrupted reference counts. See `issue 227
-          <https://github.com/zopefoundation/zope.interface/issues/227>`_.
-        
-        - Add the method ``BaseAdapterRegistry.rebuild()``. This can be used
-          to fix the reference counting issue mentioned above, as well as to
-          update the data structures when custom data types have changed.
-        
-        - Add the interface method ``IAdapterRegistry.subscribed()`` and
-          implementation ``BaseAdapterRegistry.subscribed()`` for querying
-          directly registered subscribers. See `issue 230
-          <https://github.com/zopefoundation/zope.interface/issues/230>`_.
-        
-        - Add the maintenance method
-          ``Components.rebuildUtilityRegistryFromLocalCache()``. Most users
-          will not need this, but it can be useful if the ``Components.utilities``
-          registry is suspected to be out of sync with the ``Components``
-          object itself (this might happen to persistent ``Components``
-          implementations in the face of bugs).
-        
-        - Fix the ``Provides`` and ``ClassProvides`` descriptors to stop
-          allowing redundant interfaces (those already implemented by the
-          underlying class or meta class) to produce an inconsistent
-          resolution order. This is similar to the change in ``@implementer``
-          in 5.1.0, and resolves inconsistent resolution orders with
-          ``zope.proxy`` and ``zope.location``. See `issue 207
-          <https://github.com/zopefoundation/zope.interface/issues/207>`_.
-        
-        5.2.0 (2020-11-05)
-        ==================
-        
-        - Add documentation section ``Persistency and Equality``
-          (`#218 <https://github.com/zopefoundation/zope.interface/issues/218>`_).
-        
-        - Create arm64 wheels.
-        
-        - Add support for Python 3.9.
-        
-        
-        5.1.2 (2020-10-01)
-        ==================
-        
-        - Make sure to call each invariant only once when validating invariants.
-          Previously, invariants could be called multiple times because when an
-          invariant is defined in an interface, it's found by in all interfaces
-          inheriting from that interface.  See `pull request 215
-          <https://github.com/zopefoundation/zope.interface/pull/215/>`_.
-        
-        5.1.1 (2020-09-30)
-        ==================
-        
-        - Fix the method definitions of ``IAdapterRegistry.subscribe``,
-          ``subscriptions`` and ``subscribers``. Previously, they all were
-          defined to accept a ``name`` keyword argument, but subscribers have
-          no names and the implementation of that interface did not accept
-          that argument. See `issue 208
-          <https://github.com/zopefoundation/zope.interface/issues/208>`_.
-        
-        - Fix a potential reference leak in the C optimizations. Previously,
-          applications that dynamically created unique ``Specification``
-          objects (e.g., used ``@implementer`` on dynamic classes) could
-          notice a growth of small objects over time leading to increased
-          garbage collection times. See `issue 216
-          <https://github.com/zopefoundation/zope.interface/issues/216>`_.
-        
-          .. caution::
-        
-             This leak could prevent interfaces used as the bases of
-             other interfaces from being garbage collected. Those interfaces
-             will now be collected.
-        
-             One way in which this would manifest was that ``weakref.ref``
-             objects (and things built upon them, like
-             ``WeakKey|ValueDictionary``) would continue to have access to
-             the original object even if there were no other visible
-             references to Python and the original object *should* have been
-             collected. This could be especially problematic for the
-             ``WeakKeyDictionary`` when combined with dynamic or local
-             (created in the scope of a function) interfaces, since interfaces
-             are hashed based just on their name and module name. See the
-             linked issue for an example of a resulting ``KeyError``.
-        
-             Note that such potential errors are not new, they are just once
-             again a possibility.
-        
-        5.1.0 (2020-04-08)
-        ==================
-        
-        - Make ``@implementer(*iface)`` and ``classImplements(cls, *iface)``
-          ignore redundant interfaces. If the class already implements an
-          interface through inheritance, it is no longer redeclared
-          specifically for *cls*. This solves many instances of inconsistent
-          resolution orders, while still allowing the interface to be declared
-          for readability and maintenance purposes. See `issue 199
-          <https://github.com/zopefoundation/zope.interface/issues/199>`_.
-        
-        - Remove all bare ``except:`` statements. Previously, when accessing
-          special attributes such as ``__provides__``, ``__providedBy__``,
-          ``__class__`` and ``__conform__``, this package wrapped such access
-          in a bare ``except:`` statement, meaning that many errors could pass
-          silently; typically this would result in a fallback path being taken
-          and sometimes (like with ``providedBy()``) the result would be
-          non-sensical. This is especially true when those attributes are
-          implemented with descriptors. Now, only ``AttributeError`` is
-          caught. This makes errors more obvious.
-        
-          Obviously, this means that some exceptions will be propagated
-          differently than before. In particular, ``RuntimeError`` raised by
-          Acquisition in the case of circular containment will now be
-          propagated. Previously, when adapting such a broken object, a
-          ``TypeError`` would be the common result, but now it will be a more
-          informative ``RuntimeError``.
-        
-          In addition, ZODB errors like ``POSKeyError`` could now be
-          propagated where previously they would ignored by this package.
-        
-          See `issue 200 <https://github.com/zopefoundation/zope.interface/issues/200>`_.
-        
-        - Require that the second argument (*bases*) to ``InterfaceClass`` is
-          a tuple. This only matters when directly using ``InterfaceClass`` to
-          create new interfaces dynamically. Previously, an individual
-          interface was allowed, but did not work correctly. Now it is
-          consistent with ``type`` and requires a tuple.
-        
-        - Let interfaces define custom ``__adapt__`` methods. This implements
-          the other side of the :pep:`246` adaptation protocol: objects being
-          adapted could already implement ``__conform__`` if they know about
-          the interface, and now interfaces can implement ``__adapt__`` if
-          they know about particular objects. There is no performance penalty
-          for interfaces that do not supply custom ``__adapt__`` methods.
-        
-          This includes the ability to add new methods, or override existing
-          interface methods using the new ``@interfacemethod`` decorator.
-        
-          See `issue 3 <https://github.com/zopefoundation/zope.interface/issues/3>`_.
-        
-        - Make the internal singleton object returned by APIs like
-          ``implementedBy`` and ``directlyProvidedBy`` for objects that
-          implement or provide no interfaces more immutable. Previously an
-          internal cache could be mutated. See `issue 204
-          <https://github.com/zopefoundation/zope.interface/issues/204>`_.
-        
-        5.0.2 (2020-03-30)
-        ==================
-        
-        - Ensure that objects that implement no interfaces (such as direct
-          subclasses of ``object``) still include ``Interface`` itself in
-          their ``__iro___`` and ``__sro___``. This fixes adapter registry
-          lookups for such objects when the adapter is registered for
-          ``Interface``. See `issue 197
-          <https://github.com/zopefoundation/zope.interface/issues/197>`_.
-        
-        
-        5.0.1 (2020-03-21)
-        ==================
-        
-        - Ensure the resolution order for ``InterfaceClass`` is consistent.
-          See `issue 192 <https://github.com/zopefoundation/zope.interface/issues/192>`_.
-        
-        - Ensure the resolution order for ``collections.OrderedDict`` is
-          consistent on CPython 2. (It was already consistent on Python 3 and PyPy).
-        
-        - Fix the handling of the ``ZOPE_INTERFACE_STRICT_IRO`` environment
-          variable. Previously, ``ZOPE_INTERFACE_STRICT_RO`` was read, in
-          contrast with the documentation. See `issue 194
-          <https://github.com/zopefoundation/zope.interface/issues/194>`_.
-        
-        
-        5.0.0 (2020-03-19)
-        ==================
-        
-        - Make an internal singleton object returned by APIs like
-          ``implementedBy`` and ``directlyProvidedBy`` immutable. Previously,
-          it was fully mutable and allowed changing its ``__bases___``. That
-          could potentially lead to wrong results in pathological corner
-          cases. See `issue 158
-          <https://github.com/zopefoundation/zope.interface/issues/158>`_.
-        
-        - Support the ``PURE_PYTHON`` environment variable at runtime instead
-          of just at wheel build time. A value of 0 forces the C extensions to
-          be used (even on PyPy) failing if they aren't present. Any other
-          value forces the Python implementation to be used, ignoring the C
-          extensions. See `PR 151 <https://github.com/zopefoundation/zope.interface/pull/151>`_.
-        
-        - Cache the result of ``__hash__`` method in ``InterfaceClass`` as a
-          speed optimization. The method is called very often (i.e several
-          hundred thousand times during Plone 5.2 startup). Because the hash value never
-          changes it can be cached. This improves test performance from 0.614s
-          down to 0.575s (1.07x faster). In a real world Plone case a reindex
-          index came down from 402s to 320s (1.26x faster). See `PR 156
-          <https://github.com/zopefoundation/zope.interface/pull/156>`_.
-        
-        - Change the C classes ``SpecificationBase`` and its subclass
-          ``ClassProvidesBase`` to store implementation attributes in their structures
-          instead of their instance dictionaries. This eliminates the use of
-          an undocumented private C API function, and helps make some
-          instances require less memory. See `PR 154 <https://github.com/zopefoundation/zope.interface/pull/154>`_.
-        
-        - Reduce memory usage in other ways based on observations of usage
-          patterns in Zope (3) and Plone code bases.
-        
-          - Specifications with no dependents are common (more than 50%) so
-            avoid allocating a ``WeakKeyDictionary`` unless we need it.
-          - Likewise, tagged values are relatively rare, so don't allocate a
-            dictionary to hold them until they are used.
-          - Use ``__slots___`` or the C equivalent ``tp_members`` in more
-            common places. Note that this removes the ability to set arbitrary
-            instance variables on certain objects.
-            See `PR 155 <https://github.com/zopefoundation/zope.interface/pull/155>`_.
-        
-          The changes in this release resulted in a 7% memory reduction after
-          loading about 6,000 modules that define about 2,200 interfaces.
-        
-          .. caution::
-        
-             Details of many private attributes have changed, and external use
-             of those private attributes may break. In particular, the
-             lifetime and default value of ``_v_attrs`` has changed.
-        
-        - Remove support for hashing uninitialized interfaces. This could only
-          be done by subclassing ``InterfaceClass``. This has generated a
-          warning since it was first added in 2011 (3.6.5). Please call the
-          ``InterfaceClass`` constructor or otherwise set the appropriate
-          fields in your subclass before attempting to hash or sort it. See
-          `issue 157 <https://github.com/zopefoundation/zope.interface/issues/157>`_.
-        
-        - Remove unneeded override of the ``__hash__`` method from
-          ``zope.interface.declarations.Implements``. Watching a reindex index
-          process in ZCatalog with on a Py-Spy after 10k samples the time for
-          ``.adapter._lookup`` was reduced from 27.5s to 18.8s (~1.5x faster).
-          Overall reindex index time shrunk from 369s to 293s (1.26x faster).
-          See `PR 161
-          <https://github.com/zopefoundation/zope.interface/pull/161>`_.
-        
-        - Make the Python implementation closer to the C implementation by
-          ignoring all exceptions, not just ``AttributeError``, during (parts
-          of) interface adaptation. See `issue 163
-          <https://github.com/zopefoundation/zope.interface/issues/163>`_.
-        
-        - Micro-optimization in ``.adapter._lookup`` , ``.adapter._lookupAll``
-          and ``.adapter._subscriptions``: By loading ``components.get`` into
-          a local variable before entering the loop a bytcode "LOAD_FAST 0
-          (components)" in the loop can be eliminated. In Plone, while running
-          all tests, average speedup of the "owntime" of ``_lookup`` is ~5x.
-          See `PR 167
-          <https://github.com/zopefoundation/zope.interface/pull/167>`_.
-        
-        - Add ``__all__`` declarations to all modules. This helps tools that
-          do auto-completion and documentation and results in less cluttered
-          results. Wildcard ("*") are not recommended and may be affected. See
-          `issue 153
-          <https://github.com/zopefoundation/zope.interface/issues/153>`_.
-        
-        - Fix ``verifyClass`` and ``verifyObject`` for builtin types like
-          ``dict`` that have methods taking an optional, unnamed argument with
-          no default value like ``dict.pop``. On PyPy3, the verification is
-          strict, but on PyPy2 (as on all versions of CPython) those methods
-          cannot be verified and are ignored. See `issue 118
-          <https://github.com/zopefoundation/zope.interface/issues/118>`_.
-        
-        - Update the common interfaces ``IEnumerableMapping``,
-          ``IExtendedReadMapping``, ``IExtendedWriteMapping``,
-          ``IReadSequence`` and ``IUniqueMemberWriteSequence`` to no longer
-          require methods that were removed from Python 3 on Python 3, such as
-          ``__setslice___``. Now, ``dict``, ``list`` and ``tuple`` properly
-          verify as ``IFullMapping``, ``ISequence`` and ``IReadSequence,``
-          respectively on all versions of Python.
-        
-        - Add human-readable ``__str___`` and ``__repr___`` to ``Attribute``
-          and ``Method``. These contain the name of the defining interface
-          and the attribute. For methods, it also includes the signature.
-        
-        - Change the error strings raised by ``verifyObject`` and
-          ``verifyClass``. They now include more human-readable information
-          and exclude extraneous lines and spaces. See `issue 170
-          <https://github.com/zopefoundation/zope.interface/issues/170>`_.
-        
-          .. caution:: This will break consumers (such as doctests) that
-                       depended on the exact error messages.
-        
-        - Make ``verifyObject`` and ``verifyClass`` report all errors, if the
-          candidate object has multiple detectable violations. Previously they
-          reported only the first error. See `issue
-          <https://github.com/zopefoundation/zope.interface/issues/171>`_.
-        
-          Like the above, this will break consumers depending on the exact
-          output of error messages if more than one error is present.
-        
-        - Add ``zope.interface.common.collections``,
-          ``zope.interface.common.numbers``, and ``zope.interface.common.io``.
-          These modules define interfaces based on the ABCs defined in the
-          standard library ``collections.abc``, ``numbers`` and ``io``
-          modules, respectively. Importing these modules will make the
-          standard library concrete classes that are registered with those
-          ABCs declare the appropriate interface. See `issue 138
-          <https://github.com/zopefoundation/zope.interface/issues/138>`_.
-        
-        - Add ``zope.interface.common.builtins``. This module defines
-          interfaces of common builtin types, such as ``ITextString`` and
-          ``IByteString``, ``IDict``, etc. These interfaces extend the
-          appropriate interfaces from ``collections`` and ``numbers``, and the
-          standard library classes implement them after importing this module.
-          This is intended as a replacement for third-party packages like
-          `dolmen.builtins <https://pypi.org/project/dolmen.builtins/>`_.
-          See `issue 138 <https://github.com/zopefoundation/zope.interface/issues/138>`_.
-        
-        - Make ``providedBy()`` and ``implementedBy()`` respect ``super``
-          objects. For instance, if class ``Derived`` implements ``IDerived``
-          and extends ``Base`` which in turn implements ``IBase``, then
-          ``providedBy(super(Derived, derived))`` will return ``IBase``.
-          Previously it would have returned ``IDerived`` (in general, it
-          would previously have returned whatever would have been returned
-          without ``super``).
-        
-          Along with this change, adapter registries will unpack ``super``
-          objects into their ``__self___`` before passing it to the factory.
-          Together, this means that ``component.getAdapter(super(Derived,
-          self), ITarget)`` is now meaningful.
-        
-          See `issue 11 <https://github.com/zopefoundation/zope.interface/issues/11>`_.
-        
-        - Fix a potential interpreter crash in the low-level adapter
-          registry lookup functions. See issue 11.
-        
-        - Adopt Python's standard `C3 resolution order
-          <https://www.python.org/download/releases/2.3/mro/>`_ to compute the
-          ``__iro__`` and ``__sro__`` of interfaces, with tweaks to support
-          additional cases that are common in interfaces but disallowed for
-          Python classes. Previously, an ad-hoc ordering that made no
-          particular guarantees was used.
-        
-          This has many beneficial properties, including the fact that base
-          interface and base classes tend to appear near the end of the
-          resolution order instead of the beginning. The resolution order in
-          general should be more predictable and consistent.
-        
-          .. caution::
-             In some cases, especially with complex interface inheritance
-             trees or when manually providing or implementing interfaces, the
-             resulting IRO may be quite different. This may affect adapter
-             lookup.
-        
-          The C3 order enforces some constraints in order to be able to
-          guarantee a sensible ordering. Older versions of zope.interface did
-          not impose similar constraints, so it was possible to create
-          interfaces and declarations that are inconsistent with the C3
-          constraints. In that event, zope.interface will still produce a
-          resolution order equal to the old order, but it won't be guaranteed
-          to be fully C3 compliant. In the future, strict enforcement of C3
-          order may be the default.
-        
-          A set of environment variables and module constants allows
-          controlling several aspects of this new behaviour. It is possible to
-          request warnings about inconsistent resolution orders encountered,
-          and even to forbid them. Differences between the C3 resolution order
-          and the previous order can be logged, and, in extreme cases, the
-          previous order can still be used (this ability will be removed in
-          the future). For details, see the documentation for
-          ``zope.interface.ro``.
-        
-        - Make inherited tagged values in interfaces respect the resolution
-          order (``__iro__``), as method and attribute lookup does. Previously
-          tagged values could give inconsistent results. See `issue 190
-          <https://github.com/zopefoundation/zope.interface/issues/190>`_.
-        
-        - Add ``getDirectTaggedValue`` (and related methods) to interfaces to
-          allow accessing tagged values irrespective of inheritance. See
-          `issue 190
-          <https://github.com/zopefoundation/zope.interface/issues/190>`_.
-        
-        - Ensure that ``Interface`` is always the last item in the ``__iro__``
-          and ``__sro__``. This is usually the case, but if classes that do
-          not implement any interfaces are part of a class inheritance
-          hierarchy, ``Interface`` could be assigned too high a priority.
-          See `issue 8 <https://github.com/zopefoundation/zope.interface/issues/8>`_.
-        
-        - Implement sorting, equality, and hashing in C for ``Interface``
-          objects. In micro benchmarks, this makes those operations 40% to 80%
-          faster. This translates to a 20% speed up in querying adapters.
-        
-          Note that this changes certain implementation details. In
-          particular, ``InterfaceClass`` now has a non-default metaclass, and
-          it is enforced that ``__module__`` in instances of
-          ``InterfaceClass`` is read-only.
-        
-          See `PR 183 <https://github.com/zopefoundation/zope.interface/pull/183>`_.
-        
-        
-        4.7.2 (2020-03-10)
-        ==================
-        
-        - Remove deprecated use of setuptools features.  See `issue 30
-          <https://github.com/zopefoundation/zope.interface/issues/30>`_.
-        
-        
-        4.7.1 (2019-11-11)
-        ==================
-        
-        - Use Python 3 syntax in the documentation.  See `issue 119
-          <https://github.com/zopefoundation/zope.interface/issues/119>`_.
-        
-        
-        4.7.0 (2019-11-11)
-        ==================
-        
-        - Drop support for Python 3.4.
-        
-        - Change ``queryTaggedValue``, ``getTaggedValue``,
-          ``getTaggedValueTags`` in interfaces. They now include inherited
-          values by following ``__bases__``. See `PR 144
-          <https://github.com/zopefoundation/zope.interface/pull/144>`_.
-        
-          .. caution:: This may be a breaking change.
-        
-        - Add support for Python 3.8.
-        
-        
-        4.6.0 (2018-10-23)
-        ==================
-        
-        - Add support for Python 3.7
-        
-        - Fix ``verifyObject`` for class objects with staticmethods on
-          Python 3. See `issue 126
-          <https://github.com/zopefoundation/zope.interface/issues/126>`_.
-        
-        
-        4.5.0 (2018-04-19)
-        ==================
-        
-        - Drop support for 3.3, avoid accidental dependence breakage via setup.py.
-          See `PR 110 <https://github.com/zopefoundation/zope.interface/pull/110>`_.
-        - Allow registering and unregistering instance methods as listeners.
-          See `issue 12 <https://github.com/zopefoundation/zope.interface/issues/12>`_
-          and `PR 102 <https://github.com/zopefoundation/zope.interface/pull/102>`_.
-        - Synchronize and simplify zope/__init__.py. See `issue 114
-          <https://github.com/zopefoundation/zope.interface/issues/114>`_
-        
-        
-        4.4.3 (2017-09-22)
-        ==================
-        
-        - Avoid exceptions when the ``__annotations__`` attribute is added to
-          interface definitions with Python 3.x type hints. See `issue 98
-          <https://github.com/zopefoundation/zope.interface/issues/98>`_.
-        - Fix the possibility of a rare crash in the C extension when
-          deallocating items. See `issue 100
-          <https://github.com/zopefoundation/zope.interface/issues/100>`_.
-        
-        
-        4.4.2 (2017-06-14)
-        ==================
-        
-        - Fix a regression storing
-          ``zope.component.persistentregistry.PersistentRegistry`` instances.
-          See `issue 85 <https://github.com/zopefoundation/zope.interface/issues/85>`_.
-        
-        - Fix a regression that could lead to the utility registration cache
-          of ``Components`` getting out of sync. See `issue 93
-          <https://github.com/zopefoundation/zope.interface/issues/93>`_.
-        
-        4.4.1 (2017-05-13)
-        ==================
-        
-        - Simplify the caching of utility-registration data. In addition to
-          simplification, avoids spurious test failures when checking for
-          leaks in tests with persistent registries. See `pull 84
-          <https://github.com/zopefoundation/zope.interface/pull/84>`_.
-        
-        - Raise ``ValueError`` when non-text names are passed to adapter registry
-          methods:  prevents corruption of lookup caches.
-        
-        4.4.0 (2017-04-21)
-        ==================
-        
-        - Avoid a warning from the C compiler.
-          (https://github.com/zopefoundation/zope.interface/issues/71)
-        
-        - Add support for Python 3.6.
-        
-        4.3.3 (2016-12-13)
-        ==================
-        
-        - Correct typos and ReST formatting errors in documentation.
-        
-        - Add API documentation for the adapter registry.
-        
-        - Ensure that the ``LICENSE.txt`` file is included in built wheels.
-        
-        - Fix C optimizations broken on Py3k.  See the Python bug at:
-          http://bugs.python.org/issue15657
-          (https://github.com/zopefoundation/zope.interface/issues/60)
-        
-        
-        4.3.2 (2016-09-05)
-        ==================
-        
-        - Fix equality testing of ``implementedBy`` objects and proxies.
-          (https://github.com/zopefoundation/zope.interface/issues/55)
-        
-        
-        4.3.1 (2016-08-31)
-        ==================
-        
-        - Support Components subclasses that are not hashable.
-          (https://github.com/zopefoundation/zope.interface/issues/53)
-        
-        
-        4.3.0 (2016-08-31)
-        ==================
-        
-        - Add the ability to sort the objects returned by ``implementedBy``.
-          This is compatible with the way interface classes sort so they can
-          be used together in ordered containers like BTrees.
-          (https://github.com/zopefoundation/zope.interface/issues/42)
-        
-        - Make ``setuptools`` a hard dependency of ``setup.py``.
-          (https://github.com/zopefoundation/zope.interface/issues/13)
-        
-        - Change a linear algorithm (O(n)) in ``Components.registerUtility`` and
-          ``Components.unregisterUtility`` into a dictionary lookup (O(1)) for
-          hashable components. This substantially improves the time taken to
-          manipulate utilities in large registries at the cost of some
-          additional memory usage. (https://github.com/zopefoundation/zope.interface/issues/46)
-        
-        
-        4.2.0 (2016-06-10)
-        ==================
-        
-        - Add support for Python 3.5
-        
-        - Drop support for Python 2.6 and 3.2.
-        
-        
-        4.1.3 (2015-10-05)
-        ==================
-        
-        - Fix installation without a C compiler on Python 3.5
-          (https://github.com/zopefoundation/zope.interface/issues/24).
-        
-        
-        4.1.2 (2014-12-27)
-        ==================
-        
-        - Add support for PyPy3.
-        
-        - Remove unittest assertions deprecated in Python3.x.
-        
-        - Add ``zope.interface.document.asReStructuredText``, which formats the
-          generated text for an interface using ReST double-backtick markers.
-        
-        
-        4.1.1 (2014-03-19)
-        ==================
-        
-        - Add support for Python 3.4.
-        
-        
-        4.1.0 (2014-02-05)
-        ==================
-        
-        - Update ``boostrap.py`` to version 2.2.
-        
-        - Add ``@named(name)`` declaration, that specifies the component name, so it
-          does not have to be passed in during registration.
-        
-        
-        4.0.5 (2013-02-28)
-        ==================
-        
-        - Fix a bug where a decorated method caused false positive failures on
-          ``verifyClass()``.
-        
-        
-        4.0.4 (2013-02-21)
-        ==================
-        
-        - Fix a bug that was revealed by porting zope.traversing. During a loop, the
-          loop body modified a weakref dict causing a ``RuntimeError`` error.
-        
-        4.0.3 (2012-12-31)
-        ==================
-        
-        - Fleshed out PyPI Trove classifiers.
-        
-        4.0.2 (2012-11-21)
-        ==================
-        
-        - Add support for Python 3.3.
-        
-        - Restored ability to install the package in the absence of ``setuptools``.
-        
-        - LP #1055223:  Fix test which depended on dictionary order and failed randomly
-          in Python 3.3.
-        
-        4.0.1 (2012-05-22)
-        ==================
-        
-        - Drop explicit ``DeprecationWarnings`` for "class advice" APIS (these
-          APIs are still deprecated under Python 2.x, and still raise an exception
-          under Python 3.x, but no longer cause a warning to be emitted under
-          Python 2.x).
-        
-        4.0.0 (2012-05-16)
-        ==================
-        
-        - Automated build of Sphinx HTML docs and running doctest snippets via tox.
-        
-        - Deprecate the "class advice" APIs from ``zope.interface.declarations``:
-          ``implements``, ``implementsOnly``, and ``classProvides``.  In their place,
-          prefer the equivalent class decorators: ``@implementer``,
-          ``@implementer_only``, and ``@provider``.  Code which uses the deprecated
-          APIs will not work as expected under Py3k.
-        
-        - Remove use of '2to3' and associated fixers when installing under Py3k.
-          The code is now in a "compatible subset" which supports Python 2.6, 2.7,
-          and 3.2, including PyPy 1.8 (the version compatible with the 2.7 language
-          spec).
-        
-        - Drop explicit support for Python 2.4 / 2.5 / 3.1.
-        
-        - Add support for PyPy.
-        
-        - Add support for continuous integration using ``tox`` and ``jenkins``.
-        
-        - Add 'setup.py dev' alias (runs ``setup.py develop`` plus installs
-          ``nose`` and ``coverage``).
-        
-        - Add 'setup.py docs' alias (installs ``Sphinx`` and dependencies).
-        
-        - Replace all unittest coverage previously accomplished via doctests with
-          unittests.  The doctests have been moved into a ``docs`` section, managed
-          as a Sphinx collection.
-        
-        - LP #910987:  Ensure that the semantics of the ``lookup`` method of
-          ``zope.interface.adapter.LookupBase`` are the same in both the C and
-          Python implementations.
-        
-        - LP #900906:  Avoid exceptions due to tne new ``__qualname__`` attribute
-          added in Python 3.3 (see PEP 3155 for rationale).  Thanks to Antoine
-          Pitrou for the patch.
-        
-        3.8.0 (2011-09-22)
-        ==================
-        
-        - New module ``zope.interface.registry``.  This is code moved from
-          ``zope.component.registry`` which implements a basic nonperistent component
-          registry as ``zope.interface.registry.Components``.  This class was moved
-          from ``zope.component`` to make porting systems (such as Pyramid) that rely
-          only on a basic component registry to Python 3 possible without needing to
-          port the entirety of the ``zope.component`` package.  Backwards
-          compatibility import shims have been left behind in ``zope.component``, so
-          this change will not break any existing code.
-        
-        - New ``tests_require`` dependency: ``zope.event`` to test events sent by
-          Components implementation.  The ``zope.interface`` package does not have a
-          hard dependency on ``zope.event``, but if ``zope.event`` is importable, it
-          will send component registration events when methods of an instance of
-          ``zope.interface.registry.Components`` are called.
-        
-        - New interfaces added to support ``zope.interface.registry.Components``
-          addition: ``ComponentLookupError``, ``Invalid``, ``IObjectEvent``,
-          ``ObjectEvent``, ``IComponentLookup``, ``IRegistration``,
-          ``IUtilityRegistration``, ``IAdapterRegistration``,
-          ``ISubscriptionAdapterRegistration``, ``IHandlerRegistration``,
-          ``IRegistrationEvent``, ``RegistrationEvent``, ``IRegistered``,
-          ``Registered``, ``IUnregistered``, ``Unregistered``,
-          ``IComponentRegistry``, and ``IComponents``.
-        
-        - No longer Python 2.4 compatible (tested under 2.5, 2.6, 2.7, and 3.2).
-        
-        3.7.0 (2011-08-13)
-        ==================
-        
-        - Move changes from 3.6.2 - 3.6.5 to a new 3.7.x release line.
-        
-        3.6.7 (2011-08-20)
-        ==================
-        
-        - Fix sporadic failures on x86-64 platforms in tests of rich comparisons
-          of interfaces.
-        
-        3.6.6 (2011-08-13)
-        ==================
-        
-        - LP #570942:  Now correctly compare interfaces  from different modules but
-          with the same names.
-        
-          N.B.: This is a less intrusive / destabilizing fix than the one applied in
-          3.6.3:  we only fix the underlying cmp-alike function, rather than adding
-          the other "rich comparison" functions.
-        
-        - Revert to software as released with 3.6.1 for "stable" 3.6 release branch.
-        
-        3.6.5 (2011-08-11)
-        ==================
-        
-        - LP #811792:  work around buggy behavior in some subclasses of
-          ``zope.interface.interface.InterfaceClass``, which invoke ``__hash__``
-          before initializing ``__module__`` and ``__name__``.  The workaround
-          returns a fixed constant hash in such cases, and issues a ``UserWarning``.
-        
-        - LP #804832:  Under PyPy, ``zope.interface`` should not build its C
-          extension.  Also, prevent attempting to build it under Jython.
-        
-        - Add a tox.ini for easier xplatform testing.
-        
-        - Fix testing deprecation warnings issued when tested under Py3K.
-        
-        3.6.4 (2011-07-04)
-        ==================
-        
-        - LP 804951:  InterfaceClass instances were unhashable under Python 3.x.
-        
-        3.6.3 (2011-05-26)
-        ==================
-        
-        - LP #570942:  Now correctly compare interfaces  from different modules but
-          with the same names.
-        
-        3.6.2 (2011-05-17)
-        ==================
-        
-        - Moved detailed documentation out-of-line from PyPI page, linking instead to
-          http://docs.zope.org/zope.interface .
-        
-        - Fixes for small issues when running tests under Python 3.2 using
-          ``zope.testrunner``.
-        
-        - LP # 675064:  Specify return value type for C optimizations module init
-          under Python 3:  undeclared value caused warnings, and segfaults on some
-          64 bit architectures.
-        
-        - setup.py now raises RuntimeError if you don't have Distutils installed when
-          running under Python 3.
-        
-        3.6.1 (2010-05-03)
-        ==================
-        
-        - A non-ASCII character in the changelog made 3.6.0 uninstallable on
-          Python 3 systems with another default encoding than UTF-8.
-        
-        - Fix compiler warnings under GCC 4.3.3.
-        
-        3.6.0 (2010-04-29)
-        ==================
-        
-        - LP #185974:  Clear the cache used by ``Specificaton.get`` inside
-          ``Specification.changed``.  Thanks to Jacob Holm for the patch.
-        
-        - Add support for Python 3.1. Contributors:
-        
-            Lennart Regebro
-            Martin v Loewis
-            Thomas Lotze
-            Wolfgang Schnerring
-        
-          The 3.1 support is completely backwards compatible. However, the implements
-          syntax used under Python 2.X does not work under 3.X, since it depends on
-          how metaclasses are implemented and this has changed. Instead it now supports
-          a decorator syntax (also under Python 2.X)::
-        
-            class Foo:
-                implements(IFoo)
-                ...
-        
-          can now also be written::
-        
-            @implementer(IFoo):
-            class Foo:
-                ...
-        
-          There are 2to3 fixers available to do this change automatically in the
-          zope.fixers package.
-        
-        - Python 2.3 is no longer supported.
-        
-        
-        3.5.4 (2009-12-23)
-        ==================
-        
-        - Use the standard Python doctest module instead of zope.testing.doctest, which
-          has been deprecated.
-        
-        
-        3.5.3 (2009-12-08)
-        ==================
-        
-        - Fix an edge case: make providedBy() work when a class has '__provides__' in
-          its __slots__ (see http://thread.gmane.org/gmane.comp.web.zope.devel/22490)
-        
-        
-        3.5.2 (2009-07-01)
-        ==================
-        
-        - BaseAdapterRegistry.unregister, unsubscribe: Remove empty portions of
-          the data structures when something is removed.  This avoids leaving
-          references to global objects (interfaces) that may be slated for
-          removal from the calling application.
-        
-        
-        3.5.1 (2009-03-18)
-        ==================
-        
-        - verifyObject: use getattr instead of hasattr to test for object attributes
-          in order to let exceptions other than AttributeError raised by properties
-          propagate to the caller
-        
-        - Add Sphinx-based documentation building to the package buildout
-          configuration. Use the ``bin/docs`` command after buildout.
-        
-        - Improve package description a bit. Unify changelog entries formatting.
-        
-        - Change package's mailing list address to zope-dev at zope.org as
-          zope3-dev at zope.org is now retired.
-        
-        
-        3.5.0 (2008-10-26)
-        ==================
-        
-        - Fix declaration of _zope_interface_coptimizations, it's not a top level
-          package.
-        
-        - Add a DocTestSuite for odd.py module, so their tests are run.
-        
-        - Allow to bootstrap on Jython.
-        
-        - Fix https://bugs.launchpad.net/zope3/3.3/+bug/98388: ISpecification
-          was missing a declaration for __iro__.
-        
-        - Add optional code optimizations support, which allows the building
-          of C code optimizations to fail (Jython).
-        
-        - Replace `_flatten` with a non-recursive implementation, effectively making
-          it 3x faster.
-        
-        
-        3.4.1 (2007-10-02)
-        ==================
-        
-        - Fix a setup bug that prevented installation from source on systems
-          without setuptools.
-        
-        
-        3.4.0 (2007-07-19)
-        ==================
-        
-        - Final release for 3.4.0.
-        
-        
-        3.4.0b3 (2007-05-22)
-        ====================
-        
-        
-        - When checking whether an object is already registered, use identity
-          comparison, to allow adding registering with picky custom comparison methods.
-        
-        
-        3.3.0.1 (2007-01-03)
-        ====================
-        
-        - Made a reference to OverflowWarning, which disappeared in Python
-          2.5, conditional.
-        
-        
-        3.3.0 (2007/01/03)
-        ==================
-        
-        New Features
-        ------------
-        
-        - Refactor the adapter-lookup algorithim to make it much simpler and faster.
-        
-          Also, implement more of the adapter-lookup logic in C, making
-          debugging of application code easier, since there is less
-          infrastructre code to step through.
-        
-        - Treat objects without interface declarations as if they
-          declared that they provide ``zope.interface.Interface``.
-        
-        - Add a number of richer new adapter-registration interfaces
-          that provide greater control and introspection.
-        
-        - Add a new interface decorator to zope.interface that allows the
-          setting of tagged values on an interface at definition time (see
-          zope.interface.taggedValue).
-        
-        Bug Fixes
-        ---------
-        
-        - A bug in multi-adapter lookup sometimes caused incorrect adapters to
-          be returned.
-        
-        
-        3.2.0.2 (2006-04-15)
-        ====================
-        
-        - Fix packaging bug:  'package_dir' must be a *relative* path.
-        
-        
-        3.2.0.1 (2006-04-14)
-        ====================
-        
-        - Packaging change:  suppress inclusion of 'setup.cfg' in 'sdist' builds.
-        
-        
-        3.2.0 (2006-01-05)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope 3.2.0 release.
-        
-        
-        3.1.0 (2005-10-03)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope 3.1.0 release.
-        
-        - Made attribute resolution order consistent with component lookup order,
-          i.e. new-style class MRO semantics.
-        
-        - Deprecate 'isImplementedBy' and 'isImplementedByInstancesOf' APIs in
-          favor of 'implementedBy' and 'providedBy'.
-        
-        
-        3.0.1 (2005-07-27)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope X3.0.1 release.
-        
-        - Fix a bug reported by James Knight, which caused adapter registries
-          to fail occasionally to reflect declaration changes.
-        
-        
-        3.0.0 (2004-11-07)
-        ==================
-        
-        - Corresponds to the verison of the zope.interface package shipped as part of
-          the Zope X3.0.0 release.
-        
 Keywords: interface,components,plugins
-Platform: UNKNOWN
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Zope Public License
@@ -1047,6 +19,9 @@
 Classifier: Programming Language :: Python :: 3.6
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Framework :: Zope :: 3
@@ -1055,3 +30,1056 @@
 Provides-Extra: docs
 Provides-Extra: test
 Provides-Extra: testing
+License-File: LICENSE.txt
+
+====================
+ ``zope.interface``
+====================
+
+.. image:: https://img.shields.io/pypi/v/zope.interface.svg
+    :target: https://pypi.python.org/pypi/zope.interface/
+    :alt: Latest Version
+
+.. image:: https://img.shields.io/pypi/pyversions/zope.interface.svg
+        :target: https://pypi.org/project/zope.interface/
+        :alt: Supported Python versions
+
+.. image:: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml/badge.svg
+        :target: https://github.com/zopefoundation/zope.interface/actions/workflows/tests.yml
+
+.. image:: https://readthedocs.org/projects/zopeinterface/badge/?version=latest
+        :target: https://zopeinterface.readthedocs.io/en/latest/
+        :alt: Documentation Status
+
+This package is intended to be independently reusable in any Python
+project. It is maintained by the `Zope Toolkit project
+<https://zopetoolkit.readthedocs.io/>`_.
+
+This package provides an implementation of "object interfaces" for Python.
+Interfaces are a mechanism for labeling objects as conforming to a given
+API or contract. So, this package can be considered as implementation of
+the `Design By Contract`_ methodology support in Python.
+
+.. _Design By Contract: http://en.wikipedia.org/wiki/Design_by_contract
+
+For detailed documentation, please see https://zopeinterface.readthedocs.io/en/latest/
+
+=========
+ Changes
+=========
+
+5.5.2 (2022-11-17)
+==================
+
+- Add support for building arm64 wheels on macOS.
+
+
+5.5.1 (2022-11-03)
+==================
+
+- Add support for final Python 3.11 release.
+
+
+5.5.0 (2022-10-10)
+==================
+
+- Add support for Python 3.10 and 3.11 (as of 3.11.0rc2).
+
+- Add missing Trove classifier showing support for Python 3.9.
+
+- Add some more entries to ``zope.interface.interfaces.__all__``.
+
+- Disable unsafe math optimizations in C code.  See `pull request 262
+  <https://github.com/zopefoundation/zope.interface/pull/262>`_.
+
+
+5.4.0 (2021-04-15)
+==================
+
+- Make the C implementation of the ``__providedBy__`` descriptor stop
+  ignoring all errors raised when accessing the instance's
+  ``__provides__``. Now it behaves like the Python version and only
+  catches ``AttributeError``. The previous behaviour could lead to
+  crashing the interpreter in cases of recursion and errors. See
+  `issue 239 <https://github.com/zopefoundation/zope.interface/issues>`_.
+
+- Update the ``repr()`` and ``str()`` of various objects to be shorter
+  and more informative. In many cases, the ``repr()`` is now something
+  that can be evaluated to produce an equal object. For example, what
+  was previously printed as ``<implementedBy builtins.list>`` is now
+  shown as ``classImplements(list, IMutableSequence, IIterable)``. See
+  `issue 236 <https://github.com/zopefoundation/zope.interface/issues/236>`_.
+
+- Make ``Declaration.__add__`` (as in ``implementedBy(Cls) +
+  ISomething``) try harder to preserve a consistent resolution order
+  when the two arguments share overlapping pieces of the interface
+  inheritance hierarchy. Previously, the right hand side was always
+  put at the end of the resolution order, which could easily produce
+  invalid orders. See `issue 193
+  <https://github.com/zopefoundation/zope.interface/issues/193>`_.
+
+5.3.0 (2020-03-21)
+==================
+
+- No changes from 5.3.0a1
+
+
+5.3.0a1 (2021-03-18)
+====================
+
+- Improve the repr of ``zope.interface.Provides`` to remove ambiguity
+  about what is being provided. This is especially helpful diagnosing
+  IRO issues.
+
+- Allow subclasses of ``BaseAdapterRegistry`` (including
+  ``AdapterRegistry`` and ``VerifyingAdapterRegistry``) to have
+  control over the data structures. This allows persistent
+  implementations such as those based on ZODB to choose more scalable
+  options (e.g., BTrees instead of dicts). See `issue 224
+  <https://github.com/zopefoundation/zope.interface/issues/224>`_.
+
+- Fix a reference counting issue in ``BaseAdapterRegistry`` that could
+  lead to references to interfaces being kept around even when all
+  utilities/adapters/subscribers providing that interface have been
+  removed. This is mostly an issue for persistent implementations.
+  Note that this only corrects the issue moving forward, it does not
+  solve any already corrupted reference counts. See `issue 227
+  <https://github.com/zopefoundation/zope.interface/issues/227>`_.
+
+- Add the method ``BaseAdapterRegistry.rebuild()``. This can be used
+  to fix the reference counting issue mentioned above, as well as to
+  update the data structures when custom data types have changed.
+
+- Add the interface method ``IAdapterRegistry.subscribed()`` and
+  implementation ``BaseAdapterRegistry.subscribed()`` for querying
+  directly registered subscribers. See `issue 230
+  <https://github.com/zopefoundation/zope.interface/issues/230>`_.
+
+- Add the maintenance method
+  ``Components.rebuildUtilityRegistryFromLocalCache()``. Most users
+  will not need this, but it can be useful if the ``Components.utilities``
+  registry is suspected to be out of sync with the ``Components``
+  object itself (this might happen to persistent ``Components``
+  implementations in the face of bugs).
+
+- Fix the ``Provides`` and ``ClassProvides`` descriptors to stop
+  allowing redundant interfaces (those already implemented by the
+  underlying class or meta class) to produce an inconsistent
+  resolution order. This is similar to the change in ``@implementer``
+  in 5.1.0, and resolves inconsistent resolution orders with
+  ``zope.proxy`` and ``zope.location``. See `issue 207
+  <https://github.com/zopefoundation/zope.interface/issues/207>`_.
+
+5.2.0 (2020-11-05)
+==================
+
+- Add documentation section ``Persistency and Equality``
+  (`#218 <https://github.com/zopefoundation/zope.interface/issues/218>`_).
+
+- Create arm64 wheels.
+
+- Add support for Python 3.9.
+
+
+5.1.2 (2020-10-01)
+==================
+
+- Make sure to call each invariant only once when validating invariants.
+  Previously, invariants could be called multiple times because when an
+  invariant is defined in an interface, it's found by in all interfaces
+  inheriting from that interface.  See `pull request 215
+  <https://github.com/zopefoundation/zope.interface/pull/215/>`_.
+
+5.1.1 (2020-09-30)
+==================
+
+- Fix the method definitions of ``IAdapterRegistry.subscribe``,
+  ``subscriptions`` and ``subscribers``. Previously, they all were
+  defined to accept a ``name`` keyword argument, but subscribers have
+  no names and the implementation of that interface did not accept
+  that argument. See `issue 208
+  <https://github.com/zopefoundation/zope.interface/issues/208>`_.
+
+- Fix a potential reference leak in the C optimizations. Previously,
+  applications that dynamically created unique ``Specification``
+  objects (e.g., used ``@implementer`` on dynamic classes) could
+  notice a growth of small objects over time leading to increased
+  garbage collection times. See `issue 216
+  <https://github.com/zopefoundation/zope.interface/issues/216>`_.
+
+  .. caution::
+
+     This leak could prevent interfaces used as the bases of
+     other interfaces from being garbage collected. Those interfaces
+     will now be collected.
+
+     One way in which this would manifest was that ``weakref.ref``
+     objects (and things built upon them, like
+     ``WeakKey|ValueDictionary``) would continue to have access to
+     the original object even if there were no other visible
+     references to Python and the original object *should* have been
+     collected. This could be especially problematic for the
+     ``WeakKeyDictionary`` when combined with dynamic or local
+     (created in the scope of a function) interfaces, since interfaces
+     are hashed based just on their name and module name. See the
+     linked issue for an example of a resulting ``KeyError``.
+
+     Note that such potential errors are not new, they are just once
+     again a possibility.
+
+5.1.0 (2020-04-08)
+==================
+
+- Make ``@implementer(*iface)`` and ``classImplements(cls, *iface)``
+  ignore redundant interfaces. If the class already implements an
+  interface through inheritance, it is no longer redeclared
+  specifically for *cls*. This solves many instances of inconsistent
+  resolution orders, while still allowing the interface to be declared
+  for readability and maintenance purposes. See `issue 199
+  <https://github.com/zopefoundation/zope.interface/issues/199>`_.
+
+- Remove all bare ``except:`` statements. Previously, when accessing
+  special attributes such as ``__provides__``, ``__providedBy__``,
+  ``__class__`` and ``__conform__``, this package wrapped such access
+  in a bare ``except:`` statement, meaning that many errors could pass
+  silently; typically this would result in a fallback path being taken
+  and sometimes (like with ``providedBy()``) the result would be
+  non-sensical. This is especially true when those attributes are
+  implemented with descriptors. Now, only ``AttributeError`` is
+  caught. This makes errors more obvious.
+
+  Obviously, this means that some exceptions will be propagated
+  differently than before. In particular, ``RuntimeError`` raised by
+  Acquisition in the case of circular containment will now be
+  propagated. Previously, when adapting such a broken object, a
+  ``TypeError`` would be the common result, but now it will be a more
+  informative ``RuntimeError``.
+
+  In addition, ZODB errors like ``POSKeyError`` could now be
+  propagated where previously they would ignored by this package.
+
+  See `issue 200 <https://github.com/zopefoundation/zope.interface/issues/200>`_.
+
+- Require that the second argument (*bases*) to ``InterfaceClass`` is
+  a tuple. This only matters when directly using ``InterfaceClass`` to
+  create new interfaces dynamically. Previously, an individual
+  interface was allowed, but did not work correctly. Now it is
+  consistent with ``type`` and requires a tuple.
+
+- Let interfaces define custom ``__adapt__`` methods. This implements
+  the other side of the :pep:`246` adaptation protocol: objects being
+  adapted could already implement ``__conform__`` if they know about
+  the interface, and now interfaces can implement ``__adapt__`` if
+  they know about particular objects. There is no performance penalty
+  for interfaces that do not supply custom ``__adapt__`` methods.
+
+  This includes the ability to add new methods, or override existing
+  interface methods using the new ``@interfacemethod`` decorator.
+
+  See `issue 3 <https://github.com/zopefoundation/zope.interface/issues/3>`_.
+
+- Make the internal singleton object returned by APIs like
+  ``implementedBy`` and ``directlyProvidedBy`` for objects that
+  implement or provide no interfaces more immutable. Previously an
+  internal cache could be mutated. See `issue 204
+  <https://github.com/zopefoundation/zope.interface/issues/204>`_.
+
+5.0.2 (2020-03-30)
+==================
+
+- Ensure that objects that implement no interfaces (such as direct
+  subclasses of ``object``) still include ``Interface`` itself in
+  their ``__iro___`` and ``__sro___``. This fixes adapter registry
+  lookups for such objects when the adapter is registered for
+  ``Interface``. See `issue 197
+  <https://github.com/zopefoundation/zope.interface/issues/197>`_.
+
+
+5.0.1 (2020-03-21)
+==================
+
+- Ensure the resolution order for ``InterfaceClass`` is consistent.
+  See `issue 192 <https://github.com/zopefoundation/zope.interface/issues/192>`_.
+
+- Ensure the resolution order for ``collections.OrderedDict`` is
+  consistent on CPython 2. (It was already consistent on Python 3 and PyPy).
+
+- Fix the handling of the ``ZOPE_INTERFACE_STRICT_IRO`` environment
+  variable. Previously, ``ZOPE_INTERFACE_STRICT_RO`` was read, in
+  contrast with the documentation. See `issue 194
+  <https://github.com/zopefoundation/zope.interface/issues/194>`_.
+
+
+5.0.0 (2020-03-19)
+==================
+
+- Make an internal singleton object returned by APIs like
+  ``implementedBy`` and ``directlyProvidedBy`` immutable. Previously,
+  it was fully mutable and allowed changing its ``__bases___``. That
+  could potentially lead to wrong results in pathological corner
+  cases. See `issue 158
+  <https://github.com/zopefoundation/zope.interface/issues/158>`_.
+
+- Support the ``PURE_PYTHON`` environment variable at runtime instead
+  of just at wheel build time. A value of 0 forces the C extensions to
+  be used (even on PyPy) failing if they aren't present. Any other
+  value forces the Python implementation to be used, ignoring the C
+  extensions. See `PR 151 <https://github.com/zopefoundation/zope.interface/pull/151>`_.
+
+- Cache the result of ``__hash__`` method in ``InterfaceClass`` as a
+  speed optimization. The method is called very often (i.e several
+  hundred thousand times during Plone 5.2 startup). Because the hash value never
+  changes it can be cached. This improves test performance from 0.614s
+  down to 0.575s (1.07x faster). In a real world Plone case a reindex
+  index came down from 402s to 320s (1.26x faster). See `PR 156
+  <https://github.com/zopefoundation/zope.interface/pull/156>`_.
+
+- Change the C classes ``SpecificationBase`` and its subclass
+  ``ClassProvidesBase`` to store implementation attributes in their structures
+  instead of their instance dictionaries. This eliminates the use of
+  an undocumented private C API function, and helps make some
+  instances require less memory. See `PR 154 <https://github.com/zopefoundation/zope.interface/pull/154>`_.
+
+- Reduce memory usage in other ways based on observations of usage
+  patterns in Zope (3) and Plone code bases.
+
+  - Specifications with no dependents are common (more than 50%) so
+    avoid allocating a ``WeakKeyDictionary`` unless we need it.
+  - Likewise, tagged values are relatively rare, so don't allocate a
+    dictionary to hold them until they are used.
+  - Use ``__slots___`` or the C equivalent ``tp_members`` in more
+    common places. Note that this removes the ability to set arbitrary
+    instance variables on certain objects.
+    See `PR 155 <https://github.com/zopefoundation/zope.interface/pull/155>`_.
+
+  The changes in this release resulted in a 7% memory reduction after
+  loading about 6,000 modules that define about 2,200 interfaces.
+
+  .. caution::
+
+     Details of many private attributes have changed, and external use
+     of those private attributes may break. In particular, the
+     lifetime and default value of ``_v_attrs`` has changed.
+
+- Remove support for hashing uninitialized interfaces. This could only
+  be done by subclassing ``InterfaceClass``. This has generated a
+  warning since it was first added in 2011 (3.6.5). Please call the
+  ``InterfaceClass`` constructor or otherwise set the appropriate
+  fields in your subclass before attempting to hash or sort it. See
+  `issue 157 <https://github.com/zopefoundation/zope.interface/issues/157>`_.
+
+- Remove unneeded override of the ``__hash__`` method from
+  ``zope.interface.declarations.Implements``. Watching a reindex index
+  process in ZCatalog with on a Py-Spy after 10k samples the time for
+  ``.adapter._lookup`` was reduced from 27.5s to 18.8s (~1.5x faster).
+  Overall reindex index time shrunk from 369s to 293s (1.26x faster).
+  See `PR 161
+  <https://github.com/zopefoundation/zope.interface/pull/161>`_.
+
+- Make the Python implementation closer to the C implementation by
+  ignoring all exceptions, not just ``AttributeError``, during (parts
+  of) interface adaptation. See `issue 163
+  <https://github.com/zopefoundation/zope.interface/issues/163>`_.
+
+- Micro-optimization in ``.adapter._lookup`` , ``.adapter._lookupAll``
+  and ``.adapter._subscriptions``: By loading ``components.get`` into
+  a local variable before entering the loop a bytcode "LOAD_FAST 0
+  (components)" in the loop can be eliminated. In Plone, while running
+  all tests, average speedup of the "owntime" of ``_lookup`` is ~5x.
+  See `PR 167
+  <https://github.com/zopefoundation/zope.interface/pull/167>`_.
+
+- Add ``__all__`` declarations to all modules. This helps tools that
+  do auto-completion and documentation and results in less cluttered
+  results. Wildcard ("*") are not recommended and may be affected. See
+  `issue 153
+  <https://github.com/zopefoundation/zope.interface/issues/153>`_.
+
+- Fix ``verifyClass`` and ``verifyObject`` for builtin types like
+  ``dict`` that have methods taking an optional, unnamed argument with
+  no default value like ``dict.pop``. On PyPy3, the verification is
+  strict, but on PyPy2 (as on all versions of CPython) those methods
+  cannot be verified and are ignored. See `issue 118
+  <https://github.com/zopefoundation/zope.interface/issues/118>`_.
+
+- Update the common interfaces ``IEnumerableMapping``,
+  ``IExtendedReadMapping``, ``IExtendedWriteMapping``,
+  ``IReadSequence`` and ``IUniqueMemberWriteSequence`` to no longer
+  require methods that were removed from Python 3 on Python 3, such as
+  ``__setslice___``. Now, ``dict``, ``list`` and ``tuple`` properly
+  verify as ``IFullMapping``, ``ISequence`` and ``IReadSequence,``
+  respectively on all versions of Python.
+
+- Add human-readable ``__str___`` and ``__repr___`` to ``Attribute``
+  and ``Method``. These contain the name of the defining interface
+  and the attribute. For methods, it also includes the signature.
+
+- Change the error strings raised by ``verifyObject`` and
+  ``verifyClass``. They now include more human-readable information
+  and exclude extraneous lines and spaces. See `issue 170
+  <https://github.com/zopefoundation/zope.interface/issues/170>`_.
+
+  .. caution:: This will break consumers (such as doctests) that
+               depended on the exact error messages.
+
+- Make ``verifyObject`` and ``verifyClass`` report all errors, if the
+  candidate object has multiple detectable violations. Previously they
+  reported only the first error. See `issue
+  <https://github.com/zopefoundation/zope.interface/issues/171>`_.
+
+  Like the above, this will break consumers depending on the exact
+  output of error messages if more than one error is present.
+
+- Add ``zope.interface.common.collections``,
+  ``zope.interface.common.numbers``, and ``zope.interface.common.io``.
+  These modules define interfaces based on the ABCs defined in the
+  standard library ``collections.abc``, ``numbers`` and ``io``
+  modules, respectively. Importing these modules will make the
+  standard library concrete classes that are registered with those
+  ABCs declare the appropriate interface. See `issue 138
+  <https://github.com/zopefoundation/zope.interface/issues/138>`_.
+
+- Add ``zope.interface.common.builtins``. This module defines
+  interfaces of common builtin types, such as ``ITextString`` and
+  ``IByteString``, ``IDict``, etc. These interfaces extend the
+  appropriate interfaces from ``collections`` and ``numbers``, and the
+  standard library classes implement them after importing this module.
+  This is intended as a replacement for third-party packages like
+  `dolmen.builtins <https://pypi.org/project/dolmen.builtins/>`_.
+  See `issue 138 <https://github.com/zopefoundation/zope.interface/issues/138>`_.
+
+- Make ``providedBy()`` and ``implementedBy()`` respect ``super``
+  objects. For instance, if class ``Derived`` implements ``IDerived``
+  and extends ``Base`` which in turn implements ``IBase``, then
+  ``providedBy(super(Derived, derived))`` will return ``IBase``.
+  Previously it would have returned ``IDerived`` (in general, it
+  would previously have returned whatever would have been returned
+  without ``super``).
+
+  Along with this change, adapter registries will unpack ``super``
+  objects into their ``__self___`` before passing it to the factory.
+  Together, this means that ``component.getAdapter(super(Derived,
+  self), ITarget)`` is now meaningful.
+
+  See `issue 11 <https://github.com/zopefoundation/zope.interface/issues/11>`_.
+
+- Fix a potential interpreter crash in the low-level adapter
+  registry lookup functions. See issue 11.
+
+- Adopt Python's standard `C3 resolution order
+  <https://www.python.org/download/releases/2.3/mro/>`_ to compute the
+  ``__iro__`` and ``__sro__`` of interfaces, with tweaks to support
+  additional cases that are common in interfaces but disallowed for
+  Python classes. Previously, an ad-hoc ordering that made no
+  particular guarantees was used.
+
+  This has many beneficial properties, including the fact that base
+  interface and base classes tend to appear near the end of the
+  resolution order instead of the beginning. The resolution order in
+  general should be more predictable and consistent.
+
+  .. caution::
+     In some cases, especially with complex interface inheritance
+     trees or when manually providing or implementing interfaces, the
+     resulting IRO may be quite different. This may affect adapter
+     lookup.
+
+  The C3 order enforces some constraints in order to be able to
+  guarantee a sensible ordering. Older versions of zope.interface did
+  not impose similar constraints, so it was possible to create
+  interfaces and declarations that are inconsistent with the C3
+  constraints. In that event, zope.interface will still produce a
+  resolution order equal to the old order, but it won't be guaranteed
+  to be fully C3 compliant. In the future, strict enforcement of C3
+  order may be the default.
+
+  A set of environment variables and module constants allows
+  controlling several aspects of this new behaviour. It is possible to
+  request warnings about inconsistent resolution orders encountered,
+  and even to forbid them. Differences between the C3 resolution order
+  and the previous order can be logged, and, in extreme cases, the
+  previous order can still be used (this ability will be removed in
+  the future). For details, see the documentation for
+  ``zope.interface.ro``.
+
+- Make inherited tagged values in interfaces respect the resolution
+  order (``__iro__``), as method and attribute lookup does. Previously
+  tagged values could give inconsistent results. See `issue 190
+  <https://github.com/zopefoundation/zope.interface/issues/190>`_.
+
+- Add ``getDirectTaggedValue`` (and related methods) to interfaces to
+  allow accessing tagged values irrespective of inheritance. See
+  `issue 190
+  <https://github.com/zopefoundation/zope.interface/issues/190>`_.
+
+- Ensure that ``Interface`` is always the last item in the ``__iro__``
+  and ``__sro__``. This is usually the case, but if classes that do
+  not implement any interfaces are part of a class inheritance
+  hierarchy, ``Interface`` could be assigned too high a priority.
+  See `issue 8 <https://github.com/zopefoundation/zope.interface/issues/8>`_.
+
+- Implement sorting, equality, and hashing in C for ``Interface``
+  objects. In micro benchmarks, this makes those operations 40% to 80%
+  faster. This translates to a 20% speed up in querying adapters.
+
+  Note that this changes certain implementation details. In
+  particular, ``InterfaceClass`` now has a non-default metaclass, and
+  it is enforced that ``__module__`` in instances of
+  ``InterfaceClass`` is read-only.
+
+  See `PR 183 <https://github.com/zopefoundation/zope.interface/pull/183>`_.
+
+
+4.7.2 (2020-03-10)
+==================
+
+- Remove deprecated use of setuptools features.  See `issue 30
+  <https://github.com/zopefoundation/zope.interface/issues/30>`_.
+
+
+4.7.1 (2019-11-11)
+==================
+
+- Use Python 3 syntax in the documentation.  See `issue 119
+  <https://github.com/zopefoundation/zope.interface/issues/119>`_.
+
+
+4.7.0 (2019-11-11)
+==================
+
+- Drop support for Python 3.4.
+
+- Change ``queryTaggedValue``, ``getTaggedValue``,
+  ``getTaggedValueTags`` in interfaces. They now include inherited
+  values by following ``__bases__``. See `PR 144
+  <https://github.com/zopefoundation/zope.interface/pull/144>`_.
+
+  .. caution:: This may be a breaking change.
+
+- Add support for Python 3.8.
+
+
+4.6.0 (2018-10-23)
+==================
+
+- Add support for Python 3.7
+
+- Fix ``verifyObject`` for class objects with staticmethods on
+  Python 3. See `issue 126
+  <https://github.com/zopefoundation/zope.interface/issues/126>`_.
+
+
+4.5.0 (2018-04-19)
+==================
+
+- Drop support for 3.3, avoid accidental dependence breakage via setup.py.
+  See `PR 110 <https://github.com/zopefoundation/zope.interface/pull/110>`_.
+- Allow registering and unregistering instance methods as listeners.
+  See `issue 12 <https://github.com/zopefoundation/zope.interface/issues/12>`_
+  and `PR 102 <https://github.com/zopefoundation/zope.interface/pull/102>`_.
+- Synchronize and simplify zope/__init__.py. See `issue 114
+  <https://github.com/zopefoundation/zope.interface/issues/114>`_
+
+
+4.4.3 (2017-09-22)
+==================
+
+- Avoid exceptions when the ``__annotations__`` attribute is added to
+  interface definitions with Python 3.x type hints. See `issue 98
+  <https://github.com/zopefoundation/zope.interface/issues/98>`_.
+- Fix the possibility of a rare crash in the C extension when
+  deallocating items. See `issue 100
+  <https://github.com/zopefoundation/zope.interface/issues/100>`_.
+
+
+4.4.2 (2017-06-14)
+==================
+
+- Fix a regression storing
+  ``zope.component.persistentregistry.PersistentRegistry`` instances.
+  See `issue 85 <https://github.com/zopefoundation/zope.interface/issues/85>`_.
+
+- Fix a regression that could lead to the utility registration cache
+  of ``Components`` getting out of sync. See `issue 93
+  <https://github.com/zopefoundation/zope.interface/issues/93>`_.
+
+4.4.1 (2017-05-13)
+==================
+
+- Simplify the caching of utility-registration data. In addition to
+  simplification, avoids spurious test failures when checking for
+  leaks in tests with persistent registries. See `pull 84
+  <https://github.com/zopefoundation/zope.interface/pull/84>`_.
+
+- Raise ``ValueError`` when non-text names are passed to adapter registry
+  methods:  prevents corruption of lookup caches.
+
+4.4.0 (2017-04-21)
+==================
+
+- Avoid a warning from the C compiler.
+  (https://github.com/zopefoundation/zope.interface/issues/71)
+
+- Add support for Python 3.6.
+
+4.3.3 (2016-12-13)
+==================
+
+- Correct typos and ReST formatting errors in documentation.
+
+- Add API documentation for the adapter registry.
+
+- Ensure that the ``LICENSE.txt`` file is included in built wheels.
+
+- Fix C optimizations broken on Py3k.  See the Python bug at:
+  http://bugs.python.org/issue15657
+  (https://github.com/zopefoundation/zope.interface/issues/60)
+
+
+4.3.2 (2016-09-05)
+==================
+
+- Fix equality testing of ``implementedBy`` objects and proxies.
+  (https://github.com/zopefoundation/zope.interface/issues/55)
+
+
+4.3.1 (2016-08-31)
+==================
+
+- Support Components subclasses that are not hashable.
+  (https://github.com/zopefoundation/zope.interface/issues/53)
+
+
+4.3.0 (2016-08-31)
+==================
+
+- Add the ability to sort the objects returned by ``implementedBy``.
+  This is compatible with the way interface classes sort so they can
+  be used together in ordered containers like BTrees.
+  (https://github.com/zopefoundation/zope.interface/issues/42)
+
+- Make ``setuptools`` a hard dependency of ``setup.py``.
+  (https://github.com/zopefoundation/zope.interface/issues/13)
+
+- Change a linear algorithm (O(n)) in ``Components.registerUtility`` and
+  ``Components.unregisterUtility`` into a dictionary lookup (O(1)) for
+  hashable components. This substantially improves the time taken to
+  manipulate utilities in large registries at the cost of some
+  additional memory usage. (https://github.com/zopefoundation/zope.interface/issues/46)
+
+
+4.2.0 (2016-06-10)
+==================
+
+- Add support for Python 3.5
+
+- Drop support for Python 2.6 and 3.2.
+
+
+4.1.3 (2015-10-05)
+==================
+
+- Fix installation without a C compiler on Python 3.5
+  (https://github.com/zopefoundation/zope.interface/issues/24).
+
+
+4.1.2 (2014-12-27)
+==================
+
+- Add support for PyPy3.
+
+- Remove unittest assertions deprecated in Python3.x.
+
+- Add ``zope.interface.document.asReStructuredText``, which formats the
+  generated text for an interface using ReST double-backtick markers.
+
+
+4.1.1 (2014-03-19)
+==================
+
+- Add support for Python 3.4.
+
+
+4.1.0 (2014-02-05)
+==================
+
+- Update ``boostrap.py`` to version 2.2.
+
+- Add ``@named(name)`` declaration, that specifies the component name, so it
+  does not have to be passed in during registration.
+
+
+4.0.5 (2013-02-28)
+==================
+
+- Fix a bug where a decorated method caused false positive failures on
+  ``verifyClass()``.
+
+
+4.0.4 (2013-02-21)
+==================
+
+- Fix a bug that was revealed by porting zope.traversing. During a loop, the
+  loop body modified a weakref dict causing a ``RuntimeError`` error.
+
+4.0.3 (2012-12-31)
+==================
+
+- Fleshed out PyPI Trove classifiers.
+
+4.0.2 (2012-11-21)
+==================
+
+- Add support for Python 3.3.
+
+- Restored ability to install the package in the absence of ``setuptools``.
+
+- LP #1055223:  Fix test which depended on dictionary order and failed randomly
+  in Python 3.3.
+
+4.0.1 (2012-05-22)
+==================
+
+- Drop explicit ``DeprecationWarnings`` for "class advice" APIS (these
+  APIs are still deprecated under Python 2.x, and still raise an exception
+  under Python 3.x, but no longer cause a warning to be emitted under
+  Python 2.x).
+
+4.0.0 (2012-05-16)
+==================
+
+- Automated build of Sphinx HTML docs and running doctest snippets via tox.
+
+- Deprecate the "class advice" APIs from ``zope.interface.declarations``:
+  ``implements``, ``implementsOnly``, and ``classProvides``.  In their place,
+  prefer the equivalent class decorators: ``@implementer``,
+  ``@implementer_only``, and ``@provider``.  Code which uses the deprecated
+  APIs will not work as expected under Py3k.
+
+- Remove use of '2to3' and associated fixers when installing under Py3k.
+  The code is now in a "compatible subset" which supports Python 2.6, 2.7,
+  and 3.2, including PyPy 1.8 (the version compatible with the 2.7 language
+  spec).
+
+- Drop explicit support for Python 2.4 / 2.5 / 3.1.
+
+- Add support for PyPy.
+
+- Add support for continuous integration using ``tox`` and ``jenkins``.
+
+- Add 'setup.py dev' alias (runs ``setup.py develop`` plus installs
+  ``nose`` and ``coverage``).
+
+- Add 'setup.py docs' alias (installs ``Sphinx`` and dependencies).
+
+- Replace all unittest coverage previously accomplished via doctests with
+  unittests.  The doctests have been moved into a ``docs`` section, managed
+  as a Sphinx collection.
+
+- LP #910987:  Ensure that the semantics of the ``lookup`` method of
+  ``zope.interface.adapter.LookupBase`` are the same in both the C and
+  Python implementations.
+
+- LP #900906:  Avoid exceptions due to tne new ``__qualname__`` attribute
+  added in Python 3.3 (see PEP 3155 for rationale).  Thanks to Antoine
+  Pitrou for the patch.
+
+3.8.0 (2011-09-22)
+==================
+
+- New module ``zope.interface.registry``.  This is code moved from
+  ``zope.component.registry`` which implements a basic nonperistent component
+  registry as ``zope.interface.registry.Components``.  This class was moved
+  from ``zope.component`` to make porting systems (such as Pyramid) that rely
+  only on a basic component registry to Python 3 possible without needing to
+  port the entirety of the ``zope.component`` package.  Backwards
+  compatibility import shims have been left behind in ``zope.component``, so
+  this change will not break any existing code.
+
+- New ``tests_require`` dependency: ``zope.event`` to test events sent by
+  Components implementation.  The ``zope.interface`` package does not have a
+  hard dependency on ``zope.event``, but if ``zope.event`` is importable, it
+  will send component registration events when methods of an instance of
+  ``zope.interface.registry.Components`` are called.
+
+- New interfaces added to support ``zope.interface.registry.Components``
+  addition: ``ComponentLookupError``, ``Invalid``, ``IObjectEvent``,
+  ``ObjectEvent``, ``IComponentLookup``, ``IRegistration``,
+  ``IUtilityRegistration``, ``IAdapterRegistration``,
+  ``ISubscriptionAdapterRegistration``, ``IHandlerRegistration``,
+  ``IRegistrationEvent``, ``RegistrationEvent``, ``IRegistered``,
+  ``Registered``, ``IUnregistered``, ``Unregistered``,
+  ``IComponentRegistry``, and ``IComponents``.
+
+- No longer Python 2.4 compatible (tested under 2.5, 2.6, 2.7, and 3.2).
+
+3.7.0 (2011-08-13)
+==================
+
+- Move changes from 3.6.2 - 3.6.5 to a new 3.7.x release line.
+
+3.6.7 (2011-08-20)
+==================
+
+- Fix sporadic failures on x86-64 platforms in tests of rich comparisons
+  of interfaces.
+
+3.6.6 (2011-08-13)
+==================
+
+- LP #570942:  Now correctly compare interfaces  from different modules but
+  with the same names.
+
+  N.B.: This is a less intrusive / destabilizing fix than the one applied in
+  3.6.3:  we only fix the underlying cmp-alike function, rather than adding
+  the other "rich comparison" functions.
+
+- Revert to software as released with 3.6.1 for "stable" 3.6 release branch.
+
+3.6.5 (2011-08-11)
+==================
+
+- LP #811792:  work around buggy behavior in some subclasses of
+  ``zope.interface.interface.InterfaceClass``, which invoke ``__hash__``
+  before initializing ``__module__`` and ``__name__``.  The workaround
+  returns a fixed constant hash in such cases, and issues a ``UserWarning``.
+
+- LP #804832:  Under PyPy, ``zope.interface`` should not build its C
+  extension.  Also, prevent attempting to build it under Jython.
+
+- Add a tox.ini for easier xplatform testing.
+
+- Fix testing deprecation warnings issued when tested under Py3K.
+
+3.6.4 (2011-07-04)
+==================
+
+- LP 804951:  InterfaceClass instances were unhashable under Python 3.x.
+
+3.6.3 (2011-05-26)
+==================
+
+- LP #570942:  Now correctly compare interfaces  from different modules but
+  with the same names.
+
+3.6.2 (2011-05-17)
+==================
+
+- Moved detailed documentation out-of-line from PyPI page, linking instead to
+  http://docs.zope.org/zope.interface .
+
+- Fixes for small issues when running tests under Python 3.2 using
+  ``zope.testrunner``.
+
+- LP # 675064:  Specify return value type for C optimizations module init
+  under Python 3:  undeclared value caused warnings, and segfaults on some
+  64 bit architectures.
+
+- setup.py now raises RuntimeError if you don't have Distutils installed when
+  running under Python 3.
+
+3.6.1 (2010-05-03)
+==================
+
+- A non-ASCII character in the changelog made 3.6.0 uninstallable on
+  Python 3 systems with another default encoding than UTF-8.
+
+- Fix compiler warnings under GCC 4.3.3.
+
+3.6.0 (2010-04-29)
+==================
+
+- LP #185974:  Clear the cache used by ``Specificaton.get`` inside
+  ``Specification.changed``.  Thanks to Jacob Holm for the patch.
+
+- Add support for Python 3.1. Contributors:
+
+    Lennart Regebro
+    Martin v Loewis
+    Thomas Lotze
+    Wolfgang Schnerring
+
+  The 3.1 support is completely backwards compatible. However, the implements
+  syntax used under Python 2.X does not work under 3.X, since it depends on
+  how metaclasses are implemented and this has changed. Instead it now supports
+  a decorator syntax (also under Python 2.X)::
+
+    class Foo:
+        implements(IFoo)
+        ...
+
+  can now also be written::
+
+    @implementer(IFoo):
+    class Foo:
+        ...
+
+  There are 2to3 fixers available to do this change automatically in the
+  zope.fixers package.
+
+- Python 2.3 is no longer supported.
+
+
+3.5.4 (2009-12-23)
+==================
+
+- Use the standard Python doctest module instead of zope.testing.doctest, which
+  has been deprecated.
+
+
+3.5.3 (2009-12-08)
+==================
+
+- Fix an edge case: make providedBy() work when a class has '__provides__' in
+  its __slots__ (see http://thread.gmane.org/gmane.comp.web.zope.devel/22490)
+
+
+3.5.2 (2009-07-01)
+==================
+
+- BaseAdapterRegistry.unregister, unsubscribe: Remove empty portions of
+  the data structures when something is removed.  This avoids leaving
+  references to global objects (interfaces) that may be slated for
+  removal from the calling application.
+
+
+3.5.1 (2009-03-18)
+==================
+
+- verifyObject: use getattr instead of hasattr to test for object attributes
+  in order to let exceptions other than AttributeError raised by properties
+  propagate to the caller
+
+- Add Sphinx-based documentation building to the package buildout
+  configuration. Use the ``bin/docs`` command after buildout.
+
+- Improve package description a bit. Unify changelog entries formatting.
+
+- Change package's mailing list address to zope-dev at zope.org as
+  zope3-dev at zope.org is now retired.
+
+
+3.5.0 (2008-10-26)
+==================
+
+- Fix declaration of _zope_interface_coptimizations, it's not a top level
+  package.
+
+- Add a DocTestSuite for odd.py module, so their tests are run.
+
+- Allow to bootstrap on Jython.
+
+- Fix https://bugs.launchpad.net/zope3/3.3/+bug/98388: ISpecification
+  was missing a declaration for __iro__.
+
+- Add optional code optimizations support, which allows the building
+  of C code optimizations to fail (Jython).
+
+- Replace `_flatten` with a non-recursive implementation, effectively making
+  it 3x faster.
+
+
+3.4.1 (2007-10-02)
+==================
+
+- Fix a setup bug that prevented installation from source on systems
+  without setuptools.
+
+
+3.4.0 (2007-07-19)
+==================
+
+- Final release for 3.4.0.
+
+
+3.4.0b3 (2007-05-22)
+====================
+
+
+- When checking whether an object is already registered, use identity
+  comparison, to allow adding registering with picky custom comparison methods.
+
+
+3.3.0.1 (2007-01-03)
+====================
+
+- Made a reference to OverflowWarning, which disappeared in Python
+  2.5, conditional.
+
+
+3.3.0 (2007/01/03)
+==================
+
+New Features
+------------
+
+- Refactor the adapter-lookup algorithim to make it much simpler and faster.
+
+  Also, implement more of the adapter-lookup logic in C, making
+  debugging of application code easier, since there is less
+  infrastructre code to step through.
+
+- Treat objects without interface declarations as if they
+  declared that they provide ``zope.interface.Interface``.
+
+- Add a number of richer new adapter-registration interfaces
+  that provide greater control and introspection.
+
+- Add a new interface decorator to zope.interface that allows the
+  setting of tagged values on an interface at definition time (see
+  zope.interface.taggedValue).
+
+Bug Fixes
+---------
+
+- A bug in multi-adapter lookup sometimes caused incorrect adapters to
+  be returned.
+
+
+3.2.0.2 (2006-04-15)
+====================
+
+- Fix packaging bug:  'package_dir' must be a *relative* path.
+
+
+3.2.0.1 (2006-04-14)
+====================
+
+- Packaging change:  suppress inclusion of 'setup.cfg' in 'sdist' builds.
+
+
+3.2.0 (2006-01-05)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope 3.2.0 release.
+
+
+3.1.0 (2005-10-03)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope 3.1.0 release.
+
+- Made attribute resolution order consistent with component lookup order,
+  i.e. new-style class MRO semantics.
+
+- Deprecate 'isImplementedBy' and 'isImplementedByInstancesOf' APIs in
+  favor of 'implementedBy' and 'providedBy'.
+
+
+3.0.1 (2005-07-27)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope X3.0.1 release.
+
+- Fix a bug reported by James Knight, which caused adapter registries
+  to fail occasionally to reflect declaration changes.
+
+
+3.0.0 (2004-11-07)
+==================
+
+- Corresponds to the version of the zope.interface package shipped as part of
+  the Zope X3.0.0 release.

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope.interface.egg-info/SOURCES.txt -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope.interface.egg-info/SOURCES.txt Changed

@@ -2,16 +2,19 @@
 .manylinux-install.sh
 .manylinux.sh
 CHANGES.rst
+CONTRIBUTING.md
 COPYRIGHT.txt
 LICENSE.txt
 MANIFEST.in
 README.rst
+appveyor.yml
 build.cmd
 buildout.cfg
 rtd.txt
 setup.cfg
 setup.py
 tox.ini
+benchmarks/micro.py
 docs/Makefile
 docs/README.rst
 docs/README.ru.rst
@@ -26,7 +29,25 @@
 docs/index.rst
 docs/make.bat
 docs/verify.rst
-docs/_static/.gitignore
+docs/_build/doctest/output.txt
+docs/_build/html/_sources/README.rst.txt
+docs/_build/html/_sources/README.ru.rst.txt
+docs/_build/html/_sources/adapter.rst.txt
+docs/_build/html/_sources/adapter.ru.rst.txt
+docs/_build/html/_sources/changes.rst.txt
+docs/_build/html/_sources/foodforthought.rst.txt
+docs/_build/html/_sources/hacking.rst.txt
+docs/_build/html/_sources/human.rst.txt
+docs/_build/html/_sources/human.ru.rst.txt
+docs/_build/html/_sources/index.rst.txt
+docs/_build/html/_sources/verify.rst.txt
+docs/_build/html/_sources/api/adapters.rst.txt
+docs/_build/html/_sources/api/common.rst.txt
+docs/_build/html/_sources/api/components.rst.txt
+docs/_build/html/_sources/api/declarations.rst.txt
+docs/_build/html/_sources/api/index.rst.txt
+docs/_build/html/_sources/api/ro.rst.txt
+docs/_build/html/_sources/api/specifications.rst.txt
 docs/api/adapters.rst
 docs/api/common.rst
 docs/api/components.rst
@@ -81,6 +102,7 @@
 src/zope/interface/tests/odd.py
 src/zope/interface/tests/test_adapter.py
 src/zope/interface/tests/test_advice.py
+src/zope/interface/tests/test_compile_flags.py
 src/zope/interface/tests/test_declarations.py
 src/zope/interface/tests/test_document.py
 src/zope/interface/tests/test_element.py

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/_zope_interface_coptimizations.c -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/_zope_interface_coptimizations.c Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/adapter.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/adapter.py Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/common/tests/__init__.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/common/tests/__init__.py Changed

@@ -60,7 +60,8 @@
 
                 self.assertTrue(self.verify(iface, stdlib_class))
 
-            suffix = "%s_%s_%s" % (
+            suffix = "%s_%s_%s_%s" % (
+                stdlib_class.__module__.replace('.', '_'),
                 stdlib_class.__name__,
                 iface.__module__.replace('.', '_'),
                 iface.__name__
@@ -81,16 +82,17 @@
                 sro = implements.__sro__
                 self.assertIs(sro-1, Interface)
 
-                # Check that we got the strict C3 resolution order, unless we
-                # know we cannot. Note that 'Interface' is virtual base that doesn't
-                # necessarily appear at the same place in the calculated SRO as in the
-                # final SRO.
-                strict = stdlib_class not in self.NON_STRICT_RO
-                isro = ro.ro(implements, strict=strict)
-                isro.remove(Interface)
-                isro.append(Interface)
+                if stdlib_class not in self.UNVERIFIABLE_RO:
+                    # Check that we got the strict C3 resolution order, unless
+                    # we know we cannot. Note that 'Interface' is virtual base
+                    # that doesn't necessarily appear at the same place in the
+                    # calculated SRO as in the final SRO.
+                    strict = stdlib_class not in self.NON_STRICT_RO
+                    isro = ro.ro(implements, strict=strict)
+                    isro.remove(Interface)
+                    isro.append(Interface)
 
-                self.assertEqual(tuple(isro), sro)
+                    self.assertEqual(tuple(isro), sro)
 
             name = 'test_auto_ro_' + suffix
             test_ro.__name__ = name
@@ -101,6 +103,7 @@
     verifier = staticmethod(verifyClass)
     UNVERIFIABLE = ()
     NON_STRICT_RO = ()
+    UNVERIFIABLE_RO = ()
 
     def _adjust_object_before_verify(self, iface, x):
         return x

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/common/tests/test_collections.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/common/tests/test_collections.py Changed

@@ -11,6 +11,7 @@
 ##############################################################################
 
 
+import array
 import unittest
 try:
     import collections.abc as abc
@@ -93,6 +94,10 @@
         # It's imported because...? Coverage imports it, but why do we have it without
         # coverage?
         'Row',
+        # In Python 3.10 ``array.array`` appears as ``IMutableSequence`` but it
+        # does not provide a ``clear()`` method and it cannot be instantiated
+        # using ``array.array()``.
+        array.array,
     }
 
     if PYPY:
@@ -121,6 +126,14 @@
         })
         NON_STRICT_RO = {
         }
+    else:
+        UNVERIFIABLE_RO = {
+            # ``array.array`` fails the ``test_auto_ro_*`` tests with and
+            # without strict RO but only on Windows (AppVeyor) on Python 3.10.0
+            # (in older versions ``array.array`` does not appear as
+            # ``IMutableSequence``).
+            array.array,
+        }
 
 add_abc_interface_tests(TestVerifyClass, collections.ISet.__module__)
 
@@ -158,3 +171,11 @@
         CONSTRUCTORS.update({
             collections.IValuesView: {}.viewvalues,
         })
+    else:
+        UNVERIFIABLE_RO = {
+            # ``array.array`` fails the ``test_auto_ro_*`` tests with and
+            # without strict RO but only on Windows (AppVeyor) on Python 3.10.0
+            # (in older versions ``array.array`` does not appear as
+            # ``IMutableSequence``).
+            array.array,
+        }

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/declarations.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/declarations.py Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/exceptions.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/exceptions.py Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/interfaces.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/interfaces.py Changed

@@ -20,6 +20,7 @@
 from zope.interface.declarations import implementer
 
 __all__ = 
+    'ComponentLookupError',
     'IAdapterRegistration',
     'IAdapterRegistry',
     'IAttribute',
@@ -32,6 +33,7 @@
     'IInterface',
     'IInterfaceDeclaration',
     'IMethod',
+    'Invalid',
     'IObjectEvent',
     'IRegistered',
     'IRegistration',
@@ -40,6 +42,9 @@
     'ISubscriptionAdapterRegistration',
     'IUnregistered',
     'IUtilityRegistration',
+    'ObjectEvent',
+    'Registered',
+    'Unregistered',
 
 
 # pylint:disable=inherit-non-class,no-method-argument,no-self-argument
@@ -1071,7 +1076,7 @@
     """An event related to an object.
 
     The object that generated this event is not necessarily the object
-    refered to by location.
+    referred to by location.
     """
 
     object = Attribute("The subject of the event.")
@@ -1134,7 +1139,7 @@
         """Get subscribers
 
         Subscribers are returned that provide the provided interface
-        and that depend on and are comuted from the sequence of
+        and that depend on and are computed from the sequence of
         required objects.
         """

_service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/tests/test_compile_flags.py Added

@@ -0,0 +1,29 @@
+##############################################################################
+#
+# Copyright (c) 2022 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
+#
+##############################################################################
+import struct
+import unittest
+
+import zope.interface  # noqa: try to load a C module for side effects
+
+
+class TestFloatingPoint(unittest.TestCase):
+
+    def test_no_fast_math_optimization(self):
+        # Building with -Ofast enables -ffast-math, which sets certain FPU
+        # flags that can cause breakage elsewhere.  A library such as BTrees
+        # has no business changing global FPU flags for the entire process.
+        zero_bits = struct.unpack("!Q", struct.pack("!d", 0.0))0
+        next_up = zero_bits + 1
+        smallest_subnormal = struct.unpack("!d", struct.pack("!Q", next_up))0
+        self.assertNotEqual(smallest_subnormal, 0.0)

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/tests/test_document.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/tests/test_document.py Changed

@@ -124,7 +124,7 @@
             """ This interface has a method.
             """
             def aMethod():
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -142,7 +142,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -160,7 +160,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second, *rest):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -178,7 +178,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second, **kw):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -221,9 +221,9 @@
 
         class IBase(Interface):
             def method1():
-                pass
+                """docstring"""
             def method2():
-                pass
+                """docstring"""
 
         class IDerived(IBase):
             "IDerived doc"
@@ -233,7 +233,7 @@
             def method3():
                 "method3 doc"
             def method4():
-                pass
+                pass  # pragma: no cover
             def method5():
                 "method5 doc"
 
@@ -348,7 +348,7 @@
             """ This interface has a method.
             """
             def aMethod():
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -366,7 +366,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -384,7 +384,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second, *rest):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -402,7 +402,7 @@
             """ This interface has a method.
             """
             def aMethod(first, second, **kw):
-                pass
+                pass  # pragma: no cover
 
         self.assertEqual(self._callFUT(IHasMethod), EXPECTED)
 
@@ -445,9 +445,9 @@
 
         class IBase(Interface):
             def method1():
-                pass
+                pass  # pragma: no cover
             def method2():
-                pass
+                pass  # pragma: no cover
 
         class IDerived(IBase):
             "IDerived doc"
@@ -457,7 +457,7 @@
             def method3():
                 "method3 doc"
             def method4():
-                pass
+                pass  # pragma: no cover
             def method5():
                 "method5 doc"

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/tests/test_interface.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/tests/test_interface.py Changed

@@ -563,7 +563,7 @@
 
     def test_multiple_inheritance_no_interfaces(self):
         # If we extend an object that implements interfaces,
-        # plus ane that doesn't, we do not interject `Interface`
+        # plus one that doesn't, we do not interject `Interface`
         # early in the resolution order. It stays at the end,
         # like it should.
         # See https://github.com/zopefoundation/zope.interface/issues/8
@@ -1177,9 +1177,9 @@
 
         class ICurrent(Interface):
             def method1(a, b):
-                pass
+                """docstring"""
             def method2(a, b):
-                pass
+                """docstring"""
 
         class IOther(Interface):
             pass
@@ -1207,7 +1207,7 @@
         from zope.interface import providedBy
         class IBase(Interface):
             def method():
-                pass
+                """docstring"""
         class IDerived(IBase):
             pass
         class Current():
@@ -1230,7 +1230,7 @@
 
         class IBase(Interface):
             def method():
-                pass
+                """docstring"""
 
         class IDerived(IBase):
             pass
@@ -1258,7 +1258,7 @@
 
         class ILeft(Interface):
             def method():
-                pass
+                """docstring"""
 
         class IRight(ILeft):
             pass
@@ -1292,7 +1292,7 @@
         class ILeft(Interface):
 
             def method():
-                pass
+                """docstring"""
 
         class IRight(ILeft):
             pass
@@ -1405,7 +1405,7 @@
             attr = Attribute(u'My attr')
 
             def method():
-                pass
+                """docstring"""
 
         self.assertEqual(sorted(ISimple.names()), 'attr', 'method')
 
@@ -1418,16 +1418,16 @@
             attr = Attribute(u'My attr')
 
             def method():
-                pass
+                """docstring"""
 
         class IDerived(IBase):
             attr2 = Attribute(u'My attr2')
 
             def method():
-                pass
+                """docstring"""
 
             def method2():
-                pass
+                """docstring"""
 
         self.assertEqual(sorted(IDerived.names()),
                          'attr2', 'method', 'method2')
@@ -1753,7 +1753,7 @@
 
         class ITagMe(Interface):
             def method():
-                pass
+                """docstring"""
             method.optional = 1
 
         method = ITagMe'method'

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/tests/test_odd_declarations.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/tests/test_odd_declarations.py Changed

_service:tar_scm:zope.interface-5.4.0.tar.gz/src/zope/interface/tests/test_verify.py -> _service:tar_scm:zope.interface-5.5.2.tar.gz/src/zope/interface/tests/test_verify.py Changed

@@ -69,7 +69,7 @@
 
         class ICurrent(Interface):
             def method():
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -84,7 +84,7 @@
 
         class ICurrent(Interface):
             def method():
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -101,7 +101,7 @@
 
         class IBase(Interface):
             def method():
-                pass
+                """docstring"""
 
         class IDerived(IBase):
             pass
@@ -119,7 +119,7 @@
 
         class IBase(Interface):
             def method():
-                pass
+                """docstring"""
 
         class IDerived(IBase):
             pass
@@ -140,7 +140,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -158,7 +158,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -177,7 +177,7 @@
         class ICurrent(Interface):
 
             def method(*args):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -196,7 +196,7 @@
         class ICurrent(Interface):
 
             def method(**kw):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -215,7 +215,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -233,7 +233,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -250,7 +250,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -268,7 +268,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -286,7 +286,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -303,7 +303,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -321,7 +321,7 @@
         class ICurrent(Interface):
 
             def method(a, *args):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -339,7 +339,7 @@
         class ICurrent(Interface):
 
             def method(a, *args):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -356,7 +356,7 @@
         class ICurrent(Interface):
 
             def method(a, *args):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -373,7 +373,7 @@
         class ICurrent(Interface):
 
             def method(**kwargs):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -391,7 +391,7 @@
         class ICurrent(Interface):
 
             def method(*args):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -411,7 +411,7 @@
         class ICurrent(Interface):
 
             def method(**kwargs):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):
@@ -446,7 +446,7 @@
 
         class ICurrent(Interface):
             def method():
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current:
@@ -519,7 +519,7 @@
         class ICurrent(Interface):
 
             def method(a):
-                pass
+                """docstring"""
 
         @implementer(ICurrent)
         class Current(object):

_service:tar_scm:zope.interface-5.4.0.tar.gz/tox.ini -> _service:tar_scm:zope.interface-5.5.2.tar.gz/tox.ini Changed

@@ -1,69 +1,67 @@
+# Generated from:
+# https://github.com/zopefoundation/meta/tree/master/config/c-code
 tox
+minversion = 3.18
 envlist =
-    py27,py27-pure,
-    py35,py35-pure,
-    py36,
-    py37,
-    py38,py38-cext,
-    py39,
-    pypy,
-    pypy3,
-    coverage,
+    lint
+    py27,py27-pure
+    py35,py35-pure
+    py36,py36-pure
+    py37,py37-pure
+    py38,py38-pure
+    py39,py39-pure
+    py310,py310-pure
+    py311,py311-pure
+    pypy
+    pypy3
     docs
-# NB: if you add new environments, please also add them to depends in
-# testenv:coverage so that parallel runs (tox -p auto) will work correctly
+    coverage
 
 testenv
-# ``usedevelop`` is required otherwise unittest complains that it
-# discovers a file in src/... but imports it from .tox/.../
-# ``skip_install`` also basically works, but that causes the ``extras``
-# not to be installed (though ``deps`` still are), and doesn't
-# rebuild C extensions.
 usedevelop = true
-commands =
-    coverage run -p -m unittest discover -s src
-extras = test
+deps =
 setenv =
+    pure: PURE_PYTHON=1
+    !pure-!pypy-!pypy3: PURE_PYTHON=0
     ZOPE_INTERFACE_STRICT_IRO=1
-
-testenv:py27-pure
-setenv =
-    PURE_PYTHON=1
-
-testenv:py35-pure
-setenv =
-    PURE_PYTHON=1
-
-testenv:py38-cext
-# Require the C extension
-setenv =
-    PURE_PYTHON=0
-
-testenv:py
 commands =
-    python --version
-    {testenvcommands}
+    coverage run -p -m unittest discover -s src {posargs}
+    !py27-!pypy: sphinx-build -b doctest -d {envdir}/.cache/doctrees docs {envdir}/.cache/doctest
+extras =
+    test
+    docs
 
 testenv:coverage
-# The -i/--ignore arg is necessary; we get
-# No source for code: '//.tox/pypy/site-packages/zope/interface/__init__.py'
-# without it.
+basepython = python3
+allowlist_externals =
+    mkdir
+deps =
+    coverage
+setenv =
+    PURE_PYTHON=1
 commands =
+    mkdir -p {toxinidir}/parts/htmlcov
     coverage combine
-    coverage report -i
     coverage html -i
-    coverage xml -i
-depends = py27,py27-pure,py35,py35-pure,py36,py37,py38,py38-cext,py39,pypy,pypy3,docs
+    coverage report -i -m --fail-under=99
+depends = py27,py27-pure,py35,py35-pure,py36,py36-pure,py37,py37-pure,py38,py38-pure,py39,py39-pure,py310,py310-pure,pypy,pypy3,docs
 parallel_show_output = true
 
+testenv:lint
+basepython = python3
+skip_install = true
+commands =
+    check-manifest
+    check-python-versions
+deps =
+    check-manifest
+    check-python-versions >= 0.19.1
+    wheel
+
 testenv:docs
-basepython =
-    python3
+basepython = python3
+skip_install = false
+commands_pre =
 commands =
     sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
-    coverage run -p -m sphinx -b doctest -d docs/_build/doctrees docs docs/_build/doctest
-deps =
-    Sphinx
-    repoze.sphinx.autointerface
-setenv =
-    ZOPE_INTERFACE_STRICT_IRO=0
+    sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest

Changes of Revision 2