[Checkins] SVN: grokcore.component/trunk/ move API documentation from README to the implementation
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Mon Feb 14 04:30:33 EST 2011
Log message for revision 120311:
move API documentation from README to the implementation
Changed:
U grokcore.component/trunk/README.txt
U grokcore.component/trunk/src/grokcore/component/__init__.py
U grokcore.component/trunk/src/grokcore/component/decorators.py
U grokcore.component/trunk/src/grokcore/component/directive.py
-=-
Modified: grokcore.component/trunk/README.txt
===================================================================
--- grokcore.component/trunk/README.txt 2011-02-14 09:18:51 UTC (rev 120310)
+++ grokcore.component/trunk/README.txt 2011-02-14 09:30:33 UTC (rev 120311)
@@ -213,97 +213,3 @@
"""Updated the Dublin Core 'Modified' property when a modified
event is sent for an object."""
IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
-
-***
-
-Class-level directives
-----------------------
-
-``implements(iface1, iface2, ...)``
- declares that a class implements the interfaces ``iface1``,
- ``iface2``, etc. It is identical to
- ``zope.interface.implements``.
-
-``implementsOnly(iface1, iface2, ...)``
- declares that a class *only* implements the interfaces ``iface1``,
- ``iface2``, etc. It is identical to
- ``zope.interface.implementsOnly``.
-
-``classProvides(iface1, iface2, ...)``
- declares that a class object (as opposed to instances of the class)
- provides the interfaces ``iface1``, ``iface2``, etc. It is identical to
- ``zope.interface.classProvides``.
-
-``context(iface_or_class)``
- declares the type of object that the adapter (or a similar
- context-dependent component) adapts. This can either be an
- interface (in this case all objects providing this interface will
- be eligible contexts for the adapter) or a class (then only
- instances of that particular class are eligible).
-
-``adapts(iface_or_class1, iface_or_class_2, ...)``
- declares the types of objects that a multi-adapter adapts.
-
-``name(ascii_or_unicode)``
- declares the name of a named utility, named adapter, etc.
-
-``title(ascii_or_unicode)``
- declares the human-readable title of a component (such as a
- permission, role, etc.)
-
-``provides(iface)``
- declares the interface that a utility provides (as opposed to
- potentially multiple interfaces that the class implements).
-
-``direct()``
- declares that a ``GlobalUtility`` class should be registered as a
- utility itself, rather than an instance of it.
-
-``baseclass()``
- declares that a subclass of an otherwise automatically configured
- component should not be registered, and that it serves as a base
- class instead.
-
-
-Module-level directives
------------------------
-
-``global_utility(class, [provides=iface, name=ascii_or_unicode, direct=bool])``
- registers an instance of ``class`` (or ``class`` itself, depending
- on the value of the ``direct`` parameter) as a global utility.
- This allows you to register global utilities that don't inherit
- from the ``GlobalUtility`` base class.
-
-``global_adapter(factory, [adapts=tuple_of_interfaces, provides=iface, name=ascii_or_unicode])``
- registers the ``factory`` callable as a global adapter. The ``adapts``
- argument may be a tuple of interfaces or a single interface, if this is
- a single adapter. Both ``adapts`` and ``provides`` will be deduced from
- information annotated onto the factory if necessary. If no adapted
- interface can be determined, the current context will be assumed. The
- name defaults to u"". This allows you to register global adapters that
- don't inherit from the ``Adapter`` or ``MultiAdapter`` base classes.
-
-Function decorators
--------------------
-
-``@adapter(iface_or_class1, iface_or_class2, ..., name=u"name")``
- registers the function as an adapter for the specific interface. The
- ``name`` argument must be a keyword argument and is optional. If given,
- a named adapter is registered.
-
-``@implementer(iface1, iface2, ...)``
- declares that the function implements a certain interface (or a
- number of interfaces). This is useful when a function serves as an object
- factory, e.g. as an adapter.
-
-``@provider(iface1, iface2, ...)``
- declares that the function object provides a certain interface (or a
- number of interfaces). This is akin to calling directlyProvides() on
- the function object.
-
-``@subscribe(iface_or_class1, iface_or_class2, ...)``
- declares that a function is to be registered as an event handler
- for the specified objects. Normally, an event handler is simply
- registered as a subscriber for the event interface. In case of
- object events, the event handler is registered as a subscriber for
- the object type and the event interface.
Modified: grokcore.component/trunk/src/grokcore/component/__init__.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/__init__.py 2011-02-14 09:18:51 UTC (rev 120310)
+++ grokcore.component/trunk/src/grokcore/component/__init__.py 2011-02-14 09:30:33 UTC (rev 120311)
@@ -1,4 +1,4 @@
-##############################################################################
+j pa##############################################################################
#
# Copyright (c) 2006-2007 Zope Foundation and Contributors.
# All Rights Reserved.
@@ -15,6 +15,8 @@
"""
from zope.component import adapts
+adapts.__doc__ = "Declares the types of objects that a multi-adapter adapts."
+
from zope.interface import implements, implementsOnly, classProvides
from martian import baseclass
Modified: grokcore.component/trunk/src/grokcore/component/decorators.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/decorators.py 2011-02-14 09:18:51 UTC (rev 120310)
+++ grokcore.component/trunk/src/grokcore/component/decorators.py 2011-02-14 09:30:33 UTC (rev 120311)
@@ -23,7 +23,14 @@
from zope.interface.declarations import DescriptorAwareMetaClasses
class subscribe:
+ """Declares that a function is to be registered as an event handler for the
+ specified objects.
+ Normally, an event handler is simply registered as a subscriber for the
+ event interface. In case of object events, the event handler is registered
+ as a subscriber for the object type and the event interface.
+
+ """
def __init__(self, *args):
self.subscribed = args
@@ -51,7 +58,12 @@
return zope.component.adapter(*self.subscribed)(function)
class adapter(zope.component.adapter):
+ """Registers the function as an adapter for the specific interface.
+ The ``name`` argument must be a keyword argument and is optional. If given,
+ a named adapter is registered.
+ """
+
# Override the z.c.adapter decorator to force sanity checking and
# have better error reporting and add the ability to capture the name
@@ -81,7 +93,14 @@
return ob
class implementer(zope.interface.implementer):
+ """Declares that the function implements a certain interface (or a number
+ of interfaces).
+ This is useful when a function serves as an object factory, e.g. as an
+ adapter.
+
+ """
+
def __call__(self, ob):
# XXX we do not have function grokkers (yet) so we put the annotation
# on the module.
@@ -94,7 +113,12 @@
return zope.interface.implementer.__call__(self, ob)
class provider:
+ """Declares that the function object provides a certain interface (or a
+ number of interfaces).
+ This is akin to calling directlyProvides() on the function object.
+
+ """
def __init__(self, *interfaces):
self.interfaces = interfaces
Modified: grokcore.component/trunk/src/grokcore/component/directive.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/directive.py 2011-02-14 09:18:51 UTC (rev 120310)
+++ grokcore.component/trunk/src/grokcore/component/directive.py 2011-02-14 09:30:33 UTC (rev 120311)
@@ -22,6 +22,20 @@
from grokcore.component.interfaces import IContext
class global_utility(martian.MultipleTimesDirective):
+ """Registers an instance of ``class`` (or ``class`` itself, depending on
+ the value of the ``direct`` parameter) as a global utility.
+
+ This allows you to register global utilities that don't inherit from the
+ ``GlobalUtility`` base class.
+
+ :param class: The class to register as a global utility.
+ :param provides: Optionally, the interface the utility will provide.
+ :param name: Optionally, a name for a named utility registration.
+ :type name: string or unicode
+ :param direct: Optionally, a flag indicating the class directly provides
+ the interfaces, and it needs not to be instantiated.
+ :type direct: boolean
+ """
scope = martian.MODULE
def factory(self, factory, provides=None, name=u'', direct=False):
@@ -32,6 +46,24 @@
return (factory, provides, name, direct)
class global_adapter(martian.MultipleTimesDirective):
+ """Registers the ``factory`` callable as a global adapter.
+
+ This allows you to register global adapters that
+ don't inherit from the ``Adapter`` or ``MultiAdapter`` base classes.
+
+ :param factory: The class that implements the adaptation.
+ :param adapts: Optionally, a single interface or a tuple of multiple
+ interfaces to adapts from. If omitted, this information is
+ deduced from the annotation on the factory. If no adapted
+ interface can be determinedm the current context will be
+ assumed.
+ :param provides: Optionally, the interface the adapter will provide. If
+ omitted, this information is deduced from the annotations
+ on the factory.
+ :param name: Optionally, a name for a named adapter registration.
+ :type name: string or unicode
+
+ """
scope = martian.MODULE
def factory(self, factory, adapts=None, provides=None, name=u''):
@@ -47,12 +79,24 @@
return (factory, adapts, provides, name)
class name(martian.Directive):
+ """Declares the name of a named utility, named adapter, etc.
+
+ """
scope = martian.CLASS
store = martian.ONCE
validate = martian.validateText
default = u''
class context(martian.Directive):
+ """Declares the type of object that the adapter (or a similar context-
+ dependent component) adapts.
+
+ :param context: Interface (in this case all objects providing this
+ interface will be eligible contexts for the adaptation) or
+ a class (then only instances of that particular class are
+ eligible).
+ """
+
scope = martian.CLASS_OR_MODULE
store = martian.ONCE
validate = martian.validateInterfaceOrClass
@@ -74,6 +118,10 @@
return component
class title(martian.Directive):
+ """Declares the human-readable title of a component (such as a permission,
+ role, etc.)
+
+ """
scope = martian.CLASS
store = martian.ONCE
validate = martian.validateText
@@ -82,6 +130,10 @@
pass
class direct(martian.MarkerDirective):
+ """Declares that a ``GlobalUtility`` class should be registered as a
+ utility itself, rather than an instance of it.
+
+ """
scope = martian.CLASS
class order(martian.Directive):
@@ -101,6 +153,13 @@
validate = martian.validateText
class provides(martian.Directive):
+ """Declares the interface that a adapter or utility provides for the
+ registration, as opposed to potentially multiple interfaces that the class
+ implements.
+
+ :param interface: The interface the registered component will provide.
+
+ """
scope = martian.CLASS
store = martian.ONCE
validate = martian.validateInterface
More information about the checkins
mailing list