chores: add an example of how logging can be used across modules

Author: ecarrenolozano

pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Bio-Informatics"
 ]
 dependencies = [
+    "numpy>=2.2.6",
     "toml"
 ]
 description = "This is session handler, configuration and logging handler for Saezlab packages and applications."

saezlab_core/__init__.py

@@ -13,11 +13,16 @@
 # https://opensource.org/license/mit
 #
 
+from .logger import get_logger
+from .session import Session
+
+__all__ = ['get_logger', 'Session']
+
 """This is session handler, configuration and logging handler for Saezlab packages and applications."""
 
 __all__ = [
     '__version__',
     '__author__',
 ]
 
-from ._metadata import __author__, __version__
+# from ._metadata import __author__, __version__

saezlab_core/logger.py

@@ -0,0 +1,89 @@
+import sys
+from typing import Optional
+import logging
+from datetime import datetime
+from logging.handlers import RotatingFileHandler
+
+__all__ = [
+    'DATE_FORMAT',
+    'LOG_FORMAT',
+    'get_logger',
+    'get_timestamped_log_path',
+    'setup_logging',
+]
+
+# Default format as per the requirements, adding levelname and module name for context.
+LOG_FORMAT = '[%(asctime)s]  [%(levelname)s]  [%(name)s]  %(message)s'
+DATE_FORMAT = '%Y-%m-%d %H:%M:%S'
+
+
+def setup_logging(
+    level: int = logging.INFO,
+    log_file: Optional[str] = None,
+    max_bytes: int = 10 * 1024 * 1024,  # 10 MB
+    backup_count: int = 5,
+):
+    """Configures the root logger for the application with log rotation.
+
+    This sets up handlers for console and optional file logging.
+    It uses a standardized format for all log messages and rotates
+    log files when they reach a specified size.
+
+    :param level: The minimum logging level to capture (e.g., logging.INFO).
+    :param log_file: Optional path to a file for log output.
+    :param max_bytes: The maximum size in bytes for a log file before it is rotated.
+    :param backup_count: The number of backup log files to keep.
+    """
+    formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+
+    handlers = []
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(formatter)
+    handlers.append(console_handler)
+
+    # Rotating file handler (if a path is provided)
+    if log_file:
+        # Use RotatingFileHandler for automatic log rotation.
+        file_handler = RotatingFileHandler(
+            log_file, maxBytes=max_bytes, backupCount=backup_count
+        )
+        file_handler.setFormatter(formatter)
+        handlers.append(file_handler)
+
+    # The `force=True` argument removes any existing handlers
+    # on the root logger, ensuring our configuration is the only one.
+    logging.basicConfig(level=level, handlers=handlers, force=True)
+
+    # Set up a hook for unhandled exceptions to be logged automatically.
+    # This addresses the "Log traceback" requirement.
+    def handle_exception(exc_type, exc_value, exc_traceback):
+        if issubclass(exc_type, KeyboardInterrupt):
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+        logging.getLogger().critical(
+            'Unhandled exception', exc_info=(exc_type, exc_value, exc_traceback)
+        )
+
+    sys.excepthook = handle_exception
+
+
+def get_timestamped_log_path(log_dir: str, app_name: str) -> str:
+    """Generates a timestamped log file path.
+
+    :param log_dir: The directory where the log file should be stored.
+    :param app_name: The base name for the log file.
+    :return: A string representing the full path to the log file.
+    """
+    timestamp = datetime.now().strftime('%Y-%m-%d')
+    return f'{log_dir}/{app_name}_{timestamp}.log'
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Returns a logger instance for the given name.
+
+    This is the primary function that developers will use to get a
+    pre-configured logger within their modules.
+    """
+    return logging.getLogger(name)

saezlab_core/module_a.py

@@ -0,0 +1,17 @@
+from saezlab_core import get_logger
+
+__all__ = [
+    'run_task_a',
+]
+
+log = get_logger(__name__)
+
+
+def run_task_a():
+    """A dummy task that logs its progress."""
+    log.info('Starting Task A.')
+    log.debug('Performing some complex calculations for Task A...')
+    # Simulate some work
+    result = 2 + 2
+    log.info(f'Task A finished with result: {result}')
+    return result

saezlab_core/module_b.py

@@ -0,0 +1,23 @@
+from saezlab_core import get_logger
+
+__all__ = [
+    'run_task_b',
+]
+
+log = get_logger(__name__)
+
+
+def run_task_b():
+    """Another dummy task that logs its progress and might encounter an issue."""
+    log.info('Starting Task B.')
+    log.warning(
+        'This task is deprecated and will be removed in a future version.'
+    )
+    # Simulate a potential issue
+    data = None
+    if data is None:
+        log.error('Input data for Task B is missing.')
+        return None
+
+    log.info('Task B finished.')
+    return True

saezlab_core/module_c.py

@@ -0,0 +1,19 @@
+__all__ = [
+    'utility_function',
+]
+
+def utility_function():
+    """A simple utility function that does not perform any logging.
+    Its operations are silent.
+    """
+    # This function is simple and does not need to report anything.
+    # For example, a pure calculation.
+
+    try:
+        # Perform some calculations
+        10 / 0
+    except Exception:
+        # Even in case of error, we do not log anything.
+        print('An error occurred, but we are not logging it.')
+
+    return 'This is a silent utility.'

saezlab_core/module_d.py

@@ -0,0 +1,22 @@
+from saezlab_core import get_logger
+
+__all__ = [
+    'run_task_division',
+]
+
+log = get_logger(__name__)
+
+
+def run_task_division():
+    """A task that performs division and handles division by zero."""
+    log.info('Starting Division Task.')
+    numerator = 10
+    denominator = 0  # This will cause a division by zero error
+
+    try:
+        result = numerator / denominator
+        log.info(f'Division result: {result}')
+        return result
+    except ZeroDivisionError:
+        log.exception('Division by zero encountered in Division Task.')
+        return None

saezlab_core/session.py

@@ -0,0 +1,68 @@
+import os
+from typing import Optional
+import logging
+
+from . import logger
+
+__all__ = [
+    'Session',
+]
+
+
+class Session:
+    """Manages the application session, primarily for initializing the logger.
+    This class ensures that logging is configured only once.
+    """
+
+    _initialized = False
+
+    @classmethod
+    def initialize(
+        cls,
+        log_level: str = 'INFO',
+        log_path: Optional[str] = None,
+        app_name: str = 'application',
+    ):
+        """Initializes the session by setting up the logging system.
+
+        This method should be called once at the application's entry point.
+        If `log_path` is a directory, a timestamped log file will be created within it.
+        If `log_path` is a file path, it will be used directly.
+        If `log_path` is None, logs will only be sent to the console.
+
+        :param log_level: The logging level as a string (e.g., "DEBUG", "INFO").
+        :param log_path: Optional path to a log file or a directory for logs.
+        :param app_name: The base name for the application, used for timestamped logs.
+        """
+        if cls._initialized:
+            # Using the logger itself to warn about re-initialization.
+            logging.getLogger(__name__).warning(
+                'Session.initialize() called more than once.'
+            )
+            return
+
+        # Convert string level to logging constant
+        level = getattr(logging, log_level.upper(), logging.INFO)
+
+        log_file_to_use = None
+        if log_path:
+            # If the path is a directory, create a timestamped log file inside it.
+            # Otherwise, assume it's a full file path.
+            if os.path.isdir(log_path) or not os.path.splitext(log_path)[1]:
+                os.makedirs(log_path, exist_ok=True)
+                log_file_to_use = logger.get_timestamped_log_path(
+                    log_path, app_name
+                )
+            else:
+                # Ensure the directory for the file exists.
+                log_dir = os.path.dirname(log_path)
+                if log_dir:
+                    os.makedirs(log_dir, exist_ok=True)
+                log_file_to_use = log_path
+
+        logger.setup_logging(level=level, log_file=log_file_to_use)
+        logging.getLogger(__name__).info(
+            f'Logging session initialized with level {log_level.upper()}.'
+        )
+
+        cls._initialized = True

scripts/main.py

@@ -0,0 +1,63 @@
+import numpy as np
+
+from saezlab_core import (  # TODO: Every package should have this import
+    Session,
+    module_a,
+    module_b,
+    module_c,
+    module_d,
+    get_logger,
+)
+
+__all__ = [
+    'main',
+]
+
+
+def main():
+    """A more complex main function to demonstrate logging from multiple modules."""
+    # Initialize the session once at the start.
+    # The user only needs to provide the log directory and an application name.
+    Session.initialize(
+        log_level='ERROR', log_path='./log', app_name='saezlab_core'
+    )
+
+    # Get a logger for the main application entry point.
+    log = get_logger(__name__)  # TODO: Every package should have this import
+
+    log.info('Main application process starting.')
+
+    # --- Run Task A ---
+    log.info('Calling module A...')
+    result_a = module_a.run_task_a()
+    log.debug(f'Module A returned: {result_a}')
+
+    # --- Run Task B ---
+    log.info('Calling module B...')
+    result_b = module_b.run_task_b()
+    if result_b is None:
+        log.warning('Module B indicated a problem, but we are continuing.')
+
+    # --- Use Module C ---
+    log.info('Calling module C (the silent one)...')
+    result_c = module_c.utility_function()
+    # Note: We log about module C from main.py, but module_c.py itself is silent.
+    log.debug(f"Module C returned: '{result_c}'")
+
+    # --- Additional Complex Operation ---
+    log.info('Performing a complex operation in main...')
+    array = np.array([1, 2, 3, 4, 5])
+    mean_value = np.mean(array)
+    log.debug(f'Computed mean of array {array}: {mean_value}')
+
+    # --- Handle an Exception ---
+    log.info('Attempting a risky operation...')
+    result = module_d.run_task_division()
+    if result is None:
+        log.error('Risky operation failed due to an error.')
+
+    log.info('Main application process finished.')
+
+
+if __name__ == '__main__':
+    main()