[Zope-CVS] CVS: Packages/zpkgtools/zpkgtools - publication.py:1.5

[Fred L. Drake, Jr.]

Update of /cvs-repository/Packages/zpkgtools/zpkgtools
In directory cvs.zope.org:/tmp/cvs-serv11906

Modified Files:
	publication.py 
Log Message:
fleshed out the documentation


=== Packages/zpkgtools/zpkgtools/publication.py 1.4 => 1.5 ===
--- Packages/zpkgtools/zpkgtools/publication.py:1.4	Wed Apr  7 18:00:13 2004
+++ Packages/zpkgtools/zpkgtools/publication.py	Tue Apr 27 12:07:45 2004
@@ -16,6 +16,9 @@
 Such files include the PKG-INFO files generated by `distutils` as well
 as the PUBLICATION.cfg files used by **zpkg**.
 
+:var PUBLICATION_CONF: The default name of the file containing
+  publication data as used by **zpkg**.
+
 """
 from distutils.dist import DistributionMetadata
 from distutils.util import rfc822_escape
@@ -33,7 +36,13 @@
 # accepted.
 
 def dump(metadata, f):
-    """Write package metadata to a file in PKG-INFO format."""
+    """Write package metadata to a file in PKG-INFO format.
+
+    :param metadata: Metadata object to serialize.
+
+    :param f: Open file object to write to.
+
+    """
     print >>f, "Metadata-Version: 1.0"
     print >>f, "Name:", metadata.get_name()
     if metadata.version:
@@ -67,7 +76,14 @@
 
 
 def dumps(metadata):
-    """Return package metadata serialized in PKG-INFO format."""
+    """Return package metadata serialized in PKG-INFO format.
+
+    :return: String containing the serialized metadata.
+    :rtype: str
+
+    :param metadata: Metadata object to serialize.
+
+    """
     sio = StringIO()
     dump(metadata, sio)
     return sio.getvalue()
@@ -76,7 +92,16 @@
 def load(f, versioninfo=False, metadata=None):
     """Parse a PKG-INFO file and return a DistributionMetadata instance.
 
-    Unsupported metadata formats cause a ValueError to be raised.
+    :return: Populated metadata object.
+    :rtype: `DistributionMetadata`
+
+    :param versioninfo: Flag indicating whether version-specific
+      information should be included.
+
+    :param metadata: Metadata object which should be populated from
+      the publication data.  If omitted, a fresh
+      `DistributionMetadata` instance will be used.
+
     """
     parser = Parser()
     msg = parser.parse(f, headersonly=True)
@@ -86,7 +111,16 @@
 def loads(text, versioninfo=False, metadata=None):
     """Parse PKG-INFO source text and return a DistributionMetadata instance.
 
-    Unsupported metadata formats cause a ValueError to be raised.
+    :return: Populated metadata object.
+    :rtype: `DistributionMetadata`
+
+    :param versioninfo: Flag indicating whether version-specific
+      information should be included.
+
+    :param metadata: Metadata object which should be populated from
+      the publication data.  If omitted, a fresh
+      `DistributionMetadata` instance will be used.
+
     """
     parser = Parser()
     msg = parser.parsestr(text, headersonly=True)
@@ -128,7 +162,8 @@
 def _get_single_header(msg, name, default=None):
     """Return the value for a header that only occurs once in the input.
 
-    If the header occurs more than once, ValueError is raised.
+    :raises ValueError: If the header occurs more than once.
+
     """
     headers = msg.get_all(name)
     if headers and len(headers) > 1: