[Checkins] SVN: grokcore.component/trunk/src/grokcore/component/ Backported the changes of the 1.x branch, moving the 'order' directive from grokcore.viewlet

[Souheil CHELFOUH]

Log message for revision 118053:
  Backported the changes of the 1.x branch, moving the 'order' directive from grokcore.viewlet
  

Changed:
  U   grokcore.component/trunk/src/grokcore/component/interfaces.py
  A   grokcore.component/trunk/src/grokcore/component/tests/order/
  U   grokcore.component/trunk/src/grokcore/component/tests/test_grok.py
  A   grokcore.component/trunk/src/grokcore/component/util.py

-=-
Modified: grokcore.component/trunk/src/grokcore/component/interfaces.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/interfaces.py	2010-11-01 15:21:26 UTC (rev 118052)
+++ grokcore.component/trunk/src/grokcore/component/interfaces.py	2010-11-01 15:38:34 UTC (rev 118053)
@@ -130,7 +130,26 @@
         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):
 
     def subscribe(*classes_or_interfaces):

Modified: grokcore.component/trunk/src/grokcore/component/tests/test_grok.py
===================================================================
--- grokcore.component/trunk/src/grokcore/component/tests/test_grok.py	2010-11-01 15:21:26 UTC (rev 118052)
+++ grokcore.component/trunk/src/grokcore/component/tests/test_grok.py	2010-11-01 15:38:34 UTC (rev 118053)
@@ -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):
@@ -46,7 +48,7 @@
 def test_suite():
     suite = unittest.TestSuite()
     for name in ['adapter', 'directive', 'grokker', 'utility', 'view',
-                 'event', 'inherit']:
+                 'event', 'inherit', 'order']:
         suite.addTest(suiteFromPackage(name))
 
     api = doctest.DocFileSuite('api.txt')

Copied: grokcore.component/trunk/src/grokcore/component/util.py (from rev 118052, grokcore.component/branches/1.x/src/grokcore/component/util.py)
===================================================================
--- grokcore.component/trunk/src/grokcore/component/util.py	                        (rev 0)
+++ grokcore.component/trunk/src/grokcore/component/util.py	2010-11-01 15:38:34 UTC (rev 118053)
@@ -0,0 +1,29 @@
+##############################################################################
+#
+# 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.
+"""
+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):
+    return sorted(components, key=_sort_key)