:mod:`waeup.sirp.university.course` -- Courses
**********************************************

.. module:: waeup.sirp.university.course

Components that represent 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:`Course`
---------------

.. class:: Course([code=u'NA'[, title=u'Unnamed Course'[, level=None[, credits=0[, passmark=40[, semester=1]]]]]])

   Create a course instance with the given parameters.

   .. attribute:: grok.implements(ICourse)

   All parameters are optional:

     >>> from waeup.sirp.university.course import Course
     >>> mycourse = Course()
     >>> mycourse
     <waeup.sirp.university.course.Course object at 0x...>

   Course instances have the attributes required by the
   :class:`waeup.sirp.interfaces.ICourse` interface:

     >>> from waeup.sirp.university.interfaces import ICourse
     >>> ICourse.providedBy(mycourse)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(ICourse, mycourse)
     True

   .. attribute:: title

      Each course has a title:

        >>> mycourse.title
        u'Unnamed Course'

   .. attribute:: code

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

      This value has to be unique if used in a :class:`Department`
      instance as it serves as a key:

        >>> mycourse.code
        u'NA'

   .. attribute:: passmark

      Each course holdes a passmark, which is ``40`` by default:

        >>> mycourse.passmark
        40

   .. attribute:: semester

      Each course holds a semester attribute which is ``1`` by
      default:

        >>> mycourse.semester
        1

   .. attribute:: credits

      Each course holds the number of credits that can be
      earned. Default is ``0``.

        >>> mycourse.credits
        0

   .. attribute:: level

      Courses can have a level. This attribute is not required and the
      default value is ``None``:

        >>> mycourse.level is None
        True


Utilities
=========

:class:`CourseFactory`
---------------------------

.. class:: CourseFactory()

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

   .. attribute:: grok.implements(IFactory)

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

     >>> from zope.component import createObject
     >>> mycourse = createObject(u'waeup.Course')
     >>> mycourse
     <waeup.sirp.university.course.Course 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.course import CourseFactory
     >>> verifyClass(IFactory, CourseFactory)
     True

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

     >>> course_factory = CourseFactory()
     >>> course_factory.getInterfaces()
     <implementedBy waeup.sirp.university.course.Course>

Examples
========

Creating courses
----------------

The simplest way to create a :class:`Course` instance is to import the
class and calling the constructor:

    >>> from waeup.sirp.university.course import Course
    >>> mycourse = Course()
    >>> mycourse
    <waeup.sirp.university.course.Course object at 0x...>

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

    >>> from zope.component import createObject
    >>> mycourse = createObject(u'waeup.Course')
    >>> mycourse
    <waeup.sirp.university.course.Course object at 0x...>