:mod:`waeup.sirp.accesscodes.catalog` -- Cataloging access-codes
****************************************************************

.. module:: waeup.sirp.accesscodes.catalog

Components that support cataloging and searching accesscodes inside a
WAeUP SIRP site.

:Test-Layer: functional

.. contents::


The `catalog` module of `waeup.sirp.accesscodes` provides a catalog
for search :class:`waeup.sirp.accesscode.interfaces.IAccessCode`
objects.

Components
==========

:class:`AccessCodeCatalog`
--------------------------

.. class:: AccessCodeCatalog

  .. attribute:: grok.site(waeup.sirp.interfaces.IUniversity)
  .. attribute:: grok.name('accesscode_catalog')
  .. attribute:: grok.context(waeup.sirp.accesscodes.interfaces.IAccessCode)

  A catalog is registered each time an IUniversity instance is created
  and stored in the ZODB:

    >>> from waeup.sirp.app import University
    >>> u = University()
    >>> getRootFolder()['u'] = u

  It is setup as a local utility named ``accesscode_catalog``. As a
  local utility it only catalogs objects of the 'current' site aka
  `University` object and does not interfere with catalogs for
  different sites. This means you can safely run different
  Universities in one instance which won't share their data.

  Furthermore AccessCodeCatalog objects catalog objects of type
  :class:`waeup.sirp.accesscodes.interfaces.IAccessCode`` only.

    >>> from zope.site.hooks import setSite
    >>> setSite(u)

    >>> from zope.component import getUtility
    >>> from zope.catalog.interfaces import ICatalog
    >>> catalog = getUtility(ICatalog, name=u'accesscode_catalog')
    >>> catalog
    <zope.catalog.catalog.Catalog object at 0x...>

  It provides several indexes:

    >>> from pprint import pprint
    >>> pprint(sorted(list(catalog.items())))
    [(u'invalidated', <zope...FieldIndex object at 0x...>),
     (u'name', <zope...FieldIndex object at 0x...>),
     (u'student_id', <zope...FieldIndex object at 0x...>),
     (u'text', <zope...text.TextIndex object at 0x...>)]

  The ``invalidated`` index keeps references to the
  ``invalidation_date`` field of
  :class:`waeup.sirp.accesscodes.AccessCode` instances. This also
  means, that you have to look for ``datetime.datetime`` type values.

  The ``text`` and ``name`` indexes both store the ``representation``
  field of AccessCode instances. While the first is a text index, it
  allows searching using wildcards. The latter is a field index used
  in internal search functions.

  ``student_id`` finally is an index to the search for student ids or
  similar when an access code gets invalidated.

Examples
========

We register some AccessCodes and search them afterwards.

    >>> from datetime import datetime
    >>> from waeup.sirp.accesscodes.accesscodes import AccessCodeBatch
    >>> batch = AccessCodeBatch(
    ...   datetime(2009, 12, 23), 'Fred','APP', 12.12, 3, num=10)
    >>> u['accesscodes'].addBatch(batch)

    >>> from zope.site.hooks import setSite
    >>> setSite(u)

We use the :class:`waeup.sirp.catalog.WAeUPQuery` object defined in
:mod:`waeup.sirp.catalog`:

    >>> from hurry.query.interfaces import IQuery
    >>> from zope.component import getUtility
    >>> q = getUtility(IQuery)
    >>> q
    <waeup.sirp.catalog.WAeUPQuery object at 0x...>

    >>> from hurry.query import Text
    >>> r1 = q.searchResults(
    ...   Text(('accesscode_catalog', 'text'), 'APP*'))
    >>> list(r1)
    [<...AccessCode object at 0x...>,
     <...AccessCode object at 0x...>,
     <...AccessCode object at 0x...]