config documentation

.gitignore

@@ -10,3 +10,4 @@
 *.sqlite3
 *.db
 **/matemat.conf
+static/upload/

doc

@@ -1 +1 @@
-Subproject commit d5dc5f794ad1b959b9d4dce47eeb6068e5a75115
+Subproject commit c68df9d86af1d8d0ebb6b6609efeef14f7103761

matemat/webserver/config.py

@@ -8,13 +8,30 @@ from configparser import ConfigParser
 
 
 def parse_logging(symbolic_level: str, symbolic_target: str) -> Tuple[int, logging.Handler]:
+    """
+    Parse the LogLevel and LogTarget from configuration.
+    The LogLevel value may be either an integer or a log level literal defined in the Python builtin logging module.
+    The LogTarget value may be one of the following:
+        - `stderr` to log to error output (default)
+        - `stdout` to log to standard output
+        - `none` to disable logging
+        - Any other value is interpreted as a filename
+
+    :param symbolic_level: The value for the LogLevel key.
+    :param symbolic_target: The value for the LogTarget key.
+    :return: A tuple of the log level (as an int) and the logging.Handler derived from the log target string.
+    """
     try:
+        # Attempt to cast the log level into an int
         level: int = int(symbolic_level)
     except ValueError:
         try:
+            # If this fails, look up the name in the logging class
             level = int(logging.getLevelName(symbolic_level))
         except ValueError:
+            # LogLevel value was neither an int nor a known literal
             raise ValueError(f'Unknown log level: {symbolic_level}')
+    # Special handling of the strings "stderr", "stdout" and "none"
     if symbolic_target == 'stderr':
         target: logging.Handler = logging.StreamHandler(sys.stderr)
     elif symbolic_target == 'stdout':
@@ -22,7 +39,9 @@ def parse_logging(symbolic_level: str, symbolic_target: str) -> Tuple[int, loggi
     elif symbolic_target == 'none':
         target = logging.NullHandler()
     else:
+        # Fallback: Interpret string as filename
         target = logging.FileHandler(os.path.abspath(os.path.expanduser(symbolic_target)))
+    # Return log level and log target
     return level, target
 
 

matemat/webserver/httpd.py

@@ -120,8 +120,8 @@ class MatematHTTPServer(HTTPServer):
         # Set up logger
         self.logger: logging.Logger = logging.getLogger('matemat.webserver')
         self.logger.setLevel(log_level)
-        # Set up log handler
+        # Set up the log handler's (obtained from config parsing) format string
-        log_handler.setFormatter(logging.Formatter('%(asctime)s @ %(name)s [%(levelname)s]: %(message)s'))
+        log_handler.setFormatter(logging.Formatter('%(asctime)s %(name)s [%(levelname)s]: %(message)s'))
         self.logger.addHandler(log_handler)
 
 

matemat/webserver/test/abstract_httpd_test.py

@@ -119,8 +119,9 @@ class MockServer:
         # Set up logger
         self.logger: logging.Logger = logging.getLogger('matemat unit test')
         self.logger.setLevel(0)
+        # Initalize a log handler to stderr and set the log format
         sh: logging.StreamHandler = logging.StreamHandler()
-        sh.setFormatter(logging.Formatter('%(asctime)s @ %(name)s [%(levelname)s]: %(message)s'))
+        sh.setFormatter(logging.Formatter('%(asctime)s %(name)s [%(levelname)s]: %(message)s'))
         self.logger.addHandler(sh)