improve documentation and handling of state queries

git-svn-id: svn://svn.cy55.de/Zope3/src/loops/trunk@2575 fd906abe-77d9-0310-91a1-e0d9ade77398

expert/README.txt

@@ -64,14 +64,18 @@ Type- and text-based queries
 State-based queries
 -------------------
 
-  >>> qu = query.State('loops.classification_quality', 'new')
+For selecting objects by their state their is a special query with two
+arguments, the name of the states definition and the state to search for.
+As we have not yet set up any states definitions for our objects we get
+an empty result.
+
+  >>> qu = query.State('loops.classification_quality', 'classified')
   >>> list(qu.apply())
   []
 
-  >>> from cybertools.stateful.publishing import simplePublishing
-  >>> component.provideUtility(simplePublishing(), name='loops.simple_publishing')
-  >>> from loops.organize.stateful.base import SimplePublishable
-  >>> component.provideAdapter(SimplePublishable, name='loops.simple_publishing')
+Let's now set up the ``classication quality`` states definition with the
+corresponding adapter and activate it for the current loops site.
+
   >>> from loops.organize.stateful.quality import classificationQuality
   >>> component.provideUtility(classificationQuality(),
   ...                          name='loops.classification_quality')
@@ -79,35 +83,47 @@ State-based queries
   >>> component.provideAdapter(ClassificationQualityCheckable,
   ...                          name='loops.classification_quality')
 
-  >>> loopsRoot.options = ['organize.stateful.resource:'
-  ...                      'loops.classification_quality,loops.simple_publishing']
+  >>> loopsRoot.options = ['organize.stateful.resource:loops.classification_quality']
+
+We have now to reindex all documents so that the state index gets populated
+according to the new settings.
 
   >>> from zope.app.catalog.interfaces import ICatalog
   >>> catalog = component.getUtility(ICatalog)
   >>> from loops import util
-
   >>> for r in resources.values():
   ...     catalog.index_doc(int(util.getUidForObject(r)), r)
 
+Now the three documents we are working with are shown as classified (as
+they have at least one concept assigned).
+
   >>> qu = query.State('loops.classification_quality', 'classified')
   >>> list(qu.apply())
   [23, 25, 27]
 
+Using the stateful adapter for a resource we now manually execute the
+``verify`` transition.
+
   >>> from cybertools.stateful.interfaces import IStateful
   >>> statefulD001 = component.getAdapter(resources['d001.txt'], IStateful,
   ...                                     name='loops.classification_quality')
-
-  >>> from loops.organize.stateful.base import handleTransition
-  >>> component.provideHandler(handleTransition)
-
   >>> statefulD001.doTransition('verify')
+
+Now only two resources are still in the ``qualified`` state, the changed
+one being in the ``verified`` state.
+
   >>> list(qu.apply())
   [25, 27]
-
   >>> qu = query.State('loops.classification_quality', 'verified')
   >>> list(qu.apply())
   [23]
 
+We may also provide a sequence of states for querying.
+
+  >>> qu = query.State('loops.classification_quality', ('classified', 'verified',))
+  >>> list(qu.apply())
+  [23, 25, 27]
+
 Relationship-based queries
 --------------------------
 

expert/query.py

@@ -31,7 +31,7 @@ from zope.component import adapts
 from zope.interface import implements, implementer
 from zope.cachedescriptors.property import Lazy
 
-from cybertools.catalog.query import Term, Eq, Between
+from cybertools.catalog.query import Term, Eq, Between, Or
 from cybertools.catalog.query import Text as BaseText
 from cybertools.catalog.query import AnyOf
 from loops.expert.interfaces import IQuery
@@ -64,7 +64,9 @@ def Type(value):
 
 @implementer(IQuery)
 def State(statesDefinition, value):
-    return AnyOf(stateIndex, ':'.join((statesDefinition, value)))
+    if not isinstance(value, (list, tuple)):
+        value = [value]
+    return AnyOf(stateIndex, [':'.join((statesDefinition, v)) for v in value])
 
 
 # concept map queries