Add comments and documentation

Author: kashyap-thacker

python_common_logger/__init__.py

@@ -1,6 +1,29 @@
+"""
+Python Common Logger to log in JSON format with context data.
+
+Check: https://simpplr.atlassian.net/wiki/spaces/SA/pages/2467365251/Logging+Strategy
+
+Classes:
+    Logger.ContextFilter
+    DjangoMiddleware.ContextMiddleware
+    ContextConstants.ExecutionContextType
+    LoggingConstants.LoggerContextConfigKeys
+    LoggingConstants.LoggerKeys
+    RequestConstants.RequestHeaderKeys
+
+Functions:
+    Logger.initialise_console_logger(logger_name, service_name, level=logging.WARNING, context_config=None)
+    ContextHandler.get_thread_execution_context(key='execution_context')
+    ContextHandler.update_execution_context(execution_context, key='execution_context', reset=False)
+"""
+
 from .src import logger as Logger
 from .src.context import context_handler as ContextHandler
 from .src.django import middleware as DjangoMiddleware
 
+from .src.constants import context as ContextConstants
+from .src.constants import logger as LoggingConstants
+from .src.constants import request as RequestConstants
+
 from .src.context.execution_context import *
 

python_common_logger/src/constants/context.py

@@ -1,6 +1,18 @@
 from enum import Enum
 
 class ExecutionContextType(Enum):
+    """
+    ExecutionContextType
+
+    Attributes
+    ----------
+    CORRELATION_ID : str
+        Correlation Id
+    TENANT_ID : str
+        Tenant Id
+    USER_ID : str
+        User Id
+    """
     CORRELATION_ID = 'correlation_id'
     TENANT_ID = 'tenant_id'
     USER_ID = 'user_id'

python_common_logger/src/constants/logger.py

@@ -1,11 +1,35 @@
 from enum import Enum
 
-class ContextConfig(Enum):
+class LoggerContextConfigKeys(Enum):
+    """
+    Context Config Keys
+
+    Attributes
+    ----------
+    DISABLE_TID : str
+        Disable Tenant Id
+    DISABLE_UID : str
+        Disable User Id
+    DISABLE_CID : str
+        Disable Correlation Id
+    """
     DISABLE_TID = 'disable_tid'
     DISABLE_UID = 'disable_uid'
     DISABLE_CID = 'disable_cid'
 
 class LoggerKeys(Enum):
+    """
+    Logging Key
+
+    Attributes
+    ----------
+    CORRELATION_ID : str
+        Correlation Id
+    TENANT_ID : str
+        Tenant Id
+    USER_ID : str
+        User Id
+    """
     CORRELATION_ID = 'cid'
     TENANT_ID = 'tid'
     USER_ID = 'uid'

python_common_logger/src/constants/request.py

@@ -1,6 +1,18 @@
 from enum import Enum
 
 class RequestHeaderKeys(Enum):
+    """
+    Header keys
+
+    Attributes
+    ----------
+    ACCOUNT_ID : str
+        Account Id / Tenant ID
+    USER_ID : str
+        User Id
+    CORRELATION_ID : str
+        Correlation Id
+    """
     ACCOUNT_ID = 'x-smtip-tid',
     USER_ID = 'x-smtip-uid',
     CORRELATION_ID = 'x-smtip-cid',

python_common_logger/src/context/context_handler.py

@@ -4,13 +4,34 @@
 
 _locals = local()
 
-def get_thread_execution_context() -> ExecutionContext:
-    return getattr(_locals, 'execution_context', ExecutionContext({}))
+def get_thread_execution_context(key='execution_context') -> ExecutionContext:
+    """
+    Fetches the execution context from the thread local. If absent, initialises and returns an empty one.
 
-def update_execution_context(execution_context: ExecutionContext, reset=False):
+    Args:
+        key (str, optional): key. Defaults to 'execution_context'.
+    
+    Returns:
+        ExecutionContext: Thread local execution context.
+    """
+    return getattr(_locals, key, ExecutionContext({}))
+
+def update_execution_context(execution_context: ExecutionContext, key='execution_context', reset=False) -> ExecutionContext:
+    """
+    Updates the execution context.
+
+    Args:
+        execution_context (ExecutionContext): Execution context to be updated.
+        key (str, optional): key. Defaults to 'execution_context'.
+        reset (bool, optional): Reset the entire context. Defaults to False.
+
+    Returns:
+        ExecutionContext: Updated execution context
+    """
     current_execution_context: ExecutionContext = get_thread_execution_context()
 
     current_execution_context.update(execution_context.get_context(), reset)
 
-    setattr(_locals, 'execution_context', current_execution_context)
+    setattr(_locals, key, current_execution_context)
+
     return current_execution_context

python_common_logger/src/context/execution_context.py

@@ -4,6 +4,23 @@
 from ..constants.context import ExecutionContextType
 
 class ExecutionContext:
+    """
+    Stores the Execution context and provides helper methods to manage it.
+
+    Methods
+    -------
+    update(execution_context:dict, reset:bool=False):
+        Updates the Execution Context.
+
+    get_context_by_key(key:str):
+        Returns the execution context stored for the provided key.
+
+    get_context() -> dict:
+        Returns the entire execution context.
+    
+    reset(key:str):
+        Resets the context.
+    """
     ALLOWED_KEYS = [e.value for e in ExecutionContextType]
 
     def __init__(self, execution_context: dict):
