From c47d45b655bbf9e6d13d21a1ebe4b5248f5d50df Mon Sep 17 00:00:00 2001
From: Ansgar Burchardt <ansgar@debian.org>
Date: Wed, 1 Aug 2012 17:35:24 +0200
Subject: [PATCH] change documentation style

---
 daklib/archive.py        | 389 +++++++++++++++++++++++----------------
 daklib/checks.py         |  34 ++--
 daklib/fstransactions.py |  55 +++---
 daklib/policy.py         |  65 ++++---
 daklib/upload.py         | 200 +++++++++++++-------
 daklib/utils.py          |  34 ++--
 6 files changed, 469 insertions(+), 308 deletions(-)

diff --git a/daklib/archive.py b/daklib/archive.py
index 7f6895ad..29a5621d 100644
--- a/daklib/archive.py
+++ b/daklib/archive.py
@@ -19,13 +19,13 @@
 This module provides classes to manipulate the archive.
 """
 
-from .dbconn import *
+from daklib.dbconn import *
 import daklib.checks as checks
 from daklib.config import Config
 import daklib.upload as upload
 import daklib.utils as utils
-from .fstransactions import FilesystemTransaction
-from .regexes import re_changelog_versions, re_bin_only_nmu
+from daklib.fstransactions import FilesystemTransaction
+from daklib.regexes import re_changelog_versions, re_bin_only_nmu
 
 import apt_pkg
 from datetime import datetime
@@ -50,17 +50,16 @@ class ArchiveTransaction(object):
         self.session = DBConn().session()
 
     def get_file(self, hashed_file, source_name):
-        """Look for file `hashed_file` in database
+        """Look for file C{hashed_file} in database
 
-        Args:
-           hashed_file (daklib.upload.HashedFile): file to look for in the database
+        @type  hashed_file: L{daklib.upload.HashedFile}
+        @param hashed_file: file to look for in the database
 
-        Raises:
-           KeyError: file was not found in the database
-           HashMismatchException: hash mismatch
+        @raise KeyError: file was not found in the database
+        @raise HashMismatchException: hash mismatch
 
-        Returns:
-           `daklib.dbconn.PoolFile` object for the database
+        @rtype:  L{daklib.dbconn.PoolFile}
+        @return: database entry for the file
         """
         poolname = os.path.join(utils.poolify(source_name), hashed_file.filename)
         try:
@@ -76,8 +75,8 @@ class ArchiveTransaction(object):
 
         Will not give an error when the file is already present.
 
-        Returns:
-           `daklib.dbconn.PoolFile` object for the new file
+        @rtype:  L{daklib.dbconn.PoolFile}
+        @return: batabase object for the new file
         """
         session = self.session
 
@@ -108,23 +107,35 @@ class ArchiveTransaction(object):
     def install_binary(self, directory, binary, suite, component, allow_tainted=False, fingerprint=None, source_suites=None, extra_source_archives=None):
         """Install a binary package
 
-        Args:
-           directory (str): directory the binary package is located in
-           binary (daklib.upload.Binary): binary package to install
-           suite (daklib.dbconn.Suite): target suite
-           component (daklib.dbconn.Component): target component
-
-        Kwargs:
-           allow_tainted (bool): allow to copy additional files from tainted archives
-           fingerprint (daklib.dbconn.Fingerprint): optional fingerprint
-           source_suites (list of daklib.dbconn.Suite or True): suites to copy
-              the source from if they are not in `suite` or True to allow
-              copying from any suite.
-              This can also be a SQLAlchemy (sub)query object.
-           extra_source_archives (list of daklib.dbconn.Archive): extra archives to copy Built-Using sources from
-
-        Returns:
-           `daklib.dbconn.DBBinary` object for the new package
+        @type  directory: str
+        @param directory: directory the binary package is located in
+
+        @type  binary: L{daklib.upload.Binary}
+        @param binary: binary package to install
+
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: target suite
+
+        @type  component: L{daklib.dbconn.Component}
+        @param component: target component
+
+        @type  allow_tainted: bool
+        @param allow_tainted: allow to copy additional files from tainted archives
+
+        @type  fingerprint: L{daklib.dbconn.Fingerprint}
+        @param fingerprint: optional fingerprint
+
+        @type  source_suites: list of L{daklib.dbconn.Suite} or C{True}
+        @param source_suites: suites to copy the source from if they are not
+                              in C{suite} or C{True} to allow copying from any
+                              suite.
+                              This can also be a SQLAlchemy (sub)query object.
+
+        @type  extra_source_archives: list of L{daklib.dbconn.Archive}
+        @param extra_source_archives: extra archives to copy Built-Using sources from
+
+        @rtype:  L{daklib.dbconn.DBBinary}
+        @return: databse object for the new package
         """
         session = self.session
         control = binary.control
@@ -185,14 +196,18 @@ class ArchiveTransaction(object):
 
         This is intended to be used to check that Built-Using sources exist.
 
-        Args:
-           filename (str): filename to use in error messages
-           source (daklib.dbconn.DBSource): source to look for
-           archive (daklib.dbconn.Archive): archive to look in
+        @type  filename: str
+        @param filename: filename to use in error messages
+
+        @type  source: L{daklib.dbconn.DBSource}
+        @param source: source to look for
+
+        @type  archive: L{daklib.dbconn.Archive}
+        @param archive: archive to look in
 
-        Kwargs:
-           extra_archives (list of daklib.dbconn.Archive): list of archives to copy
-               the source package from if it is not yet present in `archive`
+        @type  extra_archives: list of L{daklib.dbconn.Archive}
+        @param extra_archives: list of archives to copy the source package from
+                               if it is not yet present in C{archive}
         """
         session = self.session
         db_file = session.query(ArchiveFile).filter_by(file=source.poolfile, archive=archive).first()
