DOC: Fix up doc strings styling to comply with numpy doc style

fail2ban/__init__.py

@@ -39,7 +39,7 @@ logging.addLevelName(logging.NOTICE, 'NOTICE')
 
 # define a new logger function for notice
 # this is exactly like existing info, critical, debug...etc
-def Logger_notice(self, msg, *args, **kwargs):
+def _Logger_notice(self, msg, *args, **kwargs):
 	"""
 	Log 'msg % args' with severity 'NOTICE'.
 
@@ -51,11 +51,11 @@ def Logger_notice(self, msg, *args, **kwargs):
 	if self.isEnabledFor(logging.NOTICE):
 		self._log(logging.NOTICE, msg, args, **kwargs)
 
-logging.Logger.notice = Logger_notice
+logging.Logger.notice = _Logger_notice
 
 # define a new root level notice function
 # this is exactly like existing info, critical, debug...etc
-def root_notice(msg, *args, **kwargs):
+def _root_notice(msg, *args, **kwargs):
 	"""
 	Log a message with severity 'NOTICE' on the root logger.
 	"""
@@ -64,7 +64,7 @@ def root_notice(msg, *args, **kwargs):
 	logging.root.notice(msg, *args, **kwargs)
 
 # make the notice root level function known
-logging.notice = root_notice
+logging.notice = _root_notice
 
 # add NOTICE to the priority map of all the levels
 logging.handlers.SysLogHandler.priority_map['NOTICE'] = 'notice'

fail2ban/server/action.py

@@ -96,11 +96,28 @@ class ActionBase(object):
 	place to create a Python based action for Fail2Ban. This class can
 	be inherited from to ease implementation.
 	Required methods:
-	 - __init__(jail, name)
-	 - start()
-	 - stop()
-	 - ban(aInfo)
-	 - unban(aInfo)
+
+	- __init__(jail, name)
+	- start()
+	- stop()
+	- ban(aInfo)
+	- unban(aInfo)
+
+	Called when action is created, but before the jail/actions is
+	started. This should carry out necessary methods to initialise
+	the action but not "start" the action.
+
+	Parameters
+	----------
+	jail : Jail
+		The jail in which the action belongs to.
+	name : str
+		Name assigned to the action.
+
+	Notes
+	-----
+	Any additional arguments specified in `jail.conf` or passed
+	via `fail2ban-client` will be passed as keyword arguments.
 	"""
 	__metaclass__ = ABCMeta
 
@@ -118,24 +135,6 @@ class ActionBase(object):
 		return True
 
 	def __init__(self, jail, name):
