[Zope-CVS] CVS: Packages/pypes/pypes - interfaces.py:1.16
query.py:1.5
Casey Duncan
casey at zope.com
Mon Apr 12 00:41:44 EDT 2004
Update of /cvs-repository/Packages/pypes/pypes
In directory cvs.zope.org:/tmp/cvs-serv905
Modified Files:
interfaces.py query.py
Log Message:
Refactor query interfaces to reflect latest thinking
=== Packages/pypes/pypes/interfaces.py 1.15 => 1.16 ===
--- Packages/pypes/pypes/interfaces.py:1.15 Wed Mar 10 16:12:21 2004
+++ Packages/pypes/pypes/interfaces.py Mon Apr 12 00:41:43 2004
@@ -519,116 +519,118 @@
class IQuery(Interface):
- """Declarative query for discovering and arranging identified objects.
+ """Query definition
- 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.
+ 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.
"""
- 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.
+ def __init__(inputs=None, filter_expr=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.
- Typical Usage::
+ 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.
- query.frm(extent[Animal])
-
- query.frm(extent[Mammal], extent[Habitat])
-
- query.frm(('oldie', old_songs), ('rs', extent[RockStar]))
- """
+ filter_expr -- An IExpression object used as the query filter.
- 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.
+ order -- An IOrderExpression object or a sequence of them.
- Typical usage::
+ limit -- An integer value specifying the maximum number of results
+ the query returns.
- query.where("Animal.species == 'canine'")
-
- query.where("Mammal.location in Habitat.locations")
-
- query.where("oldie.artist.name == rs.name and rs.genre == 'blues'")
+ Missing mandatory or inappropriate argument values should fail early
+ and raise an appropriate PypesQueryError.
+ """
+
+ def inputMap():
+ """Return a dict containing the input names and input objects for its
+ respective keys and values
"""
- 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.
+ def filterExpr():
+ """Return the IExpression object used as the query filter"""
- Typical usage::
+ def orderExprs():
+ """Return a sequence of IOrderExpression objects that determine the
+ result order
+ """
- query.orderBy(("Animal.population", "descending"))
-
- query.orderBy("Mammal.location")
-
- query.orderBy("rs.name", "oldie.title")
+ def resultLimit():
+ """Return the integer result length limit for the query or None if
+ all should be returned
"""
- def select(expression):
- """Return a derived query with the specified select expression. This
- expression determines the projection from which the value for each
- result element is derived. 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.
+ def select(*input_names):
+ """Execute the query and return the results as an IResultSequence.
+
+ inputs_names -- The names of inputs to 'select' for output. If not
+ specified, then all inputs are returned in the results. If a name
+ not cooresponding to an input is specifed, raise PypesQueryError.
+
+ If one input is selected, then the result items are simply the objects
+ matched by the query. If multiple inputs are selected, then the result
+ items are tuples containing the matching joined objects cooresponding
+ to the named inputs.
- Typical usage::
+ select does not guarantee uniqueness of results, duplicates may be
+ returned depending on the inputs.
- query.select("Animal.name")
-
- query.select("Mammal")
-
- query.select("oldie")
+ Typical Usage::
+
+ query.select()
+
+ query.select("Species")
+
+ for species, habitat in query.select("Species", "Habitat"):
+ ...
"""
-
- 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
+
+ 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()'.
Typical usage::
-
- query.selectDistinct("Habitat")
- query.selectDistinct("rs")
+ set = query.distinct()
+
+ habitats = query.distinct("Habitat")
"""
- 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
+ def selectOne(*input_names):
+ """Execute a query that matches one distinct result and return it. For
+ a single input name, return the resulting object from that input. For
+ multiple input names, return a tuple of the matching objects from the
+ inputs.
+
+ The query **must** return a single result for the call to succeed. If
+ multiple results match raise PypesQueryError.
Typical usage::
+ query.selectOne()
+
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.
+ confirm that resources are properly utilized for efficiency.
"""
class IExpression(Interface):
@@ -667,37 +669,9 @@
result of expression execution
"""
-class IQueryEngine(Interface):
- """Mechanism for performing the primitive operations on inputs required to
- execute queries and generate results"""
-
- def inputs():
- """Return the query inputs as a dict keyed by input name"""
-
- def rawResults():
- """Return the current results in raw form as a dict with
- input name, result sequence as its respective key/value pairs.
- These results should be suitable for use as inputs for another
- query engine
- """
-
- def results(projection):
- """Return the current results processed as specified by the
- projection expression which is used to derive each result element
- """
-
- def filter(expression):
- """Mutate the current results using the expression object provided to
- filter those results for which the expression returns a true value
- """
-
- def sort(expression, order='ascending'):
- """Sort the current results in place using the expression object
- provided to derive the sort keys. A sort is a stable operation so that
- multiple sort passes can be applied during the query to sort by
- multiple expression simultaneously. order is either 'ascending' or
- 'descending'.
- """
+class IOrderExpression(IExpression):
+ """Expression with order information"""
+ order = Attribute('order', """1 == ascending, -1 == descending""")
=== Packages/pypes/pypes/query.py 1.4 => 1.5 ===
--- Packages/pypes/pypes/query.py:1.4 Sun Apr 4 00:27:09 2004
+++ Packages/pypes/pypes/query.py Mon Apr 12 00:41:43 2004
@@ -47,7 +47,6 @@
from zope.interface import implements
from BTrees.OOBTree import OOBTree
-from pypes.interfaces import IQueryEngine
from pypes.exceptions import PypesLookupError, PypesQueryInputError
## Exported constants ##
More information about the Zope-CVS
mailing list