@@ -213,7 +228,7 @@ class ArchiveTransaction(object):
             self._copy_file(af.file, archive, db_file.component, allow_tainted=True)
 
     def _add_built_using(self, db_binary, filename, control, suite, extra_archives=None):
-        """Add Built-Using sources to `db_binary.extra_sources`
+        """Add Built-Using sources to C{db_binary.extra_sources}
         """
         session = self.session
         built_using = control.get('Built-Using', None)
@@ -235,19 +250,29 @@ class ArchiveTransaction(object):
     def install_source(self, directory, source, suite, component, changed_by, allow_tainted=False, fingerprint=None):
         """Install a source package
 
-        Args:
-           directory (str): directory the source package is located in
-           source (daklib.upload.Source): source package to install
-           suite (daklib.dbconn.Suite): target suite
-           component (daklib.dbconn.Component): target component
-           changed_by (daklib.dbconn.Maintainer): person who prepared this version of the package
+        @type  directory: str
+        @param directory: directory the source package is located in
+
+        @type  source: L{daklib.upload.Source}
+        @param source: source package to install
+
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: target suite
+
+        @type  component: L{daklib.dbconn.Component}
+        @param component: target component
 
-        Kwargs:
-           allow_tainted (bool): allow to copy additional files from tainted archives
-           fingerprint (daklib.dbconn.Fingerprint): optional fingerprint
+        @type  changed_by: L{daklib.dbconn.Maintainer}
+        @param changed_by: person who prepared this version of the package
 
-        Returns:
-           `daklib.dbconn.DBSource` object for the new source
+        @type  allow_tainted: bool
+        @param allow_tainted: allow to copy additional files from tainted archives
+
+        @type  fingerprint: L{daklib.dbconn.Fingerprint}
+        @param fingerprint: optional fingerprint
+
+        @rtype:  L{daklib.dbconn.DBSource}
+        @return: database object for the new source
         """
         session = self.session
         archive = suite.archive
@@ -342,13 +367,17 @@ class ArchiveTransaction(object):
     def _copy_file(self, db_file, archive, component, allow_tainted=False):
         """Copy a file to the given archive and component
 
-        Args:
-           db_file (daklib.dbconn.PoolFile): file to copy
-           archive (daklib.dbconn.Archive): target archive
-           component (daklib.dbconn.Component): target component
+        @type  db_file: L{daklib.dbconn.PoolFile}
+        @param db_file: file to copy
+
+        @type  archive: L{daklib.dbconn.Archive}
+        @param archive: target archive
+
+        @type  component: L{daklib.dbconn.Archive}
+        @param component: target component
 
-        Kwargs:
-           allow_tainted (bool): allow to copy from tainted archives (such as NEW)
+        @type  allow_tainted: bool
+        @param allow_tainted: allow to copy from tainted archives (such as NEW)
         """
         session = self.session
 
@@ -368,14 +397,20 @@ class ArchiveTransaction(object):
     def copy_binary(self, db_binary, suite, component, allow_tainted=False, extra_archives=None):
         """Copy a binary package to the given suite and component
 
-        Args:
-           db_binary (daklib.dbconn.DBBinary): binary to copy
-           suite (daklib.dbconn.Suite): target suite
-           component (daklib.dbconn.Component): target component
+        @type  db_binary: L{daklib.dbconn.DBBinary}
+        @param db_binary: binary to copy
+
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: target suite
+
+        @type  component: L{daklib.dbconn.Component}
+        @param component: target component
+
+        @type  allow_tainted: bool
+        @param allow_tainted: allow to copy from tainted archives (such as NEW)
 
-        Kwargs:
-           allow_tainted (bool): allow to copy from tainted archives (such as NEW)
-           extra_archives (list of daklib.dbconn.Archive): extra archives to copy Built-Using sources from
+        @type  extra_archives: list of L{daklib.dbconn.Archive}
+        @param extra_archives: extra archives to copy Built-Using sources from
         """
         session = self.session
         archive = suite.archive
@@ -403,13 +438,17 @@ class ArchiveTransaction(object):
     def copy_source(self, db_source, suite, component, allow_tainted=False):
         """Copy a source package to the given suite and component
 
-        Args:
-           db_source (daklib.dbconn.DBSource): source to copy
-           suite (daklib.dbconn.Suite): target suite
-           component (daklib.dbconn.Component): target component
+        @type  db_source: L{daklib.dbconn.DBSource}
+        @param db_source: source to copy
 
-        Kwargs:
-           allow_tainted (bool): allow to copy from tainted archives (such as NEW)
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: target suite
+
+        @type  component: L{daklib.dbconn.Component}
+        @param component: target component
+
+        @type  allow_tainted: bool
+        @param allow_tainted: allow to copy from tainted archives (such as NEW)
         """
         archive = suite.archive
         if archive.tainted:
@@ -423,10 +462,14 @@ class ArchiveTransaction(object):
     def remove_file(self, db_file, archive, component):
         """Remove a file from a given archive and component
 
-        Args:
-           db_file (daklib.dbconn.PoolFile): file to remove
-           archive (daklib.dbconn.Archive): archive to remove the file from
-           component (daklib.dbconn.Component): component to remove the file from
+        @type  db_file: L{daklib.dbconn.PoolFile}
+        @param db_file: file to remove
+
+        @type  archive: L{daklib.dbconn.Archive}
+        @param archive: archive to remove the file from
+
+        @type  component: L{daklib.dbconn.Component}
+        @param component: component to remove the file from
         """
         af = self.session.query(ArchiveFile).filter_by(file=db_file, archive=archive, component=component)
         self.fs.unlink(af.path)
@@ -435,9 +478,11 @@ class ArchiveTransaction(object):
     def remove_binary(self, binary, suite):
         """Remove a binary from a given suite and component
 
