Changeset 4977 for main/waeup.sirp/trunk

Timestamp:

1 Feb 2010, 17:49:19 (15 years ago)

Author:

uli

Message:

Make faculty container tests compatible with real API docs.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/university/facultycontainer.txt (modified) (2 diffs)

main/waeup.sirp/trunk/src/waeup/sirp/university/facultycontainer.txt

@@ -1 @@
-FacultyContainer
-****************
+:mod:`waeup.sirp.university.facultycontainer` -- Faculty Containers
+*******************************************************************
 
-Containers for faculties.
+.. module:: waeup.sirp.university.facultycontainer
+
+Components that represent faculty containers.
 
 :Test-Layer: unit
 
-Getting a faculty container
-===========================
+Before we can create faculty containers, we have to grok the
+:mod:`waeup.sirp` package. This happens automatically in real-world
+use:
 
-We can easily create `FacultyContainers`::
+    >>> import grok
+    >>> grok.testing.grok('waeup.sirp')
+
+
+Content Classes (models and containers)
+=======================================
+
+:class:`FacultyContainer`
+-------------------------
+
+.. class:: FacultyContainer()
+
+   Create a faculty container:
+
+     >>> from waeup.sirp.university.facultycontainer import FacultyContainer
+     >>> mycontainer = FacultyContainer()
+     >>> mycontainer
+     <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>
+
+   Another way to create :class:`FacultyContainer` instances is by asking
+   for a factory called ``waeup.FacultyContainer``. This way we can create a
+   faculty without importing a class:
+
+     >>> from zope.component import createObject
+     >>> mycontainer = createObject(u'waeup.FacultyContainer')
+     >>> mycontainer
+     <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>
+
+   :class:`FacultyContainer` instances have the attributes required by the
+   `IFacultyContainer` interface:
+
+     >>> from waeup.sirp.interfaces import IFacultyContainer
+     >>> IFacultyContainer.providedBy(mycontainer)
+     True
+
+     >>> from zope.interface.verify import verifyObject
+     >>> verifyObject(IFacultyContainer, mycontainer)
+     True
+
+   .. method:: addFaculty(faculty)
+
+      Add a faculty into this container. Added objects are checked and
+      only `IFaculty` objects accepted:
+
+        >>> mycontainer.addFaculty(object())
+        Traceback (most recent call last):
+        ...
+        TypeError: FacultyContainers contain only IFaculty instances
+
+        >>> list(mycontainer.values())
+        []
+
+      Regular faculties are accepted:
+
+        >>> from waeup.sirp.university.faculty import Faculty
+        >>> mycontainer.addFaculty(Faculty(title='Physics',
+        ...                                code='FP'))
+
+        >>> list(mycontainer.items())
+        [(u'FP', <waeup.sirp.university.faculty.Faculty object at 0x...>)]
+
+   .. method:: clear()
+
+      Remove all departments from this faculty:
+
+        >>> mycontainer.clear()
+        >>> list(mycontainer.items())
+        []
+
+
+Utilities
+=========
+
+:class:`FacultyContainerFactory`
+--------------------------------
+
+.. class:: FacultyContainerFactory()
+
+   .. attribute:: grok.name(u'waeup.FacultyContainer')
+
+   .. attribute:: grok.implements(IFactoryContainer)
+
+   A named utility to deliver new instances of :class:`FacultyContainer`
+   without the need to import the implementation before:
+
+     >>> from zope.component import createObject
+     >>> mycontainer = createObject(u'waeup.FacultyContainer')
+     >>> mycontainer
+     <waeup.sirp.university.facultycontainer.FacultyContainer 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.facultycontainer import (
+     ...   FacultyContainerFactory)
+     >>> verifyClass(IFactory, FacultyContainerFactory)
+     True
+
+   This means also, that we can get the interfaces of the created
+   object from the factory:
+
+     >>> fac_container_factory = FacultyContainerFactory()
+     >>> fac_container_factory.getInterfaces()
+     <implementedBy waeup.sirp.university.facultycontainer.FacultyContainer>
+
+Examples
+========
+
+We can easily create `FacultyContainers`:
 
     >>> from waeup.sirp.university.facultycontainer import FacultyContainer
@@ -22 +135 @@
 Another way to get a faculty container -- without importing the class
 -- is via factories. We registered a factory for faculty containers
-under the name ``waeup.facultycontainer``::
-
-    >>> import grok
-    >>> grok.testing.grok('waeup')
-
-Now we can ask for an object by calling the appropriate factory:
+under the name ``waeup.facultycontainer``:
 
     >>> from zope.component import createObject