Let subclasses of BaseAdapterRegistry customize the data structures.

CHANGES.rst

@@ -2,11 +2,27 @@
  Changes
 =========
 
-5.2.1 (unreleased)
-==================
-
-- Nothing changed yet.
-
+5.3.0 (unreleased)
+==================
+
+- 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.
 
 5.2.0 (2020-11-05)
 ==================

docs/api/adapters.rst

@@ -8,6 +8,20 @@ Usage of the adapter registry is documented in :ref:`adapter-registry`.
 The adapter registry's API is defined by
 :class:`zope.interface.interfaces.IAdapterRegistry`:
 
-.. autointerface:: zope.interface.adapter.IAdapterRegistry
+.. autointerface:: zope.interface.interfaces.IAdapterRegistry
    :members:
    :member-order: bysource
+
+
+The concrete implementations of ``IAdapterRegistry`` provided by this
+package allows for some customization opportunities.
+
+.. autoclass:: zope.interface.adapter.BaseAdapterRegistry
+   :members:
+   :private-members:
+
+.. autoclass:: zope.interface.adapter.AdapterRegistry
+   :members:
+
+.. autoclass:: zope.interface.adapter.VerifyingAdapterRegistry
+   :members:

docs/conf.py

@@ -262,7 +262,11 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'https://docs.python.org/': None,
+    'https://persistent.readthedocs.io/en/latest/': None,
+    'https://btrees.readthedocs.io/en/latest/': None,
+}
 
 # Sphinx 1.8+ prefers this to `autodoc_default_flags`. It's documented that
 # either True or None mean the same thing as just setting the flag, but