[Checkins] SVN: martian/branches/philikon-moduleinfo-kwarg/src/martian/ Pass in module_info to grokkers as a keyword argument. This doesn't break backwards compatibility

[Philipp von Weitershausen]

Log message for revision 80784:
  Pass in module_info to grokkers as a keyword argument. This doesn't break backwards compatibility
  because grokkers are supposed to take **kw anyway.  If at all, it's a useful feature because grokkers
  likely need module_info for figuring out module annotations.
  

Changed:
  U   martian/branches/philikon-moduleinfo-kwarg/src/martian/README.txt
  U   martian/branches/philikon-moduleinfo-kwarg/src/martian/core.py

-=-
Modified: martian/branches/philikon-moduleinfo-kwarg/src/martian/README.txt
===================================================================
--- martian/branches/philikon-moduleinfo-kwarg/src/martian/README.txt	2007-10-10 10:25:26 UTC (rev 80783)
+++ martian/branches/philikon-moduleinfo-kwarg/src/martian/README.txt	2007-10-10 12:04:07 UTC (rev 80784)
@@ -1114,3 +1114,48 @@
 
   >>> order
   ['BSub', 'mymodule', 'ASub']
+
+
+Module info
+-----------
+
+In addition to the ``name`` and ``object`` positional arguments,
+grokkers will get also get a ``module_info`` keyword argument.  It is
+an ``IModuleInfo`` object which can be used, for example, to query
+module annotations.  Consider the following grokker:
+
+  >>> from martian.error import GrokError
+  >>> class AnnotationsGrokker(GlobalGrokker):
+  ...   def grok(self, name, module, module_info, **kw):
+  ...       ann = module_info.getAnnotation('some.annotation', None)
+  ...       if ann is None:
+  ...           raise GrokError('Did not find annotation!', module)
+  ...       if ann != 'ME GROK SAY HI':
+  ...           raise GrokError('Wrong annotation!', module)
+  ...       return True
+
+Now let's provide a fake module:
+
+  >>> import new, sys
+  >>> annotations = new.module('annotations')
+  >>> annotations.__file__ = '/fake/module/annotations.py'
+  >>> sys.modules['annotations'] = annotations
+
+Clearly, it can't find the module-level variable yet:
+
+  >>> module_grokker = ModuleGrokker()
+  >>> module_grokker.register(AnnotationsGrokker())
+  >>> import martian
+  >>> martian.grok_dotted_name('annotations', module_grokker)
+  Traceback (most recent call last):
+  ...
+  GrokError: Did not find annotation!
+
+Let's provide the annotation so that the grokker works as expected:
+
+  >>> annotations.__some_annotation__ = 'ME GROK SAY HI'
+  >>> martian.grok_dotted_name('annotations', module_grokker)
+
+Finally clean up:
+
+  >>> del sys.modules['annotations']

Modified: martian/branches/philikon-moduleinfo-kwarg/src/martian/core.py
===================================================================
--- martian/branches/philikon-moduleinfo-kwarg/src/martian/core.py	2007-10-10 10:25:26 UTC (rev 80783)
+++ martian/branches/philikon-moduleinfo-kwarg/src/martian/core.py	2007-10-10 12:04:07 UTC (rev 80784)
@@ -198,7 +198,8 @@
         grok_package(sub_module_info, grokker, **kw)
 
 def grok_module(module_info, grokker, **kw):
-    grokker.grok(module_info.dotted_name, module_info.getModule(), **kw)
+    grokker.grok(module_info.dotted_name, module_info.getModule(),
+                 module_info=module_info, **kw)
 
 # deep meta mode here - we define grokkers that can pick up the
 # three kinds of grokker: ClassGrokker, InstanceGrokker and ModuleGrokker