Add more complete function docstrings

bzr-revno: 18.2.12

1 files changed, 83 insertions, 23 deletions

diff --git a/mfdiff b/mfdiff
index 5c818c2..2829d4b 100755
--- a/mfdiff
+++ b/mfdiff
@@ -210,32 +210,61 @@ def get_cache(cache_d):
 
 
 def render_block(block):
- "Render a changelog block to something printable (dropping blank lines)"
+ """
+ Render a changelog block to something printable (dropping blank lines)
+
+ :param :class:`debian.changelog.ChangeBlock` block: Changelog block
+ :return: String containing the changelog block text
+ :rtype: str
+ """
 return '\n'.join([x.encode('ascii', 'replace').decode('ascii')
 for x in block.changes() if x])
 
 
 def print_blocks(blist):
- "Print a Changelog blocklist"
+ """
+ Print a Changelog blocklist
+
+ :param list blist: List of :class:`debian.changelog.ChangeBlock`
+ """
+
 for block in blist:
 print(render_block(block))
 
 
-def kernel_fixups(h_from, h_to):
- # fix up kernels so the pkg names match
+def kernel_fixups(manifest_from, manifest_to):
+ """
+ Fix up kernels so the pkg names match
+
+ Kernel package names change from release to release so that they are
+ coinstallable, but we need to find matching package names in the
+ two manifests to provide a list of changes between the versions of the
+ package in each manifest.
+ This function will return an altered version of manifest_from with kernel
+ package names changed to match kernel package names in manifest_to. This
+ will support later version comparisons.
+
+ :param dict manifest_from: Dictionary mapping package to version for of
+ the starting manifest
+ :param dict manifest_to: Dictionary mapping package to version for the
+ ending manifest
+ :return: Starting manifest dictionary with altered kernel package names
+ to match names in ending manifest
+ :rtype dict:
+ """
 kfixups = {}
 kmatch = re.compile("linux-image-[0-9]")
- for pkg in h_to:
+ for pkg in manifest_to:
 # if this is a linux-image-* binary package do some hacks to make it
- # look like h_from is the same (format like
+ # look like manifest_from is the same (format like
 # linux-image-2.6.32-32-virtual)
 if kmatch.match(pkg):
 logging.debug('Found kernel %s in manifest #2', pkg)
 img_type = pkg[pkg.rfind("-") + 1:]
- if pkg in h_from:
+ if pkg in manifest_from:
 logging.debug('Found same kernel in manifest #1')
 continue
- for fpkg in h_from:
+ for fpkg in manifest_from:
 if kmatch.match(fpkg) and fpkg.endswith("-%s" % img_type):
 logging.debug('Found similar kernel %s in manifest #1',
 fpkg)
@@ -244,13 +273,13 @@ def kernel_fixups(h_from, h_to):
 for pkg_to, pkg_from in iteritems(kfixups):
 logging.debug('Substituting kernel %s for %s in manifest #1 to '
 'enable version comparison', pkg_to, pkg_from)
- h_from[pkg_to] = h_from[pkg_from]
- del h_from[pkg_from]
- return h_from
+ manifest_from[pkg_to] = manifest_from[pkg_from]
+ del manifest_from[pkg_from]
+ return manifest_from
 
 
 def find_added(h_from, h_to):
- # find new packages in mf2
+ "Find new packages in h_to"
 new = {}
 for pkg in sorted(viewkeys(h_to) - viewkeys(h_from)):
 logging.debug('New package: %s', pkg)
@@ -259,7 +288,7 @@ def find_added(h_from, h_to):
 
 
 def find_removed(h_from, h_to):
- # find packages removed from mf1
+ "Find packages removed from h_from"
 removed = {}
 for pkg in sorted(viewkeys(h_from) - viewkeys(h_to)):
 logging.debug('Removed package: %s', pkg)
@@ -268,7 +297,7 @@ def find_removed(h_from, h_to):
 
 
 def find_changed(h_from, h_to):
- # find modified packages
+ "Find modified packages"
 changed = []
 for pkg in sorted(viewkeys(h_from) & viewkeys(h_to)):
 if h_from[pkg] != h_to[pkg]:
@@ -278,7 +307,7 @@ def find_changed(h_from, h_to):
 
 
 def map_source_to_binary(cache, packages):
- # Create a dictionary of source to list of binary packages
+ "Create a dictionary of source to list of binary packages"
 src2bins = {}
 for bin_pkg in packages:
 bin_name = bin_pkg.split(':')[0]
@@ -288,7 +317,7 @@ def map_source_to_binary(cache, packages):
 
 
 def get_pkg_versions(cache, binary):
- # Get all known versions from the apt cache
+ "Get all known versions from the apt cache"
 pkg_name = binary.split(':')[0]
 try:
 return cache[pkg_name].versions
@@ -299,7 +328,7 @@ def get_pkg_versions(cache, binary):
 
 
 def source_version_for_binary(cache, binary, binary_ver):
- # Find the source version data for a specific binary version
+ "Find the source version data for a specific binary version"
 versions = get_pkg_versions(cache, binary)
 try:
 return versions[binary_ver].source_version
@@ -312,7 +341,21 @@ def source_version_for_binary(cache, binary, binary_ver):
 
 
 def filter_changelog(changelog_path, version_start, version_end):
- # Filter changelog contents for version range
+ """
+ Extract changelog entries within a version range
+
+ The range of changelog entries returned will include all entries
+ after version_start up to, and including, version_end.
+ If either the starting or ending version are not found in the
+ list of changelog entries the result will be incoplete and
+ a non-empty erorr message is returned to indicate the issue.
+
+
+ :param str changelog_path: File name of the changelog to process
+ :return: list of changelog blocks and an error_msg if incomplete
+ :rtype list:
+ """
+
 chlog = Changelog(filecontents(changelog_path))
 change_blocks = []
 start = False
@@ -332,14 +375,25 @@ def filter_changelog(changelog_path, version_start, version_end):
 version_start, changelog_path)
 logging.error(error_msg)
 if not end:
- error_msg = "Missing ending version {} in {}. " \
- "Changelog output truncated".format(
- version_end, changelog_path)
+ if error_msg:
+ # Start and end were not found, put a newline between their
+ # erorr messages
+ error_msg += '\n'
+ error_msg += "Missing ending version {} in {}. " \
+ "Changelog output truncated".format(
+ version_end, changelog_path)
 logging.error(error_msg)
 return change_blocks, error_msg
 
 
 def parse_args():
+ """
+ Parse commandline arguments
+
+ :returns: options and remaining arguments from OptionParser.parse_args()
+ :rtype list:
+ """
+
 parser = OptionParser(usage="Usage: {} suite arch manifest1 manifest2\n"
 "Compare two manifest files, and show "
 "changelog differences."
@@ -358,8 +412,14 @@ def parse_args():
 return options, args
 
 
-def setup_logging(loglevel):
- # By default, log WARNING and higher messages
+def setup_logging(loglevel=0):
+ """
+ Configure logging
+
+ By default, log WARNING and higher messages
+ :param int: loglevel 0: Warning, 1: Info, 2: Debug
+ """
+
 loglevel = [logging.WARNING,
 logging.INFO,
 logging.DEBUG][min(2, loglevel)]