documentation, man page

8 files changed, 82 insertions, 64 deletions

diff --git a/src/autodep/__init__.py b/src/autodep/__init__.py
deleted file mode 100644
index e69de29..0000000
--- a/src/autodep/__init__.py
+++ /dev/null
diff --git a/src/autodep/helpers/colorize_output.py b/src/autodep/helpers/colorize_output.py
index fb4c9c4..3b8af17 100644
--- a/src/autodep/helpers/colorize_output.py
+++ b/src/autodep/helpers/colorize_output.py
@@ -1,12 +1,17 @@
 #!/usr/bin/env python
 
-# color output support
+""" Output colorizing """
+
 class color_printer:
+  """
+  A class for printing colored strings
+  """
 #  HEADER = '\033[95m'
 #  OKBLUE = '\033[94m'
 #  OKGREEN = '\033[92m'
 #  FAIL = '\033[91m'
-
+ 
+  ## \param enable_colors activate color output
   def __init__(self, enable_colors=True):
 	if enable_colors:
 	  self.COLOR2CODE={"warning":'\033[91m', "text":'\033[90m'}
@@ -14,5 +19,8 @@ class color_printer:
 	else:
 	  self.COLOR2CODE={"warning":'', "text":''}
 	  self.ENDCOLOR=''
+  ## Prints a colored message
+  # \param importance is a string "warning" or "text". Color depends on it
+  # \param msg is a message to print
   def printmsg(self,importance,msg):
 	print self.COLOR2CODE[importance] + str(msg) + self.ENDCOLOR,
diff --git a/src/autodep/helpers/events_analysis.py b/src/autodep/helpers/events_analysis.py
index e4cb342..2928aad 100644
--- a/src/autodep/helpers/events_analysis.py
+++ b/src/autodep/helpers/events_analysis.py
@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 
-# some heuristics here to cut few packets
+
+
+## some heuristics here to cut few packets
 def is_package_useful(pkg,stages,files):
   # test 1: package is not useful if all files are *.desktop or *.xml or *.m4
   for f in files:
diff --git a/src/autodep/logfs/fstracer.py b/src/autodep/logfs/fstracer.py
index 7eca160..ef185b8 100644
--- a/src/autodep/logfs/fstracer.py
+++ b/src/autodep/logfs/fstracer.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python2
 """
-This module is a bridge between low-level logging services and high level handling dependency logic
+This module is a bridge between low-level logging services and high level 
+handling dependency logic.
+
+It can be used to launch a program and get all file events
 """
 
 import os
@@ -13,8 +16,6 @@ import select
 import re
 import signal
 
-import proc_helpers
-
 import logger_hooklib
 import logger_fusefs
 
@@ -25,23 +26,6 @@ def parse_message(message):
   ret=message.split("\0")
   return ret
 
-# check if proccess is finished
-def checkfinished(pid):
-  if not os.path.exists("/proc/%d/stat" % pid):
-	return True
-
-  try:
-	pid_child,exitcode = os.waitpid(pid, os.WNOHANG)
-  except OSError, e:
-	if e.errno == 10: 
-	  return False
-	else:
-	  raise
-  
-  if pid_child==0:
-	return False
-  return True
-
 #check if process is zombie
 def iszombie(pid):
   try:
@@ -60,49 +44,31 @@ def iszombie(pid):
   except IOError,e:
 	return True
   
-
-# uses /proc filesystem to get pid of parent
-# it is not used in program. Using function on C instead
-def getparentpid(pid):
-  try:
-	statfile=open("/proc/%d/stat" % pid,"r")
-	line=statfile.readline()
-	statfile.close()
-	line=line.rsplit(")")[1] # find last ")" char
-	line=line.strip()
-	match=re.match(r"^\w\s(\d+)",line)
-	if match==None:
-	  print "Failed to get parent process. Format of /proc/<pid>/stat is incorrect. Did you change a kernel?"
-	  return 1
-	 
-	return int(match.group(1))
-	
-  except IOError,e:
-	return 1
-
-#check if message came from one of a child
-def checkparent(parent,child):
-  #print "Parent %s, child %s"%(parent,child)
-  if child==1 or getparentpid(child)==1:
-	return True
-	  
-  currpid=child
-#   for(pid=getpid();pid!=0;pid=__getparentpid(pid))
-  while getparentpid(currpid)!=1:
-	currpid=getparentpid(currpid)
-	if currpid==parent:
-	  return True
-  
-  print "External actions with filesystem detected pid of external prog is %d" % child
-  return False
-
-
 # default access filter. Allow acess to all files
 def defaultfilter(eventname, filename, stage):
   return True
 
-# run the program and get file access events
 def getfsevents(prog_name,arguments,approach="hooklib",filterproc=defaultfilter):
