Changeset 9773

Timestamp:

6 Dec 2012, 07:31:02 (12 years ago)

Author:

uli

Message:

Add docs.

File:

• main/waeup.kofa/trunk/src/waeup/kofa/catalog.py (modified) (3 diffs)

main/waeup.kofa/trunk/src/waeup/kofa/catalog.py

@@ -66 +66 @@
 class FilteredQueryBase(object):
     """A filter to find objects that match certain parameters.
+
+    Parameters are passed to constructor as keyword arguments. The
+    real data retrieval then happens when `query()` is called.
+
+    The `defaults` attribute, a dict, can set certain default values
+    for parameters that are used if the constructor is called without
+    any parameters.
     """
     defaults = dict()
@@ -81 +88 @@
 @implementer(IFilteredCatalogQuery)
 class FilteredCatalogQueryBase(FilteredQueryBase):
+    """Base for filtered queries based on catalog lookups.
+
+    This type of query asks a catalog to find objects.
+
+    You would normally use this type of query like this:
+
+      >>> query = FilteredCatalogQueryBase(name='bob')
+      >>> objects = query.query()
+
+    The name of the catalog to use can be set via `cat_name`
+    attribute.
+
+    Looked up are all objects that match keywords passed to
+    constructor where the keyword names must match a certain index of
+    the chosen catalog. So, if some catalog has indexes `name` and
+    `age`, then keywords `name='bob', age='12'` would search for all
+    objects with name ``bob`` and age ``12``.
+
+    This query supports single values (exact matches) and ranges of
+    values passed in via ``(min_value, max_value)`` tuples. So,
+    constructor keyword args `name=('a', 'd')` would find objects with
+    name ``alice``, ``bob``, ``d``, but not ``donald``, ``john``, or
+    ``zak``.
+    """
     cat_name = None
 
     def query_catalog(self, catalog):
+        """Search ``catalog``.
+
+        Use `catalog`, some ``Catalog`` instance, to search objects
+        denoted by constructor keywords.
+        """
         query = dict()
         for idx_name, value in self._kw.items():
@@ -93 +129 @@
 
     def query(self):
+        """Perform a query with parameters passed to constructor.
+
+        Returns some iterable, normally a list or a catalog result
+        set.
+        """
         catalog = queryUtility(
             ICatalog, name=self.cat_name, default=None)