Merge lp:~logan/ubuntu/raring/grokcore.component/2.5 into lp:ubuntu/raring/grokcore.component

[Logan Rosen]

[Daniel Holbach (dholbach)]

Thanks. Uploaded.

review: Approve

=== modified file 'CHANGES.txt'
--- CHANGES.txt	2010-01-29 16:22:17 +0000
+++ CHANGES.txt	2013-01-23 22:26:20 +0000
@@ -1,6 +1,61 @@
 Changes
 =======
 
+2.5 (2012-05-01)
+----------------
+
+- Introduce provideUtility, providerAdapter, provideSubscriptionAdapter,
+  provideHandler and provideInterface in grokcore.component. These by default
+  delegate the registration of components to the global site manager like
+  was done before, but provide the possibility for custom registries for the
+  grokked components.
+
+- Fix the `global_adapter` to properly use information annotated by
+  ``grok.adapter``, and using the IContext object if it was not
+  specified. (Fix Launchpad issue #960097).
+
+- Add a ``key`` option to ``sort_components`` that behave like ``key``
+  options available on standard Python sort methods.
+
+2.4 (2011-04-27)
+----------------
+
+- Fix the `global_adapter` directive implementation to accept an explicit
+  "empty" name for nameless adapter registrations (as it used to be that
+  providing an empty name in the registration would actually result in
+  registering a named adapter in case the factory has a `grok.name`).
+
+2.3 (2011-02-14)
+----------------
+
+- Implement the generic (Multi)Subscriptions components.
+
+2.2 (2010-11-03)
+----------------
+
+- The default values computation for the context directive and the provides
+  directive is now defined in the directives themselves. This means that where
+  the values for these directives is being retrieved, the "default_context"
+  function does not need to be passed along anymore for general cases.
+
+  Analogous to this, when getting values for the provides directive the
+  "default_provides" function does not need to be passed along in the general
+  case.
+
+2.1 (2010-11-01)
+----------------
+
+* Made package comply to zope.org repository policy.
+
+* Moved directives 'order' from grokcore.viewlet and 'path' from
+  grokcore.view to this very package.
+
+* Tiny dependency adjustment: moved zope.event to test dependencies.
+
+* Port from 1.x branch exclude parameter to the Grok ZCML directive.
+
+* Port from 1.x branch the ignore of testing.py modules.
+
 2.0 (2009-09-16)
 ----------------
 
@@ -26,7 +81,6 @@
 * Add missing provider, global_adapter, implementsOnly, classProvides() to
   the module interface so that they are included in __all__
 
-
 1.6 (2009-04-10)
 ----------------
 
@@ -36,7 +90,7 @@
 * Add support for registering global adapters at module level::
 
     grok.global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
-    
+
   Only 'factory' is required. If only a single interface is adapted, the
   second argument may be a single interface instead of a tuple. If the
   component has declared adapted/provided interfaces, the second and third
@@ -44,11 +98,11 @@
 
 * Add support for an @provider decorator to let a function directly provide
   an interface::
-  
+
     @grok.provider(IFoo, IBar)
     def some_function():
         ...
-        
+
   This is equivalent to doing alsoProvides(some_function, IFoo, IBar).
 
 * Add support for named adapters with the @adapter decorator::
@@ -87,7 +141,7 @@
 1.4 (2008-06-11)
 ----------------
 
-* Ported class grokkers to make use of further improvements in Martian. 
+* Ported class grokkers to make use of further improvements in Martian.
   This requires Martian 0.10.
 
 1.3 (2008-05-14)

=== modified file 'COPYRIGHT.txt'
--- COPYRIGHT.txt	2010-01-29 16:22:17 +0000
+++ COPYRIGHT.txt	2013-01-23 22:26:20 +0000
@@ -1,10 +1,1 @@
-Copyright (c) 2008 gocept gmbh & co. kg, Martijn Faassen and Philipp von
-Weitershausen
-All Rights Reserved.
-
-This software is subject to the provisions of the Zope Public License,
-Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
-THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-FOR A PARTICULAR PURPOSE. 
+Zope Foundation and Contributors
\ No newline at end of file

=== modified file 'LICENSE.txt'
--- LICENSE.txt	2010-01-29 16:22:17 +0000
+++ LICENSE.txt	2013-01-23 22:26:20 +0000
@@ -1,54 +1,44 @@
 Zope Public License (ZPL) Version 2.1
--------------------------------------
-
-A copyright notice accompanies this license document that
-identifies the copyright holders.
-
-This license has been certified as open source. It has also
-been designated as GPL compatible by the Free Software
-Foundation (FSF).
-
-Redistribution and use in source and binary forms, with or
-without modification, are permitted provided that the
-following conditions are met:
-
-1. Redistributions in source code must retain the
-   accompanying copyright notice, this list of conditions,
-   and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the accompanying
-   copyright notice, this list of conditions, and the
-   following disclaimer in the documentation and/or other
-   materials provided with the distribution.
-
-3. Names of the copyright holders must not be used to
-   endorse or promote products derived from this software
-   without prior written permission from the copyright
-   holders.
-
-4. The right to distribute this software or to use it for
-   any purpose does not give you the right to use
-   Servicemarks (sm) or Trademarks (tm) of the copyright
-   holders. Use of them is covered by separate agreement
-   with the copyright holders.
-
-5. If any files are modified, you must cause the modified
-   files to carry prominent notices stating that you changed
-   the files and the date of any change.
+
+A copyright notice accompanies this license document that identifies the
+copyright holders.
+
+This license has been certified as open source. It has also been designated as
+GPL compatible by the Free Software Foundation (FSF).
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions in source code must retain the accompanying copyright
+notice, this list of conditions, and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the accompanying copyright
+notice, this list of conditions, and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Names of the copyright holders must not be used to endorse or promote
+products derived from this software without prior written permission from the
+copyright holders.
+
+4. The right to distribute this software or to use it for any purpose does not
+give you the right to use Servicemarks (sm) or Trademarks (tm) of the
+copyright
+holders. Use of them is covered by separate agreement with the copyright
+holders.
+
+5. If any files are modified, you must cause the modified files to carry
+prominent notices stating that you changed the files and the date of any
+change.
 
 Disclaimer
 
-  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
-  AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
-  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
-  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
-  NO EVENT SHALL THE COPYRIGHT HOLDERS BE
-  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-  DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESSED
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=== modified file 'PKG-INFO'
--- PKG-INFO	2010-01-29 16:22:17 +0000
+++ PKG-INFO	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 Metadata-Version: 1.0
 Name: grokcore.component
-Version: 2.0
+Version: 2.5
 Summary: Grok-like configuration for basic components (adapters, utilities, subscribers)
 Home-page: http://grok.zope.org
 Author: Grok Team
@@ -29,34 +29,34 @@
         we need to make sure it's available to the ZCML machinery.  We do this
         by including the meta configuration from ``grokcore.component``::
         
-        <include package="grokcore.component" file="meta.zcml" />
+          <include package="grokcore.component" file="meta.zcml" />
         
         Put this line somewhere to the top of ``site.zcml``, next to other
         meta configuration includes.  Now, further down the line, we can tell
         the machinery in ``grokcore.component`` to register all components in
         your package (let's say it's called ``helloworld``)::
         
-        <grok:grok package="helloworld" />
+          <grok:grok package="helloworld" />
         
         To sum up, your ``site.zcml`` file should look like something like this::
         
-        <configure
-        xmlns="http://namespaces.zope.org/zope"
-        xmlns:grok="http://namespaces.zope.org/grok">
-        
-        <!-- do the meta configuration to make the ZCML directives available -->
-        <include package="zope.foobar" file="meta.zcml" />
-        <include package="zope.frobnaz" file="meta.zcml" />
-        <include package="grokcore.component" file="meta.zcml" />
-        
-        <!-- now load the configuration of packages that we depend on -->
-        <include package="zope.barfoo" />
-        <include package="zope.somethingorother" />
-        
-        <!-- finally load my components which are based on grokcore.component -->
-        <grok:grok package="helloworld" />
-        
-        </configure>
+          <configure
+              xmlns="http://namespaces.zope.org/zope"
+              xmlns:grok="http://namespaces.zope.org/grok">
+        
+            <!-- do the meta configuration to make the ZCML directives available -->
+            <include package="zope.foobar" file="meta.zcml" />
+            <include package="zope.frobnaz" file="meta.zcml" />
+            <include package="grokcore.component" file="meta.zcml" />
+        
+            <!-- now load the configuration of packages that we depend on -->
+            <include package="zope.barfoo" />
+            <include package="zope.somethingorother" />
+        
+            <!-- finally load my components which are based on grokcore.component -->
+            <grok:grok package="helloworld" />
+        
+          </configure>
         
         Examples
         ========
@@ -67,26 +67,26 @@
         Here's a simple adapter that may be useful in Zope.  It extracts the
         languages that a user prefers from the request::
         
-        import grokcore.component
-        from zope.publisher.interfaces.browser import IBrowserRequest
-        from zope.i18n.interfaces import IUserPreferredLanguages
-        
-        class CookieLanguage(grokcore.component.Adapter):
-        """Extract the preferred language from a cookie"""
-        grokcore.component.context(IBrowserRequest)
-        grokcore.component.implements(IUserPreferredLanguages)
-        
-        # No need to implement __init__, it's already provided by the base class.
-        
-        def getPreferredLanguages(self):
-        # This an adapter for the request, so self.context is the request.
-        request = self.context
-        
-        # Extract the preferred language from a cookie:
-        lang = request.cookies.get('language', 'en')
-        
-        # According to IUserPreferredLanguages, we must return a list.
-        return [lang]
+          import grokcore.component
+          from zope.publisher.interfaces.browser import IBrowserRequest
+          from zope.i18n.interfaces import IUserPreferredLanguages
+        
+          class CookieLanguage(grokcore.component.Adapter):
+              """Extract the preferred language from a cookie"""
+              grokcore.component.context(IBrowserRequest)
+              grokcore.component.implements(IUserPreferredLanguages)
+        
+              # No need to implement __init__, it's already provided by the base class.
+        
+              def getPreferredLanguages(self):
+                  # This an adapter for the request, so self.context is the request.
+                  request = self.context
+        
+                  # Extract the preferred language from a cookie:
+                  lang = request.cookies.get('language', 'en')
+        
+                  # According to IUserPreferredLanguages, we must return a list.
+                  return [lang]
         
         Multi-adapter
         -------------
@@ -97,21 +97,24 @@
         the content object (model), the request and the view that they're
         supposed to be a part of::
         
-        import grokcore.component
-        from zope.publisher.interfaces.browser import IBrowserRequest
-        from zope.publisher.interfaces.browser import IBrowserPage
-        from zope.contentprovider.interfaces import IContentProvider
-        
-        class HelloWorldProvider(grokcore.component.MultiAdapter):
-        """Display Hello World!"""
-        grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)
-        grokcore.component.implements(IContentProvider)
-        
-        def update(self):
-        pass
-        
-        def render(self):
-        return u'<p>Hello World!</p>'
+          import grokcore.component
+          from zope.publisher.interfaces.browser import IBrowserRequest
+          from zope.publisher.interfaces.browser import IBrowserPage
+          from zope.contentprovider.interfaces import IContentProvider
+        
+          class HelloWorldProvider(grokcore.component.MultiAdapter):
+              """Display Hello World!"""
+              grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)
+              grokcore.component.implements(IContentProvider)
+        
+              def __init__(self, context, request, view):
+                  pass
+        
+              def update(self):
+                  pass
+        
+              def render(self):
+                  return u'<p>Hello World!</p>'
         
         
         Global utility
@@ -122,24 +125,24 @@
         messages and is invoked when the i18n machinery needs to translate
         something::
         
-        import grokcore.component
-        from zope.i18n.interfaces import ITranslationDomain
-        
-        class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):
-        grokcore.component.implements(ITranslationDomain)
-        grokcore.component.name('helloworld')
-        
-        domain = u'helloworld'
-        
-        def translate(self, msgid, mapping=None, context=None,
-        target_language=None, default=None):
-        if target_language is None:
-        preferred = IUserPreferredLanguages(context)
-        target_language = preferred.getPreferredLanguages()[0]
-        
-        translations = {'de': u'Hallo Welt',
-        'nl': u'Hallo Wereld'}
-        return translations.get(target_language, u'Hello World')
+          import grokcore.component
+          from zope.i18n.interfaces import ITranslationDomain
+        
+          class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):
+              grokcore.component.implements(ITranslationDomain)
+              grokcore.component.name('helloworld')
+        
+              domain = u'helloworld'
+        
+              def translate(self, msgid, mapping=None, context=None,
+                            target_language=None, default=None):
+                  if target_language is None:
+                      preferred = IUserPreferredLanguages(context)
+                      target_language = preferred.getPreferredLanguages()[0]
+        
+                  translations = {'de': u'Hallo Welt',
+                                  'nl': u'Hallo Wereld'}
+                  return translations.get(target_language, u'Hello World')
         
         Of course, it's silly to implement your own translation domain utility
         if there are already implementations available in ``zope.i18n`` (one
@@ -147,18 +150,18 @@
         simple implementation for tests).  Let's try to reuse that
         implementation and register an instance::
         
-        import grokcore.component
-        from zope.i18n.interfaces import ITranslationDomain
-        from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
-        
-        messages = {('de', u'Hello World'): u'Hallo Welt',
-        ('nl', u'Hello World'): u'Hallo Wereld'}
-        helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)
-        
-        grokcore.component.global_utility(helloworld_domain,
-        provides=ITranslationDomain,
-        name='helloworld',
-        direct=True)
+          import grokcore.component
+          from zope.i18n.interfaces import ITranslationDomain
+          from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
+        
+          messages = {('de', u'Hello World'): u'Hallo Welt',
+                      ('nl', u'Hello World'): u'Hallo Wereld'}
+          helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)
+        
+          grokcore.component.global_utility(helloworld_domain,
+                                            provides=ITranslationDomain,
+                                            name='helloworld',
+                                            direct=True)
         
         Global adapter
         --------------
@@ -172,333 +175,265 @@
         example drawing on the ``z3c.form`` library, which provides an adapter factory
         factory for named widget attributes::
         
-        import zope.interface
-        import zope.schema
-        import grokcore.component
-        import z3c.form.widget import ComputedWidgetAttribute
-        
-        class ISchema(Interface):
-        """This schema will be used to power a z3c.form form"""
-        
-        field = zope.schema.TextLine(title=u"Sample field")
-        
-        ...
-        
-        label_override = z3c.form.widget.StaticWidgetAttribute(
-        u"Override label", field=ISchema['field'])
-        
-        grokcore.component.global_adapter(label_override, name=u"label")
+          import zope.interface
+          import zope.schema
+          import grokcore.component
+          import z3c.form.widget import ComputedWidgetAttribute
+        
+          class ISchema(Interface):
+              """This schema will be used to power a z3c.form form"""
+        
+              field = zope.schema.TextLine(title=u"Sample field")
+        
+          ...
+        
+          label_override = z3c.form.widget.StaticWidgetAttribute(
+                                u"Override label", field=ISchema['field'])
+        
+          grokcore.component.global_adapter(label_override, name=u"label")
         
         In the example above, the provided and adapted interfaces are deduced from the
         object returned by the ``StaticWidgetAttribute`` factory. The full syntax
         for global_adapter is::
         
-        global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
+          global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
         
         The factory must be a callable (the adapter factory). Adapted interfaces are
         given as a tuple. You may use a single interface instead of a one-element
         tuple for single adapters. The provided interface is given as shown. The name
         defaults to u"" (an unnamed adapter).
         
