[CMF-checkins] CVS: Products/CMFCore/interfaces - portal_metadata.py:1.5.10.1

[Tres Seaver]

Update of /cvs-repository/Products/CMFCore/interfaces
In directory cvs.zope.org:/tmp/cvs-serv5921/CMFCore/interfaces

Modified Files:
      Tag: tseaver-metadata_refactor-branch
	portal_metadata.py 
Log Message:


  "This time for sure!"  (on the branch)

  - CMFCore/interfaces/portal_metadata.py:

    o Normalize docstrings.

    o Documented 'listAllowedVocabulary', and noted the element-specifc
      convenience wrappers as being deprecated.

    o Add new methods, 'getContentMetadata' and 'setContentMetadata',
      through which the content objects may indirect their DublinCore
      storage.

  - CMFDefault/MetadataTool.py:

    o Docstring cleanup.

    o Implement new methods in interface, using propertysheet for storage.


  - CMFDefault/tests/test_MetadataTool.py:

    o Normalize unit tests:

      + Don't import module-under-test at module scope in the unit test
        module!

      + Use unittest helper methods, rather than bare asserts.

      + Avoid unnecessary setUp and tearDown methods.

      + Split overlong tests into smaller, more coherent pieces, with
        more descriptive names.



=== Products/CMFCore/interfaces/portal_metadata.py 1.5 => 1.5.10.1 ===
--- Products/CMFCore/interfaces/portal_metadata.py:1.5	Mon Apr 26 08:34:10 2004
+++ Products/CMFCore/interfaces/portal_metadata.py	Tue Jul 20 02:16:05 2004
@@ -29,76 +29,121 @@
     #   Site-wide queries.
     #
     def getFullName(userid):
-        """
-            Convert an internal userid to a "formal" name, if
-            possible, perhaps using the 'portal_membership' tool.
 
-            Used to map userid's for Creator, Contributor DCMI
-            queries.
+        """ Convert an internal userid to a "formal" name
+        
+        o Conversion occurs if possible, perhaps using the
+          'portal_membership' tool.
+
+        o Used to map userid's for Creator, Contributor DCMI queries.
         """
 
     def getPublisher():
-        """
-            Return the "formal" name of the publisher of the
-            portal.
+
+        """ Return the "formal" name of the publisher of the portal.
         """
 
     #
     #   Content-specific queries.
     #
-    def listAllowedSubjects(content=None):
+    def listAllowedVocabulary( element, content=None, content_type=None ):
+
+        """ List the allowed values of a given DCMI element.
+
+        o If 'content_type' is passed, include only values allowed for
+          that type.
+
+        o Else if 'content' is passed, include only values allowed for
+          its type.
+
+        o Else include all known values.
         """
-            List the allowed values of the 'Subject' DCMI element
-            'Subject' elements should be keywords categorizing
-            their resource.
 
-            Return only values appropriate for content's type, or
-            all values if None.
+    def listAllowedSubjects(content=None):
+
+        """ List the allowed values of the 'Subject' DCMI element.
+
+        o 'Subject' elements should be keywords categorizing their resource.
+
+        o Return only values appropriate for content's type, or all 
+          known values if None is passed.
+
+        o Deprecated;  please use 'listAllowedVocabulary' instead.
         """
 
     def listAllowedFormats(content=None):
-        """
-            List the allowed values of the 'Format' DCMI element.
-            These items should be usable as HTTP 'Content-type'
-            values.
 
-            Return only values appropriate for content's type, or
-            all values if None.
+        """ List the allowed values of the 'Format' DCMI element.
+
+        o These items should be usable as HTTP 'Content-type' values.
+
+        o Return only values appropriate for content's type, or all
+          known values if None is passed.
+
+        o Deprecated;  please use 'listAllowedVocabulary' instead.
         """
 
     def listAllowedLanguages(content=None):
-        """
-            List the allowed values of the 'Language' DCMI element.
-            'Language' element values should be suitable for generating
-            HTTP headers.
 
-            Return only values appropriate for content's type, or
-            all values if None.
+        """ List the allowed values of the 'Language' DCMI element.
+
+        o 'Language' element values should be suitable for generating
+          HTTP headers.
+
+        o Return only values appropriate for content's type, or all
+          known values if None is passed.
+
+        o Deprecated;  please use 'listAllowedVocabulary' instead.
         """
 
     def listAllowedRights(content=None):
-        """
-            List the allowed values of the 'Rights' DCMI element.
-            The 'Rights' element describes copyright or other IP
-            declarations pertaining to a resource.
 
-            Return only values appropriate for content's type, or
-            all values if None.
+        """ List the allowed values of the 'Rights' DCMI element.
+
+        o The 'Rights' element describes copyright or other IP
+          declarations pertaining to a resource.
+
+        o Return only values appropriate for content's type, or all
+          known values if None is passed.
+
+        o Deprecated;  please use 'listAllowedVocabulary' instead.
         """
 
     #
     #   Validation policy hooks.
     #
     def setInitialMetadata(content):
-        """
-            Set initial values for content metatdata, supplying
-            any site-specific defaults.
+
+        """ Set initial values for content metatdata.
+        
+        o Tool should suppl any site-specific defaults.
         """
 
     def validateMetadata(content):
+
+        """ Enforce portal-wide policies about DCI
+        
+        o E.g., tool may require non-empty title/description, etc.
+        
+        o Should be called by the skin methods immediately after saving
+          changes to the metadata of an object (or at workflow transitions).
         """
-            Enforce portal-wide policies about DCI, e.g.,
-            requiring non-empty title/description, etc.  Called
-            by the CMF immediately before saving changes to the
-            metadata of an object.
+
+    #
+    #   Content lookups
+    #
+    def getContentMetadata(content, element):
+
+        """ Return the given metadata element for 'content'.
+
+        o Allows indirection of the storage / format of metadata through
+          the tool.
+        """
+
+    def setContentMetadata(content, element, value):
+
+        """ Update the given metadata element for 'content'.
+
+        o Allows indirection of the storage / format of metadata through
+          the tool.
         """