]> err.no Git - dak/commitdiff
various
authorJoerg Jaspert <joerg@debian.org>
Mon, 26 Jan 2009 21:56:31 +0000 (22:56 +0100)
committerJoerg Jaspert <joerg@debian.org>
Mon, 26 Jan 2009 21:56:31 +0000 (22:56 +0100)
a few more docstrings

Signed-off-by: Joerg Jaspert <joerg@debian.org>
dak/process_unchecked.py
dak/transitions.py
daklib/extensions.py
daklib/logging.py

index 6761a419fa4ef0887ee3b3a125df07700ec28313..90dd5dc56996c48b63f5b8ac0f7eefaca0c1e7c1 100755 (executable)
@@ -323,13 +323,15 @@ def check_distributions():
 ################################################################################
 
 def check_deb_ar(filename):
-    """Sanity check the ar of a .deb, i.e. that there is:
+    """
+    Sanity check the ar of a .deb, i.e. that there is:
 
o debian-binary
o control.tar.gz
o data.tar.gz or data.tar.bz2
     1. debian-binary
     2. control.tar.gz
     3. data.tar.gz or data.tar.bz2
 
-in that order, and nothing else."""
+    in that order, and nothing else.
+    """
     cmd = "ar t %s" % (filename)
     (result, output) = commands.getstatusoutput(cmd)
     if result != 0:
index 750d146b872b9fa67266e6a07fded87b0e1c1f68..90d2f620bbc4c74854dbb91903fd2bb418509f90 100755 (executable)
@@ -1,7 +1,12 @@
 #!/usr/bin/env python
 
-""" Display, edit and check the release manager's transition file. """
-# Copyright (C) 2008 Joerg Jaspert <joerg@debian.org>
+"""
+Display, edit and check the release manager's transition file.
+
+@contact: Debian FTP Master <ftpmaster@debian.org>
+@copyright: 2008 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
 
 ################################################################################
 
-import os, pg, sys, time, errno, fcntl, tempfile, pwd
+import os
+import pg
+import sys
+import time
+import errno
+import fcntl
+import tempfile
+import pwd
 import apt_pkg
 from daklib import database
 from daklib import utils
@@ -32,9 +44,9 @@ from daklib.regexes import re_broken_package
 import yaml
 
 # Globals
-Cnf = None
-Options = None
-projectB = None
+Cnf = None      #: Configuration, apt_pkg.Configuration
+Options = None  #: Parsed CommandLine arguments
+projectB = None #: database connection, pgobject
 
 ################################################################################
 
@@ -42,6 +54,12 @@ projectB = None
 #### This may run within sudo !! ####
 #####################################
 def init():
+    """
+    Initialize. Sets up database connection, parses commandline arguments.
+
+    @attention: This function may run B{within sudo}
+
+    """
     global Cnf, Options, projectB
 
     apt_pkg.init()
@@ -99,6 +117,20 @@ Options:
 #### This may run within sudo !! ####
 #####################################
 def load_transitions(trans_file):
+    """
+    Parse a transition yaml file and check it for validity.
+
+    @attention: This function may run B{within sudo}
+
+    @type trans_file: string
+    @param trans_file: filename to parse
+
+    @rtype: dict or None
+    @return: validated dictionary of transition entries or None
+             if validation fails, empty string if reading C{trans_file}
+             returned something else than a dict
+
+    """
     # Parse the yaml file
     sourcefile = file(trans_file, 'r')
     sourcecontent = sourcefile.read()
@@ -184,6 +216,12 @@ def load_transitions(trans_file):
 #### This may run within sudo !! ####
 #####################################
 def lock_file(f):
+    """
+    Lock a file
+
+    @attention: This function may run B{within sudo}
+
+    """
     for retry in range(10):
         lock_fd = os.open(f, os.O_RDWR | os.O_CREAT)
         try:
@@ -205,11 +243,19 @@ def lock_file(f):
 #### This may run within sudo !! ####
 #####################################
 def write_transitions(from_trans):
-    """Update the active transitions file safely.
-       This function takes a parsed input file (which avoids invalid
-       files or files that may be be modified while the function is
-       active), and ensure the transitions file is updated atomically
-       to avoid locks."""
+    """
+    Update the active transitions file safely.
+    This function takes a parsed input file (which avoids invalid
+    files or files that may be be modified while the function is
+    active) and ensure the transitions file is updated atomically
+    to avoid locks.
+
+    @attention: This function may run B{within sudo}
+
+    @type from_trans: dict
+    @param from_trans: transitions dictionary, as returned by L{load_transitions}
+
+    """
 
     trans_file = Cnf["Dinstall::Reject::ReleaseTransitions"]
     trans_temp = trans_file + ".tmp"
@@ -231,8 +277,16 @@ def write_transitions(from_trans):
 #### This usually runs within sudo !! ####
 ##########################################
 def write_transitions_from_file(from_file):
-    """We have a file we think is valid; if we're using sudo, we invoke it
-       here, otherwise we just parse the file and call write_transitions"""
+    """
+    We have a file we think is valid; if we're using sudo, we invoke it
+    here, otherwise we just parse the file and call write_transitions
+
+    @attention: This function usually runs B{within sudo}
+
+    @type from_file: filename
+    @param from_file: filename of a transitions file
+
+    """
 
     # Lets check if from_file is in the directory we expect it to be in
     if not os.path.abspath(from_file).startswith(Cnf["Transitions::TempPath"]):
@@ -251,9 +305,20 @@ def write_transitions_from_file(from_file):
 ################################################################################
 
 def temp_transitions_file(transitions):
-    # NB: file is unlinked by caller, but fd is never actually closed.
-    # We need the chmod, as the file is (most possibly) copied from a
-    # sudo-ed script and would be unreadable if it has default mkstemp mode
+    """
+    Open a temporary file and dump the current transitions into it, so users
+    can edit them.
+
+    @type transitions: dict
+    @param transitions: current defined transitions
+
+    @rtype: string
+    @return: path of newly created tempfile
+
+    @note: NB: file is unlinked by caller, but fd is never actually closed.
+           We need the chmod, as the file is (most possibly) copied from a
+           sudo-ed script and would be unreadable if it has default mkstemp mode
+    """
 
     (fd, path) = tempfile.mkstemp("", "transitions", Cnf["Transitions::TempPath"])
     os.chmod(path, 0644)
@@ -264,6 +329,7 @@ def temp_transitions_file(transitions):
 ################################################################################
 
 def edit_transitions():
+    """ Edit the defined transitions. """
     trans_file = Cnf["Dinstall::Reject::ReleaseTransitions"]
     edit_file = temp_transitions_file(load_transitions(trans_file))
 
@@ -321,6 +387,11 @@ def edit_transitions():
 ################################################################################
 
 def check_transitions(transitions):
+    """
+    Check if the defined transitions still apply and remove those that no longer do.
+    @note: Asks the user for confirmation first.
+
+    """
     to_dump = 0
     to_remove = []
     # Now look through all defined transitions
@@ -386,6 +457,28 @@ def check_transitions(transitions):
 ################################################################################
 
 def print_info(trans, source, expected, rm, reason, packages):
+    """
+    Print information about a single transition.
+
+    @type trans: string
+    @param trans: Transition name
+
+    @type source: string
+    @param source: Source package
+
+    @type expected: string
+    @param expected: Expected version in testing
+
+    @type rm: string
+    @param rm: Responsible RM
+
+    @type reason: string
+    @param reason: Reason
+
+    @type packages: list
+    @param packages: list of blocked packages
+
+    """
     print """Looking at transition: %s
 Source:      %s
 New Version: %s