-        Subscriber
-        ----------
-        
-        Here we see a subscriber much like it occurs within Zope itself.  It
-        subscribes to the modified event for all annotatable objects (in other
-        words, objects that can have metadata associated with them).  When
-        invoked, it updates the Dublin Core 'Modified' property accordingly::
-        
-        import datetime
-        import grokcore.component
-        from zope.annotation.interfaces import IAnnotatable
-        from zope.lifecycleevent.interfaces import IObjectModifiedEvent
-        from zope.dublincore.interfaces import IZopeDublinCore
-        
-        @grokcore.component.subscribe(IAnnotatable, IObjectModifiedEvent)
-        def updateDublinCoreAfterModification(obj, event):
-        """Updated the Dublin Core 'Modified' property when a modified
-        event is sent for an object."""
-        IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
-        
-        
-        API overview
-        ============
-        
-        Base classes
-        ------------
-        
-        ``Adapter``
-        Base class for an adapter that adapts a single object (commonly
-        referred to as the *context*).  Use the ``context`` directive to
-        specify which object to adapt and the ``implements`` directive to
-        specify which interface the adapter will provide.  If it's a named
-        adapter, you may use the ``name`` directive to specify the name.
-        
-        ``MultiAdapter``
-        Base class for an adapter that adapts *n* objects (where *n>=1*).
-        Use the ``adapts`` directive to specify which kinds of objects are
-        adapted and the ``implements`` directive to specify which
-        interface the adapter will provide.  If it's a named
-        multi-adapter, you may use the ``name`` directive to specify the
-        name.
-        
-        ``GlobalUtility``
-        Base class for a globally registered utility.  Unless you use the
-        ``direct`` directive to indicate that the class itself should be
-        registered as a utility, the class will automatically be
-        instantiated, therefore the constructor may not take any
-        arguments.  Use the ``implements`` directive to specify which
-        interface the utility provides, or if that is not unambiguous,
-        also use the ``provides`` directive to specify which of the
-        implemented interfaces should be used when registering the
-        utility.  If it's a named utility, you may use the ``name``
-        directive to specify the name.
-        
-        ``Context``
-        Subclasses of this will automatically be found as potential
-        contexts for adapters and other types of context-dependent
-        components.
-        
-        
-        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.
+        Handling events
+        ---------------
+        
+        Here we see an event handler much like it occurs within Zope itself. It
+        subscribes to the modified event for all annotatable objects (in other words,
+        objects that can have metadata associated with them). When invoked, it updates
+        the Dublin Core 'Modified' property accordingly::
+        
+          import datetime
+          import grokcore.component
+          from zope.annotation.interfaces import IAnnotatable
+          from zope.lifecycleevent.interfaces import IObjectModifiedEvent
+          from zope.dublincore.interfaces import IZopeDublinCore
+        
+          @grokcore.component.subscribe(IAnnotatable, IObjectModifiedEvent)
+          def updateDublinCoreAfterModification(obj, event):
+              """Updated the Dublin Core 'Modified' property when a modified
+              event is sent for an object."""
+              IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
+        
+        Subscriptions
+        -------------
+        
+        Subscriptions look similar to Adapter, however, unlike regular adapters,
+        subscription adapters are used when we want all of the adapters that adapt an
+        object to a particular adapter.
+        
+        Analogous to MultiAdapter, there is a MultiSubscription component that "adapts"
+        multiple objects.
         
         Changes
         =======
         
+        2.5 (2012-05-01)
+        ----------------
+        
+        - Introduce provideUtility, providerAdapter, provideSubscriptionAdapter,
+          provideHandler and provideInterface in grokcore.component. These by default
+          delegate the registration of components to the global site manager like
+          was done before, but provide the possibility for custom registries for the
+          grokked components.
+        
+        - Fix the `global_adapter` to properly use information annotated by
+          ``grok.adapter``, and using the IContext object if it was not
+          specified. (Fix Launchpad issue #960097).
+        
+        - Add a ``key`` option to ``sort_components`` that behave like ``key``
+          options available on standard Python sort methods.
+        
+        2.4 (2011-04-27)
+        ----------------
+        
+        - Fix the `global_adapter` directive implementation to accept an explicit
+          "empty" name for nameless adapter registrations (as it used to be that
+          providing an empty name in the registration would actually result in
+          registering a named adapter in case the factory has a `grok.name`).
+        
+        2.3 (2011-02-14)
+        ----------------
+        
+        - Implement the generic (Multi)Subscriptions components.
+        
+        2.2 (2010-11-03)
+        ----------------
+        
+        - The default values computation for the context directive and the provides
+          directive is now defined in the directives themselves. This means that where
+          the values for these directives is being retrieved, the "default_context"
+          function does not need to be passed along anymore for general cases.
+        
+          Analogous to this, when getting values for the provides directive the
+          "default_provides" function does not need to be passed along in the general
+          case.
+        
+        2.1 (2010-11-01)
+        ----------------
+        
+        * Made package comply to zope.org repository policy.
+        
+        * Moved directives 'order' from grokcore.viewlet and 'path' from
+          grokcore.view to this very package.
+        
+        * Tiny dependency adjustment: moved zope.event to test dependencies.
+        
+        * Port from 1.x branch exclude parameter to the Grok ZCML directive.
+        
+        * Port from 1.x branch the ignore of testing.py modules.
+        
         2.0 (2009-09-16)
         ----------------
         
         * Use a newer version of Martian that has better support for
-        inheritance.  This is demonstrated in ``tests/inherit``.
+          inheritance.  This is demonstrated in ``tests/inherit``.
         
         * The ``ContextGrokker`` and the ``scan.py`` module have gone away
-        thanks the newer Martian.
+          thanks the newer Martian.
         
         * Directive implementations (in their factory method) should *not*
-        bind directives. Directive binding cannot take place at import time,
-        but only at grok time. Binding directives during import time (when
-        directives are executed) can lead to change problems. (we noticed
-        this during our refactoring to use the new Martian).
+          bind directives. Directive binding cannot take place at import time,
+          but only at grok time. Binding directives during import time (when
+          directives are executed) can lead to change problems. (we noticed
+          this during our refactoring to use the new Martian).
         
         * Use 1.0b1 versions.cfg in Grok's release info instead of a local
-        copy; a local copy for all grokcore packages is just too hard to
-        maintain.
+          copy; a local copy for all grokcore packages is just too hard to
+          maintain.
         
         1.7 (2009-06-01)
         ----------------
         
         * Add missing provider, global_adapter, implementsOnly, classProvides() to
-        the module interface so that they are included in __all__
-        
+          the module interface so that they are included in __all__
         
         1.6 (2009-04-10)
         ----------------
         
         * Add convenience imports for implementsOnly() and classProvides() class
-        declarations form zope.interface.
+          declarations form zope.interface.
         
         * Add support for registering global adapters at module level::
         
-        grok.global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
+            grok.global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
         
-        Only 'factory' is required. If only a single interface is adapted, the
-        second argument may be a single interface instead of a tuple. If the
-        component has declared adapted/provided interfaces, the second and third
-        arguments may be omitted.
+          Only 'factory' is required. If only a single interface is adapted, the
+          second argument may be a single interface instead of a tuple. If the
+          component has declared adapted/provided interfaces, the second and third
+          arguments may be omitted.
         
         * Add support for an @provider decorator to let a function directly provide
-        an interface::
-        
-        @grok.provider(IFoo, IBar)
-        def some_function():
-        ...
-        
-        This is equivalent to doing alsoProvides(some_function, IFoo, IBar).
+          an interface::
+        
+            @grok.provider(IFoo, IBar)
+            def some_function():
+                ...
+        
+          This is equivalent to doing alsoProvides(some_function, IFoo, IBar).
         
         * Add support for named adapters with the @adapter decorator::
         
-        @grok.adapter(IAdaptedOne, IAdaptedTwo, name=u"foo")
-        def some_function(one, two):
-        ...
+            @grok.adapter(IAdaptedOne, IAdaptedTwo, name=u"foo")
+            def some_function(one, two):
+                ...
         
         1.5.1 (2008-07-28)
         ------------------
         
         * The ``IGrokcoreComponentAPI`` interface was missing declarations for
-        the ``title`` and ``description`` directives.
+          the ``title`` and ``description`` directives.
         
         1.5 (2008-07-22)
         ----------------
         
         * Fix https://bugs.launchpad.net/grok/+bug/242353: grokcore.component
-        contains old-style test setup. There is no `register_all_tests`
-        method in grokcore.component.testing anymore. Use z3c.testsetup
-        instead.
+          contains old-style test setup. There is no `register_all_tests`
+          method in grokcore.component.testing anymore. Use z3c.testsetup
+          instead.
         
         * Allow functions that have been marked with @grok.subscribe also be
-        registered with ``zope.component.provideHandler()`` manually.  This
-        is useful for unit tests where you may not want to grok a whole
-        module.
+          registered with ``zope.component.provideHandler()`` manually.  This
+          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.
+          ``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)
         ----------------
         
         * Ported class grokkers to make use of further improvements in Martian.
-        This requires Martian 0.10.
+          This requires Martian 0.10.
         
         1.3 (2008-05-14)
         ----------------
         
         * Ported class grokkers to make use of the new declarative way of
-        retrieving directive information from a class.  This requires
-        Martian 0.9.6.
+          retrieving directive information from a class.  This requires
+          Martian 0.9.6.
         
         1.2.1 (2008-05-04)
         ------------------
         
         * Upgrade to Martian 0.9.5, which has a slight change in the signature of
-        ``scan_for_classes``.
+          ``scan_for_classes``.
         
         * Remove an unnecessary import ``methods_from_class`` from
-        ``grokcore.component.scan``.
+          ``grokcore.component.scan``.
         
         1.2 (2008-05-04)
         ----------------
         
         * Ported directives to Martian's new directive implementation.  As a
-        result, nearly all helper functions that were available from
-        ``grokcore.component.util`` have been removed.  The functionality is
-        mostly available from the directives themselves now.
+          result, nearly all helper functions that were available from
+          ``grokcore.component.util`` have been removed.  The functionality is
+          mostly available from the directives themselves now.
         
         * The ``baseclass`` directive has been moved to Martian.
         
         * The ``order`` directive and its helper functions have been moved
-        back to Grok, as it was of no general use, but very specific to
-        viewlets.
+          back to Grok, as it was of no general use, but very specific to
+          viewlets.
         
         1.1 (2008-05-03)
         ----------------
         
         * ``determine_module_component`` now looks for classes that implement
-        a certain interface (such as ``IContext``), instead of taking a list
-        of classes.  If looking for ``IContext``, it still will find
-        ``Context`` subclasses, as these were also made to implement
-        ``IContext``.
+          a certain interface (such as ``IContext``), instead of taking a list
+          of classes.  If looking for ``IContext``, it still will find
+          ``Context`` subclasses, as these were also made to implement
+          ``IContext``.
         
         * Move the ``public_methods_from_class`` helper function back to Grok,
-        it isn't used at all in ``grokcore.component``.
+          it isn't used at all in ``grokcore.component``.
         
         1.0.1 (2008-05-02)
         ------------------
         
         * The grokkers for adapters and global utilities did not use the
-        correct value for the *provided* interface in the configuration
-        action discriminator.  Because of this, uninformative and
-        potentially wrong conflict errors would occur, as well as no
-        conflict where a conflict should have occurred.
+          correct value for the *provided* interface in the configuration
+          action discriminator.  Because of this, uninformative and
+          potentially wrong conflict errors would occur, as well as no
+          conflict where a conflict should have occurred.
         
         * The grokker for the ``global_utility()`` directive did immediate
-        registrations instead of generating configuration actions.
-        Therefore it did not provoke ``ConflictErrors`` for conflicting
-        registrations.
+          registrations instead of generating configuration actions.
+          Therefore it did not provoke ``ConflictErrors`` for conflicting
+          registrations.
         
         * Improved documentation
         
@@ -506,8 +441,8 @@
         ----------------
         
         * Created ``grokcore.component`` in March 2008 by factoring basic
-        component base classes and their directives and grokkers out of
-        Grok.
+          component base classes and their directives and grokkers out of
+          Grok.
         
 Platform: UNKNOWN
 Classifier: Intended Audience :: Developers

=== modified file 'README.txt'
--- README.txt	2010-01-29 16:22:17 +0000
+++ README.txt	2013-01-23 22:26:20 +0000
@@ -98,6 +98,9 @@
       grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)
       grokcore.component.implements(IContentProvider)
 
+      def __init__(self, context, request, view):
+          pass
+
       def update(self):
           pass
 
@@ -170,34 +173,34 @@
 
   class ISchema(Interface):
       """This schema will be used to power a z3c.form form"""
-      
+
       field = zope.schema.TextLine(title=u"Sample field")
-      
+
   ...
 
   label_override = z3c.form.widget.StaticWidgetAttribute(
                         u"Override label", field=ISchema['field'])
-  
+
   grokcore.component.global_adapter(label_override, name=u"label")
-  
+
 In the example above, the provided and adapted interfaces are deduced from the
 object returned by the ``StaticWidgetAttribute`` factory. The full syntax
 for global_adapter is::
 
   global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
-  
+
 The factory must be a callable (the adapter factory). Adapted interfaces are
 given as a tuple. You may use a single interface instead of a one-element
 tuple for single adapters. The provided interface is given as shown. The name
 defaults to u"" (an unnamed adapter).
 
-Subscriber
-----------
+Handling events
+---------------
 
-Here we see a subscriber much like it occurs within Zope itself.  It
-subscribes to the modified event for all annotatable objects (in other
-words, objects that can have metadata associated with them).  When
-invoked, it updates the Dublin Core 'Modified' property accordingly::
+Here we see an event handler much like it occurs within Zope itself. It
+subscribes to the modified event for all annotatable objects (in other words,
+objects that can have metadata associated with them). When invoked, it updates
+the Dublin Core 'Modified' property accordingly::
 
   import datetime
   import grokcore.component
