Revize 22c09a00

re #9422 Commented both config files and api_client.py.

client/resources/client.conf

@@ +1 @@
+# This file is the configuration of the application.
+# ==================================================
+
 [usb_detector]
+# Number of seconds after which all USB devices are periodically scanned.
+# This value is a float number. It can be set to, for example, 0.1, 0.5, 300, etc.
 scan_period_seconds = 1
+
+# Path to the file that contains a list of the currently
+# connected USB devices. This file is updated whenever a device
+# is plugged or unplugged.
 connected_devices_filename = data/devices.json
 
+# ==================================================
+
 [server]
+# IP address of the server that the client sends data to.
 url = http://127.0.0.1
+
+# Port that the server listens on.
 port = 8000
+
+# Endpoint through which the server receives data from the client.
+# These three values (url, port, end_point) make up a URI that is
+# created internally by the client e.g. http://127.0.0.1:8000/api/v1/usb-logs
 end_point = /api/v1/usb-logs
 
+# ==================================================
+
 [logger]
+# Path to the logger configuration file
 config_file = ../resources/logger.conf
 
+# ==================================================
+
 [cache]
+# Name of the folder where the cache is held. This folder is created
+# automatically by the client.
 directory = data
-max_entries = 100
-max_retries = 20
+
+# Number of seconds after which the application attempts to resent a predefined
+# number of cached payloads to the server (periodically).
 retry_period_seconds = 20
+
+# Maximum number of entries (payloads) that can be cached. If the total number of cached
+# payloads reaches this number, the application will discard the oldest record with
+# every new payload (FIFO - queue).
+max_entries = 100
+
+# Number of cached entries (payloads) that can be sent to the server at a time (within one period).
+max_retries = 20

client/resources/logger.conf

@@ +1 @@
+# This file is the logger configuration file.
+# ==========================================
+
 [loggers]
+# Name of the logger.
 keys=root
 
+# ==========================================
+
 [handlers]
-keys=consoleHandler,logFileHandler
+# List of different types of handlers defined within the application.
+keys=consoleHandler, logFileHandler
+
+# ==========================================
 
 [formatters]
+# Name of the formatter used for the log messages.
 keys=simpleFormatter
 
+# ==========================================
+
 [logger_root]
+# Level of debugging set for the root logger.
 level=DEBUG
+
+# Handler set for the root logger.
 handlers=consoleHandler
 
+# ==========================================
+
 [handler_consoleHandler]
+# Class used for the console logger.
 class=StreamHandler
+
+# Level of debugging set for the console logger.
 level=DEBUG
+
+# Formatter used for for the console logger.
 formatter=simpleFormatter
+
+# Arguments passed in upon instantiating the logger.
 args=(sys.stdout,)
 
+# ==========================================
+
 [handler_logFileHandler]
+# Class used for the file logger - rotating file.
 class=handlers.RotatingFileHandler
+
+# Level of debugging set for the file logger.
 level=NOTSET
+
+# Arguments passed in when instantiating the logger.
+# log_file.log - name of the rotating log file
+# a            - append to the file - do not overwrite it
+# 10485760     - maximum size of the file - 10 MB
+# 1            - number of backups kept on the disk
 args=('log_file.log', 'a', 10485760, 1)
+
+# Formatter used for the file logger.
 formatter=simpleFormatter
 
+# ==========================================
+
 [formatter_simpleFormatter]
+# Definition of a custom log formatter. All log
+# messages have the following format: [datetime] - [level] - [message]
 format=%(asctime)s - %(levelname)s - %(message)s

client/src/usb_detector/api_client.py

@@ -6 +6 @@
 from requests import HTTPError, ConnectionError
 from requests.exceptions import InvalidSchema
 
-_uri = None
-_cache = None
-_config = None
+
+_uri = None     # server uri (url, port, and endpoint)
+_cache = None   # cache (failed payloads)
+_config = None  # instance of Config
 
 
 def api_client_set_config(config):
+    """Initializes the client API module.
+
+    This function is meant to be called prior to calling any other function
+    of the API module. It stores the instance of Config (config manager)
+    into a private variable. It also initializes the cache for unsuccessful
+    payloads and constructs a URI (endpoint on the server side).
+
+    :param config: instance of Config which holds all values defined
+                   in the configuration file.
+    """
+    # Store the variables globally within the module (file).
     global _config, _cache, _uri
+
+    # Store the instance of Config and initialize the cache.
     _config = config
     _cache = _init_cache()
+
+    # Creates the URI which is made of the server url, port, and path (endpoint).
     _uri = config.server_url + ":" + config.server_port + config.server_endpoint
 
 
 def _init_cache():
+    """ Initializes and returns a disk-based cache.
+
+    The cache holds payloads that the application failed
+    to send to the server. It periodically attempts to resent
+    them to the server. All parameters can be seen in the
+    configuration file.
+
+    :return: instance of a new cache (Deque - FIFO)
+    """
     return Deque(directory=_config.cache_dir)
 
 
 def send_data(payload: dict):
+    """Sends a payload off to the server.
+
+    This function is called whenever a USB is connected
+    or disconnected. If there is no internet connection or the
+    server is not up and running, the payload will be stored
+    into the disk cache.
+
+    :param payload:
+    """
+    # Make sure that the URI has been constructed properly.
+    # It's supposed to be done by calling the api_client_set_config function
+    # with appropriate parameters.
     if _uri is None:
         logging.warning(f"sending payload = {payload} failed because uri is set to None")
         _cache_failed_payload(payload)
@@ -40 +77 @@
 
 
 def _cache_failed_payload(payload: dict):
+    """ Caches a payload.
+
+    This function is called when the application fails to send a payload
+    to the server. The payload gets stored into a file-based cache from which
+    it will be periodically retrieved as the client will attempt to send
+    it to the server again. All parameters regarding the cache can be found
+    in the configuration file.
+
+    :param payload: payload to be cached
+    """
+    # If the cache is "full", discard the oldest record.
     if len(_cache) >= _config.cache_max_entries:
         oldest_payload = _cache.pop()
         logging.warning(f"cache is full - discarding payload = {oldest_payload}")
 
+    # Store the payload into the cache.
     logging.info(f"adding payload = {payload} into cache")
     _cache.append(payload)
 
 
 def _resend_cached_payloads():
+    """Reattempts to send cached payloads to the server (API).
+
+    In the configuration file, there is a predefined number of
+    payloads that can be sent to the server with each call of this function.
+    This function is called periodically from api_client_run in order
+    to resend failed payloads to the server.
+
+    """
+    # Calculate how many payload will be sent to the server
     retries = min(_config.cache_max_retries, len(_cache))
     logging.info(f"emptying the cache ({retries} records)")
+
+    # Send the payloads to the server one by one.
     for _ in range(0, retries):
         payload = _cache.pop()
         send_data(payload)
 
 
 def api_client_run():
+    """ Keeps resending failed payloads to the server.
+
+    This function is instantiated as a thread that periodically
+    calls the _resend_cached_payloads function in order to empty
+    the cache (failed payloads). The period can be set in the
+    configuration file.
+    """
     while True:
+        # Resend a predefined amount of failed payloads to the server.
         _resend_cached_payloads()
+
+        # Sleep for a predefined amount of seconds.
         sleep(_config.cache_retry_period_seconds)