Add __all__ to all modules.issue153

Fixes #153

The items that went in each ``__all__`` are based on what is
documented:

 $ rg --no-filename 'import' docs/ -trst | tr -s "[:blank:]" | sort | uniq | grep zope
 >>> from pprint import pprint
 >>> from zope.interface import *
 >>> from zope.interface import Interface
 >>> from zope.interface import Interface, Attribute, implementer
 >>> from zope.interface import alsoProvides
 >>> from zope.interface import classImplements
 >>> from zope.interface import classImplementsOnly
 >>> from zope.interface import directlyProvidedBy
 >>> from zope.interface import directlyProvides
 >>> from zope.interface import implementedBy
 >>> from zope.interface import implementer
 >>> from zope.interface import implementer_only
 >>> from zope.interface import noLongerProvides
 >>> from zope.interface import providedBy
 >>> from zope.interface import provider
 >>> from zope.interface.adapter import AdapterRegistry
 >>> from zope.interface.declarations import Declaration
 >>> from zope.interface.declarations import InstanceDeclarations
 >>> from zope.interface.declarations import ProvidesClass
 >>> from zope.interface.declarations import named
 >>> from zope.interface.exceptions import BrokenImplementation
 >>> from zope.interface.exceptions import Invalid
 >>> from zope.interface.interface import Specification
 >>> from zope.interface.interface import adapter_hooks
 >>> from zope.interface.verify import verifyObject
 >>> import gc
 >>> import zope.interface

And also some personal judgement about what the public API is that I'm
more than happy to have reviewed.

11 files changed, 130 insertions, 46 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index d2282c8..657fae5 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -67,13 +67,19 @@
   of) interface adaptation. See `issue 163
   <https://github.com/zopefoundation/zope.interface/issues/163>`_.
 
