#!/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
################################################################################
-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:
################################################################################
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):
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):
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):
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):
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):
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()
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()
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
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 + '_'
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)
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
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
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):
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
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
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
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
################################################################################
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):
################################################################################
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
projects / dak / commitdiff