[GNUnet-SVN] [taler-taler-util] 40/51: Doxygen-commenting gnunet_log.py

[gnunet]

This is an automated email from the git hooks/post-receive script.

ng0 pushed a commit to branch master
in repository taler-util.

commit 3063c4e08d34b8065b5dce899bcbf89edd79cb84
Author: Marcello Stanisci <address@hidden>
AuthorDate: Mon Mar 11 14:14:42 2019 +0100

    Doxygen-commenting gnunet_log.py
---
 python/log/gnunet_log.py | 100 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/python/log/gnunet_log.py b/python/log/gnunet_log.py
index 99f221a..5a7d0b2 100755
--- a/python/log/gnunet_log.py
+++ b/python/log/gnunet_log.py
@@ -1,3 +1,24 @@
+##
+#
+# This file is part of TALER
+# (C) 2014, 2015, 2016 INRIA
+#
+# TALER is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation; either version 3, or
+# (at your option) any later version. TALER is distributed in the
+# hope that it will be useful, but WITHOUT ANY WARRANTY; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public
+# License along with TALER; see the file COPYING.  If not, see
+# <http://www.gnu.org/licenses/>
+#
+# @author Marcello Stanisci
+# @brief Implementation of the GNUnet logging logic.
+#
 #!/usr/bin/env python3
 
 # GNUNET_FORCE_LOG format [component];[file];[function];[from line [to 
line]];loglevel
@@ -8,7 +29,21 @@ import logging
 import datetime
 import inspect
 
+
+##
+# Represent a definition for one logging action.
 class LogDefinition:
+
+    ##
+    # Init constructor.
+    #
+    # @param self the object itself.
+    # @param component which component this definition is going to affect.
+    # @param filename which filename this definition is going to affect.
+    # @param function which function this definition is going to affect.
+    # @param line_interval which line_interval this definition is going to 
affect.
+    # @param loglevel which loglevel is accepted.
+    # @param forced does this definition come from GNUNET_FORCE_LOG?
     def __init__(self, component, filename, function, line_interval, loglevel, 
forced):
         self.forced = forced
         self.component = ".*" if "" == component else component
@@ -19,6 +54,15 @@ class LogDefinition:
         # string here
         self.loglevel = loglevel
 
+    ##
+    # Parse the @a line_interval from a logging definition.
+    #
+    # @param self the object itself.
+    # @param line_interval the line interval value as it comes
+    #        from the user definition.  The format is X[-Y].
+    # @return a dict with min/max fields; if max is not given,
+    #         then min == max.  If the input is wrong, then just
+    #         match every line.
     def __parse_line_interval(self, line_interval):
         interval_re = "^([0-9]+)(-([0-9]+))?$"
         match = re.match(interval_re, line_interval)
@@ -29,6 +73,14 @@ class LogDefinition:
         # just match every line if bad interval was provided.
         return dict(min=0, max=float("inf"))
 
+##
+# Represent a loglevel.
+#
+# @param self the object itself.
+# @param string the loglevel given as a string (DEBUG/ERROR/WARNING/...)
+# @param level the loglevel given as for the 'logging' module API.
+# @param function the native function from 'logging' module that
+#        _actually_ outputs the log line.
 class GnunetLoglevel:
     def __init__(self, string, level, function):
         self.string = string
@@ -44,6 +96,13 @@ class GnunetLoglevel:
     def getFunction(self):
         return self.function
 
+
+##
+# The "mother" class of this module.  This class is in charge of
+# parsing the definitions given by the user, from all the streams:
+# being it programmatical, or the environment.  It is also in charge
+# of giving the right precedence to the streams: e.g. GNUNET_FORCE_LOG
+# takes precedence over the "setup()" method.
 class GnunetLogger:
 
     COMPONENT_IDX = 0
@@ -52,6 +111,12 @@ class GnunetLogger:
     LINE_INTERVAL = 3
     LEVEL_IDX = 4
 
+    ##
+    # Init contructor.
+    #
+    # @param self the object itself.
+    # @param component the component name, that will be fed
+    #        to the native 'logging' API.
     def __init__(self, component):
         self.logger = logging.getLogger(component)
         self.ERROR = GnunetLoglevel("ERROR", logging.ERROR, self.logger.error)
@@ -84,6 +149,15 @@ class GnunetLogger:
             fh = logging.FileHandler(filename)
             self.logger.addHandler(fh)
 
+
+    ##
+    # Parse the filename where to write log lines.
+    #
+    # @param self the object itself.
+    # @param filename the filename to parse (usually given
+    #        to the '-l' option).
+    # @return the parse filename string (with all the dates
+    #         placeholders interpreted.)
     def parse_filename(self, filename):
         # implement {} and [] substitution.
         f = filename.replace("{}", self.component)
@@ -94,8 +168,16 @@ class GnunetLogger:
         f = f.replace("%d", now.strftime("%d"))
         return f
 
+
+    ##
+    # Maps loglevels as strings, to loglevels as defined
+    # in _this_ object.
+    #
+    # @param self the object itself.
+    # @param level the string to map.
+    # @return the loglevel native of _this_ object; defaults
+    #         to INFO, if not found in the map.
     def string_to_loglevel(self, level):
-        
         level_map = {
             "ERROR": self.ERROR,
             "WARNING": self.WARNING,
@@ -105,9 +187,18 @@ class GnunetLogger:
         # Defaults to INFO.
         return level_map.get(level, self.INFO)
 
+
+    ##
+    # Set the loglevel for this module.
     def setup(self, loglevel):
         self.loglevel = loglevel
 
+    ##
+    # Log API for users to produce logs.
+    #
+    # @param self the object itself.
+    # @param message the message to log.
+    # @param message_loglevel the loglevel associated with the message.
     def log(self, message, message_loglevel):
         caller_frame = inspect.stack()[1]
 
@@ -154,6 +245,13 @@ class GnunetLogger:
 
         message_loglevel.getFunction()(message)
 
+
+    ##
+    # Helper function that parses definitions coming from the environment.
+    #
+    # @param self the object itself.
+    # @param line the definition coming from the environment.
+    # @param forced whether the definition comes from GNUNET_FORCE_LOG or not.
     def __parse_definitions(self, line, forced):
         gfl_split = line.split("/")
         for component in gfl_split:

-- 
To stop receiving notification emails like this one, please contact
address@hidden.