source: main/waeup.sirp/trunk/src/waeup/sirp/university/coursecontainer.txt @ 5109

:mod:`waeup.sirp.university.coursecontainer` -- Course containers
*****************************************************************

.. module:: waeup.sirp.university.coursecontainer

Containers for courses.

: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:`CourseContainer`
------------------------

.. class:: CourseContainer()

   Create a course container instance.

   .. attribute:: grok.implements(ICourseContainer)

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

   :class:`CourseContainer` instances are instances of
   :class:`grok.Container` that hold and manage instances of
   :class:`waeup.sirp.university.course.Course`.

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

   Course containers provide `ICourseContainer`:

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

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

     >>> from zope.interface.verify import verifyClass
     >>> verifyClass(ICourseContainer, CourseContainer)
     True

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

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

   .. method:: addCourse(course)

      Add a course.

      *course* must be an instance of
      :class:`waeup.sirp.university.course.Course`:

        >>> from waeup.sirp.university.coursecontainer import CourseContainer
        >>> mycontainer = CourseContainer()
        >>> mycontainer.addCourse('blah')
        Traceback (most recent call last):
        ...
        TypeError: CourseContainers contain only ICourse instances

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

        >>> from waeup.sirp.university.course import Course
        >>> mycourse = Course(code='COURSE1')
        >>> mycontainer.addCourse(mycourse)
        >>> list(mycontainer.keys())
        [u'COURSE1']

   .. method:: clear()

      Remove all contained courses:

        >>> len(mycontainer.items())
        1

        >>> mycontainer.clear()
        >>> len(mycontainer.items())
        0

Utilities
=========

:class:`CourseContainerFactory`
-------------------------------

.. class:: CourseContainerFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> mycoursecontainer = createObject(u'waeup.CourseContainer')
     >>> mycoursecontainer
     <waeup.sirp.university.coursecontainer.CourseContainer 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.coursecontainer import CourseContainerFactory
     >>> verifyClass(IFactory, CourseContainerFactory)
     True

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

     >>> coursecontainer_factory = CourseContainerFactory()
     >>> coursecontainer_factory.getInterfaces()
     <implementedBy waeup.sirp.university.coursecontainer.CourseContainer>


Examples
========

Getting a course container
--------------------------

We can easily create `CourseContainers`:

    >>> from waeup.sirp.university.coursecontainer import CourseContainer
    >>> mycontainer = CourseContainer()


Another way to get a course container -- without importing the class
-- is via factories. We registered a factory for course containers
under the name ``waeup.CourseContainer``. Now we can ask for an object
by calling the appropriate factory:

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

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