@@ -211,134 +214,12 @@
       event is sent for an object."""
       IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
 
-
-API overview
-============
-
-Base classes
-------------
-
-``Adapter``
-    Base class for an adapter that adapts a single object (commonly
-    referred to as the *context*).  Use the ``context`` directive to
-    specify which object to adapt and the ``implements`` directive to
-    specify which interface the adapter will provide.  If it's a named
-    adapter, you may use the ``name`` directive to specify the name.
-
-``MultiAdapter``
-    Base class for an adapter that adapts *n* objects (where *n>=1*).
-    Use the ``adapts`` directive to specify which kinds of objects are
-    adapted and the ``implements`` directive to specify which
-    interface the adapter will provide.  If it's a named
-    multi-adapter, you may use the ``name`` directive to specify the
-    name.
-
-``GlobalUtility``
-    Base class for a globally registered utility.  Unless you use the
-    ``direct`` directive to indicate that the class itself should be
-    registered as a utility, the class will automatically be
-    instantiated, therefore the constructor may not take any
-    arguments.  Use the ``implements`` directive to specify which
-    interface the utility provides, or if that is not unambiguous,
-    also use the ``provides`` directive to specify which of the
-    implemented interfaces should be used when registering the
-    utility.  If it's a named utility, you may use the ``name``
-    directive to specify the name.
-
-``Context``
-    Subclasses of this will automatically be found as potential
-    contexts for adapters and other types of context-dependent
-    components.
-
-
-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.
+Subscriptions
+-------------
+
+Subscriptions look similar to Adapter, however, unlike regular adapters,
+subscription adapters are used when we want all of the adapters that adapt an
+object to a particular adapter.
+
+Analogous to MultiAdapter, there is a MultiSubscription component that "adapts"
+multiple objects.

=== removed directory 'bootstrap'
=== added file 'bootstrap.py'
--- bootstrap.py	1970-01-01 00:00:00 +0000
+++ bootstrap.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,258 @@
+##############################################################################
+#
+# Copyright (c) 2006 Zope Foundation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Bootstrap a buildout-based project
+
+Simply run this script in a directory containing a buildout.cfg.
+The script accepts buildout command-line options, so you can
+use the -c option to specify an alternate configuration file.
+"""
+
+import os, shutil, sys, tempfile, textwrap, urllib, urllib2, subprocess
+from optparse import OptionParser
+
+if sys.platform == 'win32':
+    def quote(c):
+        if ' ' in c:
+            return '"%s"' % c # work around spawn lamosity on windows
+        else:
+            return c
+else:
+    quote = str
+
+# See zc.buildout.easy_install._has_broken_dash_S for motivation and comments.
+stdout, stderr = subprocess.Popen(
+    [sys.executable, '-Sc',
+     'try:\n'
+     '    import ConfigParser\n'
+     'except ImportError:\n'
+     '    print 1\n'
+     'else:\n'
+     '    print 0\n'],
+    stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate()
+has_broken_dash_S = bool(int(stdout.strip()))
+
+# In order to be more robust in the face of system Pythons, we want to
+# run without site-packages loaded.  This is somewhat tricky, in
+# particular because Python 2.6's distutils imports site, so starting
+# with the -S flag is not sufficient.  However, we'll start with that:
+if not has_broken_dash_S and 'site' in sys.modules:
+    # We will restart with python -S.
+    args = sys.argv[:]
+    args[0:0] = [sys.executable, '-S']
+    args = map(quote, args)
+    os.execv(sys.executable, args)
+# Now we are running with -S.  We'll get the clean sys.path, import site
+# because distutils will do it later, and then reset the path and clean
+# out any namespace packages from site-packages that might have been
+# loaded by .pth files.
+clean_path = sys.path[:]
+import site
+sys.path[:] = clean_path
+for k, v in sys.modules.items():
+    if (hasattr(v, '__path__') and
+        len(v.__path__)==1 and
+        not os.path.exists(os.path.join(v.__path__[0],'__init__.py'))):
+        # This is a namespace package.  Remove it.
+        sys.modules.pop(k)
+
+is_jython = sys.platform.startswith('java')
+
+setuptools_source = 'http://peak.telecommunity.com/dist/ez_setup.py'
+distribute_source = 'http://python-distribute.org/distribute_setup.py'
+
+# parsing arguments
+def normalize_to_url(option, opt_str, value, parser):
+    if value:
+        if '://' not in value: # It doesn't smell like a URL.
+            value = 'file://%s' % (
+                urllib.pathname2url(
+                    os.path.abspath(os.path.expanduser(value))),)
+        if opt_str == '--download-base' and not value.endswith('/'):
+            # Download base needs a trailing slash to make the world happy.
+            value += '/'
+    else:
+        value = None
+    name = opt_str[2:].replace('-', '_')
+    setattr(parser.values, name, value)
+
+usage = '''\
+[DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
+
+Bootstraps a buildout-based project.
+
+Simply run this script in a directory containing a buildout.cfg, using the
+Python that you want bin/buildout to use.
+
+Note that by using --setup-source and --download-base to point to
+local resources, you can keep this script from going over the network.
+'''
+
+parser = OptionParser(usage=usage)
+parser.add_option("-v", "--version", dest="version",
+                          help="use a specific zc.buildout version")
+parser.add_option("-d", "--distribute",
+                   action="store_true", dest="use_distribute", default=False,
+                   help="Use Distribute rather than Setuptools.")
+parser.add_option("--setup-source", action="callback", dest="setup_source",
+                  callback=normalize_to_url, nargs=1, type="string",
+                  help=("Specify a URL or file location for the setup file. "
+                        "If you use Setuptools, this will default to " +
+                        setuptools_source + "; if you use Distribute, this "
+                        "will default to " + distribute_source +"."))
+parser.add_option("--download-base", action="callback", dest="download_base",
+                  callback=normalize_to_url, nargs=1, type="string",
+                  help=("Specify a URL or directory for downloading "
+                        "zc.buildout and either Setuptools or Distribute. "
+                        "Defaults to PyPI."))
+parser.add_option("--eggs",
+                  help=("Specify a directory for storing eggs.  Defaults to "
+                        "a temporary directory that is deleted when the "
+                        "bootstrap script completes."))
+parser.add_option("-t", "--accept-buildout-test-releases",
+                  dest='accept_buildout_test_releases',
+                  action="store_true", default=False,
+                  help=("Normally, if you do not specify a --version, the "
+                        "bootstrap script and buildout gets the newest "
+                        "*final* versions of zc.buildout and its recipes and "
+                        "extensions for you.  If you use this flag, "
+                        "bootstrap and buildout will get the newest releases "
+                        "even if they are alphas or betas."))
+parser.add_option("-c", None, action="store", dest="config_file",
+                   help=("Specify the path to the buildout configuration "
+                         "file to be used."))
+
+options, args = parser.parse_args()
+
+# if -c was provided, we push it back into args for buildout's main function
+if options.config_file is not None:
+    args += ['-c', options.config_file]
+
+if options.eggs:
+    eggs_dir = os.path.abspath(os.path.expanduser(options.eggs))
+else:
+    eggs_dir = tempfile.mkdtemp()
+
+if options.setup_source is None:
+    if options.use_distribute:
+        options.setup_source = distribute_source
+    else:
+        options.setup_source = setuptools_source
+
+if options.accept_buildout_test_releases:
+    args.append('buildout:accept-buildout-test-releases=true')
+args.append('bootstrap')
+
+try:
+    import pkg_resources
+    import setuptools # A flag.  Sometimes pkg_resources is installed alone.
+    if not hasattr(pkg_resources, '_distribute'):
+        raise ImportError
+except ImportError:
+    ez_code = urllib2.urlopen(
+        options.setup_source).read().replace('\r\n', '\n')
+    ez = {}
+    exec ez_code in ez
+    setup_args = dict(to_dir=eggs_dir, download_delay=0)
+    if options.download_base:
+        setup_args['download_base'] = options.download_base
+    if options.use_distribute:
+        setup_args['no_fake'] = True
+    ez['use_setuptools'](**setup_args)
+    reload(sys.modules['pkg_resources'])
+    import pkg_resources
+    # This does not (always?) update the default working set.  We will
+    # do it.
+    for path in sys.path:
+        if path not in pkg_resources.working_set.entries:
+            pkg_resources.working_set.add_entry(path)
+
+cmd = [quote(sys.executable),
+       '-c',
+       quote('from setuptools.command.easy_install import main; main()'),
+       '-mqNxd',
+       quote(eggs_dir)]
+
+if not has_broken_dash_S:
+    cmd.insert(1, '-S')
+
+find_links = options.download_base
+if not find_links:
+    find_links = os.environ.get('bootstrap-testing-find-links')
+if find_links:
+    cmd.extend(['-f', quote(find_links)])
+
+if options.use_distribute:
+    setup_requirement = 'distribute'
+else:
+    setup_requirement = 'setuptools'
+ws = pkg_resources.working_set
+setup_requirement_path = ws.find(
+    pkg_resources.Requirement.parse(setup_requirement)).location
+env = dict(
+    os.environ,
+    PYTHONPATH=setup_requirement_path)
+
+requirement = 'zc.buildout'
+version = options.version
+if version is None and not options.accept_buildout_test_releases:
+    # Figure out the most recent final version of zc.buildout.
+    import setuptools.package_index
+    _final_parts = '*final-', '*final'
+    def _final_version(parsed_version):
+        for part in parsed_version:
+            if (part[:1] == '*') and (part not in _final_parts):
+                return False
+        return True
+    index = setuptools.package_index.PackageIndex(
+        search_path=[setup_requirement_path])
+    if find_links:
+        index.add_find_links((find_links,))
+    req = pkg_resources.Requirement.parse(requirement)
+    if index.obtain(req) is not None:
+        best = []
+        bestv = None
+        for dist in index[req.project_name]:
+            distv = dist.parsed_version
+            if _final_version(distv):
+                if bestv is None or distv > bestv:
+                    best = [dist]
+                    bestv = distv
+                elif distv == bestv:
+                    best.append(dist)
+        if best:
+            best.sort()
+            version = best[-1].version
+if version:
+    requirement = '=='.join((requirement, version))
+cmd.append(requirement)
+
+if is_jython:
+    import subprocess
+    exitcode = subprocess.Popen(cmd, env=env).wait()
+else: # Windows prefers this, apparently; otherwise we would prefer subprocess
+    exitcode = os.spawnle(*([os.P_WAIT, sys.executable] + cmd + [env]))
+if exitcode != 0:
+    sys.stdout.flush()
+    sys.stderr.flush()
+    print ("An error occurred when trying to install zc.buildout. "
+           "Look above this message for any errors that "
+           "were output by easy_install.")
+    sys.exit(exitcode)
+
+ws.add_entry(eggs_dir)
+ws.require(requirement)
+import zc.buildout.buildout
+zc.buildout.buildout.main(args)
+if not options.eggs: # clean up temporary egg directory
+    shutil.rmtree(eggs_dir)

=== removed file 'bootstrap/bootstrap.py'
--- bootstrap/bootstrap.py	2010-01-29 16:22:17 +0000
+++ bootstrap/bootstrap.py	1970-01-01 00:00:00 +0000
@@ -1,84 +0,0 @@
-##############################################################################
-#
-# Copyright (c) 2006 Zope Corporation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-##############################################################################
-"""Bootstrap a buildout-based project
-
-Simply run this script in a directory containing a buildout.cfg.
-The script accepts buildout command-line options, so you can
-use the -c option to specify an alternate configuration file.
-
-$Id: bootstrap.py 102545 2009-08-06 14:49:47Z chrisw $
-"""
-
-import os, shutil, sys, tempfile, urllib2
-
-tmpeggs = tempfile.mkdtemp()
-
-is_jython = sys.platform.startswith('java')
-
-try:
-    import pkg_resources
-except ImportError:
-    ez = {}
-    exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
-                         ).read() in ez
-    ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
-
-    import pkg_resources
-
-if sys.platform == 'win32':
-    def quote(c):
-        if ' ' in c:
-            return '"%s"' % c # work around spawn lamosity on windows
-        else:
-            return c
-else:
-    def quote (c):
-        return c
-
-cmd = 'from setuptools.command.easy_install import main; main()'
-ws  = pkg_resources.working_set
-
-if len(sys.argv) > 2 and sys.argv[1] == '--version':
-    VERSION = '==%s' % sys.argv[2]
-    args = sys.argv[3:] + ['bootstrap']
-else:
-    VERSION = ''
-    args = sys.argv[1:] + ['bootstrap']
-
-if is_jython:
-    import subprocess
-
-    assert subprocess.Popen([sys.executable] + ['-c', quote(cmd), '-mqNxd',
-           quote(tmpeggs), 'zc.buildout' + VERSION],
-           env=dict(os.environ,
-               PYTHONPATH=
-               ws.find(pkg_resources.Requirement.parse('setuptools')).location
-               ),
-           ).wait() == 0
-
-else:
-    assert os.spawnle(
-        os.P_WAIT, sys.executable, quote (sys.executable),
-        '-c', quote (cmd), '-mqNxd', quote (tmpeggs), 'zc.buildout' + VERSION,
-        dict(os.environ,
-            PYTHONPATH=
-            ws.find(pkg_resources.Requirement.parse('setuptools')).location
-            ),
-        ) == 0
-
-ws.add_entry(tmpeggs)
-ws.require('zc.buildout' + VERSION)
-import zc.buildout.buildout
-zc.buildout.buildout.main(args)
-shutil.rmtree(tmpeggs)

=== modified file 'buildout.cfg'
--- buildout.cfg	2010-01-29 16:22:17 +0000
+++ buildout.cfg	2013-01-23 22:26:20 +0000
@@ -1,12 +1,12 @@
 [buildout]
 develop = .
 parts = interpreter test
-extends = http://grok.zope.org/releaseinfo/grok-1.0b1.cfg
+extends = http://svn.zope.org/repos/main/groktoolkit/trunk/grok.cfg
 versions = versions
+extensions = buildout.dumppickedversions
 
 [versions]
-martian = 0.12
-grokcore.component = 
+grokcore.component =
 
 [interpreter]
 recipe = zc.recipe.egg
@@ -16,4 +16,5 @@
 [test]
 recipe = zc.recipe.testrunner
 eggs = grokcore.component
-defaults = ['--tests-pattern', '^f?tests$', '-v']
+       grokcore.component[test]
+defaults = ['--tests-pattern', '^f?tests$', '-v', '--auto-color']

=== modified file 'debian/changelog'
--- debian/changelog	2011-09-11 16:48:22 +0000
+++ debian/changelog	2013-01-23 22:26:20 +0000
@@ -1,3 +1,10 @@
+grokcore.component (2.5-0ubuntu1) raring; urgency=low
+
+  * New upstream release.
+  * Convert to dh_python2 and quilt.
+
+ -- Logan Rosen <[e-mail]>  Wed, 23 Jan 2013 17:14:27 -0500
+
 grokcore.component (2.0-0ubuntu2) oneiric; urgency=low
 
   * Remove langpack.mk; it no longer exists, and this package has no

=== modified file 'debian/control'
--- debian/control	2010-01-29 16:22:17 +0000
+++ debian/control	2013-01-23 22:26:20 +0000
@@ -1,19 +1,16 @@
 Source: grokcore.component
 Section: python
 Priority: extra
-Build-Depends: cdbs (>= 0.4.43),
- debhelper (>= 6),
- python,
- python-central (>= 0.6.5),
+Build-Depends: debhelper (>= 7.0.50~),
+ python (>= 2.6.6-3~),
  python-setuptools (>= 0.6b3)
 Maintainer: Ubuntu Developers <[e-mail]>
 XSBC-Original-Maintainer: Łukasz Czyżykowski <[e-mail]>
-Standards-Version: 3.8.4
+Standards-Version: 3.9.4
 XS-Python-Version: current
 
 Package: python-grokcore.component
 Architecture: all
-XB-Python-Version: ${python:Versions}
 Depends:
  ${misc:Depends},
  ${python:Depends},

=== added directory 'debian/patches'
=== added file 'debian/patches/series'
=== removed file 'debian/pycompat'
--- debian/pycompat	2010-01-29 16:22:17 +0000
+++ debian/pycompat	1970-01-01 00:00:00 +0000
@@ -1,1 +0,0 @@
-2

=== modified file 'debian/rules'
--- debian/rules	2011-09-11 16:48:22 +0000
+++ debian/rules	2013-01-23 22:26:20 +0000
@@ -1,6 +1,3 @@
 #!/usr/bin/make -f
-
-DEB_PYTHON_SYSTEM := pycentral
-
-include /usr/share/cdbs/1/rules/debhelper.mk
-include /usr/share/cdbs/1/class/python-distutils.mk
+%:
+	dh $@ --with python2

=== added directory 'debian/source'
=== added file 'debian/source/format'
--- debian/source/format	1970-01-01 00:00:00 +0000
+++ debian/source/format	2013-01-23 22:26:20 +0000
@@ -0,0 +1,1 @@
+3.0 (quilt)

=== added file 'debian/watch'
--- debian/watch	1970-01-01 00:00:00 +0000
+++ debian/watch	2013-01-23 22:26:20 +0000
@@ -0,0 +1,2 @@
+version=3
+http://pypi.python.org/packages/source/g/grokcore.component/grokcore.component-(.+).tar.gz

=== modified file 'setup.py'
--- setup.py	2010-01-29 16:22:17 +0000
+++ setup.py	2013-01-23 22:26:20 +0000
@@ -10,9 +10,13 @@
     read('CHANGES.txt')
     )
 
+tests_require = [
+    'zope.event',
+    ]
+
 setup(
     name='grokcore.component',
-    version = '2.0',
+    version='2.5',
     author='Grok Team',
     author_email='[e-mail]',
     url='http://grok.zope.org',
@@ -32,11 +36,13 @@
     include_package_data=True,
     zip_safe=False,
     install_requires=['setuptools',
-                      'martian >= 0.12',
+                      'martian >= 0.14',
                       'zope.component',
                       'zope.configuration',
                       'zope.interface',
-                      'zope.event', 
+                      # Note: zope.testing is NOT just a test dependency here.
                       'zope.testing',
                       ],
+    tests_require=tests_require,
+    extras_require={'test': tests_require},
 )

=== modified file 'src/grokcore.component.egg-info/PKG-INFO'
--- src/grokcore.component.egg-info/PKG-INFO	2010-01-29 16:22:17 +0000
+++ src/grokcore.component.egg-info/PKG-INFO	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 Metadata-Version: 1.0
 Name: grokcore.component
-Version: 2.0
+Version: 2.5
 Summary: Grok-like configuration for basic components (adapters, utilities, subscribers)
 Home-page: http://grok.zope.org
 Author: Grok Team
@@ -29,34 +29,34 @@
         we need to make sure it's available to the ZCML machinery.  We do this
         by including the meta configuration from ``grokcore.component``::
         
-        <include package="grokcore.component" file="meta.zcml" />
+          <include package="grokcore.component" file="meta.zcml" />
         
         Put this line somewhere to the top of ``site.zcml``, next to other
         meta configuration includes.  Now, further down the line, we can tell
         the machinery in ``grokcore.component`` to register all components in
         your package (let's say it's called ``helloworld``)::
         
-        <grok:grok package="helloworld" />
+          <grok:grok package="helloworld" />
         
         To sum up, your ``site.zcml`` file should look like something like this::
         
-        <configure
-        xmlns="http://namespaces.zope.org/zope"
-        xmlns:grok="http://namespaces.zope.org/grok">
-        
-        <!-- do the meta configuration to make the ZCML directives available -->
-        <include package="zope.foobar" file="meta.zcml" />
-        <include package="zope.frobnaz" file="meta.zcml" />
-        <include package="grokcore.component" file="meta.zcml" />
-        
-        <!-- now load the configuration of packages that we depend on -->
-        <include package="zope.barfoo" />
-        <include package="zope.somethingorother" />
-        
-        <!-- finally load my components which are based on grokcore.component -->
-        <grok:grok package="helloworld" />
-        
-        </configure>
+          <configure
+              xmlns="http://namespaces.zope.org/zope"
+              xmlns:grok="http://namespaces.zope.org/grok">
+        
+            <!-- do the meta configuration to make the ZCML directives available -->
+            <include package="zope.foobar" file="meta.zcml" />
+            <include package="zope.frobnaz" file="meta.zcml" />
+            <include package="grokcore.component" file="meta.zcml" />
+        
+            <!-- now load the configuration of packages that we depend on -->
+            <include package="zope.barfoo" />
+            <include package="zope.somethingorother" />
+        
+            <!-- finally load my components which are based on grokcore.component -->
+            <grok:grok package="helloworld" />
+        
+          </configure>
         
         Examples
         ========
@@ -67,26 +67,26 @@
         Here's a simple adapter that may be useful in Zope.  It extracts the
         languages that a user prefers from the request::
         
