Changeset 9773 for main


Ignore:
Timestamp:
6 Dec 2012, 07:31:02 (12 years ago)
Author:
uli
Message:

Add docs.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • main/waeup.kofa/trunk/src/waeup/kofa/catalog.py

    r9767 r9773  
    6666class FilteredQueryBase(object):
    6767    """A filter to find objects that match certain parameters.
     68
     69    Parameters are passed to constructor as keyword arguments. The
     70    real data retrieval then happens when `query()` is called.
     71
     72    The `defaults` attribute, a dict, can set certain default values
     73    for parameters that are used if the constructor is called without
     74    any parameters.
    6875    """
    6976    defaults = dict()
     
    8188@implementer(IFilteredCatalogQuery)
    8289class FilteredCatalogQueryBase(FilteredQueryBase):
     90    """Base for filtered queries based on catalog lookups.
     91
     92    This type of query asks a catalog to find objects.
     93
     94    You would normally use this type of query like this:
     95
     96      >>> query = FilteredCatalogQueryBase(name='bob')
     97      >>> objects = query.query()
     98
     99    The name of the catalog to use can be set via `cat_name`
     100    attribute.
     101
     102    Looked up are all objects that match keywords passed to
     103    constructor where the keyword names must match a certain index of
     104    the chosen catalog. So, if some catalog has indexes `name` and
     105    `age`, then keywords `name='bob', age='12'` would search for all
     106    objects with name ``bob`` and age ``12``.
     107
     108    This query supports single values (exact matches) and ranges of
     109    values passed in via ``(min_value, max_value)`` tuples. So,
     110    constructor keyword args `name=('a', 'd')` would find objects with
     111    name ``alice``, ``bob``, ``d``, but not ``donald``, ``john``, or
     112    ``zak``.
     113    """
    83114    cat_name = None
    84115
    85116    def query_catalog(self, catalog):
     117        """Search ``catalog``.
     118
     119        Use `catalog`, some ``Catalog`` instance, to search objects
     120        denoted by constructor keywords.
     121        """
    86122        query = dict()
    87123        for idx_name, value in self._kw.items():
     
    93129
    94130    def query(self):
     131        """Perform a query with parameters passed to constructor.
     132
     133        Returns some iterable, normally a list or a catalog result
     134        set.
     135        """
    95136        catalog = queryUtility(
    96137            ICatalog, name=self.cat_name, default=None)
Note: See TracChangeset for help on using the changeset viewer.