-        Args:
-           binary (daklib.dbconn.DBBinary): binary to remove
-           suite (daklib.dbconn.Suite): suite to remove the package from
+        @type  binary: L{daklib.dbconn.DBBinary}
+        @param binary: binary to remove
+
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to remove the package from
         """
         binary.suites.remove(suite)
         self.session.flush()
@@ -445,13 +490,14 @@ class ArchiveTransaction(object):
     def remove_source(self, source, suite):
         """Remove a source from a given suite and component
 
-        Raises:
-           ArchiveException: source package is still referenced by other
-                             binaries in the suite
+        @type  source: L{daklib.dbconn.DBSource}
+        @param source: source to remove
+
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to remove the package from
 
-        Args:
-           binary (daklib.dbconn.DBSource): source to remove
-           suite (daklib.dbconn.Suite): suite to remove the package from
+        @raise ArchiveException: source package is still referenced by other
+                                 binaries in the suite
         """
         session = self.session
 
@@ -490,40 +536,60 @@ class ArchiveTransaction(object):
 class ArchiveUpload(object):
     """handle an upload
 
-    This class can be used in a with-statement:
+    This class can be used in a with-statement::
 
        with ArchiveUpload(...) as upload:
           ...
 
     Doing so will automatically run any required cleanup and also rollback the
     transaction if it was not committed.
-
-    Attributes:
-       changes (daklib.upload.Changes): upload to process
-       directory (str): directory with temporary copy of files. set by `prepare`
-       fingerprint (daklib.dbconn.Fingerprint): fingerprint used to sign the upload
-       new (bool): upload is NEW. set by `check`
-       reject_reasons (list of str): reasons why the upload cannot be accepted
-       session: database session
-       transaction (daklib.archive.ArchiveTransaction): transaction used to handle the upload
-       warnings (list of str): warnings (NOT USED YET)
     """
     def __init__(self, directory, changes, keyrings):
         self.transaction = ArchiveTransaction()
+        """transaction used to handle the upload
+        @type: L{daklib.archive.ArchiveTransaction}
+        """
+
         self.session = self.transaction.session
+        """database session"""
 
         self.original_directory = directory
         self.original_changes = changes
+
         self.changes = None
+        """upload to process
+        @type: L{daklib.upload.Changes}
+        """
+
         self.directory = None
+        """directory with temporary copy of files. set by C{prepare}
+        @type: str
+        """
+
         self.keyrings = keyrings
 
         self.fingerprint = self.session.query(Fingerprint).filter_by(fingerprint=changes.primary_fingerprint).one()
+        """fingerprint of the key used to sign the upload
+        @type: L{daklib.dbconn.Fingerprint}
+        """
 
         self.reject_reasons = []
+        """reasons why the upload cannot by accepted
+        @type: list of str
+        """
+
         self.warnings = []
+        """warnings
+        @note: Not used yet.
+        @type: list of str
+        """
+
         self.final_suites = None
+
         self.new = False
+        """upload is NEW. set by C{check}
+        @type: bool
+        """
 
         self._new_queue = self.session.query(PolicyQueue).filter_by(queue_name='new').one()
         self._new = self._new_queue.suite
@@ -533,9 +599,9 @@ class ArchiveUpload(object):
 
         This copies the files involved to a temporary directory.  If you use
         this method directly, you have to remove the directory given by the
-        `directory` attribute later on your own.
+        C{directory} attribute later on your own.
 
-        Instead of using the method directly, you can also use a with-statement:
+        Instead of using the method directly, you can also use a with-statement::
 
            with ArchiveUpload(...) as upload:
               ...
@@ -575,12 +641,12 @@ class ArchiveUpload(object):
         """Path to unpacked source
 
         Get path to the unpacked source. This method does unpack the source
-        into a temporary directory under `self.directory` if it has not
+        into a temporary directory under C{self.directory} if it has not
         been done so already.
 
-        Returns:
-           String giving the path to the unpacked source directory
-           or None if no source was included in the upload.
+        @rtype:  str or C{None}
+        @return: string giving the path to the unpacked source directory
+                 or C{None} if no source was included in the upload.
         """
         assert self.directory is not None
 
@@ -621,8 +687,8 @@ class ArchiveUpload(object):
     def _mapped_suites(self):
         """Get target suites after mappings
 
-        Returns:
-           list of daklib.dbconn.Suite giving the mapped target suites of this upload
+        @rtype:  list of L{daklib.dbconn.Suite}
+        @return: list giving the mapped target suites of this upload
         """
         session = self.session
 
@@ -641,14 +707,14 @@ class ArchiveUpload(object):
         Evaluate component mappings from ComponentMappings in dak.conf for the
         given component name.
 
-        NOTE: ansgar wants to get rid of this. It's currently only used for
-        the security archive
+        @todo: ansgar wants to get rid of this. It's currently only used for
+               the security archive
 
-        Args:
-           component_name (str): component name
+        @type  component_name: str
+        @param component_name: component name
 
-        Returns:
-           `daklib.dbconn.Component` object
+        @rtype:  L{daklib.dbconn.Component}
+        @return: component after applying maps
         """
         cnf = Config()
         for m in cnf.value_list("ComponentMappings"):
@@ -662,11 +728,11 @@ class ArchiveUpload(object):
         """Check if upload is NEW
 
         An upload is NEW if it has binary or source packages that do not have
-        an override in `suite` OR if it references files ONLY in a tainted
+        an override in C{suite} OR if it references files ONLY in a tainted
         archive (eg. when it references files in NEW).
 
-        Returns:
-           True if the upload is NEW, False otherwise
+        @rtype:  bool
+        @return: C{True} if the upload is NEW, C{False} otherwise
         """
         session = self.session
 