@@ -16,21 +33,48 @@ def __init__(self, execution_context: dict):
                 self._context[key] = execution_context[key]
 
     def update(self, execution_context: dict, reset=False):
+        """
+        Updates the execution context.
+
+        Args:
+            execution_context (dict): Execution context to be updated.
+            reset (bool, optional): If True, replaces the entire context. If False, updates only the provided values. Defaults to False.
+
+        Raises:
+            ValidationException: If an invalid key is provided.
+        """
         if reset:
             self.reset()
 
         for key in execution_context.keys():
             if key  not in self.ALLOWED_KEYS:
-                # TODO: Create Validation error
                 raise ValidationException(f'Invalid execution context type: {key}')
             else:
                 self._context[key] = execution_context[key]
 
     def get_context_by_key(self, key: str) -> str:
+        """
+        Returns the execution context for the specified key
+
+        Args:
+            key (str): key
+
+        Returns:
+            any: Execution Context
+        """
         return copy.deepcopy(self._context[key])
 
     def get_context(self) -> dict:
+        """
+        Returns the execution context.
+
+        Returns:
+            dict: Entire execution context
+        """
         return copy.deepcopy(self._context)
 
     def reset(self):
+        """
+        Resets the execution context.
+        """
         self._context = {}

python_common_logger/src/django/middleware.py

@@ -6,6 +6,10 @@
 from ..constants.context import ExecutionContextType
 
 class ContextMiddleware():
+    """
+    Django Context Middle. Extracts the headers from the request and populates the execution context
+    in thread local data.
+    """
     def __init__(self, get_response):
         self.get_response = get_response
 

python_common_logger/src/logger.py

@@ -5,10 +5,14 @@
 from .context.context_handler import get_thread_execution_context
 from .context.execution_context import ExecutionContext, ExecutionContextType
 
-from .constants.logger import LoggerKeys, ContextConfig
+from .constants.logger import LoggerKeys, LoggerContextConfigKeys
 from .constants.context import ExecutionContextType
 
 class ContextFilter(logging.Filter):
+    """
+    Log filter to extract the execution context from thread locals and populate it in the log record
+    """
+
     def filter(self, record):
         execution_context: ExecutionContext = get_thread_execution_context()
 
@@ -21,15 +25,27 @@ def filter(self, record):
                 setattr(record, key, '')
         return True
 
-def initialise_console_logger(service_name, level=logging.WARNING, context_config=None):
-    logger = logging.getLogger(service_name)
+def initialise_console_logger(logger_name, service_name, level=logging.WARNING, context_config=None):
+    """
+    Initialises the logger with the handler, formatter and filter to log context data along with message
+    in JSON format on the console.
+
+    Args:
+        logger_name (string): Name of the logger to be initialised
+        service_name (string): Service name that appears as the source in the logs
+        level (int, optional): Log level. Defaults to logging.WARNING.
+        context_config (dict, optional): Context config to configure logging parameters See LoggerContextConfigKeys for list of allowed params. Defaults to None.
+
+    Returns:
+        Logger: Initialised logger
+    """
+    logger = logging.getLogger(logger_name)
 
     # Create handlers
-    c_handler = logging.StreamHandler(sys.stdout)
+    log_handler = logging.StreamHandler(sys.stdout)
 
-    # Populate Context Filter in Record
     log_format = {
-        "source": "%(name)s",
+        "source": f"{service_name}",
         "time": "%(asctime)s",
         "log": {
             "message": "%(message)s"
@@ -40,23 +56,24 @@ def initialise_console_logger(service_name, level=logging.WARNING, context_confi
     if not context_config:
         context_config = {}
 
-    if not context_config.get(ContextConfig.DISABLE_CID.value):
+    if not context_config.get(LoggerContextConfigKeys.DISABLE_CID.value):
         log_format[LoggerKeys.CORRELATION_ID.value] = f"%({ExecutionContextType.CORRELATION_ID.value})s"
 
-    if not context_config.get(ContextConfig.DISABLE_TID.value):
+    if not context_config.get(LoggerContextConfigKeys.DISABLE_TID.value):
         log_format[LoggerKeys.TENANT_ID.value] = f"%({ExecutionContextType.TENANT_ID.value})s"
 
-    if not context_config.get(ContextConfig.DISABLE_UID.value):
+    if not context_config.get(LoggerContextConfigKeys.DISABLE_UID.value):
         log_format[LoggerKeys.USER_ID.value] = f"%({ExecutionContextType.USER_ID.value})s"
 
     # Create formatters and add it to handlers
-    c_format = logging.Formatter(json.dumps(log_format), datefmt='%Y-%m-%dT%H:%M:%S%z')
+    log_formatter = logging.Formatter(json.dumps(log_format), datefmt='%Y-%m-%dT%H:%M:%S%z')
+    log_handler.setFormatter(log_formatter)
+    
+    # Populate Context Filter in Record
+    log_handler.addFilter(ContextFilter())
 
-    c_handler.setFormatter(c_format)
-    c_handler.addFilter(ContextFilter())
+    logger.addHandler(log_handler)
 
-    # Add handlers to the logger
-    logger.addHandler(c_handler)
     logger.setLevel(level)
 
     return logger