diff --git a/logger.py.md b/logger.py.md new file mode 100644 index 0000000..e7953fd --- /dev/null +++ b/logger.py.md @@ -0,0 +1,85 @@ +# logger.py Logger + +This document describes the detailed step-by-step process of how the `logger.py` script works, including the specific methods, classes, and functions used at each step. + +## Initialization and Start of Logger + +### Importing Modules +- The `logger.py` script imports several modules, including standard libraries (`logging`, `os`) and third-party libraries (`RotatingFileHandler` from `logging.handlers`, `Console`, `RichHandler`, `Theme` from `rich`). + +### Custom Log Level +- **Custom Log Level "SUCCESS"**: + - A custom log level named "SUCCESS" is defined with a numeric value of 25. + - A method `success` is added to the `logging.Logger` class to log messages at this custom level. + +### `VerticalFilter` Class +- **Purpose**: Excludes specific log messages containing the word "Vertical". +- **Key Steps**: + 1. **Filter Method**: + - The `filter` method returns `False` if the log message contains "Vertical", excluding such messages from the logs. + +## `Logger` Class + +### `__init__` Method +- **Purpose**: Initializes the logger with handlers for both console and file output. +- **Key Steps**: + 1. **Set Up Logger**: + - Creates a logger instance and sets the log level. + 2. **Define Custom Log Level Styles**: + - Defines a custom theme for different log levels using the `Theme` class from `rich`. + 3. **Set Up Console Handler**: + - Creates a console handler using `RichHandler` for enhanced console output. + - Sets the log level and formatter for the console handler. + 4. **Ensure Log Directory Exists**: + - Ensures the log directory exists by creating it if necessary. + 5. **Set Up File Handler**: + - Creates a file handler using `RotatingFileHandler` to manage log file sizes and backups. + - Sets the log level and formatter for the file handler. + 6. **Add Filters to Handlers**: + - Adds the `VerticalFilter` to both console and file handlers to exclude specific log messages. + 7. **Add Handlers to Logger**: + - Adds both the console and file handlers to the logger. + +### `set_level` Method +- **Purpose**: Dynamically adjusts the log level of the logger and its handlers. +- **Key Steps**: + 1. **Set Log Level**: + - Sets the log level for the logger and all its handlers. + +### Logging Methods +- **Purpose**: Provides methods to log messages at various levels. +- **Key Steps**: + 1. **Log Methods**: + - `debug(message)`: Logs a debug message. + - `info(message)`: Logs an info message. + - `warning(message)`: Logs a warning message. + - `error(message)`: Logs an error message. + - `critical(message)`: Logs a critical message. + - `success(message)`: Logs a success message. + +### `disable_logging` Method +- **Purpose**: Disables all logging. +- **Key Steps**: + 1. **Disable Logging**: + - Disables logging by setting the logging level to `CRITICAL`, the highest severity level. + +## Example Usage +- An example usage is provided to demonstrate how to create a `Logger` instance, log messages at various levels, change the log level, and disable logging. + +## Execution Flow when `logger.py` is Run + +### Step 1: Initialize Logger +- An instance of the `Logger` class is created with a specified name and log level. + +### Step 2: Log Messages +- The logger logs messages at various levels (debug, info, warning, error, critical, success) using the corresponding methods. + +### Step 3: Change Log Level +- The log level is changed dynamically using the `set_level` method, filtering out messages below the new log level. + +### Step 4: Disable Logging +- Logging is disabled using the `disable_logging` method, preventing any further messages from being logged. + +## Summary + +The `logger.py` script sets up a robust logging system for the Bjorn project. It defines custom logging levels and formats, integrates with the `Rich` library for enhanced console output, and ensures logs are written to rotating files for persistence. The `Logger` class provides methods to log messages at various levels, dynamically adjust log levels, and disable logg