Changeset 4364 for waeup/branches/ulif-rewrite

Timestamp:

26 Jun 2009, 12:18:29 (15 years ago)

Author:

uli

Message:

Make course container tests sphinx-aware.

File:

• waeup/branches/ulif-rewrite/src/waeup/university/coursecontainer.txt (modified) (4 diffs)

waeup/branches/ulif-rewrite/src/waeup/university/coursecontainer.txt

@@ -1 @@
-CourseContainer
-****************
+:mod:`waeup.university.coursecontainer` -- Course containers
+************************************************************
+
+.. module:: waeup.university.coursecontainer
 
 Containers for courses.
@@ -6 +8 @@
 :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.university.course.Course`.
+
+     >>> from waeup.university.coursecontainer import CourseContainer
+     >>> mycontainer = CourseContainer()
+     >>> mycontainer
+     <waeup.university.coursecontainer.CourseContainer object at 0x...>
+
+   Course containers provide `ICourseContainer`:
+
+     >>> from waeup.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.university.course.Course`:
+
+        >>> from waeup.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.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.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.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.university.coursecontainer.CourseContainer>
+
+
+Examples
+========
+
 Getting a course container
-===========================
+--------------------------
 
 We can easily create `CourseContainers`:
@@ -14 +139 @@
     >>> mycontainer = CourseContainer()
 
-Course containers provide `ICourseContainer`:
-
-    >>> from waeup.interfaces import ICourseContainer
-    >>> ICourseContainer.providedBy(mycontainer)
-    True
 
 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``::
-
-    >>> import grok
-    >>> grok.testing.grok('waeup')
-
-Now we can ask for an object by calling the appropriate factory:
+under the name ``waeup.CourseContainer``. Now we can ask for an object
+by calling the appropriate factory:
 
     >>> from zope.component import createObject
@@ -36 +152 @@
 imports or similar.
 
-We can be sure, that the full interface is supported by the
-CourseContainer class:
-
-    >>> from zope.interface.verify import verifyClass
-    >>> verifyClass(ICourseContainer, CourseContainer)
-    True
-