:mod:`waeup.sirp.university.faculty` -- Faculties
*************************************************

.. module:: waeup.sirp.university.faculty

Components that represent university faculties.

:Test-Layer: unit

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

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

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


:class:`Faculty`
----------------

.. class:: Faculty(title=u'Unnamed Faculty'[, title_prefix=u'faculty' [, code=u"NA"]])

   Create a representation of a university faculty:

     >>> from waeup.sirp.university.faculty import Faculty
     >>> myfac = Faculty()
     >>> myfac
     <waeup.sirp.university.faculty.Faculty object at 0x...>

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

     >>> from zope.component import createObject
     >>> myfac = createObject(u'waeup.Faculty')
     >>> myfac
     <waeup.sirp.university.faculty.Faculty object at 0x...>

   :class:`Faculty` instances have the attributes required by the
   `IFaculty` interface:

     >>> from waeup.sirp.interfaces import IFaculty
     >>> IFaculty.providedBy(myfac)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(IFaculty, myfac)
     True

   .. method:: addDepartment(department)

      Add a department into this faculty. Faculties are containers for
      departments. Added objects are checked and only `IDepartment`
      objects accepted:

        >>> myfac.addDepartment(object())
        Traceback (most recent call last):
        ...
        TypeError: Faculties contain only IDepartment instances

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

      Regular departments are accepted:

        >>> from waeup.sirp.university.department import Department
        >>> myfac.addDepartment(Department(title='Physics',
        ...                                code='DP'))

        >>> list(myfac.items())
        [(u'DP', <waeup.sirp.university.department.Department object at 0x...>)]

   .. method:: clear()

      Remove all departments from this faculty:

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

   .. attribute:: title

      (string) The title of a faculty.

      Each faculty has a title:

        >>> myfac.title
        u'Unnamed Faculty'


   .. attribute:: title_prefix

      (string) The prefix of a faculty.

      Each faculty has a title prefix, which specifies the kind of
      institution:

        >>> myfac.title_prefix
        u'faculty'


   .. attribute:: code

      (string) An internally used unique code string.

      Each faculty holds a code, which might be a shortcut or
      abbreviation of the real faculty name. By default the code is
      ``NA`` (=not assigned):

        >>> myfac.code
        u'NA'


Utilities
=========

:class:`FacultyFactory`
--------------------------

.. class:: FacultyFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> myfaculty = createObject(u'waeup.Faculty')
     >>> myfaculty
     <waeup.sirp.university.faculty.Faculty 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.faculty import FacultyFactory
     >>> verifyClass(IFactory, FacultyFactory)
     True

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

     >>> faculty_factory = FacultyFactory()
     >>> faculty_factory.getInterfaces()
     <implementedBy waeup.sirp.university.faculty.Faculty>


Examples:
=========

We can create faculties:

    >>> from waeup.sirp.university.faculty import Faculty
    >>> myfaculty = Faculty()
    >>> myfaculty
    <waeup.sirp.university.faculty.Faculty object at 0x...>

Another way to create faculties is by asking for a factory called
``waeup.Faculty``. Now we can create a factory without importing a
class:

    >>> from zope.component import createObject
    >>> myfaculty = createObject(u'waeup.Faculty')
    >>> myfaculty
    <waeup.sirp.university.faculty.Faculty object at 0x...>

Faculty attributes
==================

Faculties have the attributes required by the `IFaculty` interface:

    >>> from waeup.sirp.interfaces import IFaculty
    >>> IFaculty.providedBy(myfaculty)
    True

    >>> from zope.interface.verify import verifyObject
    >>> verifyObject(IFaculty, myfaculty)
    True

Each of the following attributes is mandatory.

`title`
-------

Each faculty has a title:

    >>> myfaculty.title
    u'Unnamed Faculty'

`title_prefix`
--------------

Each faculty has a title prefix, which specifies the kind of
institution:

    >>> myfaculty.title_prefix
    u'faculty'

`code`
------

Each faculty holds a code, which might be a shortcut or abbreviation
of the real faculty name. By default the code is ``NA`` (=not assigned):

    >>> myfaculty.code
    u'NA'