:mod:`waeup.sirp.university.facultycontainer` -- Faculty Containers
*******************************************************************

.. module:: waeup.sirp.university.facultycontainer

Components that represent faculty containers.

:Test-Layer: unit

Before we can create faculty containers, we have to grok the
:mod:`waeup.sirp` package. This happens automatically in real-world
use:

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


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

:class:`FacultyContainer`
-------------------------

.. class:: FacultyContainer()

   Create a faculty container:

     >>> from waeup.sirp.university.facultycontainer import FacultyContainer
     >>> mycontainer = FacultyContainer()
     >>> mycontainer
     <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>

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

     >>> from zope.component import createObject
     >>> mycontainer = createObject(u'waeup.FacultyContainer')
     >>> mycontainer
     <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>

   :class:`FacultyContainer` instances have the attributes required by the
   `IFacultyContainer` interface:

     >>> from waeup.sirp.interfaces import IFacultyContainer
     >>> IFacultyContainer.providedBy(mycontainer)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(IFacultyContainer, mycontainer)
     True

   .. method:: addFaculty(faculty)

      Add a faculty into this container. Added objects are checked and
      only `IFaculty` objects accepted:

        >>> mycontainer.addFaculty(object())
        Traceback (most recent call last):
        ...
        TypeError: FacultyContainers contain only IFaculty instances

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

      Regular faculties are accepted:

        >>> from waeup.sirp.university.faculty import Faculty
        >>> mycontainer.addFaculty(Faculty(title='Physics',
        ...                                code='FP'))

        >>> list(mycontainer.items())
        [(u'FP', <waeup.sirp.university.faculty.Faculty object at 0x...>)]

   .. method:: clear()

      Remove all departments from this faculty:

        >>> mycontainer.clear()
        >>> list(mycontainer.items())
        []


Utilities
=========

:class:`FacultyContainerFactory`
--------------------------------

.. class:: FacultyContainerFactory()

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

   .. attribute:: grok.implements(IFactoryContainer)

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

     >>> from zope.component import createObject
     >>> mycontainer = createObject(u'waeup.FacultyContainer')
     >>> mycontainer
     <waeup.sirp.university.facultycontainer.FacultyContainer 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.facultycontainer import (
     ...   FacultyContainerFactory)
     >>> verifyClass(IFactory, FacultyContainerFactory)
     True

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

     >>> fac_container_factory = FacultyContainerFactory()
     >>> fac_container_factory.getInterfaces()
     <implementedBy waeup.sirp.university.facultycontainer.FacultyContainer>

Examples
========

We can easily create `FacultyContainers`:

    >>> from waeup.sirp.university.facultycontainer import FacultyContainer
    >>> mycontainer = FacultyContainer()

Faculty containers provide `IFacultyContainer`:

    >>> from waeup.sirp.interfaces import IFacultyContainer
    >>> IFacultyContainer.providedBy(mycontainer)
    True

Another way to get a faculty container -- without importing the class
-- is via factories. We registered a factory for faculty containers
under the name ``waeup.facultycontainer``:

    >>> from zope.component import createObject
    >>> createObject(u'waeup.FacultyContainer')
    <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>

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

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

    >>> from zope.interface.verify import verifyClass
    >>> verifyClass(IFacultyContainer, FacultyContainer)
    True


Storing things in faculty containers
====================================

We can, of course, store things in a faculty container. But when we
really store an object, then it must be a faculty::

    >>> mycontainer.addFaculty(42)
    Traceback (most recent call last):
    ...
    TypeError: FacultyContainers contain only IFaculty instances

Okay, so we have to get a faculty first::

    >>> from waeup.sirp.university.faculty import Faculty
    >>> myfaculty = Faculty()

We can add this faculty to our container::

    >>> mycontainer.addFaculty(myfaculty)

We get back the key, under which the faculty was stored. It will be
some string, but there is no guarantee at all, how this key looks
like. It might be a string of integers, a name or whatever; you cannot
know before.