: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.university.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:`AcademicsPlugin`
------------------------

.. class:: AcademicsPlugin()

   .. attribute:: grok.implements(IWAeUPSIRPPluggable)

   This plugin component tells under which name (``faculties``) an
   instance of academics stuff should be created in plain WAeUP SIRP
   instances. It also tells the factory name for FacultyContainer
   instances, which serve as root object for academics stuff in WAeUP
   SIRP apps.


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