Changeset 4423 for waeup/branches/ulif-rewrite

Timestamp:

23 Jul 2009, 12:47:05 (15 years ago)

Author:

uli

Message:

Update docs and faculty tests.

File:

• waeup/branches/ulif-rewrite/src/waeup/university/faculty.txt (modified) (2 diffs)

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

@@ -1 @@
-Faculties
-*********
+:mod:`waeup.university.faculty` -- Faculties
+********************************************
+
+.. module:: waeup.university.faculty
+
+Components that represent university faculties.
 
 :Test-Layer: unit
 
-Creating faculties
-==================
+Before we can create faculties, 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:`Faculty`
+----------------
+
+.. class:: Faculty(title=u'Unnamed Faculty'[, title_prefix=u'faculty' [, code=u"NA"]])
+
+   Create a representation of a university faculty:
+
+     >>> from waeup.university.faculty import Faculty
+     >>> myfac = Faculty()
+     >>> myfac
+     <waeup.university.faculty.Faculty object at 0x...>
+
+   Another way to create :class:`Faculty` instances is by asking
+   for a factory called ``waeup.Faculty``. This way we can create a
+   faculty without importing a class:
+
+     >>> from zope.component import createObject
+     >>> myfac = createObject(u'waeup.Faculty')
+     >>> myfac
+     <waeup.university.faculty.Faculty object at 0x...>
+
+   :class:`Faculty` instances have the attributes required by the
+   `IFaculty` interface:
+
+     >>> from waeup.interfaces import IFaculty
+     >>> IFaculty.providedBy(myfac)
+     True
+
+     >>> from zope.interface.verify import verifyObject
+     >>> verifyObject(IFaculty, myfac)
+     True
+
+   .. method:: addDepartment(department)
+
+      Add a department into this faculty. Faculties are containers for
+      departments. Added objects are checked and only `IDepartment`
+      objects accepted:
+
+        >>> myfac.addDepartment(object())
+        Traceback (most recent call last):
+        ...
+        TypeError: Faculties contain only IDepartment instances
+
+        >>> list(myfac.values())
+        []
+
+      Regular departments are accepted:
+
+        >>> from waeup.university.department import Department
+        >>> myfac.addDepartment(Department(title='Physics',
+        ...                                code='DP'))
+
+        >>> list(myfac.items())
+        [(u'DP', <waeup.university.department.Department object at 0x...>)]
+
+   .. method:: clear()
+
+      Remove all departments from this faculty:
+
+        >>> myfac.clear()
+        >>> list(myfac.items())
+        []
+
+   .. attribute:: title
+
+      (string) The title of a faculty.
+
+      Each faculty has a title:
+
+        >>> myfac.title
+        u'Unnamed Faculty'
+
+
+   .. attribute:: title_prefix
+
+      (string) The prefix of a faculty.
+
+      Each faculty has a title prefix, which specifies the kind of
+      institution:
+
+        >>> myfac.title_prefix
+        u'faculty'
+
+
+   .. attribute:: code
+
+      (string) An internally used unique code string.
+
+      Each faculty holds a code, which might be a shortcut or
+      abbreviation of the real faculty name. By default the code is
+      ``NA`` (=not assigned):
+
+        >>> myfac.code
+        u'NA'
+
+
+Utilities
+=========
+
+:class:`FacultyFactory`
+--------------------------
+
+.. class:: FacultyFactory()
+
+   .. attribute:: grok.name(u'waeup.Faculty')
+
+   .. attribute:: grok.implements(IFactory)
+
+   A named utility to deliver new instances of :class:`Faculty`
+   without the need to import the implementation before:
+
+     >>> from zope.component import createObject
+     >>> myfaculty = createObject(u'waeup.Faculty')
+     >>> myfaculty
+     <waeup.university.faculty.Faculty 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.faculty import FacultyFactory
+     >>> verifyClass(IFactory, FacultyFactory)
+     True
+
+   This means also, that we can get the interfaces of the created
+   object from the factory:
+
+     >>> faculty_factory = FacultyFactory()
+     >>> faculty_factory.getInterfaces()
+     <implementedBy waeup.university.faculty.Faculty>
+
+
+Examples:
+=========
 
 We can create faculties:
@@ -15 +162 @@
 
 Another way to create faculties is by asking for a factory called
-``waeup.Faculty``. Before we can do this, we have to grok the `waeup`
-package. This happens automatically in real-world use:
-
-    >>> import grok
-    >>> grok.testing.grok('waeup')
-
-Now we can create a factory without importing a class:
+``waeup.Faculty``. Now we can create a factory without importing a
+class:
 
     >>> from zope.component import createObject