-- Micro-optimization in `.adapter. `, `.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
-  `_lookup`s owntime is ~5x.
-  See `PR 167 <https://github.com/zopefoundation/zope.interface/pull/167>`_.
-
+- 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>`_.
 
 4.7.1 (2019-11-11)
 ==================
diff --git a/src/zope/interface/adapter.py b/src/zope/interface/adapter.py
index 3b566ba..40b2921 100644
--- a/src/zope/interface/adapter.py
+++ b/src/zope/interface/adapter.py
@@ -25,7 +25,11 @@ from zope.interface._compat import _normalize_name
 from zope.interface._compat import STRING_TYPES
 from zope.interface._compat import _use_c_impl
 
-_BLANK = u''
+__all__ = [
+    'AdapterRegistry',
+    'VerifyingAdapterRegistry',
+]
+
 
 class BaseAdapterRegistry(object):
 
@@ -138,7 +142,7 @@ class BaseAdapterRegistry(object):
 
         self.changed(self)
 
-    def registered(self, required, provided, name=_BLANK):
+    def registered(self, required, provided, name=u''):
         required = tuple(map(_convert_None_to_Interface, required))
         name = _normalize_name(name)
         order = len(required)
@@ -207,7 +211,7 @@ class BaseAdapterRegistry(object):
 
     def subscribe(self, required, provided, value):
         required = tuple(map(_convert_None_to_Interface, required))
-        name = _BLANK
+        name = u''
         order = len(required)
         byorder = self._subscribers
         while len(byorder) <= order:
@@ -250,7 +254,7 @@ class BaseAdapterRegistry(object):
             lookups.append((components, k))
             components = d
 
-        old = components.get(_BLANK)
+        old = components.get(u'')
         if not old:
             # this is belt-and-suspenders against the failure of cleanup below
             return  # pragma: no cover
@@ -264,15 +268,15 @@ class BaseAdapterRegistry(object):
             return
 
         if new:
-            components[_BLANK] = new
+            components[u''] = new
         else:
-            # Instead of setting components[_BLANK] = new, we clean out
+            # Instead of setting components[u''] = new, we clean out
             # empty containers, since we don't want our keys to
             # reference global objects (interfaces) unnecessarily.  This
             # is often a problem when an interface is slated for
             # removal; a hold-over entry in the registry can make it
             # difficult to remove such interfaces.
-            del components[_BLANK]
+            del components[u'']
             for comp, k in reversed(lookups):
                 d = comp[k]
                 if d:
@@ -326,7 +330,7 @@ class LookupBase(object):
             cache = c
         return cache
 
-    def lookup(self, required, provided, name=_BLANK, default=None):
+    def lookup(self, required, provided, name=u'', default=None):
         if not isinstance(name, STRING_TYPES):
             raise ValueError('name is not a string')
         cache = self._getcache(provided, name)
@@ -348,7 +352,7 @@ class LookupBase(object):
 
         return result
 
-    def lookup1(self, required, provided, name=_BLANK, default=None):
+    def lookup1(self, required, provided, name=u'', default=None):
         if not isinstance(name, STRING_TYPES):
             raise ValueError('name is not a string')
         cache = self._getcache(provided, name)
@@ -361,10 +365,10 @@ class LookupBase(object):
 
         return result
 
-    def queryAdapter(self, object, provided, name=_BLANK, default=None):
+    def queryAdapter(self, object, provided, name=u'', default=None):
         return self.adapter_hook(provided, object, name, default)
 
-    def adapter_hook(self, provided, object, name=_BLANK, default=None):
+    def adapter_hook(self, provided, object, name=u'', default=None):
         if not isinstance(name, STRING_TYPES):
             raise ValueError('name is not a string')
         required = providedBy(object)
@@ -511,7 +515,7 @@ class AdapterLookupBase(object):
                 r.subscribe(self)
                 _refs[ref] = 1
 
-    def _uncached_lookup(self, required, provided, name=_BLANK):
+    def _uncached_lookup(self, required, provided, name=u''):
         required = tuple(required)
         result = None
         order = len(required)
@@ -534,7 +538,7 @@ class AdapterLookupBase(object):
 
         return result
 
-    def queryMultiAdapter(self, objects, provided, name=_BLANK, default=None):
+    def queryMultiAdapter(self, objects, provided, name=u'', default=None):
         factory = self.lookup(map(providedBy, objects), provided, name)
         if factory is None:
             return default
@@ -582,7 +586,7 @@ class AdapterLookupBase(object):
                 if extendors is None:
                     continue
 
-            _subscriptions(byorder[order], required, extendors, _BLANK,
+            _subscriptions(byorder[order], required, extendors, u'',
                            result, 0, order)
 
         self._subscribe(*required)
diff --git a/src/zope/interface/advice.py b/src/zope/interface/advice.py
index e55930d..86d0f11 100644
--- a/src/zope/interface/advice.py
+++ b/src/zope/interface/advice.py
@@ -33,6 +33,14 @@ except ImportError:
 else:
     __python3 = False
 
+__all__ = [
+    'addClassAdvisor',
+    'determineMetaclass',
+    'getFrameInfo',
+    'isClassAdvisor',
+    'minimalBases',
+]
+
 import sys
 
 def getFrameInfo(frame):
diff --git a/src/zope/interface/declarations.py b/src/zope/interface/declarations.py
index 04e2cc8..3118593 100644
--- a/src/zope/interface/declarations.py
+++ b/src/zope/interface/declarations.py
@@ -40,6 +40,11 @@ from zope.interface._compat import CLASS_TYPES as DescriptorAwareMetaClasses
 from zope.interface._compat import PYTHON3
 from zope.interface._compat import _use_c_impl
 
+__all__ = [
+    # None. The public APIs of this module are
+    # re-exported from zope.interface directly.
+]
+
 # Registry of class-implementation specifications
 BuiltinImplementationSpecifications = {}
 
diff --git a/src/zope/interface/document.py b/src/zope/interface/document.py
index e6d6e88..309bb57 100644
--- a/src/zope/interface/document.py
+++ b/src/zope/interface/document.py
@@ -18,6 +18,10 @@ interface as structured text.
 """
 import zope.interface
 
+__all__ = [
+    'asReStructuredText',
+    'asStructuredText',
+]
 
 def asStructuredText(I, munge=0, rst=False):
     """ Output structured text format.  Note, this will whack any existing
diff --git a/src/zope/interface/exceptions.py b/src/zope/interface/exceptions.py
index e9a4788..9be1b8c 100644
--- a/src/zope/interface/exceptions.py
+++ b/src/zope/interface/exceptions.py
@@ -14,6 +14,17 @@
 """Interface-specific exceptions
 """
 
+__all__ = [
+    # Invalid tree
+    'Invalid',
+    'DoesNotImplement',
+    'BrokenImplementation',
+    'BrokenMethodImplementation',
+    # Other
+    'BadImplements',
+    'InvalidInterface',
+]
+
 class Invalid(Exception):
     """A specification is violated
     """
diff --git a/src/zope/interface/interface.py b/src/zope/interface/interface.py
index 57998e0..1681c75 100644
--- a/src/zope/interface/interface.py
+++ b/src/zope/interface/interface.py
@@ -23,6 +23,15 @@ from zope.interface._compat import _use_c_impl
 from zope.interface.exceptions import Invalid
 from zope.interface.ro import ro
 
+__all__ = [
+    # Most of the public API from this module is directly exported
+    # from zope.interface. The only remaining public API intended to
+    # be imported from here should be those few things documented as
+    # such.
+    'InterfaceClass',
+    'Specification',
+    'adapter_hooks',
+]
 
 CO_VARARGS = 4
 CO_VARKEYWORDS = 8
diff --git a/src/zope/interface/interfaces.py b/src/zope/interface/interfaces.py
index 27e64e9..6d98591 100644
--- a/src/zope/interface/interfaces.py
+++ b/src/zope/interface/interfaces.py
@@ -19,8 +19,29 @@ from zope.interface.interface import Attribute
 from zope.interface.interface import Interface
 from zope.interface.declarations import implementer
 
+__all__ = [
+    'IAdapterRegistration',
+    'IAdapterRegistry',
+    'IAttribute',
+    'IComponentLookup',
+    'IComponentRegistry',
+    'IComponents',
+    'IDeclaration',
+    'IElement',
+    'IHandlerRegistration',
+    'IInterface',
+    'IInterfaceDeclaration',
+    'IMethod',
+    'IObjectEvent',
+    'IRegistered',
+    'IRegistration',
+    'IRegistrationEvent',
+    'ISpecification',
+    'ISubscriptionAdapterRegistration',
+    'IUnregistered',
+    'IUtilityRegistration',
+]
 
-_BLANK = u''
 
 class IElement(Interface):
     """Objects that have basic documentation and tagged values.
@@ -679,7 +700,7 @@ class IAdapterRegistry(Interface):
         provided interface, and a name, which must be text.
         """
 
-    def registered(required, provided, name=_BLANK):
+    def registered(required, provided, name=u''):
         """Return the component registered for the given interfaces and name
 
         name must be text.
@@ -701,11 +722,11 @@ class IAdapterRegistry(Interface):
         text.
         """
 
-    def queryMultiAdapter(objects, provided, name=_BLANK, default=None):
+    def queryMultiAdapter(objects, provided, name=u'', default=None):
         """Adapt a sequence of objects to a named, provided, interface
         """
 
-    def lookup1(required, provided, name=_BLANK, default=None):
+    def lookup1(required, provided, name=u'', default=None):
         """Lookup a value using a single required interface
 
         A value is looked up based on a single required
@@ -713,11 +734,11 @@ class IAdapterRegistry(Interface):
         text.
         """
 
-    def queryAdapter(object, provided, name=_BLANK, default=None):
+    def queryAdapter(object, provided, name=u'', default=None):
         """Adapt an object using a registered adapter factory.
         """
 
-    def adapter_hook(provided, object, name=_BLANK, default=None):
+    def adapter_hook(provided, object, name=u'', default=None):
         """Adapt an object using a registered adapter factory.
 
         name must be text.
@@ -733,7 +754,7 @@ class IAdapterRegistry(Interface):
         """Return the names for which there are registered objects
         """
 
-    def subscribe(required, provided, subscriber, name=_BLANK):
+    def subscribe(required, provided, subscriber, name=u''):
         """Register a subscriber
 
         A subscriber is registered for a *sequence* of required
@@ -743,14 +764,14 @@ class IAdapterRegistry(Interface):
         equivalent) interfaces.
         """
 
-    def subscriptions(required, provided, name=_BLANK):
+    def subscriptions(required, provided, name=u''):
         """Get a sequence of subscribers
 
         Subscribers for a *sequence* of required interfaces, and a provided
         interface are returned.
         """
 
-    def subscribers(objects, provided, name=_BLANK):
+    def subscribers(objects, provided, name=u''):
         """Get a sequence of subscription adapters
         """
 
@@ -791,26 +812,26 @@ class IComponentLookup(Interface):
     utilities = Attribute(
         "Adapter Registry to manage all registered utilities.")
 
-    def queryAdapter(object, interface, name=_BLANK, default=None):
+    def queryAdapter(object, interface, name=u'', default=None):
         """Look for a named adapter to an interface for an object
 
         If a matching adapter cannot be found, returns the default.
         """
 
-    def getAdapter(object, interface, name=_BLANK):
+    def getAdapter(object, interface, name=u''):
         """Look for a named adapter to an interface for an object
 
         If a matching adapter cannot be found, a `ComponentLookupError`
         is raised.
         """
 
-    def queryMultiAdapter(objects, interface, name=_BLANK, default=None):
+    def queryMultiAdapter(objects, interface, name=u'', default=None):
         """Look for a multi-adapter to an interface for multiple objects
 
         If a matching adapter cannot be found, returns the default.
         """
 
-    def getMultiAdapter(objects, interface, name=_BLANK):
+    def getMultiAdapter(objects, interface, name=u''):
         """Look for a multi-adapter to an interface for multiple objects
 
         If a matching adapter cannot be found, a `ComponentLookupError`
@@ -952,8 +973,8 @@ class IComponentRegistry(Interface):
     """Register components
     """
 
-    def registerUtility(component=None, provided=None, name=_BLANK,
-                        info=_BLANK, factory=None):
+    def registerUtility(component=None, provided=None, name=u'',
+                        info=u'', factory=None):
         """Register a utility
 
         :param factory:
@@ -980,7 +1001,7 @@ class IComponentRegistry(Interface):
         A `IRegistered` event is generated with an `IUtilityRegistration`.
         """
 
-    def unregisterUtility(component=None, provided=None, name=_BLANK,
+    def unregisterUtility(component=None, provided=None, name=u'',
                           factory=None):
         """Unregister a utility
 
@@ -1020,8 +1041,8 @@ class IComponentRegistry(Interface):
         in the object.
         """
 
-    def registerAdapter(factory, required=None, provided=None, name=_BLANK,
-                       info=_BLANK):
+    def registerAdapter(factory, required=None, provided=None, name=u'',
+                       info=u''):
         """Register an adapter factory
 
         :param factory:
@@ -1056,7 +1077,7 @@ class IComponentRegistry(Interface):
         """
 
     def unregisterAdapter(factory=None, required=None,
-                          provided=None, name=_BLANK):
+                          provided=None, name=u''):
         """Unregister an adapter factory
 
         :returns:
@@ -1105,7 +1126,7 @@ class IComponentRegistry(Interface):
         """
 
     def registerSubscriptionAdapter(factory, required=None, provides=None,
-                                    name=_BLANK, info=''):
+                                    name=u'', info=''):
         """Register a subscriber factory
 
         :param factory:
@@ -1143,7 +1164,7 @@ class IComponentRegistry(Interface):
         """
 
     def unregisterSubscriptionAdapter(factory=None, required=None,
-                                      provides=None, name=_BLANK):
+                                      provides=None, name=u''):
         """Unregister a subscriber factory.
 
         :returns:
@@ -1195,7 +1216,7 @@ class IComponentRegistry(Interface):
         registrations in the object.
         """
 
-    def registerHandler(handler, required=None, name=_BLANK, info=''):
+    def registerHandler(handler, required=None, name=u'', info=''):
         """Register a handler.
 
         A handler is a subscriber that doesn't compute an adapter
@@ -1230,7 +1251,7 @@ class IComponentRegistry(Interface):
         A `IRegistered` event is generated with an `IHandlerRegistration`.
         """
 
-    def unregisterHandler(handler=None, required=None, name=_BLANK):
+    def unregisterHandler(handler=None, required=None, name=u''):
         """Unregister a handler.
 
         A handler is a subscriber that doesn't compute an adapter
diff --git a/src/zope/interface/registry.py b/src/zope/interface/registry.py
index bba0267..3f1306f 100644
--- a/src/zope/interface/registry.py
+++ b/src/zope/interface/registry.py
@@ -39,6 +39,12 @@ from zope.interface.adapter import AdapterRegistry
 from zope.interface._compat import CLASS_TYPES
 from zope.interface._compat import STRING_TYPES
 
+__all__ = [
+    # Components is public API, but
+    # the *Registration classes are just implementations
+    # of public interfaces.
+    'Components',
+]
 
 class _UnhashableComponentCounter(object):
     # defaultdict(int)-like object for unhashable components
diff --git a/src/zope/interface/ro.py b/src/zope/interface/ro.py
index 84f10dc..855f101 100644
--- a/src/zope/interface/ro.py
+++ b/src/zope/interface/ro.py
@@ -15,6 +15,10 @@
 """
 __docformat__ = 'restructuredtext'
 
+__all__ = [
+    'ro',
+]
+
 def _mergeOrderings(orderings):
     """Merge multiple orderings so that within-ordering order is preserved
 
diff --git a/src/zope/interface/verify.py b/src/zope/interface/verify.py
index 62bb64c..d43e49f 100644
--- a/src/zope/interface/verify.py
+++ b/src/zope/interface/verify.py
@@ -13,11 +13,17 @@
 ##############################################################################
 """Verify interface implementations
 """
+import sys
+from types import FunctionType, MethodType
+
 from zope.interface.exceptions import BrokenImplementation, DoesNotImplement
 from zope.interface.exceptions import BrokenMethodImplementation
-from types import FunctionType, MethodType
 from zope.interface.interface import fromMethod, fromFunction, Method
-import sys
+
+__all__ = [
+    'verifyObject',
+    'verifyClass',
+]
 
 # This will be monkey-patched when running under Zope 2, so leave this
 # here: