Add documentation patches
From: Paul Jimenez <[email protected]>
Here's more doc patches for kernel.py, autotest_utils.py, and error.py.
This is a great way for me to learn the codebase :)
git-svn-id: http://test.kernel.org/svn/autotest/trunk@159 592f7852-d20e-0410-864c-8624ca9c26a4
diff --git a/bin/autotest_utils.py b/bin/autotest_utils.py
index 3a28404..0c2e344 100755
--- a/bin/autotest_utils.py
+++ b/bin/autotest_utils.py
@@ -1,21 +1,26 @@
+"""Convenience functions for use by tests or whomever.
+"""
+
import os,os.path,shutil,urllib,sys,signal,commands,pickle
from error import *
import re
def grep(pattern, file):
-# This is mainly to fix the return code inversion from grep
+ """This is mainly to fix the return code inversion from grep"""
return not system('grep "' + pattern + '" "' + file + '"')
-def difflist(list1, list2):
-# returns items in list 2 that are not in list 1
+def difflist(list1, list2):
+ """returns items in list2 that are not in list1"""
diff = [];
for x in list2:
if x not in list1:
diff.append(x)
return diff
+
def cat_file_to_cmd(file, command):
+ """equivalent to 'cat file | command' but knows to use zcat or bzcat if appropriate"""
if not os.path.isfile(file):
raise NameError, 'invalid file %s to cat to command %s' % file, command
if file.endswith('.bz2'):
@@ -25,10 +30,12 @@
else:
system('cat ' + file + ' | ' + command)
-
-# Extract a tarball to a specified directory name instead of whatever
-# the top level of a tarball is - useful for versioned directory names, etc
+
def extract_tarball_to_dir(tarball, dir):
+ """
+ Extract a tarball to a specified directory name instead of whatever
+ the top level of a tarball is - useful for versioned directory names, etc
+ """
if os.path.exists(dir):
raise NameError, 'target %s already exists' % dir
pwd = os.getcwd()
@@ -38,8 +45,8 @@
os.chdir(pwd)
-# Returns the first found newly created directory by the tarball extraction
def extract_tarball(tarball):
+ """Returns the first found newly created directory by the tarball extraction"""
oldlist = os.listdir('.')
cat_file_to_cmd(tarball, 'tar xf -')
newlist = os.listdir('.')
@@ -52,6 +59,10 @@
def update_version(srcdir, new_version, install):
+ """Make sure srcdir is version new_version
+
+ If not, delete it and install() the new version
+ """
versionfile = srcdir + '/.version'
if os.path.exists(srcdir):
if os.path.exists(versionfile):
@@ -67,16 +78,18 @@
def is_url(path):
+ """true if path is a url
+ """
+ # should cope with other url types here, but we only handle http and ftp
if (path.startswith('http://')) or (path.startswith('ftp://')):
- # should cope with other url types here, but we don't handle them yet
return 1
return 0
def get_file(src, dest):
+ """get a file, either from url or local"""
if (src == dest): # no-op here allows clean overrides in tests
return
- # get a file, either from url or local
if (is_url(src)):
print 'PWD: ' + os.getcwd()
print 'Fetching \n\t', src, '\n\t->', dest
@@ -105,18 +118,21 @@
def force_copy(src, dest):
+ """Replace dest with a new copy of src, even if it exists"""
if os.path.isfile(dest):
os.remove(dest)
return shutil.copyfile(src, dest)
def file_contains_pattern(file, pattern):
+ """Return true if file contains the specified egrep pattern"""
if not os.path.isfile(file):
raise NameError, 'file %s does not exist' % file
return not system('egrep -q ' + pattern + ' ' + file, ignorestatus = 1)
def list_grep(list, pattern):
+ """True if any item in list matches the specified pattern."""
compiled = re.compile(pattern)
for line in list:
match = compiled.search(line)
@@ -126,7 +142,10 @@
def get_vmlinux():
- # Ahem. This is crap. Pray harder. Bad Martin.
+ """Return the full path to vmlinux
+
+ Ahem. This is crap. Pray harder. Bad Martin.
+ """
vmlinux = '/boot/vmlinux'
if not os.path.isfile(vmlinux):
raise NameError, 'Cannot find vmlinux'
@@ -134,7 +153,10 @@
def get_systemmap():
- # Ahem. This is crap. Pray harder. Bad Martin.
+ """Return the full path to System.map
+
+ Ahem. This is crap. Pray harder. Bad Martin.
+ """
map = '/boot/System.map'
if not os.path.isfile(map):
raise NameError, 'Cannot find System.map'
@@ -142,12 +164,13 @@
def get_modules_dir():
+ """Return the modules dir for the running kernel version"""
kernel_version = system_output('uname -r')
return '/lib/modules/%s/kernel' % kernel_version
def get_arch():
-# Work out which CPU architecture we're running on
+ """Work out which CPU architecture we're running on"""
f = open('/proc/cpuinfo', 'r')
cpuinfo = f.readlines()
f.close()
@@ -170,6 +193,7 @@
def get_target_arch():
+ """Work out the target architecture."""
arch = get_arch()
if arch.startswith('power'):
return 'ppc64'
@@ -189,6 +213,7 @@
def count_cpus():
+ """number of CPUs in the local machine according to /proc/cpuinfo"""
f = file('/proc/cpuinfo', 'r')
cpus = 0
for line in f.readlines():
@@ -196,14 +221,16 @@
cpus += 1
return cpus
-
-# We have our own definition of system here, as the stock os.system doesn't
-# correctly handle sigpipe
-# (ie things like "yes | head" will hang because yes doesn't get the SIGPIPE).
-#
-# Also the stock os.system didn't raise errors based on exit status, this
-# version does unless you explicitly specify ignorestatus=1
def system(cmd, ignorestatus = 0):
+ """os.system replacement
+
+ We have our own definition of system here, as the stock os.system doesn't
+ correctly handle sigpipe
+ (ie things like "yes | head" will hang because yes doesn't get the SIGPIPE).
+
+ Also the stock os.system didn't raise errors based on exit status, this
+ version does unless you explicitly specify ignorestatus=1
+ """
signal.signal(signal.SIGPIPE, signal.SIG_DFL)
try:
status = os.system(cmd)
@@ -216,6 +243,11 @@
def system_output(command, ignorestatus = 0):
+ """Run command and return its output
+
+ ignorestatus
+ whether to raise a CmdError if command has a nonzero exit status
+ """
(result, data) = commands.getstatusoutput(command)
if ((result != 0) and not ignorestatus):
raise CmdError, 'command failed: ' + command
@@ -223,14 +255,20 @@
def where_art_thy_filehandles():
+ """Dump the current list of filehandles"""
os.system("ls -l /proc/%d/fd >> /dev/tty" % os.getpid())
def print_to_tty(string):
+ """Output string straight to the tty"""
os.system("echo " + string + " >> /dev/tty")
def dump_object(object):
+ """Dump an object's attributes and methods
+
+ kind of like dir()
+ """
for item in object.__dict__.iteritems():
print item
try:
@@ -241,6 +279,7 @@
def environ(env_key):
+ """return the requested environment variable, or '' if unset"""
if (os.environ.has_key(env_key)):
return os.environ(env_key)
else:
@@ -248,6 +287,7 @@
def prepend_path(newpath, oldpath):
+ """prepend newpath to oldpath"""
if (oldpath):
return newpath + ':' + oldpath
else:
@@ -255,6 +295,7 @@
def append_path(oldpath, newpath):
+ """append newpath to oldpath"""
if (oldpath):
return oldpath + ':' + newpath
else:
@@ -262,9 +303,16 @@
class fd_stack:
- # Note that we need to redirect both the sys.stdout type descriptor
- # (which print, etc use) and the low level OS numbered descriptor
- # which os.system() etc use.
+ """a stack of fd redirects
+
+ Redirects cause existing fd's to be pushed on the stack; restore()
+ causes the current set of redirects to be popped, restoring the previous
+ filehandle destinations.
+
+ Note that we need to redirect both the sys.stdout type descriptor
+ (which print, etc use) and the low level OS numbered descriptor
+ which os.system() etc use.
+ """
def __init__(self, fd, filehandle):
self.fd = fd # eg 1
@@ -273,6 +321,10 @@
def redirect(self, filename):
+ """Redirect output to the specified file
+
+ Overwrites the previous contents, if any.
+ """
fdcopy = os.dup(self.fd)
self.stack.append( (fdcopy, self.filehandle) )
# self.filehandle = file(filename, 'w')
@@ -286,6 +338,10 @@
def tee_redirect(self, filename):
+ """Tee output to the specified file
+
+ Overwrites the previous contents, if any.
+ """
print_to_tty("tee_redirect to " + filename)
where_art_thy_filehandles()
fdcopy = os.dup(self.fd)
@@ -307,6 +363,7 @@
def restore(self):
+ """unredirect one level"""
# print_to_tty("ENTERING RESTORE %d" % self.fd)
# where_art_thy_filehandles()
(old_fd, old_filehandle) = self.stack.pop()
