[Python-checkins] distutils2: add DistributionMetadata to apiref. fix directives in modules documentation

[tarek.ziade]

tarek.ziade pushed bfd11fb015af to distutils2:

http://hg.python.org/distutils2/rev/bfd11fb015af
changeset:   902:bfd11fb015af
user:        Gael Pasgrimaud <gael at gawel.org>
date:        Fri Jan 28 18:33:45 2011 +0100
summary:
  add DistributionMetadata to apiref. fix directives in modules documentation

files:
  distutils2/metadata.py
  docs/source/distutils/apiref.rst
  docs/source/distutils/examples.rst
  docs/source/library/distutils2.metadata.rst

diff --git a/distutils2/metadata.py b/distutils2/metadata.py
--- a/distutils2/metadata.py
+++ b/distutils2/metadata.py
@@ -181,7 +181,12 @@
 
 _UNICODEFIELDS = ('Author', 'Maintainer', 'Summary', 'Description')
 
-_MISSING = object()
+class NoDefault(object):
+    """Marker object used for clean representation"""
+    def __repr__(self):
+        return '<NoDefault>'
+
+_MISSING = NoDefault()
 
 class DistributionMetadata(object):
     """The metadata of a release.
@@ -455,7 +460,8 @@
         return value
 
     def check(self, strict=False):
-        """Check if the metadata is compliant."""
+        """Check if the metadata is compliant. If strict is False then raise if
+        no Name or Version are provided"""
         # XXX should check the versions (if the file was loaded)
         missing, warnings = [], []
 
diff --git a/docs/source/distutils/apiref.rst b/docs/source/distutils/apiref.rst
--- a/docs/source/distutils/apiref.rst
+++ b/docs/source/distutils/apiref.rst
@@ -1055,6 +1055,13 @@
    Create a file called *filename* and write *contents* (a sequence of strings
    without line terminators) to it.
 
+:mod:`distutils2.metadata` --- Metadata handling
+================================================================
+
+.. module:: distutils2.metadata
+
+.. autoclass:: distutils2.metadata.DistributionMetadata
+   :members:
 
 :mod:`distutils2.util` --- Miscellaneous other utility functions
 ================================================================
diff --git a/docs/source/distutils/examples.rst b/docs/source/distutils/examples.rst
--- a/docs/source/distutils/examples.rst
+++ b/docs/source/distutils/examples.rst
@@ -301,7 +301,7 @@
 :class:`distutils2.dist.DistributionMetadata` class and its
 :func:`read_pkg_file` method::
 
-    >>> from distutils2.dist import DistributionMetadata
+    >>> from distutils2.metadata import DistributionMetadata
     >>> metadata = DistributionMetadata()
     >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
     >>> metadata.name
diff --git a/docs/source/library/distutils2.metadata.rst b/docs/source/library/distutils2.metadata.rst
--- a/docs/source/library/distutils2.metadata.rst
+++ b/docs/source/library/distutils2.metadata.rst
@@ -2,7 +2,9 @@
 Metadata
 ========
 
-Distutils2 provides a :class:`DistributionMetadata` class that can read and
+.. module:: distutils2.metadata
+
+Distutils2 provides a :class:`~distutils2.metadata.DistributionMetadata` class that can read and
 write metadata files. This class is compatible with all metadata versions:
 
 * 1.0: :PEP:`241`
@@ -17,7 +19,7 @@
 Reading metadata
 ================
 
-The :class:`DistributionMetadata` class can be instantiated with the path of
+The :class:`~distutils2.metadata.DistributionMetadata` class can be instantiated with the path of
 the metadata file, and provides a dict-like interface to the values::
 
     >>> from distutils2.metadata import DistributionMetadata
@@ -33,7 +35,7 @@
 
 The fields that supports environment markers can be automatically ignored if
 the object is instantiated using the ``platform_dependent`` option.
-:class:`DistributionMetadata` will interpret in the case the markers and will
+:class:`~distutils2.metadata.DistributionMetadata` will interpret in the case the markers and will
 automatically remove the fields that are not compliant with the running
 environment. Here's an example under Mac OS X. The win32 dependency
 we saw earlier is ignored::

--
Repository URL: http://hg.python.org/distutils2