[Checkins] SVN: grok/branches/gotcha-configuration-actions/src/grok/ Bring back grok_component.

[Philipp von Weitershausen]

Log message for revision 80786:
  Bring back grok_component.
  

Changed:
  U   grok/branches/gotcha-configuration-actions/src/grok/__init__.py
  U   grok/branches/gotcha-configuration-actions/src/grok/_grok.py
  U   grok/branches/gotcha-configuration-actions/src/grok/interfaces.py
  A   grok/branches/gotcha-configuration-actions/src/grok/tests/grokker/grokcomponent.py

-=-
Modified: grok/branches/gotcha-configuration-actions/src/grok/__init__.py
===================================================================
--- grok/branches/gotcha-configuration-actions/src/grok/__init__.py	2007-10-10 12:13:26 UTC (rev 80785)
+++ grok/branches/gotcha-configuration-actions/src/grok/__init__.py	2007-10-10 12:25:14 UTC (rev 80786)
@@ -41,6 +41,7 @@
                             provides, baseclass, global_utility, local_utility,
                             permissions, require, site, layer)
 from grok._grok import do_grok as grok  # Avoid name clash within _grok
+from grok._grok import grok_component
 from grok.decorators import subscribe, adapter, implementer
 from martian.error import GrokError, GrokImportError
 

Modified: grok/branches/gotcha-configuration-actions/src/grok/_grok.py
===================================================================
--- grok/branches/gotcha-configuration-actions/src/grok/_grok.py	2007-10-10 12:13:26 UTC (rev 80785)
+++ grok/branches/gotcha-configuration-actions/src/grok/_grok.py	2007-10-10 12:25:14 UTC (rev 80786)
@@ -20,6 +20,7 @@
 
 from zope.component.interfaces import IDefaultViewName
 from zope.publisher.interfaces.browser import IBrowserRequest
+from zope.configuration.config import ConfigurationMachine
 from zope.app.component.site import LocalSiteManager
 
 import martian
@@ -80,5 +81,25 @@
         config=config
         )
 
+def grok_component(name, component,
+                   context=None, module_info=None, templates=None):
+    if module_info is None:
+        obj_module = getattr(component, '__grok_module__', None)
+        if obj_module is None:
+            obj_module = getattr(component, '__module__', None)
+        module_info = scan.module_info_from_dotted_name(obj_module)
+
+    module = module_info.getModule()
+    if context is not None:
+        module.__grok_context__ = context
+    if templates is not None:
+        module.__grok_templates__ = templates
+    config = ConfigurationMachine()
+    result = the_multi_grokker.grok(name, component,
+                                    module_info=module_info,
+                                    config=config)
+    config.execute_actions()    
+    return result
+
 the_multi_grokker = martian.MetaMultiGrokker()
 the_module_grokker = martian.ModuleGrokker(the_multi_grokker)

Modified: grok/branches/gotcha-configuration-actions/src/grok/interfaces.py
===================================================================
--- grok/branches/gotcha-configuration-actions/src/grok/interfaces.py	2007-10-10 12:13:26 UTC (rev 80785)
+++ grok/branches/gotcha-configuration-actions/src/grok/interfaces.py	2007-10-10 12:25:14 UTC (rev 80786)
@@ -204,6 +204,21 @@
     def grok(dotted_name):
         """Grok a module or package specified by ``dotted_name``."""
 
+    def grok_component(name, component, context=None, module_info=None,
+                       templates=None):
+        """Grok an arbitrary object. Can be useful during testing.
+
+        name - the name of the component (class name, or global instance name
+               as it would appear in a module).
+        component - the object (class, etc) to grok.
+        context - the context object (optional).
+        module_info - the module being grokked (optional).
+        templates - the templates registry (optional).
+
+        Note that context, module_info and templates might be required
+        for some grokkers which rely on them.
+        """
+
     def url(request, obj, name=None):
         """Generate the URL to an object with optional name attached.
         """

Copied: grok/branches/gotcha-configuration-actions/src/grok/tests/grokker/grokcomponent.py (from rev 80776, grok/branches/gotcha-configuration-actions/src/grok/tests/grokker/grokcomponent.py)
===================================================================
--- grok/branches/gotcha-configuration-actions/src/grok/tests/grokker/grokcomponent.py	                        (rev 0)
+++ grok/branches/gotcha-configuration-actions/src/grok/tests/grokker/grokcomponent.py	2007-10-10 12:25:14 UTC (rev 80786)
@@ -0,0 +1,61 @@
+"""
+
+Let's first grok the meta module to define some basic grokkers::
+
+  >>> import grok
+  >>> grok.tests.grok('grok.meta')
+  
+It is possible to grok an individual component. Let's define an adapter::
+
+  >>> from zope.interface import Interface
+  >>> class IMyInterface(Interface):
+  ...   pass
+  >>> class SomeClass(object):
+  ...   pass
+  >>> class MyAdapter(grok.Adapter):
+  ...   grok.provides(IMyInterface)
+  ...   grok.context(SomeClass)
+
+To grok this adapter, you can simply write this::
+
+  >>> grok.grok_component('MyAdapter', MyAdapter)
+  True
+
+We can now use the adapter::
+
+  >>> instance = SomeClass()
+  >>> adapter = IMyInterface(instance)
+  >>> isinstance(adapter, MyAdapter)
+  True
+
+We can use grok_component with only two arguments because we know the
+adapter grokker is not looking for more. Sometimes we need to supply
+an extra argument however::
+
+  >>> class ISecondInterface(Interface):
+  ...   pass
+  >>> class SecondAdapter(grok.Adapter):
+  ...   grok.provides(ISecondInterface)
+
+This adapter does not supply its own context. Trying to do what we did
+before will therefore fail::
+
+  >>> grok.grok_component('SecondAdapter', SecondAdapter)
+  Traceback (most recent call last):
+    ...
+  GrokError: No module-level context for <class 'grok.tests.grokker.grokcomponent.SecondAdapter'>, please use grok.context.
+
+So we need to supply the context ourselves::
+
+  >>> grok.grok_component('SecondAdapter', SecondAdapter, context=SomeClass)
+  True
+
+Now we can use the SecondAdapter as well::
+
+  >>> adapter = ISecondInterface(instance)
+  >>> isinstance(adapter, SecondAdapter)
+  True
+
+The next optional argument is module_info and the final argument is
+templates.
+"""