-        import grokcore.component
-        from zope.publisher.interfaces.browser import IBrowserRequest
-        from zope.i18n.interfaces import IUserPreferredLanguages
-        
-        class CookieLanguage(grokcore.component.Adapter):
-        """Extract the preferred language from a cookie"""
-        grokcore.component.context(IBrowserRequest)
-        grokcore.component.implements(IUserPreferredLanguages)
-        
-        # No need to implement __init__, it's already provided by the base class.
-        
-        def getPreferredLanguages(self):
-        # This an adapter for the request, so self.context is the request.
-        request = self.context
-        
-        # Extract the preferred language from a cookie:
-        lang = request.cookies.get('language', 'en')
-        
-        # According to IUserPreferredLanguages, we must return a list.
-        return [lang]
+          import grokcore.component
+          from zope.publisher.interfaces.browser import IBrowserRequest
+          from zope.i18n.interfaces import IUserPreferredLanguages
+        
+          class CookieLanguage(grokcore.component.Adapter):
+              """Extract the preferred language from a cookie"""
+              grokcore.component.context(IBrowserRequest)
+              grokcore.component.implements(IUserPreferredLanguages)
+        
+              # No need to implement __init__, it's already provided by the base class.
+        
+              def getPreferredLanguages(self):
+                  # This an adapter for the request, so self.context is the request.
+                  request = self.context
+        
+                  # Extract the preferred language from a cookie:
+                  lang = request.cookies.get('language', 'en')
+        
+                  # According to IUserPreferredLanguages, we must return a list.
+                  return [lang]
         
         Multi-adapter
         -------------
@@ -97,21 +97,24 @@
         the content object (model), the request and the view that they're
         supposed to be a part of::
         
-        import grokcore.component
-        from zope.publisher.interfaces.browser import IBrowserRequest
-        from zope.publisher.interfaces.browser import IBrowserPage
-        from zope.contentprovider.interfaces import IContentProvider
-        
-        class HelloWorldProvider(grokcore.component.MultiAdapter):
-        """Display Hello World!"""
-        grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)
-        grokcore.component.implements(IContentProvider)
-        
-        def update(self):
-        pass
-        
-        def render(self):
-        return u'<p>Hello World!</p>'
+          import grokcore.component
+          from zope.publisher.interfaces.browser import IBrowserRequest
+          from zope.publisher.interfaces.browser import IBrowserPage
+          from zope.contentprovider.interfaces import IContentProvider
+        
+          class HelloWorldProvider(grokcore.component.MultiAdapter):
+              """Display Hello World!"""
+              grokcore.component.adapts(Interface, IBrowserRequest, IBrowserPage)
+              grokcore.component.implements(IContentProvider)
+        
+              def __init__(self, context, request, view):
+                  pass
+        
+              def update(self):
+                  pass
+        
+              def render(self):
+                  return u'<p>Hello World!</p>'
         
         
         Global utility
@@ -122,24 +125,24 @@
         messages and is invoked when the i18n machinery needs to translate
         something::
         
-        import grokcore.component
-        from zope.i18n.interfaces import ITranslationDomain
-        
-        class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):
-        grokcore.component.implements(ITranslationDomain)
-        grokcore.component.name('helloworld')
-        
-        domain = u'helloworld'
-        
-        def translate(self, msgid, mapping=None, context=None,
-        target_language=None, default=None):
-        if target_language is None:
-        preferred = IUserPreferredLanguages(context)
-        target_language = preferred.getPreferredLanguages()[0]
-        
-        translations = {'de': u'Hallo Welt',
-        'nl': u'Hallo Wereld'}
-        return translations.get(target_language, u'Hello World')
+          import grokcore.component
+          from zope.i18n.interfaces import ITranslationDomain
+        
+          class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):
+              grokcore.component.implements(ITranslationDomain)
+              grokcore.component.name('helloworld')
+        
+              domain = u'helloworld'
+        
+              def translate(self, msgid, mapping=None, context=None,
+                            target_language=None, default=None):
+                  if target_language is None:
+                      preferred = IUserPreferredLanguages(context)
+                      target_language = preferred.getPreferredLanguages()[0]
+        
+                  translations = {'de': u'Hallo Welt',
+                                  'nl': u'Hallo Wereld'}
+                  return translations.get(target_language, u'Hello World')
         
         Of course, it's silly to implement your own translation domain utility
         if there are already implementations available in ``zope.i18n`` (one
@@ -147,18 +150,18 @@
         simple implementation for tests).  Let's try to reuse that
         implementation and register an instance::
         
-        import grokcore.component
-        from zope.i18n.interfaces import ITranslationDomain
-        from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
-        
-        messages = {('de', u'Hello World'): u'Hallo Welt',
-        ('nl', u'Hello World'): u'Hallo Wereld'}
-        helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)
-        
-        grokcore.component.global_utility(helloworld_domain,
-        provides=ITranslationDomain,
-        name='helloworld',
-        direct=True)
+          import grokcore.component
+          from zope.i18n.interfaces import ITranslationDomain
+          from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
+        
+          messages = {('de', u'Hello World'): u'Hallo Welt',
+                      ('nl', u'Hello World'): u'Hallo Wereld'}
+          helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)
+        
+          grokcore.component.global_utility(helloworld_domain,
+                                            provides=ITranslationDomain,
+                                            name='helloworld',
+                                            direct=True)
         
         Global adapter
         --------------
@@ -172,333 +175,265 @@
         example drawing on the ``z3c.form`` library, which provides an adapter factory
         factory for named widget attributes::
         
-        import zope.interface
-        import zope.schema
-        import grokcore.component
-        import z3c.form.widget import ComputedWidgetAttribute
-        
-        class ISchema(Interface):
-        """This schema will be used to power a z3c.form form"""
-        
-        field = zope.schema.TextLine(title=u"Sample field")
-        
-        ...
-        
-        label_override = z3c.form.widget.StaticWidgetAttribute(
-        u"Override label", field=ISchema['field'])
-        
-        grokcore.component.global_adapter(label_override, name=u"label")
+          import zope.interface
+          import zope.schema
+          import grokcore.component
+          import z3c.form.widget import ComputedWidgetAttribute
+        
+          class ISchema(Interface):
+              """This schema will be used to power a z3c.form form"""
+        
+              field = zope.schema.TextLine(title=u"Sample field")
+        
+          ...
+        
+          label_override = z3c.form.widget.StaticWidgetAttribute(
+                                u"Override label", field=ISchema['field'])
+        
+          grokcore.component.global_adapter(label_override, name=u"label")
         
         In the example above, the provided and adapted interfaces are deduced from the
         object returned by the ``StaticWidgetAttribute`` factory. The full syntax
         for global_adapter is::
         
-        global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
+          global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
         
         The factory must be a callable (the adapter factory). Adapted interfaces are
         given as a tuple. You may use a single interface instead of a one-element
         tuple for single adapters. The provided interface is given as shown. The name
         defaults to u"" (an unnamed adapter).
         
-        Subscriber
-        ----------
-        
-        Here we see a subscriber much like it occurs within Zope itself.  It
-        subscribes to the modified event for all annotatable objects (in other
-        words, objects that can have metadata associated with them).  When
-        invoked, it updates the Dublin Core 'Modified' property accordingly::
-        
-        import datetime
-        import grokcore.component
-        from zope.annotation.interfaces import IAnnotatable
-        from zope.lifecycleevent.interfaces import IObjectModifiedEvent
-        from zope.dublincore.interfaces import IZopeDublinCore
-        
-        @grokcore.component.subscribe(IAnnotatable, IObjectModifiedEvent)
-        def updateDublinCoreAfterModification(obj, event):
-        """Updated the Dublin Core 'Modified' property when a modified
-        event is sent for an object."""
-        IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
-        
-        
-        API overview
-        ============
-        
-        Base classes
-        ------------
-        
-        ``Adapter``
-        Base class for an adapter that adapts a single object (commonly
-        referred to as the *context*).  Use the ``context`` directive to
-        specify which object to adapt and the ``implements`` directive to
-        specify which interface the adapter will provide.  If it's a named
-        adapter, you may use the ``name`` directive to specify the name.
-        
-        ``MultiAdapter``
-        Base class for an adapter that adapts *n* objects (where *n>=1*).
-        Use the ``adapts`` directive to specify which kinds of objects are
-        adapted and the ``implements`` directive to specify which
-        interface the adapter will provide.  If it's a named
-        multi-adapter, you may use the ``name`` directive to specify the
-        name.
-        
-        ``GlobalUtility``
-        Base class for a globally registered utility.  Unless you use the
-        ``direct`` directive to indicate that the class itself should be
-        registered as a utility, the class will automatically be
-        instantiated, therefore the constructor may not take any
-        arguments.  Use the ``implements`` directive to specify which
-        interface the utility provides, or if that is not unambiguous,
-        also use the ``provides`` directive to specify which of the
-        implemented interfaces should be used when registering the
-        utility.  If it's a named utility, you may use the ``name``
-        directive to specify the name.
-        
-        ``Context``
-        Subclasses of this will automatically be found as potential
-        contexts for adapters and other types of context-dependent
-        components.
-        
-        
-        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.
+        Handling events
+        ---------------
+        
+        Here we see an event handler much like it occurs within Zope itself. It
+        subscribes to the modified event for all annotatable objects (in other words,
+        objects that can have metadata associated with them). When invoked, it updates
+        the Dublin Core 'Modified' property accordingly::
+        
+          import datetime
+          import grokcore.component
+          from zope.annotation.interfaces import IAnnotatable
+          from zope.lifecycleevent.interfaces import IObjectModifiedEvent
+          from zope.dublincore.interfaces import IZopeDublinCore
+        
+          @grokcore.component.subscribe(IAnnotatable, IObjectModifiedEvent)
+          def updateDublinCoreAfterModification(obj, event):
+              """Updated the Dublin Core 'Modified' property when a modified
+              event is sent for an object."""
+              IZopeDublinCore(obj).modified = datetime.datetime.utcnow()
+        
+        Subscriptions
+        -------------
+        
+        Subscriptions look similar to Adapter, however, unlike regular adapters,
+        subscription adapters are used when we want all of the adapters that adapt an
+        object to a particular adapter.
+        
+        Analogous to MultiAdapter, there is a MultiSubscription component that "adapts"
+        multiple objects.
         
         Changes
         =======
         
+        2.5 (2012-05-01)
+        ----------------
+        
+        - Introduce provideUtility, providerAdapter, provideSubscriptionAdapter,
+          provideHandler and provideInterface in grokcore.component. These by default
+          delegate the registration of components to the global site manager like
+          was done before, but provide the possibility for custom registries for the
+          grokked components.
+        
+        - Fix the `global_adapter` to properly use information annotated by
+          ``grok.adapter``, and using the IContext object if it was not
+          specified. (Fix Launchpad issue #960097).
+        
+        - Add a ``key`` option to ``sort_components`` that behave like ``key``
+          options available on standard Python sort methods.
+        
+        2.4 (2011-04-27)
+        ----------------
+        
+        - Fix the `global_adapter` directive implementation to accept an explicit
+          "empty" name for nameless adapter registrations (as it used to be that
+          providing an empty name in the registration would actually result in
+          registering a named adapter in case the factory has a `grok.name`).
+        
+        2.3 (2011-02-14)
+        ----------------
+        
+        - Implement the generic (Multi)Subscriptions components.
+        
+        2.2 (2010-11-03)
+        ----------------
+        
+        - The default values computation for the context directive and the provides
+          directive is now defined in the directives themselves. This means that where
+          the values for these directives is being retrieved, the "default_context"
+          function does not need to be passed along anymore for general cases.
+        
+          Analogous to this, when getting values for the provides directive the
+          "default_provides" function does not need to be passed along in the general
+          case.
+        
+        2.1 (2010-11-01)
+        ----------------
+        
+        * Made package comply to zope.org repository policy.
+        
+        * Moved directives 'order' from grokcore.viewlet and 'path' from
+          grokcore.view to this very package.
+        
+        * Tiny dependency adjustment: moved zope.event to test dependencies.
+        
+        * Port from 1.x branch exclude parameter to the Grok ZCML directive.
+        
+        * Port from 1.x branch the ignore of testing.py modules.
+        
         2.0 (2009-09-16)
         ----------------
         
         * Use a newer version of Martian that has better support for
-        inheritance.  This is demonstrated in ``tests/inherit``.
+          inheritance.  This is demonstrated in ``tests/inherit``.
         
         * The ``ContextGrokker`` and the ``scan.py`` module have gone away
-        thanks the newer Martian.
+          thanks the newer Martian.
         
         * Directive implementations (in their factory method) should *not*
-        bind directives. Directive binding cannot take place at import time,
-        but only at grok time. Binding directives during import time (when
-        directives are executed) can lead to change problems. (we noticed
-        this during our refactoring to use the new Martian).
+          bind directives. Directive binding cannot take place at import time,
+          but only at grok time. Binding directives during import time (when
+          directives are executed) can lead to change problems. (we noticed
+          this during our refactoring to use the new Martian).
         
         * Use 1.0b1 versions.cfg in Grok's release info instead of a local
-        copy; a local copy for all grokcore packages is just too hard to
-        maintain.
+          copy; a local copy for all grokcore packages is just too hard to
+          maintain.
         
         1.7 (2009-06-01)
         ----------------
         
         * Add missing provider, global_adapter, implementsOnly, classProvides() to
-        the module interface so that they are included in __all__
-        
+          the module interface so that they are included in __all__
         
         1.6 (2009-04-10)
         ----------------
         
         * Add convenience imports for implementsOnly() and classProvides() class
-        declarations form zope.interface.
+          declarations form zope.interface.
         
         * Add support for registering global adapters at module level::
         
-        grok.global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
+            grok.global_adapter(factory, (IAdapted1, IAdapted2,), IProvided, name=u"name")
         
-        Only 'factory' is required. If only a single interface is adapted, the
-        second argument may be a single interface instead of a tuple. If the
-        component has declared adapted/provided interfaces, the second and third
-        arguments may be omitted.
+          Only 'factory' is required. If only a single interface is adapted, the
+          second argument may be a single interface instead of a tuple. If the
+          component has declared adapted/provided interfaces, the second and third
+          arguments may be omitted.
         
         * Add support for an @provider decorator to let a function directly provide
-        an interface::
-        
-        @grok.provider(IFoo, IBar)
-        def some_function():
-        ...
-        
-        This is equivalent to doing alsoProvides(some_function, IFoo, IBar).
+          an interface::
+        
+            @grok.provider(IFoo, IBar)
+            def some_function():
+                ...
+        
+          This is equivalent to doing alsoProvides(some_function, IFoo, IBar).
         
         * Add support for named adapters with the @adapter decorator::
         
-        @grok.adapter(IAdaptedOne, IAdaptedTwo, name=u"foo")
-        def some_function(one, two):
-        ...
+            @grok.adapter(IAdaptedOne, IAdaptedTwo, name=u"foo")
+            def some_function(one, two):
+                ...
         
         1.5.1 (2008-07-28)
         ------------------
         
         * The ``IGrokcoreComponentAPI`` interface was missing declarations for
-        the ``title`` and ``description`` directives.
+          the ``title`` and ``description`` directives.
         
         1.5 (2008-07-22)
         ----------------
         
         * Fix https://bugs.launchpad.net/grok/+bug/242353: grokcore.component
-        contains old-style test setup. There is no `register_all_tests`
-        method in grokcore.component.testing anymore. Use z3c.testsetup
-        instead.
+          contains old-style test setup. There is no `register_all_tests`
+          method in grokcore.component.testing anymore. Use z3c.testsetup
+          instead.
         
         * Allow functions that have been marked with @grok.subscribe also be
-        registered with ``zope.component.provideHandler()`` manually.  This
-        is useful for unit tests where you may not want to grok a whole
-        module.
+          registered with ``zope.component.provideHandler()`` manually.  This
+          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.
+          ``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)
         ----------------
         
         * Ported class grokkers to make use of further improvements in Martian.
-        This requires Martian 0.10.
+          This requires Martian 0.10.
         
         1.3 (2008-05-14)
         ----------------
         
         * Ported class grokkers to make use of the new declarative way of
-        retrieving directive information from a class.  This requires
-        Martian 0.9.6.
+          retrieving directive information from a class.  This requires
+          Martian 0.9.6.
         
         1.2.1 (2008-05-04)
         ------------------
         
         * Upgrade to Martian 0.9.5, which has a slight change in the signature of
-        ``scan_for_classes``.
+          ``scan_for_classes``.
         
         * Remove an unnecessary import ``methods_from_class`` from
-        ``grokcore.component.scan``.
+          ``grokcore.component.scan``.
         
         1.2 (2008-05-04)
         ----------------
         
         * Ported directives to Martian's new directive implementation.  As a
-        result, nearly all helper functions that were available from
-        ``grokcore.component.util`` have been removed.  The functionality is
-        mostly available from the directives themselves now.
+          result, nearly all helper functions that were available from
+          ``grokcore.component.util`` have been removed.  The functionality is
+          mostly available from the directives themselves now.
         
         * The ``baseclass`` directive has been moved to Martian.
         
         * The ``order`` directive and its helper functions have been moved