+  """ 
+    Launches a program and gets file access events
+
+    :param prog_name: name of program
+    :param arguments: list of program's arguments
+    :param approach: a logging approach('hooklib' or 'fusefs')
+    :param filterproc: filter function, this function should take 3 strings:
+      name of event, name of file and stage, and return a *True* if event is 
+      allowed and *False* instead. Name of event is one of *'open'*, *'read'* or
+      *'write'*. Default function always returns *True*.  
+    :returns: **list** with two elements - *success* events and *failed* events.
+      Each element is dictionary **stage->file information**.
+      File information is also a dictionary **filename->type of events**.
+      Type of events for success events is a 2-element tuple: *(was file readed,
+      was file writed)*. For failed events it is also 2-element tuple:
+      *(was file not found, was file blocked by filterproc)*. Each element of 
+      tuple can be *True* or *False*. Both elements of tuple can be *False*.
+      Stage can be *'unknown'*
+  """
+
   events={}
   # generate a random socketname
   tmpdir = tempfile.mkdtemp()
diff --git a/src/autodep/package_utils/portage_log_parser.py b/src/autodep/package_utils/portage_log_parser.py
index 3854996..c0f0820 100644
--- a/src/autodep/package_utils/portage_log_parser.py
+++ b/src/autodep/package_utils/portage_log_parser.py
@@ -9,6 +9,14 @@ import time
 log_path='/var/log/emerge.log'
 
 def get_list_of_merged_packages(starttime=0,endtime=-1):
+  """
+  Parses an emerge log and finds first successfully merged packages chain
+
+  :param starttime: start time for searching(in seconds since 1970)
+  :param starttime: end time for searching(in seconds since 1970).
+  :returns: **list** of package names
+  
+  """
   ret=[]
   try:
 	log=open(log_path)
diff --git a/src/autodep/package_utils/portage_misc_functions.py b/src/autodep/package_utils/portage_misc_functions.py
index 4d63de4..c090d89 100644
--- a/src/autodep/package_utils/portage_misc_functions.py
+++ b/src/autodep/package_utils/portage_misc_functions.py
@@ -10,7 +10,9 @@ from _emerge.main import parse_opts
 
 
 class portage_api:
+  """ class for accessing the portage api """
   def __init__(self):
+	""" test """
 	self.settings=portage.config(clone=portage.settings)
 	self.vartree=portage.db[portage.root]['vartree']
 	self.vardb=self.vartree.dbapi
@@ -20,6 +22,14 @@ class portage_api:
 
   # recursive dependency getter
   def get_deps(self,pkg,dep_type=["RDEPEND","DEPEND"]):
+	""" 
+	Gets current dependencies of a package on any depth 
+	
+	:param pkg: name of package
+	:param dep_type: type of dependencies to recurse. Can be ["DEPEND"] or 
+	  ["RDEPEND", "DEPEND"]
+	:returns: **set** of packages names
+	"""
 	#pkg="kde-meta"
 	#print self.vardb.match("<sys-apps/paludis-0.26.0_alpha5")
 	#metadata = dict(zip(self.metadata_keys, self.vardb.aux_get(pkg, self.metadata_keys)))
@@ -67,8 +77,12 @@ class portage_api:
 			unknown_packages.add(pkg)
 	return ret
 
-  # returns all packages from system set. They are always implicit dependencies
   def get_system_packages_list(self):
+	""" 
+	returns all packages from system set. They are always implicit dependencies
+	
+	:returns: **list** of package names
+	"""
 	ret=[]
 	for atom in self.settings.packages:
 	  for pre_pkg in self.vartree.dep_match(atom):
@@ -77,8 +91,14 @@ class portage_api:
 			ret.append(pkg)
 	return ret
 
-  # call emerge arguments parser
   def parse_emerge_args(self,args):
+	""" 
+	call emerge arguments parser 
+	
+	:param args: arguments passed to emerge
+	:returns: **tuple** (action string, options dictionary, files or atoms 
+	  list)
+	"""
 	action, opts, files = parse_opts(args, silent=True)
 	return action, opts, files
 
diff --git a/src/autodep/package_utils/portage_utils.py b/src/autodep/package_utils/portage_utils.py
index c98ce1d..5401d99 100644
--- a/src/autodep/package_utils/portage_utils.py
+++ b/src/autodep/package_utils/portage_utils.py
@@ -5,6 +5,11 @@ import subprocess
 import re
 
 def getpackagesbyfiles(files):
+  """
+  :param files: list of filenames
+  :returns: **dictionary** file->package, if file doesn't belong to any
+    package it not returned as key of this dictionary
+  """
   ret={}
   listtocheck=[]
   for f in files:
@@ -41,6 +46,11 @@ def getpackagesbyfiles(files):
   return ret
   
 def getfilesbypackage(packagename):
+  """
+  
+  :param packagename: name of package
+  :returns: **list** of files in package with name *packagename*
+  """
   ret=[]
   try:
 	proc=subprocess.Popen(['qlist']+['--nocolor',"--obj",packagename],
diff --git a/src/autodep/showfsevents.py b/src/autodep/showfsevents.py
index 1d7834f..518eed8 100755
--- a/src/autodep/showfsevents.py
+++ b/src/autodep/showfsevents.py
@@ -10,8 +10,12 @@ import logfs.fstracer
 from helpers import colorize_output, events_analysis
 from package_utils import portage_utils, portage_misc_functions, portage_log_parser
 
-# dies if bad args
 def parse_args():
+  """
+	This function parses an input args
+	It dies if bad args passed
+  """
+  
   args_parser=optparse.OptionParser("%prog [options] <command>")
   args_parser.add_option("-b", "--block",action="store", type="string", 
 	dest="packages", default="",