@@ -398,6 +491,14 @@ Blocked Packages (total: %d): %s
 ################################################################################
 
 def transition_info(transitions):
+    """
+    Print information about all defined transitions.
+    Calls L{print_info} for every transition and then tells user if the transition is
+    still ongoing or if the expected version already hit testing.
+
+    @type transitions: dict
+    @param transitions: defined transitions
+    """
     for trans in transitions:
         t = transitions[trans]
         source = t["source"]
@@ -426,6 +527,12 @@ def transition_info(transitions):
 ################################################################################
 
 def main():
+    """
+    Prepare the work to be done, do basic checks.
+
+    @attention: This function may run B{within sudo}
+
+    """
     global Cnf
 
     #####################################
index 668cc27c9f80fa9b57b4d2fdec223e75039d60ce..88de8700a9d16d2a5060c8623909bfc463b136c5 100755 (executable)
@@ -1,9 +1,12 @@
 #!/usr/bin/env python
 
-""" Utility functions for extensions """
-# Copyright (C) 2008 Anthony Towns <ajt@dbeian.org>
+"""
+Utility functions for extensions
 
-################################################################################
+@contact: Debian FTP Master <ftpmaster@debian.org>
+@copyright: 2008 Anthony Towns <ajt@dbeian.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
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-################################################################################
-
 dak_functions_to_replace = {}
 dak_replaced_functions = {}
 
-def replace_dak_function(module,name):
-    """Decorator to make a function replace a standard dak function
-       in a given module. The replaced function will be provided as
-       the first argument."""
+def replace_dak_function(module, name):
+    """
+    Decorator to make a function replace a standard dak function
+    in a given module.
+
+    @type module: string
+    @param module: name of module where replaced function is in
+
+    @type name: string
+    @param name: name of the function to replace
+    """
 
     def x(f):
         def myfunc(*a,**kw):
index 125aa4af0b33b5c68b2b034c9aecc2be9b26a66a..0cca205e96bf83b6e1cad2c7f785e650c814b848 100755 (executable)
@@ -1,7 +1,12 @@
 #!/usr/bin/env python
 
-""" Logging functions """
-# Copyright (C) 2001, 2002, 2006  James Troup <james@nocrew.org>
+"""
+Logging functions
+
+@contact: Debian FTP Master <ftpmaster@debian.org>
+@copyright: 2001, 2002, 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
 
 ################################################################################
 
-import os, pwd, time, sys
+import os
+import pwd
+import time
+import sys
 import utils
 
 ################################################################################