-        back to Grok, as it was of no general use, but very specific to
-        viewlets.
+          back to Grok, as it was of no general use, but very specific to
+          viewlets.
         
         1.1 (2008-05-03)
         ----------------
         
         * ``determine_module_component`` now looks for classes that implement
-        a certain interface (such as ``IContext``), instead of taking a list
-        of classes.  If looking for ``IContext``, it still will find
-        ``Context`` subclasses, as these were also made to implement
-        ``IContext``.
+          a certain interface (such as ``IContext``), instead of taking a list
+          of classes.  If looking for ``IContext``, it still will find
+          ``Context`` subclasses, as these were also made to implement
+          ``IContext``.
         
         * Move the ``public_methods_from_class`` helper function back to Grok,
-        it isn't used at all in ``grokcore.component``.
+          it isn't used at all in ``grokcore.component``.
         
         1.0.1 (2008-05-02)
         ------------------
         
         * The grokkers for adapters and global utilities did not use the
-        correct value for the *provided* interface in the configuration
-        action discriminator.  Because of this, uninformative and
-        potentially wrong conflict errors would occur, as well as no
-        conflict where a conflict should have occurred.
+          correct value for the *provided* interface in the configuration
+          action discriminator.  Because of this, uninformative and
+          potentially wrong conflict errors would occur, as well as no
+          conflict where a conflict should have occurred.
         
         * The grokker for the ``global_utility()`` directive did immediate
-        registrations instead of generating configuration actions.
-        Therefore it did not provoke ``ConflictErrors`` for conflicting
-        registrations.
+          registrations instead of generating configuration actions.
+          Therefore it did not provoke ``ConflictErrors`` for conflicting
+          registrations.
         
         * Improved documentation
         
@@ -506,8 +441,8 @@
         ----------------
         
         * Created ``grokcore.component`` in March 2008 by factoring basic
-        component base classes and their directives and grokkers out of
-        Grok.
+          component base classes and their directives and grokkers out of
+          Grok.
         
 Platform: UNKNOWN
 Classifier: Intended Audience :: Developers

=== modified file 'src/grokcore.component.egg-info/SOURCES.txt'
--- src/grokcore.component.egg-info/SOURCES.txt	2010-01-29 16:22:17 +0000
+++ src/grokcore.component.egg-info/SOURCES.txt	2013-01-23 22:26:20 +0000
@@ -5,11 +5,9 @@
 LICENSE.txt
 README.txt
 TODO.txt
+bootstrap.py
 buildout.cfg
-setup.cfg
 setup.py
-versions.cfg
-bootstrap/bootstrap.py
 src/grokcore/__init__.py
 src/grokcore.component.egg-info/PKG-INFO
 src/grokcore.component.egg-info/SOURCES.txt
@@ -25,7 +23,9 @@
 src/grokcore/component/interfaces.py
 src/grokcore/component/meta.py
 src/grokcore/component/meta.zcml
+src/grokcore/component/subscription.py
 src/grokcore/component/testing.py
+src/grokcore/component/util.py
 src/grokcore/component/zcml.py
 src/grokcore/component/templates/default_display_form.pt
 src/grokcore/component/templates/default_edit_form.pt
@@ -89,6 +89,24 @@
 src/grokcore/component/tests/inherit/__init__.py
 src/grokcore/component/tests/inherit/inherit.py
 src/grokcore/component/tests/inherit/inherit_fixture.py
+src/grokcore/component/tests/order/__init__.py
+src/grokcore/component/tests/order/arg_orderdirective.py
+src/grokcore/component/tests/order/combined_orderdirective.py
+src/grokcore/component/tests/order/combinednoorder_orderdirective.py
+src/grokcore/component/tests/order/inter1.py
+src/grokcore/component/tests/order/inter2.py
+src/grokcore/component/tests/order/noarg_orderdirective.py
+src/grokcore/component/tests/order/nodirective.py
+src/grokcore/component/tests/subscriptions/__init__.py
+src/grokcore/component/tests/subscriptions/decorator.py
+src/grokcore/component/tests/subscriptions/multisubscriptions.py
+src/grokcore/component/tests/subscriptions/multisubscriptions_no_adapts.py
+src/grokcore/component/tests/subscriptions/multisubscriptions_no_interface.py
+src/grokcore/component/tests/subscriptions/ordered_multisubscriptions.py
+src/grokcore/component/tests/subscriptions/ordered_subscriptions.py
+src/grokcore/component/tests/subscriptions/subscriptions.py
+src/grokcore/component/tests/subscriptions/subscriptions_no_context.py
+src/grokcore/component/tests/subscriptions/subscriptions_no_interface.py
 src/grokcore/component/tests/utility/__init__.py
 src/grokcore/component/tests/utility/conflict.py
 src/grokcore/component/tests/utility/implementsmany.py

=== modified file 'src/grokcore.component.egg-info/requires.txt'
--- src/grokcore.component.egg-info/requires.txt	2010-01-29 16:22:17 +0000
+++ src/grokcore.component.egg-info/requires.txt	2013-01-23 22:26:20 +0000
@@ -1,7 +1,9 @@
 setuptools
-martian >= 0.12
+martian >= 0.14
 zope.component
 zope.configuration
 zope.interface
-zope.event
-zope.testing
\ No newline at end of file
+zope.testing
+
+[test]
+zope.event
\ No newline at end of file

=== modified file 'src/grokcore/component/__init__.py'
--- src/grokcore/component/__init__.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/__init__.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006-2007 Zope Corporation and Contributors.
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -14,17 +14,60 @@
 """Grok
 """
 
+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 zope.component import adapts
 
+from martian import baseclass
+from martian.error import GrokError, GrokImportError
 from martian import ClassGrokker, InstanceGrokker, GlobalGrokker
-from grokcore.component.components import Adapter, GlobalUtility, MultiAdapter, Context
-
-from martian import baseclass
+
+from grokcore.component.components import (
+    Adapter,
+    Context,
+    GlobalUtility,
+    MultiAdapter,
+    MultiSubscription,
+    Subscription,
+    )
+
 from grokcore.component.directive import (
-    context, name, title, description, provides, global_utility, global_adapter, direct)
-from grokcore.component.decorators import subscribe, adapter, implementer, provider
-from martian.error import GrokError, GrokImportError
+    context,
+    description,
+    direct,
+    global_adapter,
+    global_utility,
+    name,
+    order,
+    path,
+    provides,
+    title,
+    )
+
+from grokcore.component.decorators import (
+    adapter,
+    implementer,
+    provider,
+    subscribe,
+    )
+
+from grokcore.component.subscription import (
+    queryMultiSubscriptions,
+    queryOrderedMultiSubscriptions,
+    queryOrderedSubscriptions,
+    querySubscriptions,
+    )
+
+from grokcore.component.util import (
+    getSiteManager,
+    provideAdapter,
+    provideHandler,
+    provideInterface,
+    provideSubscriptionAdapter,
+    provideUtility,
+    sort_components,
+    )
 
 # Import this module so that it's available as soon as you import the
 # 'grokcore.component' package.  Useful for tests and interpreter examples.

=== modified file 'src/grokcore/component/components.py'
--- src/grokcore/component/components.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/components.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006-2007 Zope Corporation and Contributors.
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -17,15 +17,96 @@
 
 from grokcore.component.interfaces import IContext
 
+
 class Adapter(object):
+    """Base class for an adapter that adapts a single object (commonly referred
+    to as the *context*).
+
+    Use the ``context`` directive to specify which object to adapt and the
+    ``implements`` directive to specify which interface the adapter will
+    provide. If it's a named adapter, you may use the ``name`` directive to
+    specify the name.
+
+    .. attribute:: context
+
+       The adapted object.
+
+    """
+
     def __init__(self, context):
         self.context = context
 
+
+class MultiAdapter(object):
+    """Base class for an adapter that adapts *n* objects (where *n>=1*).
+
+    Use the ``adapts`` directive to specify which kinds of objects are adapted
+    and the ``implements`` directive to specify which interface the adapter
+    will provide. If it's a named multi-adapter, you may use the ``name``
+    directive to specify the name.
+
+    Note that contrary to the Adapter, the MultiAdapter base class does not
+    provide an `__init__` method. An `__init__` needs to accept the same number
+    of arguments as are used in the `adapts` directive.
+
+    """
+    pass
+
+
 class GlobalUtility(object):
-    pass
-
-class MultiAdapter(object):
-    pass
+    """Base class to define a globally registered utility.
+
+    Base class for a globally registered utility. Unless you use the ``direct``
+    directive to indicate that the class itself should be registered as a
+    utility, the class will automatically be instantiated, therefore the
+    constructor may not take any arguments. Use the ``implements`` directive to
+    specify which interface the utility provides, or if that is not
+    unambiguous, also use the ``provides`` directive to specify which of the
+    implemented interfaces should be used when registering the utility. If it's
+    a named utility, you may use the ``name`` directive to specify the name.
+
+    """
+    pass
+
+
+class Subscription(object):
+    """Base class for a subscription adapter.
+
+    Subscriptions are similar to adapters, except that it is possible to
+    register multiple unnamed subscriptions for identical ``context`` and
+    ``provides``.
+
+    Use the ``context`` directive to explicitly set the interface to adapt
+    from. When omitted the current context is assumed. Use the ``implements``
+    directive to specify which interface the subscription provides, or if that
+    is not unambiguous, also use the ``provides`` directive to specify which of
+    the implemented interfaces should be used when registering the subscription.
+
+    """
+
+    def __init__(self, context):
+        self.context = context
+
+
+class MultiSubscription(object):
+    """Base class for a subscription multi-adapter.
+
+    MultiSubscriptions are similar to multi adapters, except that it is
+    possible to register multiple unnamed subscriptions for identical
+    ``adapts`` and ``provides``.
+
+    Use the ``adapts`` directive to explicitly set the multiple interfaces to
+    adapt from. Use the ``implements`` directive to specify which interface the
+    subscription provides, or if that is not unambiguous, also use the
+    ``provides`` directive to specify which of the implemented interfaces
+    should be used when registering the multi subscription.
+
+    """
+
 
 class Context(object):
+    """Subclasses of this will automatically be found as potential contexts for
+    adapters and other types of context-dependent components.
+
+    """
     implements(IContext)

=== modified file 'src/grokcore/component/decorators.py'
--- src/grokcore/component/decorators.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/decorators.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006 Zope Corporation and Contributors.
+# Copyright (c) 2006 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -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
 
@@ -37,17 +44,25 @@
             raise GrokImportError("@grok.subscribe requires at least one "
                                   "argument.")
 
+        # Add the function and subscribed interfaces to the
+        # grok.subscribers module annotation.
         subscribers = frame.f_locals.get('__grok_subscribers__', None)
         if subscribers is None:
             frame.f_locals['__grok_subscribers__'] = subscribers = []
         subscribers.append((function, self.subscribed))
 
-        # Also add __grok_adapts__ attribute to the function so that
-        # you can manually register the subscriber with, say,
-        # provideHandler.
+        # Also store the subscribed interfaces on the
+        # attribute__component_adapts__ for provideHandler to register
+        # the subscriber (in case you don't grok your package and
+        # register it manually)
         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
@@ -59,18 +74,18 @@
         if type(interfaces[0]) is types.FunctionType:
             raise GrokImportError(
                 "@grok.adapter requires at least one argument.")
-        
+
         self.name = u""
-        
+
         if kw:
             if 'name' in kw:
                 self.name = kw.pop('name')
             if kw:
                 raise GrokImportError(
                     "@grok.adapter got unexpected keyword arguments: %s" % ','.join(kw.keys()))
-        
+
         zope.component.adapter.__init__(self, *interfaces)
-    
+
     def __call__(self, ob):
         ob = zope.component.adapter.__call__(self, ob)
         if self.name:
@@ -78,6 +93,13 @@
         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
@@ -87,10 +109,16 @@
         if adapters is None:
             frame.f_locals['__grok_adapters__'] = adapters = []
         adapters.append(ob)
+
         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 file 'src/grokcore/component/directive.py'
--- src/grokcore/component/directive.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/directive.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006-2007 Zope Corporation and Contributors.
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -14,11 +14,28 @@
 """Grok directives.
 """
 import martian
-import grokcore.component
+import martian.util
+from martian.error import GrokError, GrokImportError
+from martian.util import scan_for_classes
+from zope import interface
 from zope.interface.interfaces import IInterface
-from martian.error import GrokImportError
+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):
@@ -29,14 +46,34 @@
         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 determined 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''):
+    def factory(self, factory, adapts=None, provides=None, name=None):
         if provides is not None and not IInterface.providedBy(provides):
             raise GrokImportError(
                 "You can only pass an interface to the "
                 "provides argument of %s." % self.name)
-        if not isinstance(adapts, (list, tuple,)):
+        if adapts is None:
+            adapts = getattr(factory, '__component_adapts__', None)
+        elif not isinstance(adapts, (list, tuple,)):
             adapts = (adapts,)
         elif isinstance(adapts, list):
             adapts = tuple(adapts)
@@ -44,17 +81,49 @@
         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''
-    validate = martian.validateText
 
 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
 
+    @classmethod
+    def get_default(cls, component, module=None, **data):
+        components = list(scan_for_classes(module, IContext))
+        if len(components) == 0:
+            raise GrokError(
+                "No module-level context for %r, please use the 'context' "
+                "directive." % (component), component)
+        elif len(components) == 1:
+            component = components[0]
+        else:
+            raise GrokError(
+                "Multiple possible contexts for %r, please use the 'context' "
+                "directive."
+                % (component), component)
+        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
@@ -63,9 +132,41 @@
     pass
 
 class direct(martian.MarkerDirective):
-    scope = martian.CLASS
+    """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):
+    scope = martian.CLASS
+    store = martian.ONCE
+    default = 0, 0
+
+    _order = 0
+
+    def factory(self, value=0):
+        order._order += 1
+        return value, order._order
+
+class path(martian.Directive):
+    scope = martian.CLASS
+    store = martian.ONCE
+    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
+
+    @classmethod
+    def get_default(cls, component, module, **data):
+        martian.util.check_implements_one(component)
+        return list(interface.implementedBy(component))[0]

=== modified file 'src/grokcore/component/interfaces.py'
--- src/grokcore/component/interfaces.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/interfaces.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2008 Zope Corporation and Contributors.
+# Copyright (c) 2008 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -34,16 +34,24 @@
 
 
 class IBaseClasses(Interface):
+    Adapter = Attribute("Base class for adapters.")
 
     ClassGrokker = Attribute("Base class to define a class grokker.")
+
+    Context = Attribute("Base class for automatically associated contexts.")
+
+    GlobalGrokker = Attribute("Base class to define a module grokker.")
+
+    GlobalUtility = Attribute("Base class for global utilities.")
+
     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.")
+
+    MultiSubscription = Attribute(
+        "Base class for subscription mult-adapters.")
+
+    Subscription = Attribute("Base class for subscription adapters.")
 
 
 class IDirectives(Interface):
@@ -57,13 +65,13 @@
 
     def implements(*interfaces):
         """Declare that a class implements the given interfaces."""
-    
+
     def implementsOnly(*interfaces):
         """Declare that a class implements only the given interfaces.
-        
+
         Interfaces implemented by base classes are explicitly not inherited.
         """
-    
+
     def classProvides(*interfaces):
         """Declare that a class (as opposed to instances of the class)
         directly provides the given interfaces.
@@ -130,6 +138,25 @@
         utility, or an instance of it.
         """
 
+    def order(value=None):
+        """Control the ordering of components.
+
+        If the value is specified, the order will be determined by sorting on
+        it.
+        If no value is specified, the order will be determined by definition
+        order within the module.
+        If the directive is absent, the order will be determined by class name.
+        (unfortunately our preferred default behavior on absence which would
+        be like grok.order() without argument is hard to implement in Python)
+
+        Inter-module order is by dotted name of the module the
+        components are in; unless an explicit argument is specified to
+        ``grok.order()``, components are grouped by module.
+
+        The function grok.util.sort_components can be used to sort
+        components according to these rules.
+        """
+
 
 class IDecorators(Interface):
 
@@ -146,7 +173,7 @@
         """Describes that a function that's used as an adapter
         implements an interface or a number of interfaces.
         """
-    
+
     def provider(*interfaces):
         """Describes that a function directly provides an interface or a
         number of interfaces.
@@ -164,15 +191,49 @@
 
 
 class IMartianAPI(Interface):
-    """Part of Martian's API exposed by grokcore.component."""
-
-    # This should probably move to martian at some point.
+    """Part of Martian's API exposed by grokcore.component.
+    """
 
     ClassGrokker = Attribute("Grokker for classes.")
+
+    GlobalGrokker = Attribute("Grokker that's invoked for a module.")
+
     InstanceGrokker = Attribute("Grokker for instances.")