-		"""Initialise action.
-
-		Called when action is created, but before the jail/actions is
-		started. This should carry out necessary methods to initialise
-		the action but not "start" the action.
-
-		Parameters
-		----------
-		jail : Jail
-			The jail in which the action belongs to.
-		name : str
-			Name assigned to the action.
-
-		Notes
-		-----
-		Any additional arguments specified in `jail.conf` or passed
-		via `fail2ban-client` will be passed as keyword arguments.
-		"""
 		self._jail = jail
 		self._name = name
 		self._logSys = logging.getLogger(
@@ -177,22 +176,27 @@ class CommandAction(ActionBase):
 	"""A action which executes OS shell commands.
 
 	This is the default type of action which Fail2Ban uses.
+
+	Default sets all commands for actions as empty string, such
+	no command is executed.
+
+	Parameters
+	----------
+	jail : Jail
+		The jail in which the action belongs to.
+	name : str
+		Name assigned to the action.
+
+	Attributes
+	----------
+	actionban
+	actionstart
+	actionstop
+	actionunban
+	timeout
 	"""
 
 	def __init__(self, jail, name):
-		"""Initialise action.
-
-		Default sets all commands for actions as empty string, such
-		no command is executed.
-
-		Parameters
-		----------
-		jail : Jail
-			The jail in which the action belongs to.
-		name : str
-			Name assigned to the action.
-		"""
-
 		super(CommandAction, self).__init__(jail, name)
 		self.timeout = 60
 		## Command executed in order to initialize the system.

fail2ban/server/actions.py

@@ -49,16 +49,27 @@ class Actions(JailThread, Mapping):
 	Mapping type, and the `add` method must be used to add new actions.
 	This class also starts and stops the actions, and fetches bans from
 	the jail executing these bans via the actions.
+
+	Parameters
+	----------
+	jail: Jail
+		The jail of which the actions belongs to.
+
+	Attributes
+	----------
+	daemon
+	ident
+	name
+	status
+	active : bool
+		Control the state of the thread.
+	idle : bool
+		Control the idle state of the thread.
+	sleeptime : int
+		The time the thread sleeps for in the loop.
 	"""
 
 	def __init__(self, jail):
-		"""Initialise an empty Actions instance.
-
-		Parameters
-		----------
-		jail: Jail
-			The jail of which the actions belongs to.
-		"""
 		JailThread.__init__(self)
 		## The jail which contains this action.
 		self._jail = jail

fail2ban/server/database.py

@@ -62,6 +62,30 @@ class Fail2BanDb(object):
 
 	This allows after Fail2Ban is restarted to reinstated bans and
 	to continue monitoring logs from the same point.
+
+	This will either create a new Fail2Ban database, connect to an
+	existing, and if applicable upgrade the schema in the process.
+
+	Parameters
+	----------
+	filename : str
+		File name for SQLite3 database, which will be created if
+		doesn't already exist.
+	purgeAge : int
+		Purge age in seconds, used to remove old bans from
+		database during purge.
+
+	Raises
+	------
+	sqlite3.OperationalError
+		Error connecting/creating a SQLite3 database.
+	RuntimeError
+		If exisiting database fails to update to new schema.
+
+	Attributes
+	----------
+	filename
+	purgeage
 	"""
 	__version__ = 2
 	# Note all _TABLE_* strings must end in ';' for py26 compatibility
@@ -98,27 +122,6 @@ class Fail2BanDb(object):
 			"CREATE INDEX bans_ip ON bans(ip);" \
 
 	def __init__(self, filename, purgeAge=24*60*60):
-		"""Initialise the database by connecting/creating SQLite3 file.
-
-		This will either create a new Fail2Ban database, connect to an
-		existing, and if applicable upgrade the schema in the process.
-
-		Parameters
-		----------
-		filename : str
-			File name for SQLite3 database, which will be created if
-			doesn't already exist.
-		purgeAge : int
-			Purge age in seconds, used to remove old bans from
-			database during purge.
-
-		Raises
-		------
-		sqlite3.OperationalError
-			Error connecting/creating a SQLite3 database.
-		RuntimeError
-			If exisiting database fails to update to new schema.
-		"""
 		try:
 			self._lock = Lock()
 			self._db = sqlite3.connect(

fail2ban/server/datedetector.py

@@ -31,11 +31,13 @@ logSys = logging.getLogger(__name__)
 
 class DateDetector(object):
 	"""Manages one or more date templates to find a date within a log line.
+
+	Attributes
+	----------
+	templates
 	"""
 
 	def __init__(self):
-		"""Initialise the date detector.
-		"""
 		self.__lock = Lock()
 		self.__templates = list()
 		self.__known_names = set()

fail2ban/server/datetemplate.py

@@ -41,11 +41,14 @@ class DateTemplate(object):
 
 	This is an not functional abstract class which other templates should
 	inherit from.
+
+	Attributes
+	----------
+	name
+	regex
 	"""
 
 	def __init__(self):
-		"""Initialise the date template.
-		"""
 		self._name = ""
 		self._regex = ""
 		self._cRegex = None
@@ -123,11 +126,14 @@ class DateEpoch(DateTemplate):
 
 	This includes Unix timestamps which appear at start of a line, optionally
 	within square braces (nsd), or on SELinux audit log lines.
+
+	Attributes
+	----------
+	name
+	regex
 	"""
 
 	def __init__(self):
-		"""Initialise the date template.
-		"""
 		DateTemplate.__init__(self)
 		self.regex = "(?:^|(?P<square>(?<=^\[))|(?P<selinux>(?<=audit\()))\d{10}(?:\.\d{3,6})?(?(selinux)(?=:\d+\))(?(square)(?=\])))"
 
@@ -152,6 +158,19 @@ class DateEpoch(DateTemplate):
 		return None
 
 class DatePatternRegex(DateTemplate):
+	"""Date template, with regex/pattern
+
+	Parameters
+	----------
+	pattern : str
+		Sets the date templates pattern.
+
+	Attributes
+	----------
+	name
+	regex
+	pattern
+	"""
 	_patternRE = r"%%(%%|[%s])" % "".join(timeRE.keys())
 	_patternName = {
 		'a': "DAY", 'A': "DAYNAME", 'b': "MON", 'B': "MONTH", 'd': "Day",
@@ -159,17 +178,10 @@ class DatePatternRegex(DateTemplate):
 		'M': "Minute", 'p': "AMPM", 'S': "Second", 'U': "Yearweek",
 		'w': "Weekday", 'W': "Yearweek", 'y': 'Year2', 'Y': "Year", '%': "%",
 		'z': "Zone offset", 'f': "Microseconds", 'Z': "Zone name"}
-	for key in set(timeRE) - set(_patternName): # may not have them all...
-		_patternName[key] = "%%%s" % key
+	for _key in set(timeRE) - set(_patternName): # may not have them all...
+		_patternName[_key] = "%%%s" % _key
 
 	def __init__(self, pattern=None):
-		"""Initialise date template, with optional regex/pattern
-
-		Parameters
-		----------
-		pattern : str
-			Sets the date templates pattern.
-		"""
 		super(DatePatternRegex, self).__init__()
 		self._pattern = None
 		if pattern is not None:
@@ -229,11 +241,14 @@ class DatePatternRegex(DateTemplate):
 
 class DateTai64n(DateTemplate):
 	"""A date template which matches TAI64N formate timestamps.
+
+	Attributes
+	----------
+	name
+	regex
 	"""
 
 	def __init__(self):
-		"""Initialise the date template.
-		"""
 		DateTemplate.__init__(self)
 		# We already know the format for TAI64N
 		# yoh: we should not add an additional front anchor

fail2ban/server/jail.py

@@ -36,6 +36,25 @@ class Jail:
 	The class handles the initialisation of a filter, and actions. It's
 	role is then to act as an interface between the filter and actions,
 	passing bans detected by the filter, for the actions to then act upon.
+
+	Parameters
+	----------
+	name : str
+		Name assigned to the jail.
+	backend : str
+		Backend to be used for filter. "auto" will attempt to pick
+		the most preferred backend method. Default: "auto"
+	db : Fail2BanDb
+		Fail2Ban persistent database instance. Default: `None`
+
+	Attributes
+	----------
+	name
+	database
+	filter
+	actions
+	idle
+	status
 	"""
 
 	#Known backends. Each backend should have corresponding __initBackend method
@@ -44,18 +63,6 @@ class Jail:
 	_BACKENDS = ['pyinotify', 'gamin', 'polling', 'systemd']
 
 	def __init__(self, name, backend = "auto", db=None):
-		"""Initialise a jail, by initalises filter and actions.
-
-		Parameters
-		----------
-		name : str
-			Name assigned to the jail.
-		backend : str
-			Backend to be used for filter. "auto" will attempt to pick
-			the most preferred backend method. Default: "auto"
-		db : Fail2BanDb
-			Fail2Ban persistent database instance. Default: `None`
-		"""
 		self.__db = db
 		# 26 based on iptable chain name limit of 30 less len('f2b-')
 		if len(name) >= 26:

fail2ban/server/jails.py

@@ -39,8 +39,6 @@ class Jails(Mapping):
 	"""
 
 	def __init__(self):
-		"""Initialise an empty Jails instance.
-		"""
 		self.__lock = Lock()
 		self._jails = dict()
 

fail2ban/server/jailthread.py

@@ -29,11 +29,22 @@ from abc import abstractproperty, abstractmethod
 
 class JailThread(Thread):
 	"""Abstract class for threading elements in Fail2Ban.
+
+	Attributes
+	----------
+	daemon
+	ident
+	name
+	status
+	active : bool
+		Control the state of the thread.
+	idle : bool
+		Control the idle state of the thread.
+	sleeptime : int
+		The time the thread sleeps for in the loop.
 	"""
 
 	def __init__(self):
-		"""Initialise a JailThread instance.
-		"""
 		super(JailThread, self).__init__()
 		## Control the state of the thread.
 		self.active = False