- Added more comments

git-svn-id: https://fail2ban.svn.sourceforge.net/svnroot/fail2ban/trunk@556 a942ae1a-1317-0410-a47c-b1dcaea8d605

server/action.py

@@ -54,18 +54,48 @@ class Action:
 		self.__actionStop = ''
 		logSys.debug("Created Action")
 	
+	##
+	# Sets the action name.
+	#
+	# @param name the name of the action
+	
 	def setName(self, name):
 		self.__name = name
 	
+	##
+	# Returns the action name.
+	#
+	# @return the name of the action
+	
 	def getName(self):
 		return self.__name
 	
+	##
+	# Sets a "CInfo".
+	#
+	# CInfo are statically defined properties. They can be definied by
+	# the user and are used to set e-mail addresses, port, host or
+	# anything that should not change during the life of the server.
+	#
+	# @param key the property name
+	# @param value the property value
+	
 	def setCInfo(self, key, value):
 		self.__cInfo[key] = value
 	
+	##
+	# Returns a "CInfo".
+	#
+	# @param key the property name
+	
 	def getCInfo(self, key):
 		return self.__cInfo[key]
 	
+	##
+	# Removes a "CInfo".
+	#
+	# @param key the property name
+	
 	def delCInfo(self, key):
 		del self.__cInfo[key]
 	
@@ -86,6 +116,14 @@ class Action:
 	def getActionStart(self):
 		return self.__actionStart
 	
+	##
+	# Executes the action "start" command.
+	#
+	# Replaces the tags in the action command with value of "cInfo"
+	# and executes the resulting command.
+	#
+	# @return True if the command succeeded
+	
 	def execActionStart(self):
 		startCmd = Action.replaceTag(self.__actionStart, self.__cInfo)
 		return Action.executeCmd(startCmd)
@@ -107,6 +145,11 @@ class Action:
 	def getActionBan(self):
 		return self.__actionBan
 	
+	##
+	# Executes the action "ban" command.
+	#
+	# @return True if the command succeeded
+	
 	def execActionBan(self, aInfo):
 		return self.__processCmd(self.__actionBan, aInfo)
 	
@@ -127,6 +170,11 @@ class Action:
 	def getActionUnban(self):
 		return self.__actionUnban
 	
+	##
+	# Executes the action "unban" command.
+	#
+	# @return True if the command succeeded
+	
 	def execActionUnban(self, aInfo):
 		return self.__processCmd(self.__actionUnban, aInfo)
 	
@@ -164,10 +212,25 @@ class Action:
 	def getActionStop(self):
 		return self.__actionStop
 	
+	##
+	# Executes the action "stop" command.
+	#
+	# Replaces the tags in the action command with value of "cInfo"
+	# and executes the resulting command.
+	#
+	# @return True if the command succeeded
+	
 	def execActionStop(self):
 		stopCmd = Action.replaceTag(self.__actionStop, self.__cInfo)
 		return Action.executeCmd(stopCmd)
 	
+	##
+	# Replaces tags in query with property values in aInfo.
+	#
+	# @param query the query string with tags
+	# @param aInfo the properties
+	# @return a string
+	
 	@staticmethod
 	def replaceTag(query, aInfo):
 		""" Replace tags in query
@@ -179,6 +242,19 @@ class Action:
 		string = string.replace("<br>", '\n')
 		return string
 	
+	##
+	# Executes a command with preliminary checks and substitutions.
+	#
+	# Before executing any commands, executes the "check" command first
+	# in order to check if prerequirements are met. If this check fails,
+	# it tries to restore a sane environnement before executing the real
+	# command.
+	# Replaces "aInfo" and "cInfo" in the query too.
+	#
+	# @param cmd The command to execute
+	# @param aInfo Dynamic properties
+	# @return True if the command succeeded
+	
 	def __processCmd(self, cmd, aInfo = None):
 		""" Executes an OS command.
 		"""
@@ -209,6 +285,18 @@ class Action:
 		
 		return Action.executeCmd(realCmd)
 
+	##
+	# Executes a command.
+	#
+	# We need a shell here because commands are mainly shell script. They
+	# contain pipe, redirection, etc.
+	# 
+	# @todo Force the use of bash!?
+	# @todo Kill the command after a given timeout
+	#
+	# @param realCmd the command to execute
+	# @return True if the command succeeded
+
 	@staticmethod
 	def executeCmd(realCmd):
 		logSys.debug(realCmd)

server/actions.py

@@ -56,22 +56,45 @@ class Actions(JailThread):
 		## The ban manager.
 		self.__banManager = BanManager()
 	
+	##
+	# Adds an action.
+	#
+	# @param name The action name
+	
 	def addAction(self, name):
 		action = Action(name)
 		self.__actions.append(action)
 	
+	##
+	# Removes an action.
+	#
+	# @param name The action name
+	
 	def delAction(self, name):
 		for action in self.__actions:
 			if action.getName() == name:
 				self.__actions.remove(action)
 				break
 	
+	##
+	# Returns an action.
+	#
+	# Raises a KeyError exception if the action does not exist.
+	#
+	# @param name the action name
+	# @return the action
+	
 	def getAction(self, name):
 		for action in self.__actions:
 			if action.getName() == name:
 				return action
 		raise KeyError
 	
+	##
+	# Returns the last defined action.
+	#
+	# @return The last defined action.
+	
 	def getLastAction(self):
 		action = self.__actions.pop()
 		self.__actions.append(action)

server/mytime.py

@@ -26,14 +26,35 @@ __license__ = "GPL"
 
 import time
 
+##
+# MyTime class.
+#
+# This class is a wrapper around time.time()  and time.gmtime(). When
+# performing unit test, it is very useful to get a fixed value from these
+# functions.
+# Thus, time.time() and time.gmtime() should never be called directly.
+# This wrapper should be called instead. The API are equivalent.
+
 class MyTime:
 	
 	myTime = None
 	
+	##
+	# Sets the current time.
+	#
+	# Use None in order to always get the real current time.
+	#
+	# @param t the time to set or None
+	
 	@staticmethod
 	def setTime(t):
 		MyTime.myTime = t
 	
+	##
+	# Equivalent to time.time()
+	#
+	# @return time.time() if setTime was called with None
+	
 	@staticmethod
 	def time():
 		if MyTime.myTime == None:
@@ -41,6 +62,11 @@ class MyTime:
 		else:
 			return MyTime.myTime
 	
+	##
+	# Equivalent to time.gmtime()
+	#
+	# @return time.gmtime() if setTime was called with None
+	
 	@staticmethod
 	def gmtime():
 		if MyTime.myTime == None: