make the util.* methods part of the grokcore.component API

CHANGES.txt

@@ -4,14 +4,19 @@ Changes
 2.5 (unreleased)
 ----------------
 
+- Introduce provideUtility, providerAdapter, provideSubscriptionAdapter,
+  provideHandler and provideInterface in grokcore.component. These by default
+  delegate the registration of components to the global site manager like
+  was done before, but provide the possibility for custom registries for the
+  grokked components.
+
 - Fix the `global_adapter` to properly use information annotated by
   ``grok.adapter``, and using the IContext object if it was not
   specified. (Fix Launchpad issue #960097).
 
 - Add a ``key`` option to ``sort_components`` that behave like ``key``
   options available on standard Python sort methods.
 
-
 2.4 (2011-04-27)
 ----------------
 

src/grokcore/component/__init__.py

@@ -24,19 +24,50 @@
 from martian import ClassGrokker, InstanceGrokker, GlobalGrokker
 
 from grokcore.component.components import (
-    Adapter, GlobalUtility, MultiAdapter, Context, Subscription,
-    MultiSubscription)
+    Adapter,
+    Context,
+    GlobalUtility,
+    MultiAdapter,
+    MultiSubscription,
+    Subscription,
+    )
 
 from grokcore.component.directive import (
-    context, description, direct, name, order, path, provides, title,
-    global_utility, global_adapter, order)
+    context,
+    description,
+    direct,
+    global_adapter,
+    global_utility,
+    name,
+    order,
+    path,
+    provides,
+    title,
+    )
 
 from grokcore.component.decorators import (
-    subscribe, adapter, implementer, provider)
+    adapter,
+    implementer,
+    provider,
+    subscribe,
+    )
 
 from grokcore.component.subscription import (
-    querySubscriptions, queryMultiSubscriptions,
-    queryOrderedSubscriptions, queryOrderedMultiSubscriptions)
+    queryMultiSubscriptions,
+    queryOrderedMultiSubscriptions,
+    queryOrderedSubscriptions,
+    querySubscriptions,
+    )
+
+from grokcore.component.util import (
+    getSiteManager,
+    provideAdapter,
+    provideHandler,
+    provideInterface,
+    provideSubscriptionAdapter,
+    provideUtility,
+    sort_components,
+    )
 
 # Import this module so that it's available as soon as you import the
 # 'grokcore.component' package.  Useful for tests and interpreter examples.

src/grokcore/component/interfaces.py

@@ -34,20 +34,25 @@ class or interface they adapt. If there is only a single possible context
 
 
 class IBaseClasses(Interface):
+    Adapter = Attribute("Base class for adapters.")
 
     ClassGrokker = Attribute("Base class to define a class grokker.")
-    InstanceGrokker = Attribute("Base class to define an instance grokker.")
-    GlobalGrokker = Attribute("Base class to define a module grokker.")
 
     Context = Attribute("Base class for automatically associated contexts.")
 
-    Adapter = Attribute("Base class for adapters.")
-    MultiAdapter = Attribute("Base class for multi-adapters.")
+    GlobalGrokker = Attribute("Base class to define a module grokker.")
+
     GlobalUtility = Attribute("Base class for global utilities.")
-    Subscription = Attribute("Base class for subscription adapters.")
+
+    InstanceGrokker = Attribute("Base class to define an instance grokker.")
+
+    MultiAdapter = Attribute("Base class for multi-adapters.")
+
     MultiSubscription = Attribute(
         "Base class for subscription mult-adapters.")
 
+    Subscription = Attribute("Base class for subscription adapters.")
+
 
 class IDirectives(Interface):
 
@@ -186,22 +191,49 @@ def GrokImportError(*args):
 
 
 class IMartianAPI(Interface):
-    """Part of Martian's API exposed by grokcore.component."""
-
-    # This should probably move to martian at some point.
+    """Part of Martian's API exposed by grokcore.component.
+    """
 
     ClassGrokker = Attribute("Grokker for classes.")
-    InstanceGrokker = Attribute("Grokker for instances.")
+
     GlobalGrokker = Attribute("Grokker that's invoked for a module.")
 
+    InstanceGrokker = Attribute("Grokker for instances.")
+
+
+class IGrokcoreComponentAPI(
+    IBaseClasses,
+    IDecorators,
+    IDirectives,
+    IGrokErrors,
+    IMartianAPI,
+    ):
+    """grokcore.component's public API.
+    """
+
+    getSiteManager = Attribute('Get the site manager for the nearest site.')
 
-class IGrokcoreComponentAPI(IBaseClasses, IDirectives, IDecorators,
-                            IGrokErrors, IMartianAPI):
-    """grokcore.component's public API."""
+    provideAdapter = Attribute('Registers an adapters')
+
+    provideHandler = Attribute('Registers an handler')
+
+    provideInterface = Attribute('Regsiters an interfaces as a utility')
+
+    provideSubscriptionAdapter = Attribute(
+        'Registers an subscriptions adapter')
+
+    provideUtility = Attribute('Registers an utility')
 
     querySubscriptions = Attribute("Function to query subscriptions.")
+
     queryOrderedSubscriptions = Attribute(
         "Function to query subscription in order.")
+
     queryMultiSubscriptions = Attribute("Function to query subscriptions.")