@@ -714,12 +780,14 @@ class ArchiveUpload(object):
     def _binary_override(self, suite, binary):
         """Get override entry for a binary
 
-        Args:
-           suite (daklib.dbconn.Suite)
-           binary (daklib.upload.Binary)
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to get override for
 
-        Returns:
-           daklib.dbconn.Override or None
+        @type  binary: L{daklib.upload.Binary}
+        @param binary: binary to get override for
+
+        @rtype:  L{daklib.dbconn.Override} or C{None}
+        @return: override for the given binary or C{None}
         """
         if suite.overridesuite is not None:
             suite = self.session.query(Suite).filter_by(suite_name=suite.overridesuite).one()
@@ -736,12 +804,14 @@ class ArchiveUpload(object):
     def _source_override(self, suite, source):
         """Get override entry for a source
 
-        Args:
-           suite (daklib.dbconn.Suite)
-           source (daklib.upload.Source)
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to get override for
+
+        @type  source: L{daklib.upload.Source}
+        @param source: source to get override for
 
-        Returns:
-           daklib.dbconn.Override or None
+        @rtype:  L{daklib.dbconn.Override} or C{None}
+        @return: override for the given source or C{None}
         """
         if suite.overridesuite is not None:
             suite = self.session.query(Suite).filter_by(suite_name=suite.overridesuite).one()
@@ -759,18 +829,17 @@ class ArchiveUpload(object):
         """get component for a binary
 
         By default this will only look at overrides to get the right component;
-        if `only_overrides` is False this method will also look at the Section field.
+        if C{only_overrides} is C{False} this method will also look at the
+        Section field.
 
-        Args:
-           suite (daklib.dbconn.Suite)
-           binary (daklib.upload.Binary)
+        @type  suite: L{daklib.dbconn.Suite}
 
-        Kwargs:
-           only_overrides (bool): only use overrides to get the right component.
-               defaults to True.
+        @type  binary: L{daklib.upload.Binary}
 
-        Returns:
-           `daklib.dbconn.Component` object or None
+        @type  only_overrides: bool
+        @param only_overrides: only use overrides to get the right component
+
+        @rtype: L{daklib.dbconn.Component} or C{None}
         """
         override = self._binary_override(suite, binary)
         if override is not None:
@@ -782,11 +851,11 @@ class ArchiveUpload(object):
     def check(self, force=False):
         """run checks against the upload
 
-        Args:
-           force (bool): ignore failing forcable checks
+        @type  force: bool
+        @param force: ignore failing forcable checks
 
-        Returns:
-           True if all checks passed, False otherwise
+        @rtype:  bool
+        @return: C{True} if all checks passed, C{False} otherwise
         """
         # XXX: needs to be better structured.
         assert self.changes.valid_signature
@@ -835,23 +904,24 @@ class ArchiveUpload(object):
     def _install_to_suite(self, suite, source_component_func, binary_component_func, source_suites=None, extra_source_archives=None):
         """Install upload to the given suite
 
-        Args:
-           suite (daklib.dbconn.Suite): suite to install the package into.
-              This is the real suite, ie. after any redirection to NEW or a policy queue
-           source_component_func: function to get the `daklib.dbconn.Component`
-              for a `daklib.upload.Source` object
-           binary_component_func: function to get the `daklib.dbconn.Component`
-              for a `daklib.upload.Binary` object
-
-        Kwargs:
-           source_suites: see `daklib.archive.ArchiveTransaction.install_binary`
-           extra_source_archives: see `daklib.archive.ArchiveTransaction.install_binary`
-
-        Returns:
-           tuple with two elements. The first is a `daklib.dbconn.DBSource`
-           object for the install source or None if no source was included.
-           The second is a list of `daklib.dbconn.DBBinary` objects for the
-           installed binary packages.
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to install the package into. This is the real suite,
+                      ie. after any redirection to NEW or a policy queue
+
+        @param source_component_func: function to get the L{daklib.dbconn.Component}
+                                      for a L{daklib.upload.Source} object
+
+        @param binary_component_func: function to get the L{daklib.dbconn.Component}
+                                      for a L{daklib.upload.Binary} object
+
+        @param source_suites: see L{daklib.archive.ArchiveTransaction.install_binary}
+
+        @param extra_source_archives: see L{daklib.archive.ArchiveTransaction.install_binary}
+
+        @return: tuple with two elements. The first is a L{daklib.dbconn.DBSource}
+                 object for the install source or C{None} if no source was
+                 included. The second is a list of L{daklib.dbconn.DBBinary}
+                 objects for the installed binary packages.
         """
         # XXX: move this function to ArchiveTransaction?
 
@@ -934,8 +1004,8 @@ class ArchiveUpload(object):
 
         Try to handle byhand packages automatically.
 
-        Returns:
-           list of `daklib.upload.hashed_file` for the remaining byhand packages
+        @rtype:  list of L{daklib.upload.HashedFile}
+        @return: list of remaining byhand files
         """
         assert len(self.reject_reasons) == 0
         assert self.changes.valid_signature
@@ -982,10 +1052,11 @@ class ArchiveUpload(object):
         return len(remaining) == 0
 
     def _install_byhand(self, policy_queue_upload, hashed_file):
-        """
-        Args:
-           policy_queue_upload (daklib.dbconn.PolicyQueueUpload): XXX
-           hashed_file (daklib.upload.HashedFile): XXX
+        """install byhand file
+
+        @type  policy_queue_upload: L{daklib.dbconn.PolicyQueueUpload}
+
+        @type  hashed_file: L{daklib.upload.HashedFile}
         """
         fs = self.transaction.fs
         session = self.transaction.session
@@ -1041,10 +1112,10 @@ class ArchiveUpload(object):
     def install(self):
         """install upload
 
-        Install upload to a suite or policy queue.  This method does *not*
+        Install upload to a suite or policy queue.  This method does B{not}
         handle uploads to NEW.
 
-        You need to have called the `check` method before calling this method.
+        You need to have called the C{check} method before calling this method.
         """
         assert len(self.reject_reasons) == 0
         assert self.changes.valid_signature
