:mod:`waeup.university.department` -- Departments
*************************************************

.. module:: waeup.university.department

Components that represent university departments.

:Test-Layer: unit

Before we can create departments, 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:`Department`
-------------------

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

   Create a representation of a university department:

     >>> from waeup.university.department import Department
     >>> mydept = Department()
     >>> mydept
     <waeup.university.department.Department object at 0x...>

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

     >>> from zope.component import createObject
     >>> mydept = createObject(u'waeup.Department')
     >>> mydept
     <waeup.university.department.Department object at 0x...>

   :class:`Department` instances have the attributes required by the
   `IDepartment` interface:

     >>> from waeup.interfaces import IDepartment
     >>> IDepartment.providedBy(mydept)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(IDepartment, mydept)
     True


   .. attribute:: title

      (string) The title of a department.

      Each department has a title:

        >>> mydept.title
        u'Unnamed Department'


   .. attribute:: title_prefix

      (string) The prefix of a department.

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

        >>> mydept.title_prefix
        u'department'


   .. attribute:: code

      (string) An internally used unique code string.

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

        >>> mydept.code
        u'NA'


   .. attribute:: courses

      (ICourseContainer instance) A container for courses.

      Each department has a courses container:

        >>> mydept.courses
        <waeup.university.coursecontainer.CourseContainer object at 0x...>


   .. attribute:: certificates

      (ICertificateContainer instance) A container for certificates.

      Each department has a certificate container, that holds the
      descrtiptions of certificates the department has:

        >>> mydept.certificates
        <waeup...certificatecontainer.CertificateContainer object at 0x...>

Utilities
=========

:class:`DepartmentFactory`
--------------------------

.. class:: DepartmentFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> mydepartment = createObject(u'waeup.Department')
     >>> mydepartment
     <waeup.university.department.Department 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.department import DepartmentFactory
     >>> verifyClass(IFactory, DepartmentFactory)
     True

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

     >>> department_factory = DepartmentFactory()
     >>> department_factory.getInterfaces()
     <implementedBy waeup.university.department.Department>