-    GlobalGrokker = Attribute("Grokker that's invoked for a module.")
-
-
-class IGrokcoreComponentAPI(IBaseClasses, IDirectives, IDecorators,
-                            IGrokErrors, IMartianAPI):
-    """grokcore.component's public API."""
+
+
+class IGrokcoreComponentAPI(
+    IBaseClasses,
+    IDecorators,
+    IDirectives,
+    IGrokErrors,
+    IMartianAPI,
+    ):
+    """grokcore.component's public API.
+    """
+
+    getSiteManager = Attribute('Get the site manager for the nearest site.')
+
+    provideAdapter = Attribute('Registers an adapters')
+
+    provideHandler = Attribute('Registers an handler')
+
+    provideInterface = Attribute('Regsiters an interfaces as a utility')
+
+    provideSubscriptionAdapter = Attribute(
+        'Registers an subscriptions adapter')
+
+    provideUtility = Attribute('Registers an utility')
+
+    querySubscriptions = Attribute("Function to query subscriptions.")
+
+    queryOrderedSubscriptions = Attribute(
+        "Function to query subscription in order.")
+
+    queryMultiSubscriptions = Attribute("Function to query subscriptions.")
+
+    queryOrderedMultiSubscriptions = Attribute(
+        "Function to query subscriptions in order.")
+
+    sort_components = Attribute(
+        'Sort a list of components using the information provided by '
+        '`grok.order`.')

=== modified file 'src/grokcore/component/meta.py'
--- src/grokcore/component/meta.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/meta.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 #############################################################################
 #
-# Copyright (c) 2006-2007 Zope Corporation and Contributors.
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -13,56 +13,37 @@
 ##############################################################################
 """Grokkers for the various components."""
 
+import operator
+
 import martian
 import martian.util
 import grokcore.component
 import zope.component.interface
-
 from zope import component, interface
 from martian.error import GrokError
-from martian.util import scan_for_classes
-
-from grokcore.component.interfaces import IContext
-
-
-def default_provides(factory, module=None, **data):
-    martian.util.check_implements_one(factory)
-    return list(interface.implementedBy(factory))[0]
-
-def default_global_utility_provides(factory, module, direct, **data):
+from zope.interface import implementedBy
+
+def _provides(component, module=None, **data):
+    martian.util.check_implements_one(component)
+    return list(interface.implementedBy(component))[0]
+
+def default_global_utility_provides(component, module, direct, **data):
     if direct:
-        martian.util.check_provides_one(factory)
-        return list(interface.providedBy(factory))[0]
-    return default_provides(factory)
+        martian.util.check_provides_one(component)
+        return list(interface.providedBy(component))[0]
+    return _provides(component)
 
-def default_context(factory, module, **data):
-    components = list(scan_for_classes(module, IContext))
-    if len(components) == 0:
-        raise GrokError(
-            "No module-level context for %r, please use the 'context' "
-            "directive." % (factory), factory)
-    elif len(components) == 1:
-        component = components[0]
-    else:
-        raise GrokError(
-            "Multiple possible contexts for %r, please use the 'context' "
-            "directive."
-            % (factory), factory)
-    return component
 
 class AdapterGrokker(martian.ClassGrokker):
     martian.component(grokcore.component.Adapter)
+    martian.directive(grokcore.component.context)
+    martian.directive(grokcore.component.provides)
+    martian.directive(grokcore.component.name)
 
-    martian.directive(grokcore.component.context,
-                      get_default=default_context)
-    martian.directive(grokcore.component.provides,
-                      get_default=default_provides)
-    martian.directive(grokcore.component.name)
-    
     def execute(self, factory, config, context, provides, name, **kw):
         config.action(
             discriminator=('adapter', context, provides, name),
-            callable=component.provideAdapter,
+            callable=grokcore.component.provideAdapter,
             args=(factory, (context,), provides, name),
             )
         return True
@@ -70,26 +51,59 @@
 
 class MultiAdapterGrokker(martian.ClassGrokker):
     martian.component(grokcore.component.MultiAdapter)
-
-    martian.directive(grokcore.component.provides,
-                      get_default=default_provides)
+    martian.directive(grokcore.component.provides)
     martian.directive(grokcore.component.name)
 
     def execute(self, factory, config, provides, name, **kw):
-        if component.adaptedBy(factory) is None:
-            raise GrokError("%r must specify which contexts it adapts "
-                            "(use the 'adapts' directive to specify)."
-                            % factory, factory)
         for_ = component.adaptedBy(factory)
+        if for_ is None:
+            raise GrokError("%r must specify which contexts it adapts "
+                            "(use the 'adapts' directive to specify)."
+                            % factory, factory)
 
         config.action(
             discriminator=('adapter', for_, provides, name),
-            callable=component.provideAdapter,
+            callable=grokcore.component.provideAdapter,
             args=(factory, None, provides, name),
             )
         return True
 
 
+class SubscriptionGrokker(martian.ClassGrokker):
+    martian.component(grokcore.component.Subscription)
+    martian.directive(grokcore.component.context)
+    martian.directive(grokcore.component.provides)
+    martian.directive(grokcore.component.name)
+
+    def execute(self, factory, config, context, provides, name, **kw):
+        config.action(
+            discriminator=None,
+            callable=grokcore.component.provideSubscriptionAdapter,
+            args=(factory, (context,), provides),
+            )
+        return True
+
+
+class MultiSubscriptionGrokker(martian.ClassGrokker):
+    martian.component(grokcore.component.MultiSubscription)
+    martian.directive(grokcore.component.provides)
+    martian.directive(grokcore.component.name)
+
+    def execute(self, factory, config, provides, name, **kw):
+        adapts = component.adaptedBy(factory)
+        if adapts is None:
+            raise GrokError("%r must specify which contexts it adapts "
+                            "(use the 'adapts' directive to specify)."
+                            % factory, factory)
+
+        config.action(
+            discriminator=None,
+            callable=grokcore.component.provideSubscriptionAdapter,
+            args=(factory, adapts, provides),
+            )
+        return True
+
+
 class GlobalUtilityGrokker(martian.ClassGrokker):
     martian.component(grokcore.component.GlobalUtility)
 
@@ -108,30 +122,38 @@
 
         config.action(
             discriminator=('utility', provides, name),
-            callable=component.provideUtility,
+            callable=grokcore.component.provideUtility,
             args=(factory, provides, name),
             )
         return True
 
-class AdapterDecoratorGrokker(martian.GlobalGrokker):
+
+class ImplementerDecoratorGrokker(martian.GlobalGrokker):
 
     def grok(self, name, module, module_info, config, **kw):
         adapters = module_info.getAnnotation('grok.adapters', [])
+        subscribers = set(map(operator.itemgetter(0),
+                              module_info.getAnnotation('grok.subscribers', [])))
+
         for function in adapters:
+            if function in subscribers:
+                # We don't register functions that are decorated with
+                # grok.implementer() *and* the grok.subscribe()
+                # decorator. These are registered as so called
+                # subcribers and not as regular adapters.
+                continue
             interfaces = getattr(function, '__component_adapts__', None)
             if interfaces is None:
-                context = grokcore.component.context.bind(
-                    get_default=default_context).get(module)
+                context = grokcore.component.context.bind().get(module)
                 interfaces = (context, )
             name = getattr(function, '__component_name__', u"")
             config.action(
                 discriminator=('adapter', interfaces, function.__implemented__, name),
-                callable=component.provideAdapter,
+                callable=grokcore.component.provideAdapter,
                 args=(function, interfaces, function.__implemented__, name),
                 )
         return True
 
-
 class GlobalUtilityDirectiveGrokker(martian.GlobalGrokker):
 
     def grok(self, name, module, module_info, config, **kw):
@@ -141,7 +163,8 @@
             if direct is None:
                 direct = grokcore.component.direct.bind().get(factory)
             if provides is None:
-                provides = grokcore.component.provides.bind().get(factory)
+                bound = grokcore.component.provides.bind(default=None)
+                provides = bound.get(factory)
             if not name:
                 name = grokcore.component.name.bind().get(factory)
 
@@ -153,55 +176,68 @@
             else:
                 obj = factory()
                 if provides is None:
-                    provides = default_provides(factory)
+                    provides = _provides(factory)
 
             config.action(
                 discriminator=('utility', provides, name),
-                callable=component.provideUtility,
+                callable=grokcore.component.provideUtility,
                 args=(obj, provides, name),
                 )
 
         return True
 
+
 class GlobalAdapterDirectiveGrokker(martian.GlobalGrokker):
 
     def grok(self, name, module, module_info, config, **kw):
         infos = grokcore.component.global_adapter.bind().get(module)
         for factory, adapts, provides, name in infos:
             if provides is None:
-                provides = grokcore.component.provides.bind().get(factory)
+                bound = grokcore.component.provides.bind(default=None)
+                provides = bound.get(factory)
             if adapts is None:
-                adapts = getattr(factory, '__component_adapts__', None)
-                if adapts is None:
-                    adapts = grokcore.component.context.bind(
-                        get_default=default_context).get(factory)
-            if not name:
+                adapts = (grokcore.component.context.bind().get(module),)
+            if name is None:
                 name = grokcore.component.name.bind().get(factory)
-            
+
             config.action(
                 discriminator=('adapter', adapts, provides, name),
-                callable=component.provideAdapter,
+                callable=grokcore.component.provideAdapter,
                 args=(factory, adapts, provides, name),
                 )
 
         return True
 
-class SubscriberGrokker(martian.GlobalGrokker):
+
+class SubscriberDirectiveGrokker(martian.GlobalGrokker):
 
     def grok(self, name, module, module_info, config, **kw):
         subscribers = module_info.getAnnotation('grok.subscribers', [])
 
         for factory, subscribed in subscribers:
-            config.action(
-                discriminator=None,
-                callable=component.provideHandler,
-                args=(factory, subscribed),
-                )
+            provides = None
+            implemented = list(implementedBy(factory))
+            if len(implemented) == 1:
+                provides = implemented[0]
+            # provideHandler is essentially the same as
+            # provideSubscriptionAdapter, where provided=None. However,
+            # handlers and subscription adapters are tracked in
+            # separately so we cannot exchange one registration call
+            # for the the other.
+            if provides is None:
+                config.action(
+                    discriminator=None,
+                    callable=grokcore.component.provideHandler,
+                    args=(factory, subscribed))
+            else:
+                config.action(
+                    discriminator=None,
+                    callable=grokcore.component.provideSubscriptionAdapter,
+                    args=(factory, subscribed, provides))
 
             for iface in subscribed:
                 config.action(
                     discriminator=None,
-                    callable=zope.component.interface.provideInterface,
-                    args=('', iface)
-                    )
+                    callable=grokcore.component.provideInterface,
+                    args=('', iface))
         return True

=== added file 'src/grokcore/component/subscription.py'
--- src/grokcore/component/subscription.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/subscription.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,41 @@
+##############################################################################
+#
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Grok subscriptions functions.
+"""
+from zope import component
+from grokcore.component import util
+
+def queryOrderedMultiSubscriptions(components, interface):
+    return util.sort_components(component.subscribers(components, interface))
+
+def queryOrderedSubscriptions(component, interface):
+    return queryOrderedMultiSubscriptions((component, ), interface)
+
+def queryMultiSubscriptions(components, interface):
+    """Query for subscriptions on the `components` providing `interface`.
+
+    :parameter components: tuple of components to lookup the subscription for.
+    :parameter interface: interface that the subscriptions should provide.
+    :return: a list of subscriptions.
+    """
+    return component.subscribers(components, interface)
+
+def querySubscriptions(component, interface):
+    """Query for subscriptions on `component` providing `interface`.
+
+    :parameter component: a component to lookup the subscriptions for.
+    :parameter interface: interface that the subscriptions should provide.
+    :return: a list of subscription.
+    """
+    return queryMultiSubscriptions((component,), interface)

=== modified file 'src/grokcore/component/testing.py'
--- src/grokcore/component/testing.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/testing.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2007 Zope Corporation and Contributors.
+# Copyright (c) 2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,

=== modified file 'src/grokcore/component/tests/adapter/globaladapter.py'
--- src/grokcore/component/tests/adapter/globaladapter.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/tests/adapter/globaladapter.py	2013-01-23 22:26:20 +0000
@@ -1,77 +1,103 @@
 """
   >>> grok.testing.grok(__name__)
   >>> from zope.component import getAdapter, getMultiAdapter
-  
+
   >>> cave = Cave()
   >>> fireplace = Fireplace()
-  
+
   >>> home = IHome(cave)
   >>> home.id
   u'one'
-  
+
   >>> home = getAdapter(cave, IHome, name=u"two")
   >>> home.id
   u'two'
-  
+
   >>> home = getAdapter(cave, IHome, name=u"three")
   >>> home.id
   u'three'
-  
+
   >>> home = getAdapter(cave, IHome, name=u"four")
   >>> home.id
   u'four'
-  
+
   >>> home = getAdapter(fireplace, IHome, name=u"five")
   >>> home.id
   u'five'
-  
+
   >>> home = getMultiAdapter((cave, fireplace), IHome)
   >>> home.id
   u'six'
-  
+
+  >>> home = getAdapter(fireplace, IHome, name=u'seven')
+  >>> home.id
+  u'seven-a'
+
+  >>> home = getMultiAdapter((cave, fireplace), IHome, name=u'seven')
+  >>> home.id
+  u'seven-b'
+
+  >>> garage = getAdapter(cave, IGarage, name='named_garage_factory_name')
+  >>> garage.id
+  u"I'm a garage"
+
+  >>> garage = getAdapter(cave, IGarage)
+  >>> garage.id
+  u"I'm a garage"
+
 """
 
 import grokcore.component as grok
 from zope import interface
 from zope.interface import implementer
 
+
 class Cave(grok.Context):
     pass
 
+
 class Fireplace(object):
     pass
 
+
 class IHome(interface.Interface):
     pass
 
+
 class Home(object):
     grok.implements(IHome)
-    
+
     def __init__(self, id):
         self.id = id
 
+
 class CaveHomeFactory(object):
     grok.implements(IHome)
-    
+
     def __init__(self, id):
         self.id = id
-    
+
     def __call__(self, context):
         return Home(self.id)
 
+
 class CaveFireplaceHomeFactory(object):
+
     def __init__(self, id):
         self.id = id
-    
+
     def __call__(self, cave, fireplace):
         return Home(self.id)
 
+
 factory1 = CaveHomeFactory(u"one")
 factory2 = CaveHomeFactory(u"two")
 factory3 = CaveHomeFactory(u"three")
 factory4 = CaveHomeFactory(u"four")
 factory5 = CaveHomeFactory(u"five")
 factory6 = CaveFireplaceHomeFactory(u"six")
+factory7a = CaveHomeFactory(u"seven-a")
+factory7b = CaveFireplaceHomeFactory(u"seven-b")
 
 # make some direct assertions
 
@@ -79,12 +105,45 @@
 implementer(IHome)(factory4)
 implementer(IHome)(factory5)
 implementer(IHome)(factory6)
+implementer(IHome)(factory7a)
+implementer(IHome)(factory7b)
 
 grok.adapter(Fireplace)(factory5)
-
-grok.global_adapter(factory1, Cave, IHome)                  # should accept single value for adapts
-grok.global_adapter(factory2, (Cave,), IHome, name="two")   # should accept tuple for adapts
-grok.global_adapter(factory3, Cave, name="three")           # should look at the provided interface
-grok.global_adapter(factory4, name=u"four")                 # should pick the canonical context
-grok.global_adapter(factory5, name="five")                  # should use __component_adapts__
-grok.global_adapter(factory6, (Cave, Fireplace,))           # should work as multi-adapter
+grok.adapter(Fireplace)(factory7a)
+grok.adapter(Cave, Fireplace)(factory7b)
+
+# should accept single value for adapts
+grok.global_adapter(factory1, Cave, IHome)
+# should accept tuple for adapts
+grok.global_adapter(factory2, (Cave,), IHome, name=u"two")
+# should look at the provided interface
+grok.global_adapter(factory3, Cave, name=u"three")
+# should pick the canonical context
+grok.global_adapter(factory4, name=u"four")
+# should use __component_adapts__
+grok.global_adapter(factory5, name=u"five")
+# should work as multi-adapter
+grok.global_adapter(factory6, (Cave, Fireplace,))
+# should use __component_adapts__ adapting one object
+grok.global_adapter(factory7a, name=u"seven")
+# should use __component_adapts__ adaping two objects
+grok.global_adapter(factory7b, name=u"seven")
+
+
+class IGarage(interface.Interface):
+    pass
+
+
+class NamedGarageFactory(object):
+    grok.implements(IGarage)
+    grok.name('named_garage_factory_name')
+
+    def __init__(self, context):
+        self.id = u"I'm a garage"
+
+implementer(IGarage)(NamedGarageFactory)
+
+# should register a named adapter
+grok.global_adapter(NamedGarageFactory, Cave, IGarage)
+# should override component's name
+grok.global_adapter(NamedGarageFactory, Cave, IGarage, name=u'')

=== modified file 'src/grokcore/component/tests/adapter/nomodel.py'
--- src/grokcore/component/tests/adapter/nomodel.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/tests/adapter/nomodel.py	2013-01-23 22:26:20 +0000
@@ -5,7 +5,8 @@
   Traceback (most recent call last):
     ...
   GrokError: No module-level context for
-  <class 'grokcore.component.tests.adapter.nomodel.Home'>, please use the 'context' directive.
+  <class 'grokcore.component.tests.adapter.nomodel.Home'>, please use the
+  'context' directive.
 
 """
 import grokcore.component as grok