@@ -1082,10 +1153,10 @@ class ArchiveUpload(object):
     def install_to_new(self):
         """install upload to NEW
 
-        Install upload to NEW.  This method does *not* handle regular uploads
+        Install upload to NEW.  This method does B{not} handle regular uploads
         to suites or policy queues.
 
-        You need to have called the `check` method before calling this method.
+        You need to have called the C{check} method before calling this method.
         """
         # Uploads to NEW are special as we don't have overrides.
         assert len(self.reject_reasons) == 0
diff --git a/daklib/checks.py b/daklib/checks.py
index 260eb18a..06626fd1 100644
--- a/daklib/checks.py
+++ b/daklib/checks.py
@@ -20,14 +20,14 @@
 
 """module provided pre-acceptance tests
 
-Please read the documentation for the `Check` class for the interface.
+Please read the documentation for the L{Check} class for the interface.
 """
 
 from daklib.config import Config
-from .dbconn import *
+from daklib.dbconn import *
 import daklib.dbconn as dbconn
-from .regexes import *
-from .textutils import fix_maintainer, ParseMaintError
+from daklib.regexes import *
+from daklib.textutils import fix_maintainer, ParseMaintError
 import daklib.lintian as lintian
 import daklib.utils as utils
 
@@ -48,37 +48,37 @@ class Reject(Exception):
 class Check(object):
     """base class for checks
 
-    checks are called by daklib.archive.ArchiveUpload.  Failing tests should
-    raise a `daklib.checks.Reject` exception including a human-readable
+    checks are called by L{daklib.archive.ArchiveUpload}. Failing tests should
+    raise a L{daklib.checks.Reject} exception including a human-readable
     description why the upload should be rejected.
     """
     def check(self, upload):
         """do checks
 
-        Args:
-           upload (daklib.archive.ArchiveUpload): upload to check
+        @type  upload: L{daklib.archive.ArchiveUpload}
+        @param upload: upload to check
 
-        Raises:
-           daklib.checks.Reject
+        @raise daklib.checks.Reject: upload should be rejected
         """
         raise NotImplemented
     def per_suite_check(self, upload, suite):
         """do per-suite checks
 
-        Args:
-           upload (daklib.archive.ArchiveUpload): upload to check
-           suite (daklib.dbconn.Suite): suite to check
+        @type  upload: L{daklib.archive.ArchiveUpload}
+        @param upload: upload to check
 
-        Raises:
-           daklib.checks.Reject
+        @type  suite: L{daklib.dbconn.Suite}
+        @param suite: suite to check
+
+        @raise daklib.checks.Reject: upload should be rejected
         """
         raise NotImplemented
     @property
     def forcable(self):
         """allow to force ignore failing test
 
-        True if it is acceptable to force ignoring a failing test,
-        False otherwise
+        C{True} if it is acceptable to force ignoring a failing test,
+        C{False} otherwise
         """
         return False
 
diff --git a/daklib/fstransactions.py b/daklib/fstransactions.py
index f76a4bc6..33f59c8c 100644
--- a/daklib/fstransactions.py
+++ b/daklib/fstransactions.py
@@ -123,16 +123,22 @@ class FilesystemTransaction(object):
         self.actions = []
 
     def copy(self, source, destination, link=True, symlink=False, mode=None):
-        """copy `source` to `destination`
+        """copy C{source} to C{destination}
 
-        Args:
-           source (str): source file
-           destination (str): destination file
+        @type  source: str
+        @param source: source file
 
-        Kwargs:
-           link (bool): Try hardlinking, falling back to copying.
-           symlink (bool): Create a symlink instead
-           mode (int): Permissions to change `destination` to.
+        @type  destination: str
+        @param destination: destination file
+
+        @type  link: bool
+        @param link: try hardlinking, falling back to copying
+
+        @type  symlink: bool
+        @param symlink: create a symlink instead of copying
+
+        @type  mode: int
+        @param mode: permissions to change C{destination} to
         """
         if isinstance(mode, str) or isinstance(mode, unicode):
             mode = int(mode, 8)
@@ -140,37 +146,38 @@ class FilesystemTransaction(object):
         self.actions.append(_FilesystemCopyAction(source, destination, link=link, symlink=symlink, mode=mode))
 
     def move(self, source, destination, mode=None):
-        """move `source` to `destination`
+        """move C{source} to C{destination}
+
+        @type  source: str
+        @param source: source file
 
-        Args:
-           source (str): source file
-           destination (str): destination file
+        @type  destination: str
+        @param destination: destination file
 
-        Kwargs:
-           mode (int): Permissions to change `destination` to.
+        @type  mode: int
+        @param mode: permissions to change C{destination} to
         """
         self.copy(source, destination, link=True, mode=mode)
         self.unlink(source)
 
     def unlink(self, path):
-        """unlink `path`
+        """unlink C{path}
 
-        Args:
-           path (str): file to unlink
+        @type  path: str
+        @param path: file to unlink
         """
         self.actions.append(_FilesystemUnlinkAction(path))
 
     def create(self, path, mode=None):
-        """create `filename` and return file handle
+        """create C{filename} and return file handle
 
-        Args:
-           filename (str): file to create
+        @type  filename: str
+        @param filename: file to create
 
-        Kwargs:
-           mode (int): Permissions for the new file
+        @type  mode: int
+        @param mode: permissions for the new file
 
-        Returns:
-           file handle of the new file
+        @return: file handle of the new file
         """
         if isinstance(mode, str) or isinstance(mode, unicode):
             mode = int(mode, 8)
