source: main/waeup.kofa/trunk/src/waeup/kofa/doctests/facultiescontainer.txt @ 17650

Last change on this file since 17650 was 12951, checked in by Henrik Bettermann, 9 years ago

Simplify headlines in doctests. Remove some API documentation.

File size: 5.5 KB
RevLine 
[12951]1Faculty Containers
2******************
[3923]3
[7811]4.. module:: waeup.kofa.university.facultiescontainer
[3923]5
[4977]6Components that represent faculty containers.
7
[5140]8.. :doctest:
[7819]9.. :layer: waeup.kofa.testing.KofaUnitTestLayer
[3923]10
11
[4977]12Content Classes (models and containers)
13=======================================
14
[7333]15:class:`FacultiesContainer`
16---------------------------
[4977]17
[7333]18.. class:: FacultiesContainer()
[4977]19
20   Create a faculty container:
21
[7811]22     >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
[7333]23     >>> mycontainer = FacultiesContainer()
[4977]24     >>> mycontainer
[7811]25     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
[4977]26
[7333]27   Another way to create :class:`FacultiesContainer` instances is by asking
28   for a factory called ``waeup.FacultiesContainer``. This way we can create a
[4977]29   faculty without importing a class:
30
31     >>> from zope.component import createObject
[7333]32     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
[4977]33     >>> mycontainer
[7811]34     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
[4977]35
[7333]36   :class:`FacultiesContainer` instances have the attributes required by the
37   `IFacultiesContainer` interface:
[4977]38
[7811]39     >>> from waeup.kofa.university.interfaces import IFacultiesContainer
[7333]40     >>> IFacultiesContainer.providedBy(mycontainer)
[4977]41     True
42
43     >>> from zope.interface.verify import verifyObject
[7333]44     >>> verifyObject(IFacultiesContainer, mycontainer)
[4977]45     True
46
47   .. method:: addFaculty(faculty)
48
49      Add a faculty into this container. Added objects are checked and
50      only `IFaculty` objects accepted:
51
52        >>> mycontainer.addFaculty(object())
53        Traceback (most recent call last):
54        ...
[7333]55        TypeError: FacultiesContainers contain only IFaculty instances
[4977]56
57        >>> list(mycontainer.values())
58        []
59
60      Regular faculties are accepted:
61
[7811]62        >>> from waeup.kofa.university.faculty import Faculty
[4977]63        >>> mycontainer.addFaculty(Faculty(title='Physics',
64        ...                                code='FP'))
65
66        >>> list(mycontainer.items())
[7811]67        [(u'FP', <waeup.kofa.university.faculty.Faculty object at 0x...>)]
[4977]68
69
70
71Utilities
72=========
73
[5015]74:class:`AcademicsPlugin`
75------------------------
76
77.. class:: AcademicsPlugin()
78
[7819]79   .. attribute:: grok.implements(IKofaPluggable)
[5015]80
81   This plugin component tells under which name (``faculties``) an
[7819]82   instance of academics stuff should be created in plain Kofa
[7333]83   instances. It also tells the factory name for FacultiesContainer
[7819]84   instances, which serve as root object for academics stuff in Kofa apps.
[5015]85
86
[7333]87:class:`FacultiesContainerFactory`
88----------------------------------
[4977]89
[7333]90.. class:: FacultiesContainerFactory()
[4977]91
[7333]92   .. attribute:: grok.name(u'waeup.FacultiesContainer')
[4977]93
94   .. attribute:: grok.implements(IFactoryContainer)
95
[7333]96   A named utility to deliver new instances of :class:`FacultiesContainer`
[4977]97   without the need to import the implementation before:
98
99     >>> from zope.component import createObject
[7333]100     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
[4977]101     >>> mycontainer
[7811]102     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
[4977]103
104   The factory complies with the specifications from the
105   :class:`IFactory` insterface:
106
107     >>> from zope.interface.verify import verifyClass
108     >>> from zope.component.interfaces import IFactory
[7811]109     >>> from waeup.kofa.university.facultiescontainer import (
[7333]110     ...   FacultiesContainerFactory)
111     >>> verifyClass(IFactory, FacultiesContainerFactory)
[4977]112     True
113
114   This means also, that we can get the interfaces of the created
115   object from the factory:
116
[7333]117     >>> fac_container_factory = FacultiesContainerFactory()
[4977]118     >>> fac_container_factory.getInterfaces()
[7811]119     <implementedBy waeup.kofa.university.facultiescontainer.FacultiesContainer>
[4977]120
121Examples
122========
123
[7333]124We can easily create `FacultiesContainers`:
[4977]125
[7811]126    >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
[7333]127    >>> mycontainer = FacultiesContainer()
[3923]128
[7333]129Faculty containers provide `IFacultiesContainer`:
[3923]130
[7811]131    >>> from waeup.kofa.university.interfaces import IFacultiesContainer
[7333]132    >>> IFacultiesContainer.providedBy(mycontainer)
[3923]133    True
134
[4080]135Another way to get a faculty container -- without importing the class
136-- is via factories. We registered a factory for faculty containers
[7333]137under the name ``waeup.facultiescontainer``:
[3923]138
[4080]139    >>> from zope.component import createObject
[7333]140    >>> createObject(u'waeup.FacultiesContainer')
[7811]141    <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
[3923]142
[7333]143This way we get a thing that implements IFacultiesContainer without
[3923]144imports or similar.
145
146We can be sure, that the full interface is supported by the
[7333]147FacultiesContainer class::
[3923]148
149    >>> from zope.interface.verify import verifyClass
[7333]150    >>> verifyClass(IFacultiesContainer, FacultiesContainer)
[3923]151    True
152
153
154Storing things in faculty containers
155====================================
156
157We can, of course, store things in a faculty container. But when we
158really store an object, then it must be a faculty::
159
160    >>> mycontainer.addFaculty(42)
161    Traceback (most recent call last):
162    ...
[7333]163    TypeError: FacultiesContainers contain only IFaculty instances
[3923]164
165Okay, so we have to get a faculty first::
166
[7811]167    >>> from waeup.kofa.university.faculty import Faculty
[3923]168    >>> myfaculty = Faculty()
169
170We can add this faculty to our container::
171
172    >>> mycontainer.addFaculty(myfaculty)
173
[3924]174We get back the key, under which the faculty was stored. It will be
175some string, but there is no guarantee at all, how this key looks
176like. It might be a string of integers, a name or whatever; you cannot
177know before.
[4162]178
Note: See TracBrowser for help on using the repository browser.