=== modified file 'src/grokcore/component/tests/event/subscriber.py'
--- src/grokcore/component/tests/event/subscriber.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/tests/event/subscriber.py	2013-01-23 22:26:20 +0000
@@ -8,9 +8,9 @@
   ['Manfred']
   >>> mammoths2
   ['Manfred']
-  
-The decorated event handling function can also be called directly:  
-  
+
+The decorated event handling function can also be called directly:
+
   >>> mammothAdded(Mammoth('Max'),None)
   >>> mammoths
   ['Manfred', 'Max']

=== added directory 'src/grokcore/component/tests/order'
=== added file 'src/grokcore/component/tests/order/__init__.py'
--- src/grokcore/component/tests/order/__init__.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/__init__.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,1 @@
+#

=== added file 'src/grokcore/component/tests/order/arg_orderdirective.py'
--- src/grokcore/component/tests/order/arg_orderdirective.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/arg_orderdirective.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,42 @@
+"""
+If the grok.order directive is present with arguments, sorting will be
+done by the order specified.
+
+  >>> from grokcore.component import sort_components
+
+  >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
+  >>> sort_components(components)
+  [<...Fifth object at ...>,
+   <...Fourth object at ...>,
+   <...Third object at ...>,
+   <...Second object at ...>,
+   <...First object at ...>]
+
+You can use the key option:
+
+  >>> from operator import itemgetter
+
+  >>> components = [(1, First()), (2, Second()), (3, Third())]
+  >>> sort_components(components, key=itemgetter(1))
+  [(3, <...Third object at ...>),
+   (2, <...Second object at ...>),
+   (1, <...First object at ...>)]
+
+"""
+
+import grokcore.component as grok
+
+class First(object):
+    grok.order(5)
+
+class Second(object):
+    grok.order(4)
+
+class Third(object):
+    grok.order(3)
+
+class Fourth(object):
+    grok.order(2)
+
+class Fifth(object):
+    grok.order(1)

=== added file 'src/grokcore/component/tests/order/combined_orderdirective.py'
--- src/grokcore/component/tests/order/combined_orderdirective.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/combined_orderdirective.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,34 @@
+"""
+
+If the grok.order directive is specified with other classes that don't
+have the order specified, then the order will be determined by first
+sorting on the order specified, and then by the definition order.
+
+  >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
+
+  >>> from grokcore.component import sort_components
+  >>> sort_components(components)
+  [<...Third object at ...>,
+   <...Fourth object at ...>,
+   <...Second object at ...>,
+   <...Fifth object at ...>,
+   <...First object at ...>]
+
+"""
+
+import grokcore.component as grok
+
+class First(object):
+    grok.order(2)
+
+class Second(object):
+    grok.order(1)
+
+class Third(object):
+    grok.order()
+
+class Fourth(object):
+    grok.order()
+
+class Fifth(object):
+    grok.order(1)

=== added file 'src/grokcore/component/tests/order/combinednoorder_orderdirective.py'
--- src/grokcore/component/tests/order/combinednoorder_orderdirective.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/combinednoorder_orderdirective.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,34 @@
+"""
+
+If the grok.order directive is specified with other classes that don't
+have the order specified, then the order will be determined by first
+sorting on the order specified, and then by the definition order.
+
+  >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
+
+  >>> from grokcore.component import sort_components
+  >>> sort_components(components)
+  [<...Fifth object at ...>,
+   <...Third object at ...>,
+   <...First object at ...>,
+   <...Fourth object at ...>,
+   <...Second object at ...>]
+
+"""
+
+import grokcore.component as grok
+
+class First(object):
+    grok.order()
+
+class Second(object):
+    grok.order(1)
+
+class Third(object):
+    pass
+
+class Fourth(object):
+    grok.order()
+
+class Fifth(object):
+    pass

=== added file 'src/grokcore/component/tests/order/inter1.py'
--- src/grokcore/component/tests/order/inter1.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/inter1.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,35 @@
+"""
+
+The ordering works like so:
+1. Objects with explicit ordering
+   (if combined with objects with no ordering not specified, then the orderless
+    objects come first)
+2. Objects with same ordering get grouped by module import order
+3. Internal order within module
+4. If no ordering is specified by any objects, then objects are sorted
+   alphabetically by class name
+
+  >>> from inter2 import Four, Five, Six
+  >>> components = [One(), Two(), Three(), Four(), Five(), Six()]
+
+  >>> from grokcore.component import sort_components
+  >>> sort_components(components)
+  [<...Three object at ...>,
+   <...One object at ...>,
+   <...Five object at ...>,
+   <...Six object at ...>,
+   <...Four object at ...>,
+   <...Two object at ...>]
+
+"""
+
+import grokcore.component as grok
+
+class One(object):
+    grok.order()
+
+class Two(object):
+    grok.order(2)
+
+class Three(object):
+    pass

=== added file 'src/grokcore/component/tests/order/inter2.py'
--- src/grokcore/component/tests/order/inter2.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/inter2.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,14 @@
+"""
+This module used by inter1 tests
+"""
+
+import grokcore.component as grok
+
+class Four(object):
+    grok.order(1)
+
+class Five(object):
+    pass
+
+class Six(object):
+    grok.order()

=== added file 'src/grokcore/component/tests/order/noarg_orderdirective.py'
--- src/grokcore/component/tests/order/noarg_orderdirective.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/noarg_orderdirective.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,33 @@
+"""
+
+If the grok.order directive is present with no arguments, sorting will
+be done by definition order.
+
+  >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
+
+  >>> from grokcore.component import sort_components
+  >>> sort_components(components)
+  [<...First object at ...>,
+   <...Second object at ...>,
+   <...Third object at ...>,
+   <...Fourth object at ...>,
+   <...Fifth object at ...>]
+
+"""
+
+import grokcore.component as grok
+
+class First(object):
+    grok.order()
+
+class Second(object):
+    grok.order()
+
+class Third(object):
+    grok.order()
+
+class Fourth(object):
+    grok.order()
+
+class Fifth(object):
+    grok.order()

=== added file 'src/grokcore/component/tests/order/nodirective.py'
--- src/grokcore/component/tests/order/nodirective.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/order/nodirective.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,31 @@
+"""
+
+If the grok.order directive is absent, sorting will be done by class
+name.
+
+  >>> components = [First(), Second(), Third(), Fourth(), Fifth()]
+
+  >>> from grokcore.component import sort_components
+  >>> sort_components(components)
+  [<...Fifth object at ...>,
+   <...First object at ...>,
+   <...Fourth object at ...>,
+   <...Second object at ...>,
+   <...Third object at ...>]
+
+"""
+
+class First(object):
+    pass
+
+class Second(object):
+    pass
+
+class Third(object):
+    pass
+
+class Fourth(object):
+    pass
+
+class Fifth(object):
+    pass

=== added directory 'src/grokcore/component/tests/subscriptions'
=== added file 'src/grokcore/component/tests/subscriptions/__init__.py'
--- src/grokcore/component/tests/subscriptions/__init__.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/__init__.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,1 @@
+# this is a package

