Changeset 7039 for main/waeup.sirp/branches/ulif-extimgstore/src

Timestamp:

8 Nov 2011, 21:13:59 (13 years ago)

Author:

uli

Message:

Update docs.

File:

• main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/applicants/applicant.py (modified) (1 diff)

main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/applicants/applicant.py

@@ -108 +108 @@
 
 class ApplicantImageNameChooser(grok.Adapter):
+    """A file id chooser for :class:`Applicant` objects.
+
+    `context` is an :class:`Applicant` instance.
+
+    The :class:`ApplicantImageNameChooser` can build/check file ids
+    for :class:`Applicant` objects suitable for use with
+    :class:`ExtFileStore` instances. The delivered file_id contains
+    the file id marker for :class:`Applicant` object and the
+    registration number or access code of the context applicant. Also
+    the name of the connected applicant container will be part of the
+    generated file id.
+
+    This chooser is registered as an adapter providing
+    :class:`waeup.sirp.interfaces.IFileStoreNameChooser`.
+
+    File store name choosers like this one are only convenience
+    components to ease the task of creating file ids for applicant
+    objects. You are nevertheless encouraged to use them instead of
+    manually setting up filenames for applicants.
+
+    .. seealso:: :mod:`waeup.sirp.imagestorage`
+
+    """
     grok.context(IApplicant)
     grok.implements(IFileStoreNameChooser)
 
     def checkName(self, name=None):
+        """Check whether the given name is a valid file id for the context.
+
+        Returns ``True`` only if `name` equals the result of
+        :meth:`chooseName`.
+        """
         return name == self.chooseName(name, self.context)
 
     def chooseName(self, name=None):
+        """Get a valid file id for applicant context.
+
+        *Example:*
+
+        For an applicant with registration no. ``'My_reg_no_1234'``
+        and stored in an applicants container called
+        ``'mycontainer'``, this chooser would create:
+
+          ``'__img-applicant__mycontainer/My_reg_no_1234.jpg'``
+
+        meaning that the passport image of this applicant would be
+        stored in the site-wide file storage in path:
+
+          ``mycontainer/My_reg_no_1234.jpg``
+
+        If the context applicant has no parent, ``'_default'`` is used
+        as parent name.
+        """
         parent_name = getattr(
             getattr(self.context, '__parent__', None),