+
     queryOrderedMultiSubscriptions = Attribute(
         "Function to query subscriptions in order.")
+
+    sort_components = Attribute(
+        'Sort a list of components using the information provided by '
+        '`grok.order`.')

src/grokcore/component/meta.py

@@ -22,7 +22,6 @@
 from zope import component, interface
 from martian.error import GrokError
 from zope.interface import implementedBy
-from grokcore.component import util
 
 def _provides(component, module=None, **data):
     martian.util.check_implements_one(component)
@@ -44,7 +43,7 @@ class AdapterGrokker(martian.ClassGrokker):
     def execute(self, factory, config, context, provides, name, **kw):
         config.action(
             discriminator=('adapter', context, provides, name),
-            callable=util.provideAdapter,
+            callable=grokcore.component.provideAdapter,
             args=(factory, (context,), provides, name),
             )
         return True
@@ -64,7 +63,7 @@ def execute(self, factory, config, provides, name, **kw):
 
         config.action(
             discriminator=('adapter', for_, provides, name),
-            callable=util.provideAdapter,
+            callable=grokcore.component.provideAdapter,
             args=(factory, None, provides, name),
             )
         return True
@@ -79,7 +78,7 @@ class SubscriptionGrokker(martian.ClassGrokker):
     def execute(self, factory, config, context, provides, name, **kw):
         config.action(
             discriminator=None,
-            callable=util.provideSubscriptionAdapter,
+            callable=grokcore.component.provideSubscriptionAdapter,
             args=(factory, (context,), provides),
             )
         return True
@@ -99,7 +98,7 @@ def execute(self, factory, config, provides, name, **kw):
 
         config.action(
             discriminator=None,
-            callable=util.provideSubscriptionAdapter,
+            callable=grokcore.component.provideSubscriptionAdapter,
             args=(factory, adapts, provides),
             )
         return True
@@ -123,7 +122,7 @@ def execute(self, factory, config, direct, provides, name, **kw):
 
         config.action(
             discriminator=('utility', provides, name),
-            callable=util.provideUtility,
+            callable=grokcore.component.provideUtility,
             args=(factory, provides, name),
             )
         return True
@@ -150,7 +149,7 @@ def grok(self, name, module, module_info, config, **kw):
             name = getattr(function, '__component_name__', u"")
             config.action(
                 discriminator=('adapter', interfaces, function.__implemented__, name),
-                callable=util.provideAdapter,
+                callable=grokcore.component.provideAdapter,
                 args=(function, interfaces, function.__implemented__, name),
                 )
         return True
@@ -181,7 +180,7 @@ def grok(self, name, module, module_info, config, **kw):
 
             config.action(
                 discriminator=('utility', provides, name),
-                callable=util.provideUtility,
+                callable=grokcore.component.provideUtility,
                 args=(obj, provides, name),
                 )
 
@@ -203,7 +202,7 @@ def grok(self, name, module, module_info, config, **kw):
 
             config.action(
                 discriminator=('adapter', adapts, provides, name),
-                callable=util.provideAdapter,
+                callable=grokcore.component.provideAdapter,
                 args=(factory, adapts, provides, name),
                 )
 
@@ -228,17 +227,17 @@ def grok(self, name, module, module_info, config, **kw):
             if provides is None:
                 config.action(
                     discriminator=None,
-                    callable=util.provideHandler,
+                    callable=grokcore.component.provideHandler,
                     args=(factory, subscribed))
             else:
                 config.action(
                     discriminator=None,
-                    callable=util.provideSubscriptionAdapter,
+                    callable=grokcore.component.provideSubscriptionAdapter,
                     args=(factory, subscribed, provides))
 
             for iface in subscribed:
                 config.action(
                     discriminator=None,
-                    callable=util.provideInterface,
+                    callable=grokcore.component.provideInterface,
                     args=('', iface))
         return True

src/grokcore/component/tests/order/arg_orderdirective.py

@@ -2,7 +2,7 @@
 If the grok.order directive is present with arguments, sorting will be
 done by the order specified.
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
 
   >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
   >>> sort_components(components)

src/grokcore/component/tests/order/combined_orderdirective.py

@@ -6,7 +6,7 @@
 
   >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
   >>> sort_components(components)
   [<...Third object at ...>,
    <...Fourth object at ...>,

src/grokcore/component/tests/order/combinednoorder_orderdirective.py

@@ -6,7 +6,7 @@
 
   >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
   >>> sort_components(components)
   [<...Fifth object at ...>,
    <...Third object at ...>,

src/grokcore/component/tests/order/inter1.py

@@ -12,7 +12,7 @@
   >>> from inter2 import Four, Five, Six
   >>> components = [One(), Two(), Three(), Four(), Five(), Six()]
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
   >>> sort_components(components)
   [<...Three object at ...>,
    <...One object at ...>,

src/grokcore/component/tests/order/noarg_orderdirective.py

@@ -5,7 +5,7 @@
 
   >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
   >>> sort_components(components)
   [<...First object at ...>,
    <...Second object at ...>,

src/grokcore/component/tests/order/nodirective.py

@@ -5,7 +5,7 @@
 
   >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
 
-  >>> from grokcore.component.util import sort_components
+  >>> from grokcore.component import sort_components
   >>> sort_components(components)
   [<...Fifth object at ...>,
    <...First object at ...>,