:mod:`waeup.university.certificatecontainer` -- Certificate containers
**********************************************************************

.. module:: waeup.university.certificatecontainer

Containers for certificates.

:Test-Layer: unit

Because this module makes use of components registered with the Zope
Component Architecture (ZCA), we first have to grok the `waeup`
package if we want to deploy it. This happens automatically in
real-world use:

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

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

:class:`CertificateContainer`
-----------------------------

.. class:: CertificateContainer()

   Create a certificate container instance.

   .. attribute:: grok.implements(ICertificateContainer)

   .. attribute:: grok.require('waeup.manageUniversity')

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

     >>> from waeup.university.certificatecontainer import CertificateContainer
     >>> mycontainer = CertificateContainer()
     >>> mycontainer
     <waeup.university.certificatecontainer.CertificateContainer object at 0x...>

   Certificate containers provide `ICertificateContainer`:

     >>> from waeup.interfaces import ICertificateContainer
     >>> ICertificateContainer.providedBy(mycontainer)
     True

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

     >>> from zope.interface.verify import verifyClass
     >>> verifyClass(ICertificateContainer, CertificateContainer)
     True

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

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

   .. method:: addCertificate(certificate)

      Add a certificate.

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

        >>> from waeup.university.certificatecontainer import (
        ...   CertificateContainer)
        >>> mycontainer = CertificateContainer()
        >>> mycontainer.addCertificate('blah')
        Traceback (most recent call last):
        ...
        TypeError: CertificateContainers contain only ICertificate instances

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

        >>> from waeup.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:`CertificateContainerFactory`
------------------------------------

.. class:: CertificateContainerFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> mycertificatecontainer = createObject(u'waeup.CertificateContainer')
     >>> mycertificatecontainer
     <waeup.university.certificatecontainer.CertificateContainer 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.university.certificatecontainer import (
     ...   CertificateContainerFactory)
     >>> verifyClass(IFactory, CertificateContainerFactory)
     True

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

     >>> certificatecontainer_factory = CertificateContainerFactory()
     >>> certificatecontainer_factory.getInterfaces()
     <implementedBy waeup.university.certificatecontainer.CertificateContainer>


Examples
========

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

We can easily create `CertificateContainers`:

    >>> from waeup.university.certificatecontainer import CertificateContainer
    >>> mycontainer = CertificateContainer()


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.CertificateContainer``. Now we can
ask for an object by calling the appropriate factory:

    >>> from zope.component import createObject
    >>> createObject(u'waeup.CertificateContainer')
    <waeup.university.certificatecontainer.CertificateContainer object at 0x...>

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