[Checkins] SVN: zope.introspector/trunk/src/zope/introspector/README.txt Describe how to build own description providers.

Uli Fouquet uli at gnufix.de
Thu Jul 3 09:06:05 EDT 2008


Log message for revision 87957:
  Describe how to build own description providers.

Changed:
  U   zope.introspector/trunk/src/zope/introspector/README.txt

-=-
Modified: zope.introspector/trunk/src/zope/introspector/README.txt
===================================================================
--- zope.introspector/trunk/src/zope/introspector/README.txt	2008-07-03 13:05:14 UTC (rev 87956)
+++ zope.introspector/trunk/src/zope/introspector/README.txt	2008-07-03 13:06:04 UTC (rev 87957)
@@ -46,7 +46,135 @@
   certain objects. See `utilityinfo.txt` to learn more about that.
 
 
+Code objects
+------------
+
+Code objects are such, that provide information about packages,
+classes and other pieces of code. We can retrieve informations about
+packages::
+
+  >>> import grokcore.component as grok
+  >>> grok.grok('zope.introspector')
+  >>> 
+
+
 Writing your own introspector
 =============================
 
-XXX To come
+Writing an introspector means providing a component (the ``Info``
+component), that delivers information about certain kinds of objects
+and another component (the ``DescriptionProvider`` component), that
+decides for an arbitrary object, whether it can be decribed by your
+new ``Info`` component.
+
+Step 1: Writing an ``Info`` component
+-------------------------------------
+
+An Info component can be a simple object. We define a class, whose
+instances should be described afterwards::
+
+  >>> class Mammoth(object):
+  ...   def __init__(self, name='Fred'):
+  ...     self.name=name
+
+An accompanied ``Info`` component now could look like this::
+
+  >>> class MammothInfo(object):
+  ...   def __init__(self, obj):
+  ...     self.obj = obj
+  ...   def getName(self):
+  ...     return self.obj.name
+
+Apparently this class gives us interesting informations about
+mammoths::
+
+  >>> fred = Mammoth()
+  >>> fred.name
+  'Fred'
+
+The trick now is to make this ``Info`` available in the framework when
+a ``Mammoth`` object should be described. This is currently not the
+case. We generally look up infos for objects using an utility
+providing ``IObjectDescriptionProvider`` interface::
+
+  >>> from zope.component import getUtility
+  >>> from zope.introspector.interfaces import IObjectDescriptionProvider
+  >>> info_provider = getUtility(IObjectDescriptionProvider)
+
+When we ask this provider for infos about fred, we will get one of the
+default ``Info`` components::
+  
+  >>> info_provider.getDescription(fred)
+  <zope.introspector.objectinfo.ObjectInfo object at 0x...>
+
+Instead of this ``ObjectInfo`` we want to get our new ``MammothInfo``
+returned. To let this happen, we first have to register it by writing
+a ``DescriptionProvider``.
+
+
+Step 2: Writing an ``DescriptionProvider``
+------------------------------------------
+
+``DescriptionProviders`` are built by inheriting from
+``zope.introspector.DescriptionProvider``. They provide a
+``canHandle()`` and a ``getDescription()`` method::
+
+  >>> from zope.introspector import DescriptionProvider
+
+  >>> class MammothDescriptionProvider(DescriptionProvider):
+  ...   def canHandle(self, obj, *args, **kw):
+  ...     if isinstance(obj, Mammoth):
+  ...       return True
+  ...     return False
+  ...   def getDescription(self, obj, *args, **kw):
+  ...     return MammothInfo(obj)
+
+If we ask this class whether it can handle a ``Mammoth`` instance, it
+will agree::
+
+  >>> mdp = MammothDescriptionProvider()
+  >>> mdp.canHandle(fred)
+  True
+
+For other objects it should fail::
+
+  >>> mdp.canHandle(object())
+  False
+
+We can also get a description::
+
+  >>> mdp.getDescription(fred)
+  <MammothInfo object at 0x...>
+
+This is all very well, but how can the framework know, that we have a
+ready-to-use description provider for mammoths? The
+``zope.introspector`` package uses grokkers from the ``martian``
+package to find description providers on startup. Before grokking a
+module with a description provider, the latter will be unknown to the
+framework::
+
+  >>> info_provider.getDescription(fred)
+  <zope.introspector.objectinfo.ObjectInfo object at 0x...>
+
+This means, that we have to grok all modules and classes, that contain
+description providers::
+
+  >>> import grokcore.component as grok
+  >>> grok.testing.grok('zope.introspector')
+  >>> grok.testing.grok_component('MammothDescriptionProvider',
+  ...                             MammothDescriptionProvider)
+  True
+
+If we now repeat our request to the global info provider, we get the
+descriptor we want::
+
+  >>> info_provider.getDescription(fred)
+  <MammothInfo object at 0x...>
+
+
+We remove the MammothInfo handler to clean up the registry::
+
+  >>> import zope.introspector.descriptionprovider as zid
+  >>> zid.descriptor_registry =  [x for x in zid.descriptor_registry
+  ...     if not x['handler'] is MammothDescriptionProvider]
+



More information about the Checkins mailing list