daklib/database

the first fully documented (well, docstrings, but many) file.
Signed-off-by: NJoerg Jaspert <joerg@debian.org>

daklib/database.py

 #!/usr/bin/env python
 
-""" DB access fucntions """
-# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006  James Troup <james@nocrew.org>
+""" DB access functions
+@group readonly: get_suite_id, get_section_id, get_priority_id, get_override_type_id,
+                 get_architecture_id, get_archive_id, get_component_id, get_location_id,
+                 get_source_id, get_suite_version, get_files_id, get_maintainer, get_suites
+@group read/write: get_or_set*, set_files_id
+
+@contact: Debian FTPMaster <ftpmaster@debian.org>
+@copyright: 2000, 2001, 2002, 2003, 2004, 2006  James Troup <james@nocrew.org>
+@copyright: 2009  Joerg Jaspert <joerg@debian.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,45 +34,59 @@ import types
 
 ################################################################################
 
-Cnf = None
-projectB = None
-suite_id_cache = {}
-section_id_cache = {}
-priority_id_cache = {}
-override_type_id_cache = {}
-architecture_id_cache = {}
-archive_id_cache = {}
-component_id_cache = {}
-location_id_cache = {}
-maintainer_id_cache = {}
-keyring_id_cache = {}
-source_id_cache = {}
-files_id_cache = {}
-maintainer_cache = {}
-fingerprint_id_cache = {}
-queue_id_cache = {}
-uid_id_cache = {}
-suite_version_cache = {}
+Cnf = None                    #: Configuration, apt_pkg.Configuration
+projectB = None               #: database connection, pgobject
+suite_id_cache = {}           #: cache for suites
+section_id_cache = {}         #: cache for sections
+priority_id_cache = {}        #: cache for priorities
+override_type_id_cache = {}   #: cache for overrides
+architecture_id_cache = {}    #: cache for architectures
+archive_id_cache = {}         #: cache for archives
+component_id_cache = {}       #: cache for components
+location_id_cache = {}        #: cache for locations
+maintainer_id_cache = {}      #: cache for maintainers
+keyring_id_cache = {}         #: cache for keyrings
+source_id_cache = {}          #: cache for sources
+files_id_cache = {}           #: cache for files
+maintainer_cache = {}         #: cache for maintainer names
+fingerprint_id_cache = {}     #: cache for fingerprints
+queue_id_cache = {}           #: cache for queues
+uid_id_cache = {}             #: cache for uids
+suite_version_cache = {}      #: cache for suite_versions (packages)
 
 ################################################################################
 
 def init (config, sql):
-    """ database module init. Just sets two variables"""
+    """
+    database module init.
+
+    @type config: apt_pkg.Configuration
+    @param config: apt config, see U{http://apt.alioth.debian.org/python-apt-doc/apt_pkg/cache.html#Configuration}
+
+    @type sql: pgobject
+    @param sql: database connection
+
+    """
     global Cnf, projectB
 
     Cnf = config
     projectB = sql
 
 
-def do_query(q):
+def do_query(query):
     """
-    Executes a database query q. Writes statistics to stderr and returns
-    the result.
+    Executes a database query. Writes statistics / timing to stderr.
+
+    @type query: string
+    @param query: database query string, passed unmodified
 
+    @return: db result
+
+    @warning: The query is passed B{unmodified}, so be careful what you use this for.
     """
-    sys.stderr.write("query: \"%s\" ... " % (q))
+    sys.stderr.write("query: \"%s\" ... " % (query))
     before = time.time()
-    r = projectB.query(q)
+    r = projectB.query(query)
     time_diff = time.time()-before
     sys.stderr.write("took %.3f seconds.\n" % (time_diff))
     if type(r) is int:
@@ -77,7 +100,17 @@ def do_query(q):
 ################################################################################
 
 def get_suite_id (suite):
-    """ Returns database suite_id for given suite, caches result. """
+    """
+    Returns database id for given C{suite}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type suite: string
+    @param suite: The name of the suite
+
+    @rtype: int
+    @return: the database id for the given suite
+
+    """
     global suite_id_cache
 
     if suite_id_cache.has_key(suite):
@@ -94,7 +127,17 @@ def get_suite_id (suite):
     return suite_id
 
 def get_section_id (section):
-    """ Returns database section_id for given section, caches result. """
+    """
+    Returns database id for given C{section}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type section: string
+    @param section: The name of the section
+
+    @rtype: int
+    @return: the database id for the given section
+
+    """
     global section_id_cache
 
     if section_id_cache.has_key(section):
@@ -111,7 +154,17 @@ def get_section_id (section):
     return section_id
 
 def get_priority_id (priority):
-    """ Returns database priority_id for given priority, caches result. """
+    """
+    Returns database id for given C{priority}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type priority: string
+    @param priority: The name of the priority
+
+    @rtype: int
+    @return: the database id for the given priority
+
+    """
     global priority_id_cache
 
     if priority_id_cache.has_key(priority):
@@ -128,7 +181,17 @@ def get_priority_id (priority):
     return priority_id
 
 def get_override_type_id (type):
-    """ Returns database override_id for given override_type type, caches result. """
+    """
+    Returns database id for given override C{type}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type type: string
+    @param type: The name of the override type
+
+    @rtype: int
+    @return: the database id for the given override type
+
+    """
     global override_type_id_cache
 
     if override_type_id_cache.has_key(type):
@@ -145,7 +208,17 @@ def get_override_type_id (type):
     return override_type_id
 
 def get_architecture_id (architecture):
-    """ Returns database architecture_id for given architecture, caches result. """
+    """
+    Returns database id for given C{architecture}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type architecture: string
+    @param architecture: The name of the override type
+
+    @rtype: int
+    @return: the database id for the given architecture
+
+    """
     global architecture_id_cache
 
     if architecture_id_cache.has_key(architecture):
@@ -162,7 +235,17 @@ def get_architecture_id (architecture):
     return architecture_id
 
 def get_archive_id (archive):
-    """ Returns database archive_id for given archive, caches result. """
+    """
+    Returns database id for given C{archive}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type archive: string
+    @param archive: The name of the override type
+
+    @rtype: int
+    @return: the database id for the given archive
+
+    """
     global archive_id_cache
 
     archive = archive.lower()
@@ -181,7 +264,17 @@ def get_archive_id (archive):
     return archive_id
 
 def get_component_id (component):
-    """ Returns database component_id for given component, caches result. """
+    """
+    Returns database id for given C{component}.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type component: string
+    @param component: The name of the override type
+
+    @rtype: int
+    @return: the database id for the given component
+
+    """
     global component_id_cache
 
     component = component.lower()
@@ -201,15 +294,23 @@ def get_component_id (component):
 
 def get_location_id (location, component, archive):
     """
-    Returns database location_id for given combination of
-    location
-    component
-    archive.
+    Returns database id for the location behind the given combination of
+      - B{location} - the path of the location, eg. I{/srv/ftp.debian.org/ftp/pool/}
+      - B{component} - the id of the component as returned by L{get_component_id}
+      - B{archive} - the id of the archive as returned by L{get_archive_id}
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type location: string
+    @param location: the path of the location
+
+    @type component: int
+    @param component: the id of the component
 
-    The 3 parameters are the database ids returned by the respective
-    "get_foo_id" functions.
+    @type archive: int
+    @param archive: the id of the archive
 
-    The result will be cached.
+    @rtype: int
+    @return: the database id for the location
 
     """
     global location_id_cache
@@ -235,7 +336,22 @@ def get_location_id (location, component, archive):
     return location_id
 
 def get_source_id (source, version):
-    """ Returns database source_id for given combination of source and version, caches result. """
+    """
+    Returns database id for the combination of C{source} and C{version}
+      - B{source} - source package name, eg. I{mailfilter}, I{bbdb}, I{glibc}
+      - B{version}
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type source: string
+    @param source: source package name
+
+    @type version: string
+    @param version: the source version
+
+    @rtype: int
+    @return: the database id for the source
+
+    """
     global source_id_cache
 
     cache_key = source + '_' + version + '_'
@@ -253,7 +369,24 @@ def get_source_id (source, version):
     return source_id
 
 def get_suite_version(source, suite):
-    """ Returns database version for a given source in a given suite, caches result. """
+    """
+    Returns database id for a combination of C{source} and C{suite}.
+
+      - B{source} - source package name, eg. I{mailfilter}, I{bbdb}, I{glibc}
+      - B{suite} - a suite name, eg. I{unstable}
+
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type source: string
+    @param source: source package name
+
+    @type suite: string
+    @param suite: the suite name
+
+    @rtype: string
+    @return: the version for I{source} in I{suite}
+
+    """
     global suite_version_cache
     cache_key = "%s_%s" % (source, suite)
 
@@ -280,11 +413,17 @@ def get_suite_version(source, suite):
 
 def get_or_set_maintainer_id (maintainer):
     """
-    If maintainer does not have an entry in the maintainer table yet, create one
-    and return its id.
-    If maintainer already has an entry, simply return its id.
+    If C{maintainer} does not have an entry in the maintainer table yet, create one
+    and return the new id.
+    If C{maintainer} already has an entry, simply return the existing id.
 
-    Result is cached.
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type maintainer: string
+    @param maintainer: the maintainer name
+
+    @rtype: int
+    @return: the database id for the maintainer
 
     """
     global maintainer_id_cache
@@ -305,11 +444,17 @@ def get_or_set_maintainer_id (maintainer):
 
 def get_or_set_keyring_id (keyring):
     """
-    If keyring does not have an entry in the keyring table yet, create one
-    and return its id.
-    If keyring already has an entry, simply return its id.
+    If C{keyring} does not have an entry in the C{keyrings} table yet, create one
+    and return the new id.
+    If C{keyring} already has an entry, simply return the existing id.
+
+    Results are kept in a cache during runtime to minimize database queries.
 
-    Result is cached.
+    @type keyring: string
+    @param keyring: the keyring name
+
+    @rtype: int
+    @return: the database id for the keyring
 
     """
     global keyring_id_cache
@@ -330,13 +475,20 @@ def get_or_set_keyring_id (keyring):
 
 def get_or_set_uid_id (uid):
     """
-    If uid does not have an entry in the uid table yet, create one
-    and return its id.
-    If uid already has an entry, simply return its id.
+    If C{uid} does not have an entry in the uid table yet, create one
+    and return the new id.
+    If C{uid} already has an entry, simply return the existing id.
+
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type uid: string
+    @param uid: the uid.
 
-    Result is cached.
+    @rtype: int
+    @return: the database id for the uid
 
     """
+
     global uid_id_cache
 
     if uid_id_cache.has_key(uid):
@@ -355,11 +507,17 @@ def get_or_set_uid_id (uid):
 
 def get_or_set_fingerprint_id (fingerprint):
     """
-    If fingerprintd does not have an entry in the fingerprint table yet, create one
-    and return its id.
-    If fingerprint already has an entry, simply return its id.
+    If C{fingerprint} does not have an entry in the fingerprint table yet, create one
+    and return the new id.
+    If C{fingerprint} already has an entry, simply return the existing id.
+
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type fingerprint: string
+    @param fingerprint: the fingerprint
 
-    Result is cached.
+    @rtype: int
+    @return: the database id for the fingerprint
 
     """
     global fingerprint_id_cache
@@ -380,22 +538,35 @@ def get_or_set_fingerprint_id (fingerprint):
 
 def get_files_id (filename, size, md5sum, location_id):
     """
-    Returns -1, -2 or the file_id for a given combination of
-    filename
-    size
-    md5sum
-    location_id.
+    Returns -1, -2 or the file_id for filename, if its C{size} and C{md5sum} match an
+    existing copy.
+
+    The database is queried using the C{filename} and C{location_id}. If a file does exist
+    at that location, the existing size and md5sum are checked against the provided
+    parameters. A size or checksum mismatch returns -2. If more than one entry is
+    found within the database, a -1 is returned, no result returns None, otherwise
+    the file id.
+
+    Results are kept in a cache during runtime to minimize database queries.
 
-    The database is queried using filename and location_id, size and md5sum are for
-    extra checks.
+    @type filename: string
+    @param filename: the filename of the file to check against the DB
 
-    Return values:
-    -1 - The given combination of arguments result in more (or less) than
-         one result from the database
-    -2 - The given size and md5sum do not match the values in the database
-    anything else is a file_id
+    @type size: int
+    @param size: the size of the file to check against the DB
 
-    Result is cached.
+    @type md5sum: string
+    @param md5sum: the md5sum of the file to check against the DB
+
+    @type location_id: int
+    @param location_id: the id of the location as returned by L{get_location_id}
+
+    @rtype: int / None
+    @return: Various return values are possible:
+               - -2: size/checksum error
+               - -1: more than one file found in database
+               - None: no file found in database
+               - int: file id
 
     """
     global files_id_cache
@@ -425,11 +596,17 @@ def get_files_id (filename, size, md5sum, location_id):
 
 def get_or_set_queue_id (queue):
     """
-    If queue does not have an entry in the queue_name table yet, create one
-    and return its id.
-    If queue already has an entry, simply return its id.
+    If C{queue} does not have an entry in the queue table yet, create one
+    and return the new id.
+    If C{queue} already has an entry, simply return the existing id.
+
+    Results are kept in a cache during runtime to minimize database queries.
 
-    Result is cached.
+    @type queue: string
+    @param queue: the queue name (no full path)
+
+    @rtype: int
+    @return: the database id for the queue
 
     """
     global queue_id_cache
@@ -450,9 +627,28 @@ def get_or_set_queue_id (queue):
 
 def set_files_id (filename, size, md5sum, sha1sum, sha256sum, location_id):
     """
-    Insert a new entry into the files table.
+    Insert a new entry into the files table and return its id.
+
+    @type filename: string
+    @param filename: the filename
+
+    @type size: int
+    @param size: the size in bytes
 
-    Returns the new file_id
+    @type md5sum: string
+    @param md5sum: md5sum of the file
+
+    @type sha1sum: string
+    @param sha1sum: sha1sum of the file
+
+    @type sha256sum: string
+    @param sha256sum: sha256sum of the file
+
+    @type location_id: int
+    @param location_id: the id of the location as returned by L{get_location_id}
+
+    @rtype: int
+    @return: the database id for the new file
 
     """
     global files_id_cache
@@ -474,7 +670,18 @@ def set_files_id (filename, size, md5sum, sha1sum, sha256sum, location_id):
 ################################################################################
 
 def get_maintainer (maintainer_id):
-    """ Return the name of the maintainer behind maintainer_id """
+    """
+    Return the name of the maintainer behind C{maintainer_id}.
+
+    Results are kept in a cache during runtime to minimize database queries.
+
+    @type maintainer_id: int
+    @param maintainer_id: the id of the maintainer, eg. from L{get_or_set_maintainer_id}
+
+    @rtype: string
+    @return: the name of the maintainer
+
+    """
     global maintainer_cache
 
     if not maintainer_cache.has_key(maintainer_id):
@@ -486,7 +693,20 @@ def get_maintainer (maintainer_id):
 ################################################################################
 
 def get_suites(pkgname, src=False):
-    """ Return the suites in which pkgname is. If src is True, query for source package, else binary. """
+    """
+    Return the suites in which C{pkgname} can be found. If C{src} is True query for source
+    package, else binary package.
+
+    @type pkgname: string
+    @param pkgname: name of the package
+
+    @type src: bool
+    @param src: if True look for source packages, false (default) looks for binary.
+
+    @rtype: list
+    @return: list of suites, or empty list if no match
+
+    """
     if src:
         sql = """
         SELECT suite_name