diff --git a/daklib/policy.py b/daklib/policy.py
index c989f1f2..78d58d67 100644
--- a/daklib/policy.py
+++ b/daklib/policy.py
@@ -29,31 +29,36 @@ import tempfile
 class UploadCopy(object):
     """export a policy queue upload
 
-    This class can be used in a with-statements:
+    This class can be used in a with-statement::
 
        with UploadCopy(...) as copy:
           ...
 
     Doing so will provide a temporary copy of the upload in the directory
-    given by the `directory` attribute.  The copy will be removed on leaving
+    given by the C{directory} attribute.  The copy will be removed on leaving
     the with-block.
-
-    Args:
-       upload (daklib.dbconn.PolicyQueueUpload)
     """
     def __init__(self, upload):
+        """initializer
+
+        @type  upload: L{daklib.dbconn.PolicyQueueUpload}
+        @param upload: upload to handle
+        """
+
         self.directory = None
         self.upload = upload
 
     def export(self, directory, mode=None, symlink=True):
         """export a copy of the upload
 
-        Args:
-           directory (str)
+        @type  directory: str
+        @param directory: directory to export to
 
-        Kwargs:
-           mode (int): permissions to use for the copied files
-           symlink (bool): use symlinks instead of copying the files (default: True)
+        @type  mode: int
+        @param mode: permissions to use for the copied files
+
+        @type  symlink: bool
+        @param symlink: use symlinks instead of copying the files
         """
         with FilesystemTransaction() as fs:
             source = self.upload.source
@@ -103,9 +108,10 @@ class PolicyQueueUploadHandler(object):
     def __init__(self, upload, session):
         """initializer
 
-        Args:
-           upload (daklib.dbconn.PolicyQueueUpload): upload to process
-           session: database session
+        @type  upload: L{daklib.dbconn.PolicyQueueUpload}
+        @param upload: upload to process
+
+        @param session: database session
         """
         self.upload = upload
         self.session = session
@@ -169,8 +175,8 @@ class PolicyQueueUploadHandler(object):
     def reject(self, reason):
         """mark upload as rejected
 
-        Args:
-           reason (str): reason for the rejection
+        @type  reason: str
+        @param reason: reason for the rejection
         """
         fn1 = 'REJECT.{0}'.format(self._changes_prefix)
         assert re_file_safe.match(fn1)
@@ -190,8 +196,8 @@ class PolicyQueueUploadHandler(object):
     def get_action(self):
         """get current action
 
-        Returns:
-           string giving the current action, one of 'ACCEPT', 'ACCEPTED', 'REJECT'
+        @rtype:  str
+        @return: string giving the current action, one of 'ACCEPT', 'ACCEPTED', 'REJECT'
         """
         changes_prefix = self._changes_prefix
 
@@ -206,18 +212,19 @@ class PolicyQueueUploadHandler(object):
     def missing_overrides(self, hints=None):
         """get missing override entries for the upload
 
-        Kwargs:
-           hints (list of dict): suggested hints for new overrides in the same
-              format as the return value
-
-        Returns:
-           list of dicts with the following keys:
-              package: package name
-              priority: default priority (from upload)
-              section: default section (from upload)
-              component: default component (from upload)
-              type: type of required override ('dsc', 'deb' or 'udeb')
-           All values are strings.
+        @type  hints: list of dict
+        @param hints: suggested hints for new overrides in the same format as
+                      the return value
+
+        @return: list of dicts with the following keys:
+
+                 - package: package name
+                 - priority: default priority (from upload)
+                 - section: default section (from upload)
+                 - component: default component (from upload)
+                 - type: type of required override ('dsc', 'deb' or 'udeb')
+
+                 All values are strings.
         """
         # TODO: use Package-List field
         missing = []
diff --git a/daklib/upload.py b/daklib/upload.py
index 5c19478b..b0baf8cb 100644
--- a/daklib/upload.py
+++ b/daklib/upload.py
@@ -17,7 +17,7 @@
 """module to handle uploads not yet installed to the archive
 
 This module provides classes to handle uploads not yet installed to the
-archive.  Central is the `Changes` class which represents a changes file.
+archive.  Central is the L{Changes} class which represents a changes file.
 It provides methods to access the included binary and source packages.
 """
 
@@ -25,8 +25,9 @@ import apt_inst
 import apt_pkg
 import os
 import re
-from .gpg import SignedFile
-from .regexes import *
+
+from daklib.gpg import SignedFile
+from daklib.regexes import *
 
 class InvalidChangesException(Exception):
     pass
@@ -54,35 +55,52 @@ class InvalidFilenameException(Exception):
 
 class HashedFile(object):
     """file with checksums
-
-    Attributes:
-       filename (str): name of the file
-       size (long): size in bytes
-       md5sum (str): MD5 hash in hexdigits
-       sha1sum (str): SHA1 hash in hexdigits
-       sha256sum (str): SHA256 hash in hexdigits
-       section (str): section or None
-       priority (str): priority or None
     """
     def __init__(self, filename, size, md5sum, sha1sum, sha256sum, section=None, priority=None):
         self.filename = filename
+        """name of the file
+        @type: str
+        """
+
         self.size = size
+        """size in bytes
+        @type: long
+        """
+
         self.md5sum = md5sum
+        """MD5 hash in hexdigits
+        @type: str
+        """
+
         self.sha1sum = sha1sum
+        """SHA1 hash in hexdigits
+        @type: str
+        """
+
         self.sha256sum = sha256sum
+        """SHA256 hash in hexdigits
+        @type: str
+        """
+
         self.section = section
+        """section or C{None}
+        @type: str or C{None}
+        """
+
         self.priority = priority
