Changeset 6240

Timestamp:

30 May 2011, 01:48:59 (13 years ago)

Author:

uli

Message:

Add docs and make setitem check for cert.code == key.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/university/certificatecontainer.py (modified) (3 diffs)

main/waeup.sirp/trunk/src/waeup/sirp/university/certificatecontainer.py

@@ -11 +11 @@
 
 class CertificateContainer(grok.Container):
-    """See interfaces for description.
+    """A storage for certificates.
+
+    A :class:`CertificateContainer` stores
+    :class:`waeup.sirp.university.Certificate` instances.
+
+    It is a :class:`grok.Container` basically acting like a standard
+    Python dictionary. That means you can add certificates like items
+    in a normal dictionary and also get certificates by using
+    :meth:`values`, :meth:`keys`, and :meth:`items`.
+
+    This container type is picky about its contents: only real
+    certificates can be stored here and each new certificate must
+    provide a unique `code`. See :meth:`addCertificate` for details.
+
+    Each :class:`CertificateContainer` provides
+    :iface:`ICertificateContainer`.
     """
     grok.implements(ICertificateContainer)
@@ -17 +32 @@
 
     def __setitem__(self, name, certificate):
-        """XXX: docstring missing.
+        """Insert `certificate` with `name` as key into container.
+
+        The certificate must be an object implementing
+        :iface:`waeup.sirp.university.interfaces.ICertificate`. If
+        not, a :exc:`TypeError` is raised.
+
+        If the certificate `code` does not equal `name` a
+        :exc:`ValueError` is raised.
+
+        If the `code` attribute of `certificate` is already in use by
+        another certificate stored in the local site
+        (:class:`waeup.sirp.app.University` instance), then a
+        :exc:`waeup.sirp.interfaces.DuplicationError` will be raised.
+
+        If `name` is already used as a key, a :exc:`KeyError` will be
+        raised.
         """
         if not ICertificate.providedBy(certificate):
             raise TypeError('CertificateContainers contain only '
                             'ICertificate instances')
+
+        # Only accept certs with code == key.
+        if certificate.code != name:
+            raise ValueError('key must match certificate code: '
+                             '%s, %s' % (name, certificate.code))
+
         # Lookup catalog. If we find none: no duplicates possible.
         cat = queryUtility(ICatalog, name='certificates_catalog', default=None)
@@ -36 +72 @@
 
     def addCertificate(self, certificate):
+        """Add `certificate` to the container.
+
+        The certificate must be an object implementing
+        :iface:`waeup.sirp.university.interfaces.ICertificate`. If
+        not, a :exc:`TypeError` is raised.
+
+        The certificate will be stored in the container with its
+        `code` attribute as key. If this key is already used for
+        another certificate stored in the local site
+        (:class:`waeup.sirp.app.University` instance), then a
+        :exc:`waeup.sirp.interfaces.DuplicationError` will be raised.
+        """
         self[getattr(certificate, 'code', None)] = certificate