[Checkins] SVN: grokcore.component/trunk/ * Document
grokcore.component's public API in an interface,
Philipp von Weitershausen
philikon at philikon.de
Tue Jul 22 09:37:05 EDT 2008
Log message for revision 88686:
* Document grokcore.component's public API in an interface,
``IGrokcoreComponentAPI``. When you now do::
from grokcore.component import *
only the items documented in that interface will be imported into
your local namespace.
Changed:
U grokcore.component/trunk/CHANGES.txt
U grokcore.component/trunk/src/grokcore/component/__init__.py
U grokcore.component/trunk/src/grokcore/component/interfaces.py
A grokcore.component/trunk/src/grokcore/component/tests/api.txt
U grokcore.component/trunk/src/grokcore/component/tests/test_grok.py
-=-
Modified: grokcore.component/trunk/CHANGES.txt
===================================================================
--- grokcore.component/trunk/CHANGES.txt 2008-07-22 13:04:45 UTC (rev 88685)
+++ grokcore.component/trunk/CHANGES.txt 2008-07-22 13:37:03 UTC (rev 88686)
@@ -14,6 +14,14 @@
is useful for unit tests where you may not want to grok a whole
module.
+* Document grokcore.component's public API in an interface,
+ ``IGrokcoreComponentAPI``. When you now do::
+
+ from grokcore.component import *
+
+ only the items documented in that interface will be imported into
+ your local namespace.
+
1.4 (2008-06-11)
----------------
Modified: grokcore.component/trunk/src/grokcore/component/__init__.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/__init__.py 2008-07-22 13:04:45 UTC (rev 88685)
+++ grokcore.component/trunk/src/grokcore/component/__init__.py 2008-07-22 13:37:03 UTC (rev 88686)
@@ -29,3 +29,7 @@
# Import this module so that it's available as soon as you import the
# 'grokcore.component' package. Useful for tests and interpreter examples.
import grokcore.component.testing
+
+# Only export public API
+from grokcore.component.interfaces import IGrokcoreComponentAPI
+__all__ = list(IGrokcoreComponentAPI)
Modified: grokcore.component/trunk/src/grokcore/component/interfaces.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/interfaces.py 2008-07-22 13:04:45 UTC (rev 88685)
+++ grokcore.component/trunk/src/grokcore/component/interfaces.py 2008-07-22 13:37:03 UTC (rev 88686)
@@ -1,4 +1,4 @@
-from zope.interface import Interface
+from zope.interface import Interface, Attribute
class IContext(Interface):
"""Marker interface for auto-association of context.
@@ -16,3 +16,96 @@
mark up your class with ``zope.interface.implements(IContext)`` to make
it a candidate for auto-association.
"""
+
+class IBaseClasses(Interface):
+
+ 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.")
+ GlobalUtility = Attribute("Base class for global utilities.")
+
+class IDirectives(Interface):
+
+ def baseclass():
+ """Mark this class as a base class.
+
+ This means it won't be grokked, though if it's a possible context,
+ it can still serve as a context.
+ """
+
+ def implements(*interfaces):
+ """Declare that a class implements the given interfaces."""
+
+ def adapts(*classes_or_interfaces):
+ """Declare that a class adapts objects of the given classes or
+ interfaces."""
+
+ def context(class_or_interface):
+ """Declare the context for views, adapters, etc.
+
+ This directive can be used on module and class level. When
+ used on module level, it will set the context for all views,
+ adapters, etc. in that module. When used on class level, it
+ will set the context for that particular class."""
+
+ def name(name):
+ """Declare the name of a view or adapter/multi-adapter.
+
+ This directive can only be used on class level."""
+
+ def provides(interface):
+ """Explicitly specify with which interface a component will be
+ looked up."""
+
+ def global_utility(factory, provides=None, name=u''):
+ """Register a global utility.
+
+ factory - the factory that creates the global utility
+ provides - the interface the utility should be looked up with
+ name - the name of the utility
+ """
+
+ def direct():
+ """Specify whether the class should be used for the component
+ or whether it should be used to instantiate the component.
+
+ This directive can be used on GlobalUtility-based classes to
+ indicate whether the class itself should be registered as a
+ utility, or an instance of it.
+ """
+
+class IDecorators(Interface):
+
+ def subscribe(*classes_or_interfaces):
+ """Declare that a function subscribes to an event or a
+ combination of objects and events."""
+
+ def adapter(*classes_or_interfaces):
+ """Describes that a function adapts an object or a combination
+ of objects.
+ """
+
+ def implementer(*interfaces):
+ """Describes that a function that's used as an adapter
+ implements an interface or a number of interfaces.
+ """
+
+class IMartianAPI(Interface):
+ """Part of Martian's API exposed by grokcore.component."""
+
+ # This should probably move to martian at some point.
+
+ ClassGrokker = Attribute("Grokker for classes.")
+ InstanceGrokker = Attribute("Grokker for instances.")
+ GlobalGrokker = Attribute("Grokker that's invoked for a module.")
+ GrokImportError = Attribute("Error that may while importing components.")
+ GrokError = Attribute("Error that may occur during the grokking process.")
+
+class IGrokcoreComponentAPI(IBaseClasses, IDirectives,
+ IDecorators, IMartianAPI):
+ """grokcore.component's public API."""
Added: grokcore.component/trunk/src/grokcore/component/tests/api.txt
===================================================================
--- grokcore.component/trunk/src/grokcore/component/tests/api.txt (rev 0)
+++ grokcore.component/trunk/src/grokcore/component/tests/api.txt 2008-07-22 13:37:03 UTC (rev 88686)
@@ -0,0 +1,17 @@
+The grokcore.component API
+==========================
+
+The grokcore.component API is described by the
+``grokcore.component.interfaces.IGrokcoreComponentAPI`` interface.
+When you do
+
+ >>> from grokcore.component import *
+
+only those objects described in that API interface are imported into
+your local namespace. In other words, if we take the list of things
+that have been imported and subtract the things that have been defined
+in the API interface, we'll end with pretty much nothing:
+
+ >>> from grokcore.component.interfaces import IGrokcoreComponentAPI
+ >>> sorted(set(locals()) - set(IGrokcoreComponentAPI))
+ ['IGrokcoreComponentAPI', '__builtins__', '__file__']
Property changes on: grokcore.component/trunk/src/grokcore/component/tests/api.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: grokcore.component/trunk/src/grokcore/component/tests/test_grok.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/tests/test_grok.py 2008-07-22 13:04:45 UTC (rev 88685)
+++ grokcore.component/trunk/src/grokcore/component/tests/test_grok.py 2008-07-22 13:37:03 UTC (rev 88686)
@@ -49,6 +49,9 @@
'event']:
suite.addTest(suiteFromPackage(name))
+ api = doctest.DocFileSuite('api.txt')
+ suite.addTest(api)
+
# this test cannot follow the normal testing pattern, as the
# bug it tests for is only exposed in the context of a doctest
grok_component = doctest.DocFileSuite('grok_component.txt',
More information about the Checkins
mailing list