+        """priority or C{None}
+        @type: str of C{None}
+        """
 
     def check(self, directory):
         """Validate hashes
 
         Check if size and hashes match the expected value.
 
-        Args:
-           directory (str): directory the file is located in
+        @type  directory: str
+        @param directory: directory the file is located in
 
-        Raises:
-           InvalidHashException: hash mismatch
+        @raise InvalidHashException: hash mismatch
         """
         path = os.path.join(directory, self.filename)
         fh = open(path, 'r')
@@ -108,15 +126,17 @@ class HashedFile(object):
 def parse_file_list(control, has_priority_and_section):
     """Parse Files and Checksums-* fields
 
-    Args:
-       control (dict-like): control file to take fields from
-       has_priority_and_section (bool): Files include section and priority (as in .changes)
+    @type  control: dict-like
+    @param control: control file to take fields from
+
+    @type  has_priority_and_section: bool
+    @param has_priority_and_section: Files field include section and priority
+                                     (as in .changes)
 
-    Raises:
-       InvalidChangesException: missing fields or other grave errors
+    @raise InvalidChangesException: missing fields or other grave errors
 
-    Returns:
-       dictonary mapping filenames to `daklib.upload.HashedFile` objects
+    @rtype:  dict
+    @return: dict mapping filenames to L{daklib.upload.HashedFile} objects
     """
     entries = {}
 
@@ -172,32 +192,28 @@ def parse_file_list(control, has_priority_and_section):
 
 class Changes(object):
     """Representation of a .changes file
-
-    Attributes:
-       architectures (list of str): list of architectures included in the upload
-       binaries (list of daklib.upload.Binary): included binary packages
-       binary_names (list of str): names of included binary packages
-       byhand_files (list of daklib.upload.HashedFile): included byhand files
-       bytes (int): total size of files included in this upload in bytes
-       changes (dict-like): dict to access fields of the .changes file
-       closed_bugs (list of str): list of bugs closed by this upload
-       directory (str): directory the .changes is located in
-       distributions (list of str): list of target distributions for the upload
-       filename (str): name of the .changes file
-       files (dict): dict mapping filenames to daklib.upload.HashedFile objects
-       path (str): path to the .changes files
-       primary_fingerprint (str): fingerprint of the PGP key used for the signature
-       source (daklib.upload.Source or None): included source
-       valid_signature (bool): True if the changes has a valid signature
     """
     def __init__(self, directory, filename, keyrings, require_signature=True):
         if not re_file_safe.match(filename):
             raise InvalidChangesException('{0}: unsafe filename'.format(filename))
+
         self.directory = directory
+        """directory the .changes is located in
+        @type: str
+        """
+
         self.filename = filename
+        """name of the .changes file
+        @type: str
+        """
+
         data = open(self.path).read()
         self._signed_file = SignedFile(data, keyrings, require_signature)
         self.changes = apt_pkg.TagSection(self._signed_file.contents)
+        """dict to access fields of the .changes file
+        @type: dict-like
+        """
+
         self._binaries = None
         self._source = None
         self._files = None
@@ -206,26 +222,44 @@ class Changes(object):
 
     @property
     def path(self):
+        """path to the .changes file
+        @type: str
+        """
         return os.path.join(self.directory, self.filename)
 
     @property
     def primary_fingerprint(self):
+        """fingerprint of the key used for signing the .changes file
+        @type: str
+        """
         return self._signed_file.primary_fingerprint
 
     @property
     def valid_signature(self):
+        """C{True} if the .changes has a valid signature
+        @type: bool
+        """
         return self._signed_file.valid
 
     @property
     def architectures(self):
+        """list of architectures included in the upload
+        @type: list of str
+        """
         return self.changes['Architecture'].split()
 
     @property
     def distributions(self):
+        """list of target distributions for the upload
+        @type: list of str
+        """
         return self.changes['Distribution'].split()
 
     @property
     def source(self):
+        """included source or C{None}
+        @type: L{daklib.upload.Source} or C{None}
+        """
         if self._source is None:
             source_files = []
             for f in self.files.itervalues():
@@ -237,6 +271,9 @@ class Changes(object):
 
     @property
     def binaries(self):
+        """included binary packages
+        @type: list of L{daklib.upload.Binary}
+        """
         if self._binaries is None:
             binaries = []
             for f in self.files.itervalues():
@@ -247,6 +284,9 @@ class Changes(object):
 
     @property
     def byhand_files(self):
+        """included byhand files
+        @type: list of L{daklib.upload.HashedFile}
+        """
         byhand = []
 
         for f in self.files.itervalues():
@@ -260,35 +300,47 @@ class Changes(object):
 
     @property
     def binary_names(self):
+        """names of included binary packages
+        @type: list of str
+        """
         return self.changes['Binary'].split()
 
     @property
     def closed_bugs(self):
+        """bugs closed by this upload
+        @type: list of str
+        """
         return self.changes.get('Closes', '').split()
 
     @property
     def files(self):
+        """dict mapping filenames to L{daklib.upload.HashedFile} objects
+        @type: dict
+        """
         if self._files is None:
             self._files = parse_file_list(self.changes, True)
         return self._files
 
     @property
     def bytes(self):
+        """total size of files included in this upload in bytes
+        @type: number
+        """
         count = 0
         for f in self.files.itervalues():
             count += f.size
         return count
 
     def __cmp__(self, other):
-        """Compare two changes packages
+        """compare two changes files
 
         We sort by source name and version first.  If these are identical,
         we sort changes that include source before those without source (so
         that sourceful uploads get processed first), and finally fall back
         to the filename (this should really never happen).
 
-        Returns:
-           -1 if self < other, 0 if self == other, 1 if self > other
+        @rtype:  number
+        @return: n where n < 0 if self < other, n = 0 if self == other, n > 0 if self > other
         """
         ret = cmp(self.changes.get('Source'), other.changes.get('Source'))
 
@@ -313,25 +365,25 @@ class Changes(object):
 
 class Binary(object):
     """Representation of a binary package
