: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.

Tools
=====

:func:`search_invalidated`
--------------------------

.. function:: search_invalidated(batch_prefix, batch_num)

  Get set of accesscode catalog entries, where the accesscode was
  already invalidated and that belong to the batch given by the
  arguments.

  Note, that the set returned for efficiency reasons returns a set of
  catalog entries (int id mappings) and not the access-code objects
  themselves.

:func:`invalidated_num`
-----------------------

.. function:: invalidated_num(batch_prefix, batch_num)

  Get number of accesscodes found by `search_invalidated` for the
  batch specified by arguments.

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...]

We can lookup catalog entries refering to invalidated accesscodes:

    >>> from waeup.sirp.accesscodes.catalog import search_invalidated
    >>> r2 = search_invalidated(batch.prefix, batch.num)
    >>> list(r2)
    []

And also lookup the number of entries:

    >>> from waeup.sirp.accesscodes.catalog import invalidated_num
    >>> invalidated_num(batch.prefix, batch.num)
    0

When we invalidate an accesscode, we will get different results:

    >>> import grok
    >>> ac0 = list(r1)[0]
    >>> ac0.invalidation_date = datetime.now()

We have to fire an ObjectModifiedEvent in order to inform the
component architechture about the changed status of the object:

    >>> grok.notify(grok.ObjectModifiedEvent(ac0))

    >>> invalidated_num(batch.prefix, batch.num)
    1