[Zope-CVS] CVS: Packages/pypes/pypes - interfaces.py:1.25

Casey Duncan casey at zope.com
Wed Jun 9 00:23:13 EDT 2004


Update of /cvs-repository/Packages/pypes/pypes
In directory cvs.zope.org:/tmp/cvs-serv5274

Modified Files:
	interfaces.py 
Log Message:
Factor out the basic query factory interface
Replace IQuery.selectDistinct with IQuery.resultSet which should be more practical and useful for feeding the output of one query into the input of another
Add initial IQueryResult interface


=== Packages/pypes/pypes/interfaces.py 1.24 => 1.25 ===
--- Packages/pypes/pypes/interfaces.py:1.24	Mon May 31 23:05:48 2004
+++ Packages/pypes/pypes/interfaces.py	Wed Jun  9 00:23:12 2004
@@ -480,38 +480,26 @@
         specifed to compute all paths connecting source to target
         """
 
-
-class IQuery(Interface):
-    """Query definition
-    
-    Queries consist of inputs, a filter and an order expression. Only inputs
-    are generally required. 
-    
-    - Inputs are typically extents, identity sets or query result sets.
-    
-    - The filter is an expression which selects the objects from the inputs
-      appear in the results. They can also be used to "join" multiple inputs.
-
-    - The order declaration specifies the sort order of the results.
-
-    Expressions are IExpression objects. Declarations consist of one or
-    more IExpression objects.
+class IBasicQueryFactory(Interface):
+    """Factory to create a query from input sets, criteria and sort
+    expressions.
     """
     
-    def __init__(inputs=None, criteria=None, order=None, limit=None):
-        """Query constructor. Arguments values override defaults provided
-        by the class (if any).Query classes that supply defaults for all 
-        the necessary arguments can be constructed with no arguments.
-        
+    def __call__(inputs=None, criteria=None, order=None, limit=None):
+        """Create and return an IQuery object. Argument values override
+        defaults provided by the query class (if any).Query classes that 
+        supply defaults for  all the necessary arguments can be constructed
+        with no arguments.
+
         inputs -- A tuple(!) of self-named inputs (with __name__ attrs) or a
-        mapping of 'name':'input' pairs. Inputs may be any sequence of 
-        objects, but are typically sets of identified objects.
+        mapping of 'name':'input' pairs. Inputs are sets of objects,
+        typically extents or identity sets.
         
         criteria -- An IExpression object used as the criteria for selecting
         objects from the inputs.
         
         order -- An IOrderExpression object or a sequence of them that
-        determines the order of the results output.
+        determines the order of the result output.
         
         limit -- An integer value specifying the maximum number of results
         the query returns.
@@ -519,6 +507,23 @@
         Missing mandatory or inappropriate argument values should fail early
         and raise an appropriate PypesQueryError.
         """
+
+class IQuery(Interface):
+    """Query definition
+    
+    Queries consist of inputs, criteria and an order expression. Only inputs
+    are generally required. 
+    
+    - Inputs are typically extents or identity sets.
+    
+    - The criteria is an expression which selects the objects from the inputs
+      appear in the results. They can also be used to "join" multiple inputs.
+
+    - The order declaration specifies the sort order of the results.
+
+    Expressions are IExpression objects. Declarations consist of one or
+    more IExpression objects.
+    """
     
     def inputMap():
         """Return a dict containing the input names and input objects for its
@@ -533,13 +538,13 @@
         result order
         """
         
-    def resultLimit():
+    def lengthLimit():
         """Return the integer result length limit for the query or None if
         all should be returned
         """
     
     def select(*input_names):
-        """Execute the query and return the results as an IResultSequence.
+        """Execute the query and return the results as an IQueryResult.
         
         inputs_names -- The names of inputs to 'select' for output. If not
         specified, then all inputs are returned in the results. If a name
@@ -550,8 +555,8 @@
         items are tuples containing the matching joined objects cooresponding
         to the  named inputs.
 
-        select does not guarantee uniqueness of results, duplicates may be
-        returned depending on the inputs.
+        select may return duplicate results if one or more inputs is not
+        selected for output.
         
         Typical Usage::
             
@@ -563,16 +568,13 @@
                ...
         """
 
-    def selectDistinct(*input_names):
-        """Execute the query and return the results as an IResultSet if
-        query is unordered or an IOrderedResultSet if ordered. Semantics
-        are otherwise the same as 'select()'.
+    def resultSet(input_name):
+        """Execute the query and return an ISet object containing the
+        objects from input_name that were selected by the criteria.
         
         Typical usage::
-        
-          set = query.distinct()
             
-          habitats = query.distinct("Habitat")
+          habitats = query.resultSet("Habitat")
         """
     
     def selectOne(*input_names):
@@ -747,3 +749,42 @@
     #   tuples of the matching items from the cooresponding named inputs.
     #    """
 
+class IQueryResult(Interface):
+    """Result from running a query"""
+    
+    def query():
+        """Return the query object which generated this result"""
+        
+    def names():
+        """Return a sequence of input names selected for query output"""
+    
+    def __iter__():
+        """Return an iterator of the query output.
+        
+        If the query selects a single name then each iteration returns the
+        next selected object. If multiple names were selected then each
+        iteration returns a tuple of the selected objects.
+        """
+    
+    def __len__():
+        """Return the length of the query results.
+        
+        This requires full evaluation of the query result which may be
+        expensive if it has not already been performed. An application can test
+        if the query is already fully evaluated by calling the evaluated()
+        method. If it returns true then the length compution is already done,
+        if false then it requires computation to return.
+        """
+        
+    def __contains__(item):
+        """Return true if item is a result in the query output"""
+    
+    def evaluated():
+        """Return true if the query is fully evaluated, false if not. 
+        
+        A fully evaluated query requires no additional criteria selection or
+        sorting computation and its length is already calculated. Queries are
+        generally fully evaluated if they are fulfilled entirely by indexes,
+        already have been fully iterated, had their length calculated or are
+        very simple.
+        """




More information about the Zope-CVS mailing list