-
-    Attributes:
-       component (str): component name
-       control (dict-like): dict to access fields in DEBIAN/control
-       hashed_file (HashedFile): HashedFile object for the .deb
     """
     def __init__(self, directory, hashed_file):
         self.hashed_file = hashed_file
+        """file object for the .deb
+        @type: HashedFile
+        """
 
         path = os.path.join(directory, hashed_file.filename)
         data = apt_inst.DebFile(path).control.extractdata("control")
+
         self.control = apt_pkg.TagSection(data)
+        """dict to access fields in DEBIAN/control
+        @type: dict-like
+        """
 
     @property
     def source(self):
-        """Get source package name and version
-
-        Returns:
-           tuple containing source package name and version
+        """get tuple with source package name and version
+        @type: tuple of str
         """
         source = self.control.get("Source", None)
         if source is None:
@@ -346,10 +398,8 @@ class Binary(object):
 
     @property
     def type(self):
-        """Get package type
-
-        Returns:
-           String with the package type ('deb' or 'udeb')
+        """package type ('deb' or 'udeb')
+        @type: str
         """
         match = re_file_binary.match(self.hashed_file.filename)
         if not match:
@@ -358,6 +408,9 @@ class Binary(object):
 
     @property
     def component(self):
+        """component name
+        @type: str
+        """
         fields = self.control['Section'].split('/')
         if len(fields) > 1:
             return fields[0]
@@ -365,18 +418,13 @@ class Binary(object):
 
 class Source(object):
     """Representation of a source package
-
-    Attributes:
-       component (str): guessed component name. Might be wrong!
-       dsc (dict-like): dict to access fields in the .dsc file
-       hashed_files (list of daklib.upload.HashedFile): list of source files (including .dsc)
-       files (dict): dictonary mapping filenames to HashedFile objects for
-           additional source files (not including .dsc)
-       primary_fingerprint (str): fingerprint of the PGP key used for the signature
-       valid_signature (bool):  True if the dsc has a valid signature
     """
     def __init__(self, directory, hashed_files, keyrings, require_signature=True):
         self.hashed_files = hashed_files
+        """list of source files (including the .dsc itself)
+        @type: list of L{HashedFile}
+        """
+
         self._dsc_file = None
         for f in hashed_files:
             if re_file_dsc.match(f.filename):
@@ -388,24 +436,46 @@ class Source(object):
         data = open(dsc_file_path, 'r').read()
         self._signed_file = SignedFile(data, keyrings, require_signature)
         self.dsc = apt_pkg.TagSection(self._signed_file.contents)
+        """dict to access fields in the .dsc file
+        @type: dict-like
+        """
+
         self._files = None
 
     @property
     def files(self):
+        """dict mapping filenames to L{HashedFile} objects for additional source files
+
+        This list does not include the .dsc itself.
+
+        @type: dict
+        """
         if self._files is None:
             self._files = parse_file_list(self.dsc, False)
         return self._files
 
     @property
     def primary_fingerprint(self):
+        """fingerprint of the key used to sign the .dsc
+        @type: str
+        """
         return self._signed_file.primary_fingerprint
 
     @property
     def valid_signature(self):
+        """C{True} if the .dsc has a valid signature
+        @type: bool
+        """
         return self._signed_file.valid
 
     @property
     def component(self):
+        """guessed component name
+
+        Might be wrong. Don't rely on this.
+
+        @type: str
+        """
         if 'Section' not in self.dsc:
             return 'main'
         fields = self.dsc['Section'].split('/')
diff --git a/daklib/utils.py b/daklib/utils.py
index cd5eb791..4ee00a1c 100644
--- a/daklib/utils.py
+++ b/daklib/utils.py
@@ -1550,7 +1550,6 @@ def get_packages_from_ftp(root, suite, component, architecture):
 
     @rtype: TagFile
     @return: apt_pkg class containing package data
-
     """
     filename = "%s/dists/%s/%s/binary-%s/Packages.gz" % (root, suite, component, architecture)
     (fd, temp_file) = temp_filename()
@@ -1576,15 +1575,20 @@ def deb_extract_control(fh):
 ################################################################################
 
 def mail_addresses_for_upload(maintainer, changed_by, fingerprint):
-    """Mail addresses to contact for an upload
+    """mail addresses to contact for an upload
+
+    @type  maintainer: str
+    @param maintainer: Maintainer field of the .changes file
 
-    Args:
-       maintainer (str): Maintainer field of the changes file
-       changed_by (str): Changed-By field of the changes file
-       fingerprint (str): Fingerprint of the PGP key used to sign the upload
+    @type  changed_by: str
+    @param changed_by: Changed-By field of the .changes file
 
-    Returns:
-       List of RFC 2047-encoded mail addresses to contact regarding this upload
+    @type  fingerprint: str
+    @param fingerprint: fingerprint of the key used to sign the upload
+
+    @rtype:  list of str
+    @return: list of RFC 2047-encoded mail addresses to contact regarding
+             this upload
     """
     addresses = [maintainer]
     if changed_by != maintainer:
@@ -1600,14 +1604,16 @@ def mail_addresses_for_upload(maintainer, changed_by, fingerprint):
 ################################################################################
 
 def call_editor(text="", suffix=".txt"):
-    """Run editor and return the result as a string
+    """run editor and return the result as a string
+
+    @type  text: str
+    @param text: initial text
 
-    Kwargs:
-       text (str): initial text
-       suffix (str): extension for temporary file
+    @type  suffix: str
+    @param suffix: extension for temporary file
 
-    Returns:
-       string with the edited text
+    @rtype:  str
+    @return: string with the edited text
     """
     editor = os.environ.get('VISUAL', os.environ.get('EDITOR', 'vi'))
     tmp = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
-- 
2.39.2