=== added file 'src/grokcore/component/tests/subscriptions/decorator.py'
--- src/grokcore/component/tests/subscriptions/decorator.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/decorator.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,41 @@
+"""
+  >>> grok.testing.grok(__name__)
+
+  >>> cave = Cave('sweet home')
+
+  >>> subscriptions = grok.querySubscriptions(cave, IActivity)
+  >>> subscriptions
+  [<grokcore.component.tests.subscriptions.decorator.DebuggingGrokcore object at ...>]
+
+  Subscription adapters are not registered as regular adapters:
+
+  >>> from zope import component
+  >>> component.queryAdapter(cave, IActivity)
+
+"""
+
+
+import grokcore.component as grok
+from zope import interface
+
+
+class Cave(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+class IActivity(interface.Interface):
+    pass
+
+
+class DebuggingGrokcore(object):
+
+    def __init__(self, where):
+        self.where = where
+
+
[e-mail](Cave)
[e-mail](IActivity)
+def debugging(content):
+    return DebuggingGrokcore(content)

=== added file 'src/grokcore/component/tests/subscriptions/multisubscriptions.py'
--- src/grokcore/component/tests/subscriptions/multisubscriptions.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/multisubscriptions.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,98 @@
+"""
+  >>> grok.testing.grok(__name__)
+
+  >>> cave = Cave('Tilburg cave')
+  >>> martijn = Mammoth('Martijn')
+
+  You can query a subscriptions using multiple components. You will get
+  all subscriptions registered for office and cave (since office is a
+  base class of cave):
+
+  >>> subscriptions = grok.queryMultiSubscriptions((cave, martijn), IActivity)
+  >>> subscriptions
+  [<grokcore.component.tests.subscriptions.multisubscriptions.Sleep object at ...>,
+   <grokcore.component.tests.subscriptions.multisubscriptions.Food object at ...>,
+   <grokcore.component.tests.subscriptions.multisubscriptions.WritingCode object at ...>]
+
+  >>> _ = map(lambda s: s.do(), subscriptions)
+  Martijn is sleeping at Tilburg cave.
+  Martijn is feeding himself at Tilburg cave.
+  Martijn is writing code at Tilburg cave!
+
+
+  Now, Martijn goes to the office. You will only get subscriptions
+  registered for office:
+
+  >>> office = Office('Grok corp(r)(tm) headquarters')
+  >>> office_subscriptions = grok.queryMultiSubscriptions(
+  ...     (office, martijn), IActivity)
+  >>> office_subscriptions
+  [<grokcore.component.tests.subscriptions.multisubscriptions.Sleep object at ...>]
+
+  >>> _ = map(lambda s: s.do(), office_subscriptions)
+  Martijn is sleeping at Grok corp(r)(tm) headquarters.
+
+"""
+
+import grokcore.component as grok
+from zope import interface
+
+
+class Office(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+# All caves are a kind of office.
+class Cave(Office):
+    pass
+
+
+class Mammoth(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+class IActivity(interface.Interface):
+
+    def do():
+        """Do something.
+        """
+
+class Sleep(grok.MultiSubscription):
+    grok.implements(IActivity)
+    grok.adapts(Office, Mammoth)
+
+    def __init__(self, where, who):
+        self.where = where
+        self.who = who
+
+    def do(self):
+        print '%s is sleeping at %s.' % (self.who.name, self.where.name)
+
+
+class DayTimeActivity(grok.MultiSubscription):
+    grok.implements(IActivity)
+    grok.adapts(Cave, Mammoth)
+    grok.baseclass()
+
+    def __init__(self, where, who):
+        self.where = where
+        self.who = who
+
+    def do(self):
+        print 'nothing'
+
+
+class Food(DayTimeActivity):
+
+    def do(self):
+        print '%s is feeding himself at %s.' % (self.who.name, self.where.name)
+
+
+class WritingCode(DayTimeActivity):
+
+    def do(self):
+        print '%s is writing code at %s!' % (self.who.name, self.where.name)

=== added file 'src/grokcore/component/tests/subscriptions/multisubscriptions_no_adapts.py'
--- src/grokcore/component/tests/subscriptions/multisubscriptions_no_adapts.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/multisubscriptions_no_adapts.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,19 @@
+"""
+  >>> grok.testing.grok(__name__)
+  Traceback (most recent call last):
+    ...
+  GrokError: <class 'grokcore.component.tests.subscriptions.multisubscriptions_no_adapts.CaveGardenRenovator'>
+  must specify which contexts it adapts (use the 'adapts' directive to specify).
+
+"""
+
+import grokcore.component as grok
+from zope import interface
+
+class IRenovate(interface.Interface):
+
+    def takedown():
+        pass
+
+class CaveGardenRenovator(grok.MultiSubscription):
+    grok.provides(IRenovate)

=== added file 'src/grokcore/component/tests/subscriptions/multisubscriptions_no_interface.py'
--- src/grokcore/component/tests/subscriptions/multisubscriptions_no_interface.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/multisubscriptions_no_interface.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,20 @@
+"""
+  >>> grok.testing.grok(__name__)
+  Traceback (most recent call last):
+    ...
+  GrokError: <class 'grokcore.component.tests.subscriptions.multisubscriptions_no_interface.CaveGardenRedecorator'>
+  must implement at least one interface (use grok.implements to specify).
+
+"""
+
+import grokcore.component as grok
+
+
+class Cave(grok.Context):
+    pass
+
+class Garden(grok.Context):
+    pass
+
+class CaveGardenRedecorator(grok.MultiSubscription):
+    pass

=== added file 'src/grokcore/component/tests/subscriptions/ordered_multisubscriptions.py'
--- src/grokcore/component/tests/subscriptions/ordered_multisubscriptions.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/ordered_multisubscriptions.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,97 @@
+"""
+  >>> grok.testing.grok(__name__)
+
+  >>> cave = Cave('Tilburg cave')
+  >>> martijn = Mammoth('Martijn')
+
+  You can query a subscriptions using multiple components and sort them
+  using `grok.order` information:
+
+  >>> ordered_subscriptions = grok.queryOrderedMultiSubscriptions(
+  ...     (cave, martijn), IActivity)
+  >>> ordered_subscriptions
+  [<grokcore.component.tests.subscriptions.ordered_multisubscriptions.Cooking object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_multisubscriptions.Gardening object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_multisubscriptions.Cleaning object at ...>]
+
+  >>> _ = map(lambda a: a.do(), ordered_subscriptions)
+  Martijn is cooking in Tilburg cave!
+  Martijn is growing pumpkins in Tilburg cave!
+  Martijn is cleaning the Tilburg cave.
+
+  Or choose not to:
+
+  >>> subscriptions = grok.queryMultiSubscriptions(
+  ...     (cave, martijn), IActivity)
+
+  (still need to sort them on class name in order to have a working doctest)
+
+  >>> subscriptions = sorted(subscriptions, key=lambda s: s.__class__.__name__)
+  >>> subscriptions
+  [<grokcore.component.tests.subscriptions.ordered_multisubscriptions.Cleaning object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_multisubscriptions.Cooking object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_multisubscriptions.Gardening object at ...>]
+
+  >>> _ = map(lambda a: a.do(), subscriptions)
+  Martijn is cleaning the Tilburg cave.
+  Martijn is cooking in Tilburg cave!
+  Martijn is growing pumpkins in Tilburg cave!
+
+
+"""
+
+import grokcore.component as grok
+from zope import interface
+
+
+class Cave(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+class Mammoth(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+class IActivity(interface.Interface):
+
+    def do():
+        """Do something.
+        """
+
+
+class DayTimeActivity(grok.MultiSubscription):
+    grok.provides(IActivity)
+    grok.adapts(Cave, Mammoth)
+    grok.baseclass()
+
+    def __init__(self, where, who):
+        self.where = where
+        self.who = who
+
+    def do(self):
+        print 'Doing nothing.'
+
+
+class Cleaning(DayTimeActivity):
+    grok.order(99)
+
+    def do(self):
+        print '%s is cleaning the %s.' % (self.who.name, self.where.name)
+
+
+class Cooking(DayTimeActivity):
+    grok.order(10)
+
+    def do(self):
+        print '%s is cooking in %s!' % (self.who.name, self.where.name)
+
+
+class Gardening(DayTimeActivity):
+    grok.order(15)
+
+    def do(self):
+        print '%s is growing pumpkins in %s!' % (self.who.name, self.where.name)

=== added file 'src/grokcore/component/tests/subscriptions/ordered_subscriptions.py'
--- src/grokcore/component/tests/subscriptions/ordered_subscriptions.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/ordered_subscriptions.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,71 @@
+"""
+  >>> grok.testing.grok(__name__)
+
+  >>> cave = Cave()
+
+  You can query the subscriptions and sort them with the information
+  provided by grok.order:
+
+  >>> ordered_subscriptions = grok.queryOrderedSubscriptions(cave, ICleaner)
+  >>> ordered_subscriptions
+  [<grokcore.component.tests.subscriptions.ordered_subscriptions.MondayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_subscriptions.WednesdayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_subscriptions.SaturdayCleaner object at ...>]
+
+  >>> _ = map(lambda s: s.work(), ordered_subscriptions)
+  Monday cleaning!
+  Wednesday cleaning!
+  Saturday cleaning!
+
+  If you use the regular query method, they won't be sorted:
+
+  >>> subscriptions = grok.querySubscriptions(cave, ICleaner)
+  >>> subscriptions
+  [<grokcore.component.tests.subscriptions.ordered_subscriptions.MondayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_subscriptions.SaturdayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.ordered_subscriptions.WednesdayCleaner object at ...>]
+
+  >>> _ = map(lambda s: s.work(), subscriptions)
+  Monday cleaning!
+  Saturday cleaning!
+  Wednesday cleaning!
+
+"""
+
+import grokcore.component as grok
+from zope import interface
+
+
+class Cave(grok.Context):
+    pass
+
+
+class ICleaner(interface.Interface):
+
+    def work():
+        """Clean that cave.
+        """
+
+class MondayCleaner(grok.Subscription):
+    grok.implements(ICleaner)
+    grok.order(1)
+
+    def work(self):
+        print 'Monday cleaning!'
+
+
+class WednesdayCleaner(grok.Subscription):
+    grok.implements(ICleaner)
+    grok.order(3)
+
+    def work(self):
+        print 'Wednesday cleaning!'
+
+
+class SaturdayCleaner(grok.Subscription):
+    grok.implements(ICleaner)
+    grok.order(6)
+
+    def work(self):
+        print 'Saturday cleaning!'
+

=== added file 'src/grokcore/component/tests/subscriptions/subscriptions.py'
--- src/grokcore/component/tests/subscriptions/subscriptions.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/subscriptions.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,58 @@
+"""
+  >>> grok.testing.grok(__name__)
+
+  >>> cave = Cave('sweet home')
+
+  >>> subscriptions = grok.querySubscriptions(cave, ICleaner)
+  >>> subscriptions
+  [<grokcore.component.tests.subscriptions.subscriptions.MondayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.subscriptions.SaturdayCleaner object at ...>,
+   <grokcore.component.tests.subscriptions.subscriptions.WednesdayCleaner object at ...>]
+
+  >>> _ = map(lambda s: s.work(), subscriptions)
+  Monday cleaning sweet home!
+  Saturday cleaning sweet home!
+  Wednesday cleaning sweet home!
+
+  Subscription adapters are not registered as regular adapters:
+
+  >>> component.queryAdapter(cave, ICleaner)
+
+"""
+
+import grokcore.component as grok
+from zope import interface, component
+
+
+class Cave(grok.Context):
+
+    def __init__(self, name):
+        self.name = name
+
+
+class ICleaner(interface.Interface):
+
+    def work():
+        """Clean that cave.
+        """
+
+class MondayCleaner(grok.Subscription):
+    grok.implements(ICleaner)
+
+    def work(self):
+        print 'Monday cleaning %s!' % self.context.name
+
+
+class WednesdayCleaner(grok.Subscription):
+    grok.provides(ICleaner)
+
+    def work(self):
+        print 'Wednesday cleaning %s!' % self.context.name
+
+
+class SaturdayCleaner(grok.Subscription):
+    grok.implements(ICleaner)
+
+    def work(self):
+        print 'Saturday cleaning %s!' % self.context.name
+

=== added file 'src/grokcore/component/tests/subscriptions/subscriptions_no_context.py'
--- src/grokcore/component/tests/subscriptions/subscriptions_no_context.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/subscriptions_no_context.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,20 @@
+"""
+  >>> grok.testing.grok(__name__)
+  Traceback (most recent call last):
+    ...
+  GrokError: No module-level context for
+  <class 'grokcore.component.tests.subscriptions.subscriptions_no_context.CaveProcessor'>,
+  please use the 'context' directive.
+
+"""
+
+import grokcore.component as grok
+from zope import interface
+
+class ITask(interface.Interface):
+
+    def finish():
+        pass
+
+class CaveProcessor(grok.Subscription):
+    grok.provides(ITask)

=== added file 'src/grokcore/component/tests/subscriptions/subscriptions_no_interface.py'
--- src/grokcore/component/tests/subscriptions/subscriptions_no_interface.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/tests/subscriptions/subscriptions_no_interface.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,17 @@
+"""
+  >>> grok.testing.grok(__name__)
+  Traceback (most recent call last):
+    ...
+  GrokError: <class 'grokcore.component.tests.subscriptions.subscriptions_no_interface.CaveProcessor'>
+  must implement at least one interface (use grok.implements to specify).
+
+"""
+
+import grokcore.component as grok
+
+
+class Cave(grok.Context):
+    pass
+
+class CaveProcessor(grok.Subscription):
+    pass

=== modified file 'src/grokcore/component/tests/test_grok.py'
--- src/grokcore/component/tests/test_grok.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/tests/test_grok.py	2013-01-23 22:26:20 +0000
@@ -1,7 +1,9 @@
 import re
-import unittest, traceback
+import unittest
+import traceback
+import doctest
 from pkg_resources import resource_listdir
-from zope.testing import doctest, cleanup, renormalizing
+from zope.testing import cleanup, renormalizing
 import zope.component.eventtesting
 
 def setUpZope(test):
@@ -37,7 +39,7 @@
                                         checker=checker,
                                         optionflags=doctest.ELLIPSIS+
                                         doctest.NORMALIZE_WHITESPACE)
-        except ImportError, e:  # or should this accept anything?
+        except ImportError:  # or should this accept anything?
             traceback.print_exc()
             raise
         suite.addTest(test)
@@ -46,7 +48,7 @@
 def test_suite():
     suite = unittest.TestSuite()
     for name in ['adapter', 'directive', 'grokker', 'utility', 'view',
-                 'event', 'inherit']:
+                 'event', 'inherit', 'order', 'subscriptions']:
         suite.addTest(suiteFromPackage(name))
 
     api = doctest.DocFileSuite('api.txt')

=== added file 'src/grokcore/component/util.py'
--- src/grokcore/component/util.py	1970-01-01 00:00:00 +0000
+++ src/grokcore/component/util.py	2013-01-23 22:26:20 +0000
@@ -0,0 +1,143 @@
+##############################################################################
+#
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Grok utility functions.
+"""
+import types
+import zope.component.hooks
+from zope.interface.interfaces import IInterface
+from zope.interface import alsoProvides
+from grokcore.component import directive
+
+def _sort_key(component):
+    # If components have a grok.order directive, sort by that.
+    explicit_order, implicit_order = directive.order.bind().get(component)
+    return (explicit_order,
+            component.__module__,
+            implicit_order,
+            component.__class__.__name__)
+
+
+def sort_components(components, key=None):
+    """Sort a list of components using the information provided by
+    `grok.order`.
+    """
+    sort_key = _sort_key
+    if key is not None:
+        sort_key = lambda item: _sort_key(key(item))
+    return sorted(components, key=sort_key)
+
+
+def getSiteManager():
+    site = zope.component.hooks.getSite()
+    if site is None:
+        sm = zope.component.getGlobalSiteManager()
+    else:
+        sm = site.getSiteManager()
+    return sm
+
+
+def provideUtility(component, provides=None, name=u''):
+    sm = getSiteManager()
+    sm.registerUtility(component, provides, name, event=False)
+
+
+def provideAdapter(factory, adapts=None, provides=None, name=''):
+    sm = getSiteManager()
+    sm.registerAdapter(factory, adapts, provides, name, event=False)
+
+
+def provideSubscriptionAdapter(factory, adapts=None, provides=None):
+    sm = getSiteManager()
+    sm.registerSubscriptionAdapter(factory, adapts, provides, event=False)
+
+
+def provideHandler(factory, adapts=None):
+    sm = getSiteManager()
+    sm.registerHandler(factory, adapts, event=False)
+
+def provideInterface(id, interface, iface_type=None, info=''):
+    """register Interface with global site manager as utility
+
+    >>> gsm = zope.component.getGlobalSiteManager()
+
+    >>> from zope.interface import Interface
+    >>> from zope.interface.interfaces import IInterface
+    >>> from zope.component.tests import ITestType
+
+    >>> class I(Interface):
+    ...     pass
+    >>> IInterface.providedBy(I)
+    True
+    >>> ITestType.providedBy(I)
+    False
+    >>> interfaces = gsm.getUtilitiesFor(ITestType)
+    >>> list(interfaces)
+    []
+
+    # provide first interface type
+    >>> provideInterface('', I, ITestType)
+    >>> ITestType.providedBy(I)
+    True
+    >>> interfaces = list(gsm.getUtilitiesFor(ITestType))
+    >>> [name for (name, iface) in interfaces]
+    [u'zope.component.interface.I']
+    >>> [iface.__name__ for (name, iface) in interfaces]
+    ['I']
+
+    # provide second interface type
+    >>> class IOtherType(IInterface):
+    ...     pass
+    >>> provideInterface('', I, IOtherType)
+
+    >>> ITestType.providedBy(I)
+    True
+    >>> IOtherType.providedBy(I)
+    True
+    >>> interfaces = list(gsm.getUtilitiesFor(ITestType))
+    >>> [name for (name, iface) in interfaces]
+    [u'zope.component.interface.I']
+    >>> interfaces = list(gsm.getUtilitiesFor(IOtherType))
+    >>> [name for (name, iface) in interfaces]
+    [u'zope.component.interface.I']
+
+    >>> class I1(Interface):
+    ...     pass
+    >>> provideInterface('', I1)
+    >>> IInterface.providedBy(I1)
+    True
+    >>> ITestType.providedBy(I1)
+    False
+    >>> interfaces = list(gsm.getUtilitiesFor(ITestType))
+    >>> [name for (name, iface) in interfaces]
+    [u'zope.component.interface.I']
+    >>> [iface.__name__ for (name, iface) in interfaces]
+    ['I']
+    """
+    if not id:
+        id = "%s.%s" % (interface.__module__, interface.__name__)
+
+    if not IInterface.providedBy(interface):
+        if not isinstance(interface, (type, types.ClassType)):
+            raise TypeError(id, "is not an interface or class")
+        return
+
+    if iface_type is not None:
+        if not iface_type.extends(IInterface):
+            raise TypeError(iface_type, "is not an interface type")
+        alsoProvides(interface, iface_type)
+    else:
+        iface_type = IInterface
+
+    sm = getSiteManager()
+    sm.registerUtility(interface, iface_type, id, info)

=== modified file 'src/grokcore/component/zcml.py'
--- src/grokcore/component/zcml.py	2010-01-29 16:22:17 +0000
+++ src/grokcore/component/zcml.py	2013-01-23 22:26:20 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006-2007 Zope Corporation and Contributors.
+# Copyright (c) 2006-2007 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -15,11 +15,10 @@
 
 from zope.interface import Interface
 from zope.configuration.fields import GlobalObject
-#from zope.configuration.config import ConfigurationMachine
+from zope.schema import TextLine
 
 import martian
-#from martian import scan
-#from martian.error import GrokError
+
 
 class IGrokDirective(Interface):
     """Grok a package or module."""
@@ -27,28 +26,46 @@
     package = GlobalObject(
         title=u"Package",
         description=u"The package or module to be analyzed by grok.",
-        required=False,
-        )
+        required=False)
+
+    exclude = TextLine(
+        title=u"Exclude",
+        description=u"Name to exclude in the grokking process.",
+        required=False)
+
 
 # add a cleanup hook so that grok will bootstrap itself again whenever
 # the Component Architecture is torn down.
 def resetBootstrap():
     # we need to make sure that the grokker registry is clean again
     the_module_grokker.clear()
+
 from zope.testing.cleanup import addCleanUp
 addCleanUp(resetBootstrap)
 
 the_multi_grokker = martian.MetaMultiGrokker()
 the_module_grokker = martian.ModuleGrokker(the_multi_grokker)
 
+
 def skip_tests(name):
-    return name in ['tests', 'ftests']
-
-def grokDirective(_context, package):
-    do_grok(package.__name__, _context)
-
-def do_grok(dotted_name, config):
+    return name in ['tests', 'ftests', 'testing']
+
+
+def grokDirective(_context, package, exclude=None):
+    if not exclude:
+        exclude = None
+    do_grok(package.__name__, _context, extra_exclude=exclude)
+
+
+def do_grok(dotted_name, config, extra_exclude=None):
+    if extra_exclude is not None:
+
+        def exclude_filter(name):
+            return skip_tests(name) or extra_exclude == name
+
+    else:
+        exclude_filter = skip_tests
+
     martian.grok_dotted_name(
-        dotted_name, the_module_grokker, exclude_filter=skip_tests,
-        config=config
-        )
+        dotted_name, the_module_grokker, exclude_filter=exclude_filter,
+        config=config)

=== removed file 'versions.cfg'
--- versions.cfg	2010-01-29 16:22:17 +0000
+++ versions.cfg	1970-01-01 00:00:00 +0000
@@ -1,115 +0,0 @@
-# This is a copy of grok/versions.cfg revision 102959.
-#
-# Don't make local modifications here, just override it explicitly in
-# your buildout's [versions] part.
-
-[versions]
-ClientForm = 0.2.9
-grokcore.component = 1.7
-grokcore.formlib = 1.2
-grokcore.security = 1.1
-grokcore.view = 1.9
-grokcore.viewlet = 1.1
-grokui.admin = 0.3.2
-martian = 0.11
-mechanize = 0.1.7b
-pytz = 2007k
-RestrictedPython = 3.4.2
-simplejson = 1.7.1
-z3c.autoinclude = 0.2.2
-z3c.flashmessage = 1.0
-z3c.testsetup = 0.4
-zc.catalog = 1.2.0
-ZConfig = 2.5.1
-zc.recipe.testrunner = 1.0.0
-zdaemon = 2.0.2
-ZODB3 = 3.8.2
-zodbcode = 3.4.0
-zope.annotation = 3.4.1
-zope.app.apidoc = 3.4.3
-zope.app.applicationcontrol = 3.4.3
-zope.app.appsetup = 3.4.1
-zope.app.authentication = 3.4.4
-zope.app.basicskin = 3.4.0
-zope.app.broken = 3.4.0
-zope.app.catalog = 3.5.1
-zope.app.component = 3.4.1
-zope.app.container = 3.5.6
-zope.app.content = 3.4.0
-zope.app.debug = 3.4.1
-zope.app.dependable = 3.4.0
-zope.app.error = 3.5.1
-zope.app.exception = 3.4.1
-zope.app.file = 3.4.4
-zope.app.folder = 3.4.0
-zope.app.form = 3.4.1
-zope.app.generations = 3.4.1
-zope.app.http = 3.4.1
-zope.app.i18n = 3.4.4
-zope.app.interface = 3.4.0
-zope.app.intid = 3.4.1
-zope.app.keyreference = 3.4.1
-zope.app.locales = 3.4.5
-zope.app.onlinehelp = 3.4.1
-zope.app.pagetemplate = 3.4.1
-zope.app.preference = 3.4.1
-zope.app.principalannotation = 3.4.0
-zope.app.publication = 3.4.3
-zope.app.publisher = 3.5.1
-zope.app.renderer = 3.4.0
-zope.app.rotterdam = 3.4.1
-zope.app.schema = 3.4.0
-zope.app.security = 3.5.2
-zope.app.securitypolicy = 3.4.6
-zope.app.server = 3.4.2
-zope.app.session = 3.5.1
-zope.app.skins = 3.4.0
-zope.app.testing = 3.4.3
-zope.app.tree = 3.4.0
-zope.app.twisted = 3.4.1
-zope.app.wsgi = 3.4.1
-zope.app.zapi = 3.4.0
-zope.app.zcmlfiles = 3.4.3
-zope.app.zopeappgenerations = 3.4.0
-zope.cachedescriptors = 3.4.1
-zope.component = 3.4.0
-zope.configuration = 3.4.0
-zope.contentprovider = 3.4.0
-zope.contenttype = 3.4.0
-zope.copypastemove = 3.4.0
-zope.datetime = 3.4.0
-zope.deferredimport = 3.4.0
-zope.deprecation = 3.4.0
-zope.dottedname = 3.4.2
-zope.dublincore = 3.4.0
-zope.error = 3.5.1
-zope.event = 3.4.0
-zope.exceptions = 3.4.0
-zope.filerepresentation = 3.4.0
-zope.formlib = 3.4.0
-zope.hookable = 3.4.0
-zope.i18n = 3.4.0
-zope.i18nmessageid = 3.4.3
-zope.index = 3.4.1
-zope.interface = 3.4.1
-zope.lifecycleevent = 3.4.0
-zope.location = 3.4.0
-zope.minmax = 1.1.0
-zope.modulealias = 3.4.0
-zope.pagetemplate = 3.4.0
-zope.proxy = 3.4.2
-zope.publisher = 3.4.9
-zope.schema = 3.4.0
-zope.security = 3.4.1
-zope.securitypolicy = 3.4.1
-zope.server = 3.4.3
-zope.session = 3.4.1
-zope.size = 3.4.0
-zope.structuredtext = 3.4.0
-zope.tal = 3.4.1
-zope.tales = 3.4.0
-zope.testbrowser = 3.4.2
-zope.testing = 3.7.6
-zope.thread = 3.4
-zope.traversing = 3.4.1
-zope.viewlet = 3.4.2