source: main/waeup.kofa/branches/0.2/src/waeup/kofa/university/certificatescontainer.txt @ 17931

:mod:`waeup.kofa.university.certificatescontainer` -- Certificate containers
****************************************************************************

.. module:: waeup.kofa.university.certificatescontainer

Containers for certificates.

.. :doctest:
.. :layer: waeup.kofa.testing.KofaUnitTestLayer


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

:class:`CertificatesContainer`
------------------------------

.. class:: CertificatesContainer()

   Create a certificate container instance.

   .. attribute:: grok.implements(ICertificatesContainer)

   :class:`CertificatesContainer` instances are instances of
   :class:`grok.Container` that hold and manage instances of
   :class:`waeup.kofa.university.certificate.Certificate`.

     >>> from waeup.kofa.university.certificatescontainer import CertificatesContainer
     >>> mycontainer = CertificatesContainer()
     >>> mycontainer
     <waeup.kofa.university.certificatescontainer.CertificatesContainer object at 0x...>

   Certificate containers provide `ICertificatesContainer`:

     >>> from waeup.kofa.university.interfaces import ICertificatesContainer
     >>> ICertificatesContainer.providedBy(mycontainer)
     True

   We can be sure, that the full interface is supported by the
   CertificatesContainer class:

     >>> from zope.interface.verify import verifyClass
     >>> verifyClass(ICertificatesContainer, CertificatesContainer)
     True

   As normal ``grok.Container``, :class:`CertificatesContainer` instances
   can be used like dicts:

     >>> list(mycontainer.keys())
     []

   .. method:: addCertificate(certificate)

      Add a certificate.

      *certificate* must be an instance of
      :class:`waeup.kofa.university.certificate.Certificate`:

        >>> from waeup.kofa.university.certificatescontainer import (
        ...   CertificatesContainer)
        >>> mycontainer = CertificatesContainer()
        >>> mycontainer.addCertificate('blah')
        Traceback (most recent call last):
        ...
        TypeError: CertificatesContainers contain only ICertificate instances

      The key of added items is the ``code`` attribute:

        >>> from waeup.kofa.university.certificate import Certificate
        >>> mycertificate = Certificate(code='CERTIFICATE1')
        >>> mycontainer.addCertificate(mycertificate)
        >>> list(mycontainer.keys())
        [u'CERTIFICATE1']

   .. method:: clear()

      Remove all contained certificates:

        >>> len(mycontainer.items())
        1

        >>> mycontainer.clear()
        >>> len(mycontainer.items())
        0

Utilities
=========

:class:`CertificatesContainerFactory`
-------------------------------------

.. class:: CertificatesContainerFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> mycertificatescontainer = createObject(u'waeup.CertificatesContainer')
     >>> mycertificatescontainer
     <waeup.kofa.university.certificatescontainer.CertificatesContainer 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.kofa.university.certificatescontainer import (
     ...   CertificatesContainerFactory)
     >>> verifyClass(IFactory, CertificatesContainerFactory)
     True

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

     >>> certificatescontainer_factory = CertificatesContainerFactory()
     >>> certificatescontainer_factory.getInterfaces()
     <implementedBy waeup.kofa.university.certificatescontainer.CertificatesContainer>


Examples
========

Getting a certificate container
-------------------------------

We can easily create `CertificatesContainers`:

    >>> from waeup.kofa.university.certificatescontainer import CertificatesContainer
    >>> mycontainer = CertificatesContainer()


Another way to get a certificate container -- without importing the
class -- is via factories. We registered a factory for certificate
containers under the name ``waeup.CertificatesContainer``. Now we can
ask for an object by calling the appropriate factory:

    >>> from zope.component import createObject
    >>> createObject(u'waeup.CertificatesContainer')
    <waeup.kofa.university.certificatescontainer.CertificatesContainer object at 0x...>

This way we get a thing that implements ICertificatesContainer without
imports or similar.