:mod:`waeup.sirp.university.certificate` -- Certificates for WAeUP
******************************************************************

.. module:: waeup.sirp.university.certificate

Components that represent and manage certificates.

.. :doctest:
.. :layer: waeup.sirp.testing.WAeUPSIRPUnitTestLayer


Content Classes (models and containers)
=======================================


:class:`Certificate`
--------------------

.. class:: Certificate([code=u'NA',[ title=u'Unnamed Certificate',[ study_mode=None,[ start_level=None,[ end_level=None,[ application_category=None,[ m_prefix=u'']]]]]]])

   Create a certificate object with the given parameters.

   .. attribute:: grok.implements(ICertificate)

   All parameters are optional:

     >>> from waeup.sirp.university.certificate import Certificate
     >>> mycertificate = Certificate()

   Certificates have the attributes required by the `ICertificate` interface:

     >>> from waeup.sirp.university.interfaces import ICertificate
     >>> ICertificate.providedBy(mycertificate)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(ICertificate, mycertificate)
     True

   Beside the attributes, certificates are containers for
   certificate-courses (see :class:`CertificateCourse`). Each
   certificate course can be accessed by the code of the course it wraps.

   .. attribute:: title

      Each certificate has a title:

        >>> mycertificate.title
        u'Unnamed Certificate'

   .. attribute:: code

      Each certificate holds a code, which might be a shortcut or
      abbreviation of the real certificate name. By default the code
      is ``NA`` (=not assigned):

        >>> mycertificate.code
        u'NA'


   .. attribute:: study_mode

      Each :class:`Certificate` instance has a study mode:

        >>> print mycertificate.study_mode
        None

      .. XXX: This is not a proper description

   .. attribute:: start_level

      Each :class:`Certificate` instance has a start level:

        >>> print mycertificate.start_level
        None

      .. XXX: This is not a proper description

   .. attribute:: end_level

      Each :class:`Certificate` instance has a end level:

        >>> print mycertificate.end_level
        None

      .. XXX: This is not a proper description
   

   .. attribute:: application_category

      Each :class:`Certificate` instance has an application category:

        >>> print mycertificate.application_category
        None

      .. XXX: This is not a proper description

   .. method:: addCourseRef(course[, level=100,[ core_or_elective=True]])

      Add a referrer of a course. A course is an object implementing
      :class:`waeup.sirp.interfaces.ICourse`.

      Please don't be confused by the term 'referrer'. As course objects 
      will normaly be  stored
      in a department, the course referrer refers to 
      the 'real' course in the department container.

   .. method:: delCourseRef(code)

      Remove a course referrer from a certificate.

      The referrer must be given by its code number.

:class:`CertificateCourse`
--------------------------

.. class:: CertificateCourse(course[, level=100[, core_or_elective=True]])

   Create a course referrer.

   A certificate course (old term) or course referrer are held in
   certificates and refer to an existing :class:`Course` instance held
   elsewhere.

   A certificate can require several course referrers and one
   course referrer can be required by several certificates.

   .. attribute:: course

      An instance of :class:`ICourse`.

   .. attribute:: level

      An integer telling the level to which this course applies.

   .. attribute:: core_or_elective

      A bool stating whether this course is required or optional to
      get the certificate.



Utilities
=========

:class:`CertificateFactory`
---------------------------

.. class:: CertificateFactory()

   .. attribute:: grok.name(u'waeup.Certificate')

   .. attribute:: grok.implements(IFactory)

   A named utility to deliver new instances of :class:`Certificate`
   without the need to import the implementation before:

     >>> from zope.component import createObject
     >>> mycertificate = createObject(u'waeup.Certificate')
     >>> mycertificate
     <waeup.sirp.university.certificate.Certificate object at 0x...>

   The factory complies with the specifications from the
   :class:`IFactory` insterface:

     >>> from zope.interface.verify import verifyClass
     >>> from zope.component.interfaces import IFactory
     >>> from waeup.sirp.university.certificate import CertificateFactory
     >>> verifyClass(IFactory, CertificateFactory)
     True

   This means also, that we can get the interfaces of the created
   object from the factory:

     >>> certificate_factory = CertificateFactory()
     >>> certificate_factory.getInterfaces()
     <implementedBy waeup.sirp.university.certificate.Certificate>


:class:`CertificateCourseFactory`
---------------------------------

.. class:: CertificateCourseFactory()

   .. attribute:: grok.name(u'waeup.CertificateCourse')

   .. attribute:: grok.implements(IFactory)

   A named utility to deliver new instances of :class:`CertificateCourse`
   without the need to import the implementation before:

     >>> from zope.component import createObject
     >>> mycertificatecourse = createObject(u'waeup.CertificateCourse')
     >>> mycertificatecourse
     <waeup.sirp.university.certificate.CertificateCourse object at 0x...>

   The factory complies with the specifications from the
   :class:`IFactory` insterface:

     >>> from zope.interface.verify import verifyClass
     >>> from zope.component.interfaces import IFactory
     >>> from waeup.sirp.university.certificate import CertificateCourseFactory
     >>> verifyClass(IFactory, CertificateCourseFactory)
     True

   This means also, that we can get the interfaces of the created
   object from the factory:

     >>> certcourse_factory = CertificateCourseFactory()
     >>> certcourse_factory.getInterfaces()
     <implementedBy waeup.sirp.university.certificate.CertificateCourse>


