source: waeup/branches/ulif-rewrite/src/waeup/university/certificate.txt @ 4317

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

Components that represent and manage certificates.

:Test-Layer: unit

Because certificates make use of components registered with the Zope
Component Architecture (ZCA), we first have to grok the `waeup`
package. This happens automatically in real-world use:

    >>> import grok
    >>> grok.testing.grok('waeup')


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

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

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

   Create a certificate object with the given parameters.

   .. attribute:: grok.implements(ICertificate)

   All parameters are optional:

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

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

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

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

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

      The review state can have one of the ``checking`` states defined
      in the WAeUP workflow. These are at least the states ``checked``
      and ``unchecked``. After a certificate is created, the review
      state is ``unchecked``:

        >>> mycertificate.review_state
        'unchecked'

      .. seealso::
         :meth:`Certificate.check` -- mark a certificate as ``checked``

   .. attribute:: category

      Each :class:`Certificate` instance has a category:

        >>> print mycertificate.category
        None

      .. XXX: This is not a proper description

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

   
   .. attribute:: m_prefix

      Each :class:`Certificate` instance has an ``m_prefix``:

        >>> mycertificate.m_prefix
        u''

      .. XXX: This is not a proper description

   
   .. attribute:: max_pass

      Each :class:`Certificate` instance has a maximum number of passes:

        >>> mycertificate.max_pass
        u''

      .. XXX: This is not a proper description


   .. method:: check()

      Mark a certificate instance's review state as ``checked``:

        >>> mycertificate.review_state
        'unchecked'

        >>> mycertificate.check()
        >>> mycertificate.review_state
        'checked'

      We cannot uncheck a certificate:

        >>> mycertificate.review_state = 'init'
        Traceback (most recent call last):
        ...
        InvalidTransitionError: Transition 'init' requires 'None' 
          as source state (is: 'checked')


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.university.certificate.Certificate object at 0x...>

Examples
========


We can create certificates:

    >>> from waeup.university.certificate import Certificate
    >>> mycertificate = Certificate()
    >>> mycertificate
    <waeup.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.university.certificate.Certificate object at 0x...>