Add __all__ to all modules.

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.

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)
 ==================

src/zope/interface/adapter.py

@@ -25,7 +25,11 @@
 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 @@ def register(self, required, provided, name, value):
 
         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 @@ def unregister(self, required, provided, name, value=None):
 
     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 @@ def unsubscribe(self, required, provided, value=None):
             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 @@ def unsubscribe(self, required, provided, value=None):
             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 @@ def _getcache(self, provided, name):
             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 @@ def lookup(self, required, provided, name=_BLANK, default=None):
 
         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 @@ def lookup1(self, required, provided, name=_BLANK, default=None):
 
         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 @@ def _subscribe(self, *required):
                 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 @@ def _uncached_lookup(self, required, provided, name=_BLANK):
 
         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 @@ def _uncached_subscriptions(self, required, provided):
                 if extendors is None:
                     continue
 
-            _subscriptions(byorder[order], required, extendors, _BLANK,
+            _subscriptions(byorder[order], required, extendors, u'',
                            result, 0, order)
 
         self._subscribe(*required)

src/zope/interface/advice.py

@@ -33,6 +33,14 @@
 else:
     __python3 = False
 
+__all__ = [
+    'addClassAdvisor',
+    'determineMetaclass',
+    'getFrameInfo',
+    'isClassAdvisor',
+    'minimalBases',
+]
+
 import sys
 
 def getFrameInfo(frame):

src/zope/interface/declarations.py

@@ -40,6 +40,11 @@ class implements (that instances of the class provides).
 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 = {}
 

src/zope/interface/document.py

@@ -18,6 +18,10 @@
 """
 import zope.interface
 
+__all__ = [
+    'asReStructuredText',
+    'asStructuredText',
+]
 
 def asStructuredText(I, munge=0, rst=False):
     """ Output structured text format.  Note, this will whack any existing

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
     """

src/zope/interface/interface.py

@@ -23,6 +23,15 @@
 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