Event Subscribers
=================

.. function:: removedCourseHandler(course, event)

   An event subscriber triggered for
   :class:`grok.IObjectRemovedEvent`s, when an :class:`ICourse`
   instance is removed from a container.

   Tries to remove all referring :class:`CertificateCourse`
   instances that refer to a removed course.

   To accomplish that, the parents of the removed course are looked up
   for a certifcate container which contains a course referrer that
   refers to the deleted course.

   .. seealso:: :ref:`removecertificatecourses`

   **handles:**
     :class:`ICourse`

   **event type:**
     :class:`grok.IObjectRemovedEvent`

Examples
========

Certificates
------------

We can create certificates:

    >>> from waeup.sirp.university.certificate import Certificate
    >>> mycertificate = Certificate()
    >>> mycertificate
    <waeup.sirp.university.certificate.Certificate object at 0x...>

Another way to create certificates is by asking for a factory called
``waeup.Certificate``. This way we can create a factory without
importing a class:

    >>> from zope.component import createObject
    >>> mycertificate = createObject(u'waeup.Certificate')
    >>> mycertificate
    <waeup.sirp.university.certificate.Certificate object at 0x...>

CertificateCourses
------------------

:class:`CertificateCourse` instances comply with the
:class:`ICertificateCourse` interface:

    >>> from waeup.sirp.university.interfaces import ICertificateCourse
    >>> from waeup.sirp.university.certificate import CertificateCourse
    >>> mycertcourse = CertificateCourse(None, 200, False)
    >>> ICertificateCourse.providedBy(mycertcourse)
    True

    >>> from zope.interface.verify import verifyObject
    >>> verifyObject(ICertificateCourse, mycertcourse)
    True

Also instances of :class:`CertificateCourse` can be created by asking
the component architechture:

    >>> from zope.component import createObject
    >>> mycertcourse = createObject(u'waeup.CertificateCourse')
    >>> mycertcourse
    <waeup.sirp.university.certificate.CertificateCourse object at 0x...>

.. _removecertificatecourses:

Persistence of certificate courses
----------------------------------

If a certificate course requires a certain course and this is course
is deleted, also the referring certificate course is deleted.

We setup a data structure that reflects typical usage. It looks like
this::

    Department-Instance
    |
    +---> courses
    |        |
    |        +--------------------> Course-Instance
    |                                        ^
    +---> certificates                       |
             |                               |
             +-----> Certificate-Instance    |
                        |                    |
                        +------> Certificate-Course

The certifcate-Course here refers to a Course-Instance.

In Python we build such a structure like this (from top to bottom):

    >>> from zope.component import createObject
    >>> mydept = createObject('waeup.Department')

In real world use this data will be stored in a ZODB. We setup our own
litte ZODB backend (which is easy!):

    >>> from ZODB import FileStorage, DB
    >>> dbpath = 'tinyData.fs'
    >>> class TinyZODB(object):
    ...   def __init__(self, path=dbpath):
    ...     self.storage = FileStorage.FileStorage(path)
    ...     self.db = DB(self.storage)
    ...     self.connection = self.db.open()
    ...     self.dbroot = self.connection.root()
    ...   def close(self):
    ...     self.connection.close()
    ...     self.db.close()
    ...     self.storage.close()

Now we can use this ZODB as backend database and store our data
structure:

    >>> import transaction
    >>> db = TinyZODB()
    >>> dbroot = db.dbroot
    >>> dbroot['mydept'] = mydept
    >>> mycourse = createObject('waeup.Course')
    >>> mycourse.code = 'MYCOURSE'
    >>> mydept.courses.addCourse(mycourse)
    >>> mycert = createObject('waeup.Certificate')
    >>> mycert.code = 'MYCERT'
    >>> mydept.certificates.addCertificate(mycert)
    >>> mycert.addCourseRef(mycourse)

    >>> transaction.commit()

The data is now stored in the ZODB. We can close the DB, reopen it
later and the data will still be there:

    >>> db.close()
    >>> newdb = TinyZODB()
    >>> newdbroot = newdb.dbroot
    >>> list(newdbroot)
    ['mydept']

The course referrer we stored in the certificate is indeed a
referrer of the course, not a copy of it:

    >>> course = newdbroot['mydept'].courses['MYCOURSE']
    >>> certcourse = newdbroot['mydept'].certificates['MYCERT']['MYCOURSE_100']
    >>> certcourse.course is course
    True

So, we can be sure that modifications to the course are immediately
reflected in the certcourse.