more docstrings

[dak.git] / dak / make_maintainers.py

diff --git a/dak/make_maintainers.py b/dak/make_maintainers.py
index f60c19b751b0317082626f4bbb47a7357273520c..4e2fe244bb6fd911930641eebef3730fb19f9a66 100755 (executable)
--- a/dak/make_maintainers.py
+++ b/dak/make_maintainers.py
@@ -1,7 +1,12 @@
 #!/usr/bin/env python
 
-# Generate Maintainers file used by e.g. the Debian Bug Tracking System
-# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006  James Troup <james@nocrew.org>
+"""
+Generate Maintainers file used by e.g. the Debian Bug Tracking System
+@contact: Debian FTP Master <ftpmaster@debian.org>
+@copyright: 2000, 2001, 2002, 2003, 2004, 2006  James Troup <james@nocrew.org>
+@license: GNU General Public License version 2 or later
+
+"""
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -25,17 +30,20 @@
 
 ################################################################################
 
-import pg, sys
-import dak.lib.database, dak.lib.utils
+import pg
+import sys
 import apt_pkg
+from daklib import database
+from daklib import utils
+from daklib.regexes import re_comments
 
 ################################################################################
 
-projectB = None
-Cnf = None
-maintainer_from_source_cache = {}
-packages = {}
-fixed_maintainer_cache = {}
+Cnf = None                          #: Configuration, apt_pkg.Configuration
+projectB = None                     #: database connection, pgobject
+maintainer_from_source_cache = {}   #: caches the maintainer name <email> per source_id
+packages = {}                       #: packages data to write out
+fixed_maintainer_cache = {}         #: caches fixed ( L{daklib.utils.fix_maintainer} ) maintainer data
 
 ################################################################################
 
@@ -50,17 +58,42 @@ Generate an index of packages <=> Maintainers.
 ################################################################################
 
 def fix_maintainer (maintainer):
+    """
+    Fixup maintainer entry, cache the result.
+
+    @type maintainer: string
+    @param maintainer: A maintainer entry as passed to L{daklib.utils.fix_maintainer}
+
+    @rtype: tuple
+    @returns: fixed maintainer tuple
+    """
     global fixed_maintainer_cache
 
     if not fixed_maintainer_cache.has_key(maintainer):
-        fixed_maintainer_cache[maintainer] = dak.lib.utils.fix_maintainer(maintainer)[0]
+        fixed_maintainer_cache[maintainer] = utils.fix_maintainer(maintainer)[0]
 
     return fixed_maintainer_cache[maintainer]
 
 def get_maintainer (maintainer):
-    return fix_maintainer(dak.lib.database.get_maintainer(maintainer))
+    """
+    Retrieves maintainer name from database, passes it through fix_maintainer and
+    passes on whatever that returns.
+
+    @type maintainer: int
+    @param maintainer: maintainer_id
+    """
+    return fix_maintainer(database.get_maintainer(maintainer))
 
 def get_maintainer_from_source (source_id):
+    """
+    Returns maintainer name for given source_id.
+
+    @type source_id: int
+    @param source_id: source package id
+
+    @rtype: string
+    @return: maintainer name/email
+    """
     global maintainer_from_source_cache
 
     if not maintainer_from_source_cache.has_key(source_id):
@@ -75,11 +108,11 @@ def get_maintainer_from_source (source_id):
 def main():
     global Cnf, projectB
 
-    Cnf = dak.lib.utils.get_conf()
+    Cnf = utils.get_conf()
 
     Arguments = [('h',"help","Make-Maintainers::Options::Help")]
     if not Cnf.has_key("Make-Maintainers::Options::Help"):
-       Cnf["Make-Maintainers::Options::Help"] = ""
+        Cnf["Make-Maintainers::Options::Help"] = ""
 
     extra_files = apt_pkg.ParseCommandLine(Cnf,Arguments,sys.argv)
     Options = Cnf.SubTree("Make-Maintainers::Options")
@@ -88,7 +121,7 @@ def main():
         usage()
 
     projectB = pg.connect(Cnf["DB::Name"], Cnf["DB::Host"], int(Cnf["DB::Port"]))
-    dak.lib.database.init(Cnf, projectB)
+    database.init(Cnf, projectB)
 
     for suite in Cnf.SubTree("Suite").List():
         suite = suite.lower()
@@ -127,18 +160,18 @@ def main():
             else:
                 packages[package] = { "maintainer": maintainer, "priority": suite_priority, "version": version }
 
-    # Process any additional Maintainer files (e.g. from non-US or pseudo packages)
+    # Process any additional Maintainer files (e.g. from pseudo packages)
     for filename in extra_files:
-        file = dak.lib.utils.open_file(filename)
-        for line in file.readlines():
-            line = dak.lib.utils.re_comments.sub('', line).strip()
+        extrafile = utils.open_file(filename)
+        for line in extrafile.readlines():
+            line = re_comments.sub('', line).strip()
             if line == "":
                 continue
             split = line.split()
             lhs = split[0]
             maintainer = fix_maintainer(" ".join(split[1:]))
             if lhs.find('~') != -1:
-                (package, version) = lhs.split('~')
+                (package, version) = lhs.split('~', 1)
             else:
                 package = lhs
                 version = '*'
@@ -146,7 +179,7 @@ def main():
             if not packages.has_key(package) or version == '*' \
                or apt_pkg.VersionCompare(packages[package]["version"], version) < 0:
                 packages[package] = { "maintainer": maintainer, "version": version }
-        file.close()
+        extrafile.close()
 
     package_keys = packages.keys()
     package_keys.sort()
@@ -158,4 +191,3 @@ def main():
 
 if __name__ == '__main__':
     main()
-