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

Casey Duncan casey at zope.com
Sat Feb 28 01:02:20 EST 2004


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

Modified Files:
	interfaces.py 
Log Message:
Initial IQuery interface spec


=== Packages/pypes/pypes/interfaces.py 1.11 => 1.12 ===
--- Packages/pypes/pypes/interfaces.py:1.11	Sun Feb 15 23:43:59 2004
+++ Packages/pypes/pypes/interfaces.py	Sat Feb 28 01:02:18 2004
@@ -513,7 +513,121 @@
         paths between nodes of the graph. If source and target are omitted,
         all possible paths between all graph nodes are returned. If source
         is specified, only paths starting from source are returned. If 
-        target is specified, only paths to target are returned. If both are
+        target is specified, only paths to target are returned. Both are
         specifed to compute all paths connecting source to target
         """
+                
 
+class IQuery(Interface):
+    """Declarative query for discovering and arranging identified objects.
+    
+    Queries consist of sources, a where expression, an order expression and a
+    select expression. Only sources are required by a query. Sources are the
+    input for the query which are containers of identified objects: typically
+    extents, identity sets or query results. Where expressions select which
+    objects from the sources appear in the results. Order expressions declare
+    the sort order of the results and select expressions specify the value of
+    each result item.
+    
+    Expressions are Python expression strings. Source key names, names from the
+    globals and locals of the caller and Python builtins are available to
+    use in the expression string.
+    """
+    
+    def frm(*sources):
+        """Return a derived query using sources. Each source must have a
+        unique key that identifies it. This key may be provided by the object
+        through a key attribute (such as ICanonicalExtents) or the source and
+        key can be specified by passing a (key, source) pair.
+        
+        Typical Usage::
+        
+          query.frm(extent[Animal])
+          
+          query.frm(extent[Mammal], extent[Habitat])
+          
+          query.frm(('oldie', old_songs), ('rs', extent[RockStar]))
+        """
+        
+    def where(expression):
+        """Return a derived query with the specified where expression, a 
+        Python expression string. This expression is a filter which determines
+        which objects appear in the results. 
+        
+        Typical usage::
+        
+          query.where("Animal.species == 'canine'")
+          
+          query.where("Mammal.location in Habitat.locations")
+          
+          query.where("oldie.artist.name == rs.name and rs.genre == 'blues'")
+        """
+    
+    def orderBy(*expressions):
+        """Return a derived query with the specified order expressions.
+        Each expression specifies a value to sort by. They may also
+        specify a sort order with the default order ascending.
+        
+        Typical usage::
+        
+          query.orderBy(("Animal.population", "descending"))
+          
+          query.orderBy("Mammal.location")
+          
+          query.orderBy("rs.name", "oldie.title")
+        """
+    
+    def select(expression):
+        """Return a derived query with the specified select expression. This
+        expression determines the value for each result returned. If a query
+        has no select expression specified then the value for each
+        result is the object from the single source of the query or a tuple of 
+        objects if there are multiple sources.
+        
+        Typical usage::
+        
+          query.select("Animal.name")
+          
+          query.select("Mammal")
+          
+          query.select("oldie")
+        """
+    
+    def selectDistinct(expression=None):
+        """Return a derived query with the specified select expression. 
+        selectDistinct is like select except that it all results returned
+        by the query are unique. If expression is omitted then the
+        result values are the members of the query sources
+        
+        Typical usage::
+            
+          query.selectDistinct("Habitat")
+        
+          query.selectDistinct("rs")
+        """
+    
+    def selectOne(expression=None):
+        """Return a derived query with the specified select expression. 
+        selectOne is like select except that the query returns only a single
+        result instead of a result set. If the query results in multiple
+        results found then a PypesQueryError is returned. If the query results
+        in no results found, then None is returned instead of an empty
+        result set. If expression is omitted then the result value is from the 
+        the members of the query sources
+
+        Typical usage::
+            
+          query.selectOne("Winner")
+        """
+    
+    def results():
+        """Execute the query and return the results"""
+        
+    def analyse():
+        """Return a human-readable analysis string of the steps and resources
+        that would be used to execute the query. This information can be
+        used to determine the complexity of queries and optimize them or to
+        confirm that resources are properly utilized for effiency.
+        """
+    
+    




More information about the Zope-CVS mailing list