# `pyloggermanager`
The 'pyloggermanager' package is a vital logging framework for Python applications, providing developers with essential
tools to streamline logging operations. Its primary function is to simplify the recording and organization of log
messages, including critical information, debugging messages, errors, and warnings. By offering a centralized interface
and robust functionalities, the package facilitates efficient monitoring and troubleshooting processes.
With its intuitive interface, the pyloggermanager package enables developers to seamlessly integrate logging mechanisms
into their applications. This allows for systematic recording and categorization of log entries based on severity
levels, enhancing readability and prioritization of issues. Moreover, the package offers flexibility in customizing
logging configurations to suit specific project requirements, including formatting, output destinations, and thread
safety.
Beyond technical capabilities, the pyloggermanager package contributes to the reliability and maintainability of Python
applications. It establishes consistent logging practices, simplifying collaboration, code reviews, and issue resolution
across development teams. Overall, the pyloggermanager package is an invaluable asset for developers aiming to implement
robust logging solutions, ensuring efficient and resilient application performance.
## Installation
Logger Manager can be installed using pip:
```bash
pip install pyloggermanager
```
## Usage
```python
import pyloggermanager
# Load configuration
pyloggermanager.load_config()
# Log a debug message
pyloggermanager.debug("This is a debug message.")
# Log an informational message
pyloggermanager.info("This is an informational message.")
# Log a warning message
pyloggermanager.warning("This is a warning message.")
# Log an error message
pyloggermanager.error("This is an error message.")
# Log a critical message
pyloggermanager.critical("This is a critical message.")
# Output
# 2024-03-22 23:37:21 :: INFO :: This is an informational message.
# 2024-03-22 23:37:21 :: WARNING :: This is a warning message.
# 2024-03-22 23:37:21 :: ERROR :: This is an error message.
# 2024-03-22 23:37:21 :: CRITICAL :: This is a critical message.
```
# Documentation
## `pyloggermanager`
#### Methods
- `load_config(file_name='default.log', file_mode='a', level=LogLevel.INFO, format_str=DEFAULT_FORMAT, date_format=DATE_FORMAT, stream=None, handlers=None, colorization=None, encoding='UTF-8')` -
This function loads the logging configuration based on the provided parameters. It acquires a lock for thread safety,
configures default handlers if no handlers are specified, configures the formatter and level for each handler, and
adds the handlers to the root logger. Finally, it releases the lock.
- `disable(level=LogLevel.CRITICAL)` - This function disables logging up to the specified level.
- `critical(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with CRITICAL level.
- `debug(self, message: str, ignore_display: bool = True, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with DEBUG level.
- `error(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with ERROR level.
- `info(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with INFO level.
- `log(self, level: int, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message at the specified level.
- `warning(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with WARNING level.
### `CallerFrame`
The CallerFrame class represents caller details such as class name, file name, function name, module name, and path name
based on the caller's frame information. It provides a method to retrieve caller details from a given frame.
#### Properties
- `class_name`: Represents the name of the class where the function was called.
- `file_name`: Represents the name of the file from which the function was called.
- `function_name`: Represents the name of the function that called the method.
- `module_name`: Represents the name of the module where the function was called.
- `path_name`: Represents the path of the file from which the function was called.
#### Methods
- `__init__()`: Initializes the CallerFrame object with default attribute values.
- `get_caller_details(frame: FrameType) -> CallerFrame`: Retrieves caller details from the given frame.
#### Usage
````python
import pyloggermanager
import inspect
# Assume we have a function where we want to retrieve caller details
def some_function():
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
print("Caller Class:", caller_frame.class_name)
print("Caller File:", caller_frame.file_name)
print("Caller Function:", caller_frame.function_name)
print("Caller Module:", caller_frame.module_name)
print("Caller Path:", caller_frame.path_name)
# Now we call the function
some_function()
# Output
# Caller Class: Unknown Class
# Caller File: example
# Caller Function: test_function
# Caller Module: example
# Caller Path: /path/to/example.py
````
### `FileMode`
The FileMode class represents file modes supported by the Python open() function for reading, writing, and appending to
files. It provides methods to retrieve the default file mode, get the file mode mappings, check if a mode is valid, set
the default file mode, and get readable and writable modes.
#### Constants
- `READ`: Represents the read file mode.
- `READ_PLUS`: Represents the read/write file mode.
- `WRITE`: Represents the write file mode.
- `WRITE_PLUS`: Represents the read/write file mode.
- `EXCLUSIVE_CREATE`: Represents the exclusive creation file mode.
- `APPEND`: Represents the append file mode.
- `APPEND_PLUS`: Represents the read/append file mode.
- `BINARY`: Represents the binary file mode.
- `READ_BINARY`: Represents the read binary file mode.
- `READ_WRITE_BINARY`: Represents the read/write binary file mode.
- `TEXT`: Represents the text file mode.
- `UPDATE`: Represents the update file mode.
#### Methods
- `check_mode(mode: str) -> str`: Checks if the provided mode exists and returns the same value if it exists; otherwise,
raises a ValueError.
- `get_default_mode() -> str`: Returns the default file mode.
- `get_file_mode(mode_str: str) -> str`: Returns the file mode string corresponding to the provided mode name.
- `get_file_modes() -> dict`: Returns a dictionary mapping file mode names to their corresponding strings.
- `get_readable_modes() -> dict`: Returns a dictionary of reading file modes and their corresponding strings.
- `get_writable_modes() -> dict`: Returns a dictionary of writable file modes and their corresponding strings.
- `is_valid_mode(mode: str) -> bool`: Checks if the provided mode string is a valid file mode.
- `set_default_mode(mode: str) -> None`: Sets the default file mode.
#### Usage
````python
# Import the FileMode class
import pyloggermanager
# Check if a mode is valid
mode = 'r'
if pyloggermanager.FileMode.is_valid_mode(mode):
print(f"The mode '{mode}' is valid.")
else:
print(f"The mode '{mode}' is invalid.")
# Get default mode
default_mode = pyloggermanager.FileMode.get_default_mode()
print(f"The default mode is: {default_mode}")
# Set default mode
new_default_mode = 'a'
pyloggermanager.FileMode.set_default_mode(new_default_mode)
print(f"New default mode set to: {new_default_mode}")
# Get readable modes
readable_modes = pyloggermanager.FileMode.get_readable_modes()
print("Readable modes:")
for mode_name, mode_str in readable_modes.items():
print(f"- {mode_name}: {mode_str}")
# Get writable modes
writable_modes = pyloggermanager.FileMode.get_writable_modes()
print("Writable modes:")
for mode_name, mode_str in writable_modes.items():
print(f"- {mode_name}: {mode_str}")
# Output
# The mode 'r' is valid.
# The default mode is: a
# New default mode set to: a
# Readable modes:
# - READ: r
# - READ_PLUS: r+
# - WRITE_PLUS: w+
# - APPEND_PLUS: a+
# Writable modes:
# - WRITE: w
# - WRITE_PLUS: w+
# - APPEND: a
# - APPEND_PLUS: a+
````
### `Lock`
The Lock class provides a simple interface to manage locks using the Python threading module. It allows acquiring,
creating, checking if a lock is locked, and releasing locks.
#### Methods
- `acquire(name: str, blocking: bool = True, timeout: float = -1) -> bool`: Acquires the lock with the given name.
- `create(name: str) -> None`: Creates a new lock with the given name.
- `generate_name(length: int = 10) -> str`: Generates a random name for a lock of specified length.
- `locked(name: str) -> bool`: Checks if the lock with the given name is currently locked.
- `release(name: str) -> None`: Releases the lock with the given name.
#### Usage
````python
# Import the Lock class
import pyloggermanager
import threading
import time
# Define a function to perform an action using a lock
def perform_action(lock_name):
print(f"Thread {threading.current_thread().name} attempting to acquire lock {lock_name}")
if pyloggermanager.Lock.acquire(lock_name, timeout=3):
print(f"Thread {threading.current_thread().name} acquired lock {lock_name}")
time.sleep(2) # Simulating some action being performed
pyloggermanager.Lock.release(lock_name)
print(f"Thread {threading.current_thread().name} released lock {lock_name}")
else:
print(f"Thread {threading.current_thread().name} couldn't acquire lock {lock_name}")
# Create locks
lock1_name = pyloggermanager.Lock.generate_name()
lock2_name = pyloggermanager.Lock.generate_name()
pyloggermanager.Lock.create(lock1_name)
pyloggermanager.Lock.create(lock2_name)
# Spawn threads to perform actions using locks
thread1 = threading.Thread(target=perform_action, args=(lock1_name,))
thread2 = threading.Thread(target=perform_action, args=(lock2_name,))
thread1.start()
thread2.start()
thread1.join()
thread2.join()
# Output
# Thread Thread-1 (perform_action) attempting to acquire lock nzlggljagd
# Thread Thread-2 (perform_action) attempting to acquire lock mbsvxfocxdThread Thread-1 (perform_action) acquired lock nzlggljagd
#
# Thread Thread-2 (perform_action) acquired lock mbsvxfocxd
# Thread Thread-1 (perform_action) released lock nzlggljagdThread Thread-2 (perform_action) released lock mbsvxfocxd
````
### `LogLevel`
The LogLevel class represents different log levels used in logging systems. It provides methods to check if a log level
is valid, get the default log level, get log level mappings, remove log levels, set the default log level, and set
custom log levels.
#### Constants
- `DEBUG`: Constant representing the debug log level (integer: 10)
- `INFO`: Constant representing the info log level (integer: 20)
- `WARNING`: Constant representing the warning log level (integer: 30)
- `ERROR`: Constant representing the error log level (integer: 40)
- `CRITICAL`: Constant representing the critical log level (integer: 50)
#### Methods
- `check_level(level: int) -> int`: Checks if the provided level exists and returns the same value if exists, else
raises ValueError.
- `get_default_level() -> str`: Returns the default log level as a string.
- `get_level(level: int | str) -> str | int`: Returns the log level name if an integer level is provided, or returns the
log level integer if a string level is provided.
- `get_levels() -> dict`: Returns a dictionary mapping log level integers to their corresponding names, sorted by level.
- `get_next_level(current_level: int) -> int | None`: Returns the next log level integer after the provided current
level, or None if it is the highest level.
- `get_previous_level(current_level: int) -> int | None`: Returns the previous log level integer before the provided
current level, or None if it is the lowest level.
- `is_valid_level(level: int | str) -> bool`: Checks if the provided log level (integer or string) is a valid log level.
- `remove_level(level: int | str) -> None`: Removes the log level mapping for the specified level.
- `set_default_level(level: int | str) -> None`: Sets the default log level based on the provided integer or string
level.
- `set_level(level: int, level_name: str) -> None`: Sets a custom log level with the provided level integer and name.
#### Usage
````python
# Import the LogLevel class
import pyloggermanager
# Check if a log level is valid
print(pyloggermanager.LogLevel.is_valid_level(pyloggermanager.LogLevel.DEBUG)) # Output: True
# Get default log level
print(pyloggermanager.LogLevel.get_default_level()) # Output: INFO
# Get log level mappings
print(
pyloggermanager.LogLevel.get_levels()) # Output: {10: 'DEBUG', 20: 'INFO', 30: 'WARNING', 40: 'ERROR', 50: 'CRITICAL'}
# Set default log level
pyloggermanager.LogLevel.set_default_level(pyloggermanager.LogLevel.WARNING)
print(pyloggermanager.LogLevel.get_default_level()) # Output: WARNING
# Set custom log level
pyloggermanager.LogLevel.set_level(15, 'CUSTOM')
print(pyloggermanager.LogLevel.get_level(15)) # Output: 'CUSTOM'
# Remove log level
pyloggermanager.LogLevel.remove_level('CUSTOM')
print(pyloggermanager.LogLevel.get_level(15)) # Output: 'Level 15'
````
### `Record`
The Record class represents a log record with various attributes such as message, logger name, level name, caller frame
information, execution information, stack information, and thread/process details. It provides methods to serialize the
record to a dictionary and JSON format.
#### Properties
- `time`: Property representing the timestamp of the log record.
- `message`: Property representing the log message.
- `logger_name`: Property representing the name of the logger.
- `level_number`: Property representing the numeric value of the log level.
- `level_name`: Property representing the name of the log level.
- `file_name`: Property representing the name of the file where the log occurred.
- `class_name`: Property representing the name of the class where the log occurred.
- `function_name`: Property representing the name of the function/method where the log occurred.
- `module_name`: Property representing the name of the module where the log occurred.
- `path_name`: Property representing the path of the file where the log occurred.
- `exec_info`: Property representing the execution information associated with the log record.
- `stack_info`: Property representing the stack information associated with the log record.
- `thread`: Property representing the thread ID associated with the log record.
- `thread_name`: Property representing the name of the thread associated with the log record.
- `process_id`: Property representing the process ID associated with the log record.
#### Methods
- `__init__(message: str, logger_name: str, level_number: int, caller_frame: CallerFrame, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: Optional[str] = None) -> None`:
Constructs a new 'Record' object with the provided parameters.
- `json_serializer(obj: Any) -> Union[str, None]`: Static method to serialize objects to JSON format.
- `to_dict() -> dict`: Converts the 'Record' object to a dictionary.
- `to_json() -> str`: Converts the 'Record' object to JSON string.
#### Usage
````python
# Import the Record class
import inspect
import pyloggermanager
# Create a CallerFrame object (Assuming it's defined elsewhere)
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Create a new Record object
record = pyloggermanager.Record(
message="An example log message",
logger_name="example_logger",
level_number=20,
caller_frame=caller_frame,
exec_info=(ValueError, ValueError("An example error occurred"), None),
stack_info="Stack trace information"
)
# Access properties of the Record object
print(record.message) # Output: An example log message
print(record.level_name) # Output: INFO
print(record.file_name) # Output: example
# Serialize the Record object to a dictionary
record_dict = record.to_dict()
print(record_dict)
# Output: {
# 'time': datetime.datetime(2024, 3, 22, 23, 41, 47, 604552),
# 'message': 'An example log message',
# 'logger_name': 'example_logger',
# 'level_name': 'INFO',
# 'level_number': 20,
# 'file_name': 'example',
# 'class_name': 'ExampleClass',
# 'function_name': 'example_function',
# 'module_name': 'example',
# 'path_name': 'example_path',
# 'exec_info': (<class 'ValueError', ValueError('An example error occurred'), None),
# 'stack_info': 'Stack trace information',
# 'thread': 12345,
# 'thread_name': 'MainThread',
# 'process_id': 67890
# }
# Serialize the Record object to JSON format
json_string = record.to_json()
print(json_string)
# Output:
# {
# "time": "2024-03-22T23:41:47.604552",
# "message": "An example log message",
# "logger_name": "example_logger",
# "level_name": "INFO",
# "level_number": 20,
# "file_name": "example",
# "class_name": "ExampleClass",
# "function_name": "example_function",
# "module_name": "example",
# "path_name": "example_path",
# "exec_info": [
# "ValueError",
# "An example error occurred",
# null
# ],
# "stack_info": "Stack trace information",
# "thread": 12345,
# "thread_name": "MainThread",
# "process_id": 67890
# }
````
### `Logger`
The Logger class represents a logger object with various attributes and methods for logging messages.
#### Properties
- `cache`: Gets or sets the cache dictionary.
- `disabled`: Indicates whether the logger is disabled or not.
- `handlers`: The list of handlers associated with the logger.
- `level`: The logging level of the logger.
- `lock_name`: Gets or sets the name of the lock used for thread safety.
- `manager`: The manager associated with the logger.
- `name`: The name of the logger.
- `parent`: The parent logger in the logger hierarchy.
- `root`: The root logger associated with the logger hierarchy.
#### Methods
- `__init__(self, name: str, level: int = LogLevel.INFO) -> None`: Initializes a new Logger object.
- `add_handler(self, handler: Handler) -> None`: Adds a handler to the logger's list of handlers after acquiring the
lock.
- `call_handlers(self, record: Record, ignore_display: bool) -> None`: Calls the handlers associated with the logger.
- `critical(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with CRITICAL level.
- `debug(self, message: str, ignore_display: bool = True, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with DEBUG level.
- `error(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with ERROR level.
- `find_caller(self, stack_info: bool = False, stack_level: int = 1) -> Tuple[CallerFrame, str]`: Finds the caller frame
and optionally collects stack information.
- `get_child(self, suffix: str) -> 'Logger'`: Get a child logger with the specified suffix.
- `get_effective_level(self) -> int`: Retrieves the effective log level for the logger.
- `handle(self, record: Record, ignore_display: bool) -> None`: Handles the given log record by calling its handlers if
the logger is not disabled.
- `has_handlers(self) -> bool`: Checks if the logger or any of its ancestors have handlers.
- `info(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with INFO level.
- `is_enabled_for(self, level: int) -> bool`: Checks if logging is enabled for the specified log level.
- `log(self, level: int, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message at the specified level.
- `make_record(self, name: str, level: int, message: str, caller_frame: Optional[CallerFrame] = None, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: Optional[str] = None) -> Record`:
Creates a Record object with specified attributes.
- `remove_handler(self, handler: Handler) -> None`: Removes a handler from the logger's list of handlers after acquiring
the lock.
- `warning(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:
Logs a message with WARNING level.
#### Usage
````python
# Importing the necessary modules
import pyloggermanager
from pyloggermanager.handlers import ConsoleHandler
# Sample usage of the Logger class
# Creating a logger instance
logger = pyloggermanager.Logger("example_logger")
# Adding a handler
handler = ConsoleHandler()
logger.add_handler(handler)
# Logging messages
logger.info("This is an informational message.\n")
logger.error("An error occurred.")
# Removing the handler
logger.remove_handler(handler)
# Output
# 2024-03-22 23:45:14 :: INFO :: This is an informational message.
# 2024-03-22 23:45:14 :: ERROR :: An error occurred.
````
### `Manager`
The Manager class manages loggers and their settings within a logging hierarchy.
#### Properties
- `disable`: Gets or sets the level at which logging is disabled.
- `lock_name`: Gets or sets the name of the lock used for thread safety.
- `logger_class`: Gets or sets the logger class used for creating logger instances.
- `logger_dict`: Gets or sets the dictionary mapping logger names to their instances.
- `record_factory`: Gets or sets the factory used for creating log records.
- `root`: Gets or sets the root logger of the logging hierarchy.
#### Methods
- `__init__(self, root_node: Logger) -> None`: Initializes the Manager with a root logger.
- `clear_cache(self) -> None`: Clears the cache for all loggers and the root logger.
- `get_logger(self, name: str) -> Logger`: Retrieves a logger with the specified name. If the logger does not exist, it
creates a new logger.
- `set_logger(self, logger: Logger) -> None`: Sets the logger class to be used for creating new loggers.
#### Usage
````python
# Importing the necessary modules
import pyloggermanager
# Create a root logger
root_logger = pyloggermanager.Logger("root")
# Create a manager with the root logger
manager = pyloggermanager.Manager(root_logger)
# Set the level at which logging is disabled
manager.disable = 20
# Get a logger named 'example_logger'
example_logger = manager.get_logger("example_logger")
# Set the logger class
manager.set_logger(example_logger)
# Clear the cache for all loggers and the root logger
manager.clear_cache()
````
### `Registry`
The Registry class serves as a registry to store and manage instances of the Logger class.
#### Properties
- `logger_map`: Gets or sets the dictionary mapping loggers to their associated values.
#### Methods
- `__init__(self, logger: Logger) -> None`: Initializes the Registry with a single logger.
- `append(self, logger: Logger) -> None`: Adds a new logger to the registry.
#### Usage
````python
# Importing the necessary modules
import pyloggermanager
# Create a logger
logger = pyloggermanager.Logger("example_logger")
# Create a registry with the logger
registry = pyloggermanager.Registry(logger)
# Append a new logger to the registry
new_logger = pyloggermanager.Logger("new_logger")
registry.append(new_logger)
# Get the logger map
logger_map = registry.logger_map
````
### `RootLogger`
The RootLogger class represents the root logger in a logging hierarchy. It inherits from the Logger class and
initializes itself with the name 'root' and the specified log level. The root logger serves as the ancestor of all other
loggers in the logging hierarchy.
#### Methods
- `__init__(self, level: int) -> None`: Constructs a new RootLogger object with the specified log level.
## `pyloggermanager.formatters`
The 'pyloggermanager.formatters' package provides classes for formatting log messages in various formats within the
logger manager framework. It includes implementations for formatting log messages as CSV (Comma-Separated Values),
JSON (JavaScript Object Notation), and the default text format.
Below listed formatter classes enable users to customize the appearance and structure of log messages according to their
requirements. By supporting different formats such as CSV and JSON, users have the flexibility to choose the most
suitable format for their logging needs, whether it's for human-readable output, structured data storage, or integration
with external systems.
Overall, the 'pyloggermanager.formatters' package enhances the logger manager framework by offering versatile formatting
options for log messages, catering to a wide range of logging use cases and preferences.
#### Constants
- `DEFAULT_FORMAT` (str): The default format string used for log message formatting.
- `CSV_FORMAT` (str): The format string used for CSV log message formatting.
- `JSON_FORMAT` (str): The format string used for JSON log message formatting.
- `DATE_FORMAT` (str): The default date format string used for log message formatting.
### `Formatter`
Base class for log record formatters. It allows customization of log message format. Subclasses must implement the
format method to customize log message formatting.
| Placeholder | Description |
|---------------------|-----------------------------------------------------------------------------------------|
| `%(time)s` | The time at which the log record was created, formatted using `date_format`. |
| `%(message)s` | The message associated with the log record. |
| `%(logger_name)s` | The name of the logger. |
| `%(level_name)s` | The name of the logging level (e.g., INFO, WARNING). |
| `%(level_number)d` | The numeric value of the logging level. |
| `%(file_name)s` | The name of the file from which the logging call was made. |
| `%(class_name)s` | The name of the class containing the logging call. |
| `%(function_name)s` | The name of the function/method containing the logging call. |
| `%(module_name)s` | The name of the module containing the logging call. |
| `%(path_name)s` | The full pathname of the source file. |
| `%(exec_info)s` | The formatted traceback information if an exception was raised during the logging call. |
| `%(stack_info)s` | The stack information at the time of the logging call. |
| `%(thread)d` | The thread ID. |
| `%(thread_name)s` | The name of the thread. |
| `%(process_id)d` | The ID of the process. |
#### Methods
- `__init__(format_str: str | dict = DEFAULT_FORMAT, date_format: str = DATE_FORMAT)`: Initializes the Formatter object.
- `format(record: 'Record') -> str`: Formats the log record into a string based on the provided record object.
- `format_time(value: time.struct_time, date_format: str) -> str`: Formats the provided time value into a string using
the specified date format.
- `format_exception(exec_info: Optional[Tuple[Type[BaseException], BaseException, Optional[TracebackType]]] = None) -> str`:
Formats the exception information into a string.
### `DefaultFormatter`
Custom formatter for log records. It allows customization of log record formatting using a specified format string.
Replaces tokens in the format string with corresponding values from the log record.
#### Methods
- `__init__(format_str: str = DEFAULT_FORMAT, date_format: str = DATE_FORMAT)`: Initializes a 'DefaultFormatter'
instance with the specified format string.
- `format(record: 'Record') -> str`: Formats the given log record according to the format string.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.formatters import DefaultFormatter
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Create a log record
record = pyloggermanager.Record(
message="This is a log message",
logger_name="example_logger",
level_number=20,
caller_frame=caller_frame,
exec_info=None,
stack_info=None
)
# Create a DefaultFormatter instance
formatter = DefaultFormatter()
# Format the log record
formatted_message = formatter.format(record)
print(formatted_message)
# Output: '2024-03-22 15:30:45 :: INFO :: This is a log message'
````
### `CSVFormatter`
Subclass of the 'Formatter' class for formatting log records in CSV format. It allows customization of the format string
used for formatting log records.
#### Methods
- `__init__(format_str: str = CSV_FORMAT, date_format: str = DATE_FORMAT)`: Initializes a 'CSVFormatter' object with the
specified format string.
- `format(record: 'Record') -> str`: Formats the given log record into a CSV string based on the specified format
string.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.formatters import CSVFormatter
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Create a log record
record = pyloggermanager.Record(
message="This is a log message",
logger_name="example_logger",
level_number=20,
caller_frame=caller_frame,
exec_info=None,
stack_info=None
)
# Create a CSVFormatter instance
formatter = CSVFormatter()
# Format the log record as CSV
formatted_message = formatter.format(record)
print(formatted_message)
# Output: '2024-03-22 23:46:41,INFO,This is a log message'
````
### `JSONFormatter`
Subclass of the 'Formatter' class for formatting log records into JSON format. It provides methods to initialize the
formatter with a custom format string, format log records into JSON strings, and handle JSON decoding errors.
#### Methods
- `__init__(format_str: dict = None, date_format: str = DATE_FORMAT)`: Initializes the JSONFormatter object with a
custom format string.
- `format(record: 'Record') -> str`: Formats the given log record into a JSON string.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.formatters import JSONFormatter
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Create a log record
record = pyloggermanager.Record(
message="This is a log message",
logger_name="example_logger",
level_number=20,
caller_frame=caller_frame,
exec_info=None,
stack_info=None
)
# Create a JSONFormatter instance
formatter = JSONFormatter()
# Format the log record as JSON
formatted_message = formatter.format(record)
print(formatted_message)
# Output:
# {
# "time": "2024-03-22 23:47:03",
# "levelName": "INFO",
# "message": "This is a log message"
# }
````
## `pyloggermanager.handlers`
The 'pyloggermanager.handlers' package provides classes responsible for handling log records generated within the logger
manager framework. It includes various handlers for processing log messages, directing them to different destinations,
and performing actions based on logging levels.
Below listed handler classes offer flexibility and customization options for managing log records within the logger
manager framework. They enable users to define how log messages are processed, where they are directed, and how they are
formatted, catering to various logging scenarios and deployment environments.
Overall, the 'pyloggermanager.handlers' package enhances the functionality of the logger manager framework by providing
a robust set of handlers for managing log records effectively and efficiently. Users can choose and configure handlers
based on their specific logging needs and infrastructure requirements.
### `Handler`
The Handler class is a base class for different log handlers used in logging systems. It provides methods and properties
to manage handler attributes such as name, log level, colorization, and formatter. Additionally, it includes methods to
acquire/release locks, close the handler, emit log records, format log records, flush buffered records, and retrieve a
list of all handlers.
#### Properties
- `colorization`: Gets or sets the colorization object for the handler.
- `formatter`: Gets or sets the formatter object for formatting log records.
- `level`: Gets or sets the log level for the handler.
- `name`: Gets or sets the name of the handler.
#### Methods
- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter())` -
Initializes the handler with optional attributes.
- `close()`: Closes the handler.
- `emit(record: 'Record', ignore_display: bool) -> None`: Abstract method to emit a log record.
- `format(record: 'Record') -> str`: Formats a log record using the handler's formatter.
- `flush()`: Flushes buffered records.
- `get_handlers() -> list[Any]`: Retrieves a list of all handlers.
- `handle(record: 'Record', ignore_display: bool) -> None`: Handles a log record.
#### Usage
````python
from pyloggermanager.formatters import Formatter
from pyloggermanager.handlers import Handler
# Create a custom formatter
class CustomFormatter(Formatter):
def format(self, record):
return f"[{record.level_name}] {record.message}"
# Create a handler with custom formatter
handler = Handler(formatter=CustomFormatter())
````
### `ConsoleHandler`
The ConsoleHandler class is a subclass of Handler representing a handler that writes log records to the console. It
provides methods to set and retrieve the stream used for logging, close the stream, emit log records, and flush the
stream.
#### Properties
- `stream`: Gets or sets the stream of the handler.
#### Methods
- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), stream: Stream = TerminalStream())` -
Initializes a ConsoleHandler instance with optional attributes
- `close()`: Closes the stream if it has a close method.
- `emit(record: 'Record', ignore_display: bool = True) -> None`: Emits the log record by formatting it, colorizing the
message, and writing it to the stream.
- `flush()`: Flushes the stream if it has a flush method.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.handlers import ConsoleHandler
# Create a console handler
console_handler = ConsoleHandler()
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Emit a log record
console_handler.emit(pyloggermanager.Record(
message="This is a log message",
logger_name='TestLogger',
level_number=20,
caller_frame=caller_frame
))
# Output
# 2024-03-22 23:47:35 :: INFO :: This is a log message
````
### `StreamHandler`
The StreamHandler class is a subclass of Handler representing a handler that emits log records to a stream. It provides
methods to set the log level, formatter, and stream, as well as to emit log records and flush the stream.
#### Properties
- `stream`: Gets or sets the stream of the handler.
#### Methods
- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), stream: Stream = StdoutStream())` -
Initializes a StreamHandler instance with optional attributes.
- `close()`: Closes the stream if it has a close method.
- `emit(record: 'Record', ignore_display: bool) -> None`: Emits a log record to the stream.
- `flush()`: Flushes the stream if it has a flush method.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.handlers import StreamHandler
# Create a stream handler
stream_handler = StreamHandler()
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Emit a log record
stream_handler.emit(pyloggermanager.Record(
message="This is a log message",
logger_name='TestLogger',
level_number=20,
caller_frame=caller_frame
), ignore_display=True)
# Output
# 2024-03-22 23:48:13 :: INFO :: This is a log message
````
### `FileHandler`
The FileHandler class is a subclass of Handler responsible for handling log records by writing them to a file. It allows
customization of various parameters such as file name, file mode, encoding, etc.
#### Properties
- `encoding`: Gets or sets the encoding of the handler.
- `filemode`: Gets or sets the file mode for opening the file handler.
- `filename`: Gets or sets the file name of the handler.
#### Methods
- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), file_name: str = 'default.log', file_mode: str = 'a', encoding: str = 'UTF-8')` -
Initializes a FileHandler object with optional attributes.
- `close()`: Closes the file stream used for writing log records.
- `emit(record: 'Record', ignore_display: bool) -> None`: Emits a log record by writing it to the log file.
- `flush()`: Flushes the file stream used for writing log records.
#### Usage
````python
import inspect
import pyloggermanager
from pyloggermanager.handlers import FileHandler
# Create a file handler
file_handler = FileHandler(file_name='app.log', encoding='utf-8')
caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())
# Emit a log record
file_handler.emit(pyloggermanager.Record(
message="This is a log message",
logger_name='TestLogger',
level_number=20,
caller_frame=caller_frame
), ignore_display=False)
# Output
# 2024-03-22 23:48:30 :: INFO :: This is a log message
````
### `StderrHandler`
The StderrHandler class is a subclass of Handler responsible for handling log records by writing them to the standard
error stream (stderr).
#### Properties
- `stream`: Gets the standard error stream (stderr).
#### Methods
- `__init__(self, level: int = 30)` - Initializes a StderrHandler object with an optional log level.
## `pyloggermanager.streams`
The 'pyloggermanager.streams' package provides classes related to handling output streams for log records within the
logger manager framework. These classes define different types of streams that log messages can be directed to, allowing
for flexible and customizable logging behaviour.
Below listed stream classes offer versatility in directing log messages to different output channels, allowing users to
customize logging behavior based on their application's requirements and environment configuration. By supporting
various stream types, the logger manager framework enables users to control where log records are displayed or stored,
facilitating effective logging and troubleshooting processes.
Overall, the 'pyloggermanager.streams' package enhances the functionality of the logger manager framework by providing a
range of stream classes for directing log messages to different output channels. Users can leverage these classes to
tailor their logging setup to suit their specific needs and preferences, ensuring efficient management and processing of
log records.
### `Stream`
The Stream class is an abstract base class representing an output stream. It defines two abstract methods: write() and
flush(), which must be implemented by subclasses.
#### Methods
- `write(message: str) -> None`: Abstract method to write the given message to the stream.
- `flush() -> None`: Abstract method to flush the stream, ensuring all buffered data is written.
### `StdoutStream`
The StdoutStream class is a subclass of Stream representing a stream that writes messages to the standard output (
sys.stdout). It overrides the write and flush methods inherited from the Stream class.
#### Methods
- `write(message: str) -> None`: Writes the given message to the standard output (sys.stdout).
- `flush() -> None`: Flushes the output buffer of the standard output (sys.stdout), ensuring all buffered data is
written.
#### Usage
````python
from pyloggermanager.streams import StdoutStream
# Create an instance of StdoutStream
stdout_stream = StdoutStream()
# Write a message to stdout
stdout_stream.write("This is a message to stdout\n")
# Flush stdout buffer
stdout_stream.flush()
# Output
# This is a message to stdout
````
### `StderrStream`
The StderrStream class is a subclass of Stream representing a stream for writing messages to the standard error (
sys.stderr) output. It overrides the write and flush methods inherited from the Stream class.
#### Methods
- `write(message: str) -> None`: Writes the provided message to the standard error (sys.stderr) output.
- `flush() -> None`: Flushes the standard error (sys.stderr) buffer.
#### Usage
````python
from pyloggermanager.streams import StderrStream
# Create an instance of StderrStream
stderr_stream = StderrStream()
# Write a message to stderr
stderr_stream.write("This is an error message to stderr\n")
# Flush stderr buffer
stderr_stream.flush()
# Output
# This is an error message to stderr
````
### `TerminalStream`
The TerminalStream class is a subclass of Stream representing a stream for writing messages to the terminal. It
overrides the write and flush methods inherited from the Stream class.
#### Methods
- `write(message: str) -> None`: Writes the provided message to the terminal.
- `flush() -> None`: Flushes the output buffer, but does nothing for the terminal stream since output is immediately
displayed.
#### Usage
````python
from pyloggermanager.streams import TerminalStream
# Create an instance of TerminalStream
terminal_stream = TerminalStream()
# Write a message to the terminal
terminal_stream.write("This is a message to the terminal\n")
# Flush the terminal buffer (No operation required)
terminal_stream.flush()
# Output
# This is a message to the terminal
````
# Text Styles
For text colorization and styling, this package utilizes the `pycolorecho` package. You can find additional details
about its usage and features by following this
link: [pycolorecho](https://github.com/coldsofttech/pycolorecho/blob/main/README.md) package.
# License
Please refer to the [MIT license](LICENSE) within the project for more information.
# Contributing
We welcome contributions from the community! Whether you have ideas for new features, bug fixes, or enhancements, feel
free to open an issue or submit a pull request on [GitHub](https://github.com/coldsofttech/pyloggermanager).
Raw data
{
"_id": null,
"home_page": "https://github.com/coldsofttech/pyloggermanager",
"name": "pyloggermanager",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "logger, logging, logging-framework, logger-manager",
"author": "coldsofttech",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# `pyloggermanager`\n\nThe 'pyloggermanager' package is a vital logging framework for Python applications, providing developers with essential\ntools to streamline logging operations. Its primary function is to simplify the recording and organization of log\nmessages, including critical information, debugging messages, errors, and warnings. By offering a centralized interface\nand robust functionalities, the package facilitates efficient monitoring and troubleshooting processes.\n\nWith its intuitive interface, the pyloggermanager package enables developers to seamlessly integrate logging mechanisms\ninto their applications. This allows for systematic recording and categorization of log entries based on severity\nlevels, enhancing readability and prioritization of issues. Moreover, the package offers flexibility in customizing\nlogging configurations to suit specific project requirements, including formatting, output destinations, and thread\nsafety.\n\nBeyond technical capabilities, the pyloggermanager package contributes to the reliability and maintainability of Python\napplications. It establishes consistent logging practices, simplifying collaboration, code reviews, and issue resolution\nacross development teams. Overall, the pyloggermanager package is an invaluable asset for developers aiming to implement\nrobust logging solutions, ensuring efficient and resilient application performance.\n\n## Installation\n\nLogger Manager can be installed using pip:\n\n```bash\npip install pyloggermanager\n```\n\n## Usage\n\n```python\nimport pyloggermanager\n\n# Load configuration\npyloggermanager.load_config()\n\n# Log a debug message\npyloggermanager.debug(\"This is a debug message.\")\n\n# Log an informational message\npyloggermanager.info(\"This is an informational message.\")\n\n# Log a warning message\npyloggermanager.warning(\"This is a warning message.\")\n\n# Log an error message\npyloggermanager.error(\"This is an error message.\")\n\n# Log a critical message\npyloggermanager.critical(\"This is a critical message.\")\n\n# Output\n# 2024-03-22 23:37:21 :: INFO :: This is an informational message.\n# 2024-03-22 23:37:21 :: WARNING :: This is a warning message.\n# 2024-03-22 23:37:21 :: ERROR :: This is an error message.\n# 2024-03-22 23:37:21 :: CRITICAL :: This is a critical message.\n```\n\n# Documentation\n\n## `pyloggermanager`\n\n#### Methods\n\n- `load_config(file_name='default.log', file_mode='a', level=LogLevel.INFO, format_str=DEFAULT_FORMAT, date_format=DATE_FORMAT, stream=None, handlers=None, colorization=None, encoding='UTF-8')` -\n This function loads the logging configuration based on the provided parameters. It acquires a lock for thread safety,\n configures default handlers if no handlers are specified, configures the formatter and level for each handler, and\n adds the handlers to the root logger. Finally, it releases the lock.\n- `disable(level=LogLevel.CRITICAL)` - This function disables logging up to the specified level.\n- `critical(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with CRITICAL level.\n- `debug(self, message: str, ignore_display: bool = True, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with DEBUG level.\n- `error(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with ERROR level.\n- `info(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with INFO level.\n- `log(self, level: int, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message at the specified level.\n- `warning(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with WARNING level.\n\n### `CallerFrame`\n\nThe CallerFrame class represents caller details such as class name, file name, function name, module name, and path name\nbased on the caller's frame information. It provides a method to retrieve caller details from a given frame.\n\n#### Properties\n\n- `class_name`: Represents the name of the class where the function was called.\n- `file_name`: Represents the name of the file from which the function was called.\n- `function_name`: Represents the name of the function that called the method.\n- `module_name`: Represents the name of the module where the function was called.\n- `path_name`: Represents the path of the file from which the function was called.\n\n#### Methods\n\n- `__init__()`: Initializes the CallerFrame object with default attribute values.\n- `get_caller_details(frame: FrameType) -> CallerFrame`: Retrieves caller details from the given frame.\n\n#### Usage\n\n````python\nimport pyloggermanager\nimport inspect\n\n\n# Assume we have a function where we want to retrieve caller details\ndef some_function():\n caller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n print(\"Caller Class:\", caller_frame.class_name)\n print(\"Caller File:\", caller_frame.file_name)\n print(\"Caller Function:\", caller_frame.function_name)\n print(\"Caller Module:\", caller_frame.module_name)\n print(\"Caller Path:\", caller_frame.path_name)\n\n\n# Now we call the function\nsome_function()\n\n# Output\n# Caller Class: Unknown Class\n# Caller File: example\n# Caller Function: test_function\n# Caller Module: example\n# Caller Path: /path/to/example.py\n````\n\n### `FileMode`\n\nThe FileMode class represents file modes supported by the Python open() function for reading, writing, and appending to\nfiles. It provides methods to retrieve the default file mode, get the file mode mappings, check if a mode is valid, set\nthe default file mode, and get readable and writable modes.\n\n#### Constants\n\n- `READ`: Represents the read file mode.\n- `READ_PLUS`: Represents the read/write file mode.\n- `WRITE`: Represents the write file mode.\n- `WRITE_PLUS`: Represents the read/write file mode.\n- `EXCLUSIVE_CREATE`: Represents the exclusive creation file mode.\n- `APPEND`: Represents the append file mode.\n- `APPEND_PLUS`: Represents the read/append file mode.\n- `BINARY`: Represents the binary file mode.\n- `READ_BINARY`: Represents the read binary file mode.\n- `READ_WRITE_BINARY`: Represents the read/write binary file mode.\n- `TEXT`: Represents the text file mode.\n- `UPDATE`: Represents the update file mode.\n\n#### Methods\n\n- `check_mode(mode: str) -> str`: Checks if the provided mode exists and returns the same value if it exists; otherwise,\n raises a ValueError.\n- `get_default_mode() -> str`: Returns the default file mode.\n- `get_file_mode(mode_str: str) -> str`: Returns the file mode string corresponding to the provided mode name.\n- `get_file_modes() -> dict`: Returns a dictionary mapping file mode names to their corresponding strings.\n- `get_readable_modes() -> dict`: Returns a dictionary of reading file modes and their corresponding strings.\n- `get_writable_modes() -> dict`: Returns a dictionary of writable file modes and their corresponding strings.\n- `is_valid_mode(mode: str) -> bool`: Checks if the provided mode string is a valid file mode.\n- `set_default_mode(mode: str) -> None`: Sets the default file mode.\n\n#### Usage\n\n````python\n# Import the FileMode class\nimport pyloggermanager\n\n# Check if a mode is valid\nmode = 'r'\nif pyloggermanager.FileMode.is_valid_mode(mode):\n print(f\"The mode '{mode}' is valid.\")\nelse:\n print(f\"The mode '{mode}' is invalid.\")\n\n# Get default mode\ndefault_mode = pyloggermanager.FileMode.get_default_mode()\nprint(f\"The default mode is: {default_mode}\")\n\n# Set default mode\nnew_default_mode = 'a'\npyloggermanager.FileMode.set_default_mode(new_default_mode)\nprint(f\"New default mode set to: {new_default_mode}\")\n\n# Get readable modes\nreadable_modes = pyloggermanager.FileMode.get_readable_modes()\nprint(\"Readable modes:\")\nfor mode_name, mode_str in readable_modes.items():\n print(f\"- {mode_name}: {mode_str}\")\n\n# Get writable modes\nwritable_modes = pyloggermanager.FileMode.get_writable_modes()\nprint(\"Writable modes:\")\nfor mode_name, mode_str in writable_modes.items():\n print(f\"- {mode_name}: {mode_str}\")\n\n# Output\n# The mode 'r' is valid.\n# The default mode is: a\n# New default mode set to: a\n# Readable modes:\n# - READ: r\n# - READ_PLUS: r+\n# - WRITE_PLUS: w+\n# - APPEND_PLUS: a+\n# Writable modes:\n# - WRITE: w\n# - WRITE_PLUS: w+\n# - APPEND: a\n# - APPEND_PLUS: a+\n````\n\n### `Lock`\n\nThe Lock class provides a simple interface to manage locks using the Python threading module. It allows acquiring,\ncreating, checking if a lock is locked, and releasing locks.\n\n#### Methods\n\n- `acquire(name: str, blocking: bool = True, timeout: float = -1) -> bool`: Acquires the lock with the given name.\n- `create(name: str) -> None`: Creates a new lock with the given name.\n- `generate_name(length: int = 10) -> str`: Generates a random name for a lock of specified length.\n- `locked(name: str) -> bool`: Checks if the lock with the given name is currently locked.\n- `release(name: str) -> None`: Releases the lock with the given name.\n\n#### Usage\n\n````python\n# Import the Lock class\nimport pyloggermanager\nimport threading\nimport time\n\n\n# Define a function to perform an action using a lock\ndef perform_action(lock_name):\n print(f\"Thread {threading.current_thread().name} attempting to acquire lock {lock_name}\")\n if pyloggermanager.Lock.acquire(lock_name, timeout=3):\n print(f\"Thread {threading.current_thread().name} acquired lock {lock_name}\")\n time.sleep(2) # Simulating some action being performed\n pyloggermanager.Lock.release(lock_name)\n print(f\"Thread {threading.current_thread().name} released lock {lock_name}\")\n else:\n print(f\"Thread {threading.current_thread().name} couldn't acquire lock {lock_name}\")\n\n\n# Create locks\nlock1_name = pyloggermanager.Lock.generate_name()\nlock2_name = pyloggermanager.Lock.generate_name()\npyloggermanager.Lock.create(lock1_name)\npyloggermanager.Lock.create(lock2_name)\n\n# Spawn threads to perform actions using locks\nthread1 = threading.Thread(target=perform_action, args=(lock1_name,))\nthread2 = threading.Thread(target=perform_action, args=(lock2_name,))\n\nthread1.start()\nthread2.start()\n\nthread1.join()\nthread2.join()\n\n# Output\n# Thread Thread-1 (perform_action) attempting to acquire lock nzlggljagd\n# Thread Thread-2 (perform_action) attempting to acquire lock mbsvxfocxdThread Thread-1 (perform_action) acquired lock nzlggljagd\n# \n# Thread Thread-2 (perform_action) acquired lock mbsvxfocxd\n# Thread Thread-1 (perform_action) released lock nzlggljagdThread Thread-2 (perform_action) released lock mbsvxfocxd\n````\n\n### `LogLevel`\n\nThe LogLevel class represents different log levels used in logging systems. It provides methods to check if a log level\nis valid, get the default log level, get log level mappings, remove log levels, set the default log level, and set\ncustom log levels.\n\n#### Constants\n\n- `DEBUG`: Constant representing the debug log level (integer: 10)\n- `INFO`: Constant representing the info log level (integer: 20)\n- `WARNING`: Constant representing the warning log level (integer: 30)\n- `ERROR`: Constant representing the error log level (integer: 40)\n- `CRITICAL`: Constant representing the critical log level (integer: 50)\n\n#### Methods\n\n- `check_level(level: int) -> int`: Checks if the provided level exists and returns the same value if exists, else\n raises ValueError.\n- `get_default_level() -> str`: Returns the default log level as a string.\n- `get_level(level: int | str) -> str | int`: Returns the log level name if an integer level is provided, or returns the\n log level integer if a string level is provided.\n- `get_levels() -> dict`: Returns a dictionary mapping log level integers to their corresponding names, sorted by level.\n- `get_next_level(current_level: int) -> int | None`: Returns the next log level integer after the provided current\n level, or None if it is the highest level.\n- `get_previous_level(current_level: int) -> int | None`: Returns the previous log level integer before the provided\n current level, or None if it is the lowest level.\n- `is_valid_level(level: int | str) -> bool`: Checks if the provided log level (integer or string) is a valid log level.\n- `remove_level(level: int | str) -> None`: Removes the log level mapping for the specified level.\n- `set_default_level(level: int | str) -> None`: Sets the default log level based on the provided integer or string\n level.\n- `set_level(level: int, level_name: str) -> None`: Sets a custom log level with the provided level integer and name.\n\n#### Usage\n\n````python\n# Import the LogLevel class\nimport pyloggermanager\n\n# Check if a log level is valid\nprint(pyloggermanager.LogLevel.is_valid_level(pyloggermanager.LogLevel.DEBUG)) # Output: True\n\n# Get default log level\nprint(pyloggermanager.LogLevel.get_default_level()) # Output: INFO\n\n# Get log level mappings\nprint(\n pyloggermanager.LogLevel.get_levels()) # Output: {10: 'DEBUG', 20: 'INFO', 30: 'WARNING', 40: 'ERROR', 50: 'CRITICAL'}\n\n# Set default log level\npyloggermanager.LogLevel.set_default_level(pyloggermanager.LogLevel.WARNING)\nprint(pyloggermanager.LogLevel.get_default_level()) # Output: WARNING\n\n# Set custom log level\npyloggermanager.LogLevel.set_level(15, 'CUSTOM')\nprint(pyloggermanager.LogLevel.get_level(15)) # Output: 'CUSTOM'\n\n# Remove log level\npyloggermanager.LogLevel.remove_level('CUSTOM')\nprint(pyloggermanager.LogLevel.get_level(15)) # Output: 'Level 15'\n````\n\n### `Record`\n\nThe Record class represents a log record with various attributes such as message, logger name, level name, caller frame\ninformation, execution information, stack information, and thread/process details. It provides methods to serialize the\nrecord to a dictionary and JSON format.\n\n#### Properties\n\n- `time`: Property representing the timestamp of the log record.\n- `message`: Property representing the log message.\n- `logger_name`: Property representing the name of the logger.\n- `level_number`: Property representing the numeric value of the log level.\n- `level_name`: Property representing the name of the log level.\n- `file_name`: Property representing the name of the file where the log occurred.\n- `class_name`: Property representing the name of the class where the log occurred.\n- `function_name`: Property representing the name of the function/method where the log occurred.\n- `module_name`: Property representing the name of the module where the log occurred.\n- `path_name`: Property representing the path of the file where the log occurred.\n- `exec_info`: Property representing the execution information associated with the log record.\n- `stack_info`: Property representing the stack information associated with the log record.\n- `thread`: Property representing the thread ID associated with the log record.\n- `thread_name`: Property representing the name of the thread associated with the log record.\n- `process_id`: Property representing the process ID associated with the log record.\n\n#### Methods\n\n- `__init__(message: str, logger_name: str, level_number: int, caller_frame: CallerFrame, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: Optional[str] = None) -> None`:\n Constructs a new 'Record' object with the provided parameters.\n- `json_serializer(obj: Any) -> Union[str, None]`: Static method to serialize objects to JSON format.\n- `to_dict() -> dict`: Converts the 'Record' object to a dictionary.\n- `to_json() -> str`: Converts the 'Record' object to JSON string.\n\n#### Usage\n\n````python\n# Import the Record class\nimport inspect\nimport pyloggermanager\n\n# Create a CallerFrame object (Assuming it's defined elsewhere)\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Create a new Record object\nrecord = pyloggermanager.Record(\n message=\"An example log message\",\n logger_name=\"example_logger\",\n level_number=20,\n caller_frame=caller_frame,\n exec_info=(ValueError, ValueError(\"An example error occurred\"), None),\n stack_info=\"Stack trace information\"\n)\n\n# Access properties of the Record object\nprint(record.message) # Output: An example log message\nprint(record.level_name) # Output: INFO\nprint(record.file_name) # Output: example\n\n# Serialize the Record object to a dictionary\nrecord_dict = record.to_dict()\nprint(record_dict)\n# Output: {\n# 'time': datetime.datetime(2024, 3, 22, 23, 41, 47, 604552),\n# 'message': 'An example log message',\n# 'logger_name': 'example_logger',\n# 'level_name': 'INFO',\n# 'level_number': 20,\n# 'file_name': 'example',\n# 'class_name': 'ExampleClass',\n# 'function_name': 'example_function',\n# 'module_name': 'example',\n# 'path_name': 'example_path',\n# 'exec_info': (<class 'ValueError', ValueError('An example error occurred'), None),\n# 'stack_info': 'Stack trace information',\n# 'thread': 12345,\n# 'thread_name': 'MainThread',\n# 'process_id': 67890 \n# }\n\n# Serialize the Record object to JSON format\njson_string = record.to_json()\nprint(json_string)\n# Output:\n# {\n# \"time\": \"2024-03-22T23:41:47.604552\",\n# \"message\": \"An example log message\",\n# \"logger_name\": \"example_logger\",\n# \"level_name\": \"INFO\",\n# \"level_number\": 20,\n# \"file_name\": \"example\",\n# \"class_name\": \"ExampleClass\",\n# \"function_name\": \"example_function\",\n# \"module_name\": \"example\",\n# \"path_name\": \"example_path\",\n# \"exec_info\": [\n# \"ValueError\",\n# \"An example error occurred\",\n# null\n# ],\n# \"stack_info\": \"Stack trace information\",\n# \"thread\": 12345,\n# \"thread_name\": \"MainThread\",\n# \"process_id\": 67890\n# }\n````\n\n### `Logger`\n\nThe Logger class represents a logger object with various attributes and methods for logging messages.\n\n#### Properties\n\n- `cache`: Gets or sets the cache dictionary.\n- `disabled`: Indicates whether the logger is disabled or not.\n- `handlers`: The list of handlers associated with the logger.\n- `level`: The logging level of the logger.\n- `lock_name`: Gets or sets the name of the lock used for thread safety.\n- `manager`: The manager associated with the logger.\n- `name`: The name of the logger.\n- `parent`: The parent logger in the logger hierarchy.\n- `root`: The root logger associated with the logger hierarchy.\n\n#### Methods\n\n- `__init__(self, name: str, level: int = LogLevel.INFO) -> None`: Initializes a new Logger object.\n- `add_handler(self, handler: Handler) -> None`: Adds a handler to the logger's list of handlers after acquiring the\n lock.\n- `call_handlers(self, record: Record, ignore_display: bool) -> None`: Calls the handlers associated with the logger.\n- `critical(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with CRITICAL level.\n- `debug(self, message: str, ignore_display: bool = True, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with DEBUG level.\n- `error(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with ERROR level.\n- `find_caller(self, stack_info: bool = False, stack_level: int = 1) -> Tuple[CallerFrame, str]`: Finds the caller frame\n and optionally collects stack information.\n- `get_child(self, suffix: str) -> 'Logger'`: Get a child logger with the specified suffix.\n- `get_effective_level(self) -> int`: Retrieves the effective log level for the logger.\n- `handle(self, record: Record, ignore_display: bool) -> None`: Handles the given log record by calling its handlers if\n the logger is not disabled.\n- `has_handlers(self) -> bool`: Checks if the logger or any of its ancestors have handlers.\n- `info(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with INFO level.\n- `is_enabled_for(self, level: int) -> bool`: Checks if logging is enabled for the specified log level.\n- `log(self, level: int, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message at the specified level.\n- `make_record(self, name: str, level: int, message: str, caller_frame: Optional[CallerFrame] = None, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: Optional[str] = None) -> Record`:\n Creates a Record object with specified attributes.\n- `remove_handler(self, handler: Handler) -> None`: Removes a handler from the logger's list of handlers after acquiring\n the lock.\n- `warning(self, message: str, ignore_display: bool = False, exec_info: Optional[Tuple[Type, BaseException, Optional[TracebackType]]] = None, stack_info: bool = False, stack_level: int = 1) -> None`:\n Logs a message with WARNING level.\n\n#### Usage\n\n````python\n# Importing the necessary modules\nimport pyloggermanager\nfrom pyloggermanager.handlers import ConsoleHandler\n\n# Sample usage of the Logger class\n# Creating a logger instance\nlogger = pyloggermanager.Logger(\"example_logger\")\n\n# Adding a handler\nhandler = ConsoleHandler()\nlogger.add_handler(handler)\n\n# Logging messages\nlogger.info(\"This is an informational message.\\n\")\nlogger.error(\"An error occurred.\")\n\n# Removing the handler\nlogger.remove_handler(handler)\n\n# Output\n# 2024-03-22 23:45:14 :: INFO :: This is an informational message.\n# 2024-03-22 23:45:14 :: ERROR :: An error occurred.\n````\n\n### `Manager`\n\nThe Manager class manages loggers and their settings within a logging hierarchy.\n\n#### Properties\n\n- `disable`: Gets or sets the level at which logging is disabled.\n- `lock_name`: Gets or sets the name of the lock used for thread safety.\n- `logger_class`: Gets or sets the logger class used for creating logger instances.\n- `logger_dict`: Gets or sets the dictionary mapping logger names to their instances.\n- `record_factory`: Gets or sets the factory used for creating log records.\n- `root`: Gets or sets the root logger of the logging hierarchy.\n\n#### Methods\n\n- `__init__(self, root_node: Logger) -> None`: Initializes the Manager with a root logger.\n- `clear_cache(self) -> None`: Clears the cache for all loggers and the root logger.\n- `get_logger(self, name: str) -> Logger`: Retrieves a logger with the specified name. If the logger does not exist, it\n creates a new logger.\n- `set_logger(self, logger: Logger) -> None`: Sets the logger class to be used for creating new loggers.\n\n#### Usage\n\n````python\n# Importing the necessary modules\nimport pyloggermanager\n\n# Create a root logger\nroot_logger = pyloggermanager.Logger(\"root\")\n\n# Create a manager with the root logger\nmanager = pyloggermanager.Manager(root_logger)\n\n# Set the level at which logging is disabled\nmanager.disable = 20\n\n# Get a logger named 'example_logger'\nexample_logger = manager.get_logger(\"example_logger\")\n\n# Set the logger class\nmanager.set_logger(example_logger)\n\n# Clear the cache for all loggers and the root logger\nmanager.clear_cache()\n````\n\n### `Registry`\n\nThe Registry class serves as a registry to store and manage instances of the Logger class.\n\n#### Properties\n\n- `logger_map`: Gets or sets the dictionary mapping loggers to their associated values.\n\n#### Methods\n\n- `__init__(self, logger: Logger) -> None`: Initializes the Registry with a single logger.\n- `append(self, logger: Logger) -> None`: Adds a new logger to the registry.\n\n#### Usage\n\n````python\n# Importing the necessary modules\nimport pyloggermanager\n\n# Create a logger\nlogger = pyloggermanager.Logger(\"example_logger\")\n\n# Create a registry with the logger\nregistry = pyloggermanager.Registry(logger)\n\n# Append a new logger to the registry\nnew_logger = pyloggermanager.Logger(\"new_logger\")\nregistry.append(new_logger)\n\n# Get the logger map\nlogger_map = registry.logger_map\n````\n\n### `RootLogger`\n\nThe RootLogger class represents the root logger in a logging hierarchy. It inherits from the Logger class and\ninitializes itself with the name 'root' and the specified log level. The root logger serves as the ancestor of all other\nloggers in the logging hierarchy.\n\n#### Methods\n\n- `__init__(self, level: int) -> None`: Constructs a new RootLogger object with the specified log level.\n\n## `pyloggermanager.formatters`\n\nThe 'pyloggermanager.formatters' package provides classes for formatting log messages in various formats within the\nlogger manager framework. It includes implementations for formatting log messages as CSV (Comma-Separated Values),\nJSON (JavaScript Object Notation), and the default text format.\n\nBelow listed formatter classes enable users to customize the appearance and structure of log messages according to their\nrequirements. By supporting different formats such as CSV and JSON, users have the flexibility to choose the most\nsuitable format for their logging needs, whether it's for human-readable output, structured data storage, or integration\nwith external systems.\n\nOverall, the 'pyloggermanager.formatters' package enhances the logger manager framework by offering versatile formatting\noptions for log messages, catering to a wide range of logging use cases and preferences.\n\n#### Constants\n\n- `DEFAULT_FORMAT` (str): The default format string used for log message formatting.\n- `CSV_FORMAT` (str): The format string used for CSV log message formatting.\n- `JSON_FORMAT` (str): The format string used for JSON log message formatting.\n- `DATE_FORMAT` (str): The default date format string used for log message formatting.\n\n### `Formatter`\n\nBase class for log record formatters. It allows customization of log message format. Subclasses must implement the\nformat method to customize log message formatting.\n\n| Placeholder | Description |\n|---------------------|-----------------------------------------------------------------------------------------|\n| `%(time)s` | The time at which the log record was created, formatted using `date_format`. |\n| `%(message)s` | The message associated with the log record. |\n| `%(logger_name)s` | The name of the logger. |\n| `%(level_name)s` | The name of the logging level (e.g., INFO, WARNING). |\n| `%(level_number)d` | The numeric value of the logging level. |\n| `%(file_name)s` | The name of the file from which the logging call was made. |\n| `%(class_name)s` | The name of the class containing the logging call. |\n| `%(function_name)s` | The name of the function/method containing the logging call. |\n| `%(module_name)s` | The name of the module containing the logging call. |\n| `%(path_name)s` | The full pathname of the source file. |\n| `%(exec_info)s` | The formatted traceback information if an exception was raised during the logging call. |\n| `%(stack_info)s` | The stack information at the time of the logging call. |\n| `%(thread)d` | The thread ID. |\n| `%(thread_name)s` | The name of the thread. |\n| `%(process_id)d` | The ID of the process. |\n\n#### Methods\n\n- `__init__(format_str: str | dict = DEFAULT_FORMAT, date_format: str = DATE_FORMAT)`: Initializes the Formatter object.\n- `format(record: 'Record') -> str`: Formats the log record into a string based on the provided record object.\n- `format_time(value: time.struct_time, date_format: str) -> str`: Formats the provided time value into a string using\n the specified date format.\n- `format_exception(exec_info: Optional[Tuple[Type[BaseException], BaseException, Optional[TracebackType]]] = None) -> str`:\n Formats the exception information into a string.\n\n### `DefaultFormatter`\n\nCustom formatter for log records. It allows customization of log record formatting using a specified format string.\nReplaces tokens in the format string with corresponding values from the log record.\n\n#### Methods\n\n- `__init__(format_str: str = DEFAULT_FORMAT, date_format: str = DATE_FORMAT)`: Initializes a 'DefaultFormatter'\n instance with the specified format string.\n- `format(record: 'Record') -> str`: Formats the given log record according to the format string.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.formatters import DefaultFormatter\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Create a log record\nrecord = pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name=\"example_logger\",\n level_number=20,\n caller_frame=caller_frame,\n exec_info=None,\n stack_info=None\n)\n\n# Create a DefaultFormatter instance\nformatter = DefaultFormatter()\n\n# Format the log record\nformatted_message = formatter.format(record)\nprint(formatted_message)\n\n# Output: '2024-03-22 15:30:45 :: INFO :: This is a log message'\n````\n\n### `CSVFormatter`\n\nSubclass of the 'Formatter' class for formatting log records in CSV format. It allows customization of the format string\nused for formatting log records.\n\n#### Methods\n\n- `__init__(format_str: str = CSV_FORMAT, date_format: str = DATE_FORMAT)`: Initializes a 'CSVFormatter' object with the\n specified format string.\n- `format(record: 'Record') -> str`: Formats the given log record into a CSV string based on the specified format\n string.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.formatters import CSVFormatter\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Create a log record\nrecord = pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name=\"example_logger\",\n level_number=20,\n caller_frame=caller_frame,\n exec_info=None,\n stack_info=None\n)\n\n# Create a CSVFormatter instance\nformatter = CSVFormatter()\n\n# Format the log record as CSV\nformatted_message = formatter.format(record)\nprint(formatted_message)\n\n# Output: '2024-03-22 23:46:41,INFO,This is a log message'\n````\n\n### `JSONFormatter`\n\nSubclass of the 'Formatter' class for formatting log records into JSON format. It provides methods to initialize the\nformatter with a custom format string, format log records into JSON strings, and handle JSON decoding errors.\n\n#### Methods\n\n- `__init__(format_str: dict = None, date_format: str = DATE_FORMAT)`: Initializes the JSONFormatter object with a\n custom format string.\n- `format(record: 'Record') -> str`: Formats the given log record into a JSON string.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.formatters import JSONFormatter\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Create a log record\nrecord = pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name=\"example_logger\",\n level_number=20,\n caller_frame=caller_frame,\n exec_info=None,\n stack_info=None\n)\n\n# Create a JSONFormatter instance\nformatter = JSONFormatter()\n\n# Format the log record as JSON\nformatted_message = formatter.format(record)\nprint(formatted_message)\n\n# Output:\n# {\n# \"time\": \"2024-03-22 23:47:03\",\n# \"levelName\": \"INFO\",\n# \"message\": \"This is a log message\"\n# }\n````\n\n## `pyloggermanager.handlers`\n\nThe 'pyloggermanager.handlers' package provides classes responsible for handling log records generated within the logger\nmanager framework. It includes various handlers for processing log messages, directing them to different destinations,\nand performing actions based on logging levels.\n\nBelow listed handler classes offer flexibility and customization options for managing log records within the logger\nmanager framework. They enable users to define how log messages are processed, where they are directed, and how they are\nformatted, catering to various logging scenarios and deployment environments.\n\nOverall, the 'pyloggermanager.handlers' package enhances the functionality of the logger manager framework by providing\na robust set of handlers for managing log records effectively and efficiently. Users can choose and configure handlers\nbased on their specific logging needs and infrastructure requirements.\n\n### `Handler`\n\nThe Handler class is a base class for different log handlers used in logging systems. It provides methods and properties\nto manage handler attributes such as name, log level, colorization, and formatter. Additionally, it includes methods to\nacquire/release locks, close the handler, emit log records, format log records, flush buffered records, and retrieve a\nlist of all handlers.\n\n#### Properties\n\n- `colorization`: Gets or sets the colorization object for the handler.\n- `formatter`: Gets or sets the formatter object for formatting log records.\n- `level`: Gets or sets the log level for the handler.\n- `name`: Gets or sets the name of the handler.\n\n#### Methods\n\n- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter())` -\n Initializes the handler with optional attributes.\n- `close()`: Closes the handler.\n- `emit(record: 'Record', ignore_display: bool) -> None`: Abstract method to emit a log record.\n- `format(record: 'Record') -> str`: Formats a log record using the handler's formatter.\n- `flush()`: Flushes buffered records.\n- `get_handlers() -> list[Any]`: Retrieves a list of all handlers.\n- `handle(record: 'Record', ignore_display: bool) -> None`: Handles a log record.\n\n#### Usage\n\n````python\nfrom pyloggermanager.formatters import Formatter\nfrom pyloggermanager.handlers import Handler\n\n\n# Create a custom formatter\nclass CustomFormatter(Formatter):\n def format(self, record):\n return f\"[{record.level_name}] {record.message}\"\n\n\n# Create a handler with custom formatter\nhandler = Handler(formatter=CustomFormatter())\n````\n\n### `ConsoleHandler`\n\nThe ConsoleHandler class is a subclass of Handler representing a handler that writes log records to the console. It\nprovides methods to set and retrieve the stream used for logging, close the stream, emit log records, and flush the\nstream.\n\n#### Properties\n\n- `stream`: Gets or sets the stream of the handler.\n\n#### Methods\n\n- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), stream: Stream = TerminalStream())` -\n Initializes a ConsoleHandler instance with optional attributes\n- `close()`: Closes the stream if it has a close method.\n- `emit(record: 'Record', ignore_display: bool = True) -> None`: Emits the log record by formatting it, colorizing the\n message, and writing it to the stream.\n- `flush()`: Flushes the stream if it has a flush method.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.handlers import ConsoleHandler\n\n# Create a console handler\nconsole_handler = ConsoleHandler()\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Emit a log record\nconsole_handler.emit(pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name='TestLogger',\n level_number=20,\n caller_frame=caller_frame\n))\n\n# Output\n# 2024-03-22 23:47:35 :: INFO :: This is a log message\n````\n\n### `StreamHandler`\n\nThe StreamHandler class is a subclass of Handler representing a handler that emits log records to a stream. It provides\nmethods to set the log level, formatter, and stream, as well as to emit log records and flush the stream.\n\n#### Properties\n\n- `stream`: Gets or sets the stream of the handler.\n\n#### Methods\n\n- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), stream: Stream = StdoutStream())` -\n Initializes a StreamHandler instance with optional attributes.\n- `close()`: Closes the stream if it has a close method.\n- `emit(record: 'Record', ignore_display: bool) -> None`: Emits a log record to the stream.\n- `flush()`: Flushes the stream if it has a flush method.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.handlers import StreamHandler\n\n# Create a stream handler\nstream_handler = StreamHandler()\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Emit a log record\nstream_handler.emit(pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name='TestLogger',\n level_number=20,\n caller_frame=caller_frame\n), ignore_display=True)\n\n# Output\n# 2024-03-22 23:48:13 :: INFO :: This is a log message\n````\n\n### `FileHandler`\n\nThe FileHandler class is a subclass of Handler responsible for handling log records by writing them to a file. It allows\ncustomization of various parameters such as file name, file mode, encoding, etc.\n\n#### Properties\n\n- `encoding`: Gets or sets the encoding of the handler.\n- `filemode`: Gets or sets the file mode for opening the file handler.\n- `filename`: Gets or sets the file name of the handler.\n\n#### Methods\n\n- `__init__(name: str = None, level: int = 20, colorization: pycolorecho.ColorMapper = None, formatter: Formatter = DefaultFormatter(), file_name: str = 'default.log', file_mode: str = 'a', encoding: str = 'UTF-8')` -\n Initializes a FileHandler object with optional attributes.\n- `close()`: Closes the file stream used for writing log records.\n- `emit(record: 'Record', ignore_display: bool) -> None`: Emits a log record by writing it to the log file.\n- `flush()`: Flushes the file stream used for writing log records.\n\n#### Usage\n\n````python\nimport inspect\nimport pyloggermanager\nfrom pyloggermanager.handlers import FileHandler\n\n# Create a file handler\nfile_handler = FileHandler(file_name='app.log', encoding='utf-8')\n\ncaller_frame = pyloggermanager.CallerFrame.get_caller_details(inspect.currentframe())\n\n# Emit a log record\nfile_handler.emit(pyloggermanager.Record(\n message=\"This is a log message\",\n logger_name='TestLogger',\n level_number=20,\n caller_frame=caller_frame\n), ignore_display=False)\n\n# Output\n# 2024-03-22 23:48:30 :: INFO :: This is a log message\n````\n\n### `StderrHandler`\n\nThe StderrHandler class is a subclass of Handler responsible for handling log records by writing them to the standard\nerror stream (stderr).\n\n#### Properties\n\n- `stream`: Gets the standard error stream (stderr).\n\n#### Methods\n\n- `__init__(self, level: int = 30)` - Initializes a StderrHandler object with an optional log level.\n\n## `pyloggermanager.streams`\n\nThe 'pyloggermanager.streams' package provides classes related to handling output streams for log records within the\nlogger manager framework. These classes define different types of streams that log messages can be directed to, allowing\nfor flexible and customizable logging behaviour.\n\nBelow listed stream classes offer versatility in directing log messages to different output channels, allowing users to\ncustomize logging behavior based on their application's requirements and environment configuration. By supporting\nvarious stream types, the logger manager framework enables users to control where log records are displayed or stored,\nfacilitating effective logging and troubleshooting processes.\n\nOverall, the 'pyloggermanager.streams' package enhances the functionality of the logger manager framework by providing a\nrange of stream classes for directing log messages to different output channels. Users can leverage these classes to\ntailor their logging setup to suit their specific needs and preferences, ensuring efficient management and processing of\nlog records.\n\n### `Stream`\n\nThe Stream class is an abstract base class representing an output stream. It defines two abstract methods: write() and\nflush(), which must be implemented by subclasses.\n\n#### Methods\n\n- `write(message: str) -> None`: Abstract method to write the given message to the stream.\n- `flush() -> None`: Abstract method to flush the stream, ensuring all buffered data is written.\n\n### `StdoutStream`\n\nThe StdoutStream class is a subclass of Stream representing a stream that writes messages to the standard output (\nsys.stdout). It overrides the write and flush methods inherited from the Stream class.\n\n#### Methods\n\n- `write(message: str) -> None`: Writes the given message to the standard output (sys.stdout).\n- `flush() -> None`: Flushes the output buffer of the standard output (sys.stdout), ensuring all buffered data is\n written.\n\n#### Usage\n\n````python\nfrom pyloggermanager.streams import StdoutStream\n\n# Create an instance of StdoutStream\nstdout_stream = StdoutStream()\n\n# Write a message to stdout\nstdout_stream.write(\"This is a message to stdout\\n\")\n\n# Flush stdout buffer\nstdout_stream.flush()\n\n# Output\n# This is a message to stdout\n````\n\n### `StderrStream`\n\nThe StderrStream class is a subclass of Stream representing a stream for writing messages to the standard error (\nsys.stderr) output. It overrides the write and flush methods inherited from the Stream class.\n\n#### Methods\n\n- `write(message: str) -> None`: Writes the provided message to the standard error (sys.stderr) output.\n- `flush() -> None`: Flushes the standard error (sys.stderr) buffer.\n\n#### Usage\n\n````python\nfrom pyloggermanager.streams import StderrStream\n\n# Create an instance of StderrStream\nstderr_stream = StderrStream()\n\n# Write a message to stderr\nstderr_stream.write(\"This is an error message to stderr\\n\")\n\n# Flush stderr buffer\nstderr_stream.flush()\n\n# Output\n# This is an error message to stderr\n````\n\n### `TerminalStream`\n\nThe TerminalStream class is a subclass of Stream representing a stream for writing messages to the terminal. It\noverrides the write and flush methods inherited from the Stream class.\n\n#### Methods\n\n- `write(message: str) -> None`: Writes the provided message to the terminal.\n- `flush() -> None`: Flushes the output buffer, but does nothing for the terminal stream since output is immediately\n displayed.\n\n#### Usage\n\n````python\nfrom pyloggermanager.streams import TerminalStream\n\n# Create an instance of TerminalStream\nterminal_stream = TerminalStream()\n\n# Write a message to the terminal\nterminal_stream.write(\"This is a message to the terminal\\n\")\n\n# Flush the terminal buffer (No operation required)\nterminal_stream.flush()\n\n# Output\n# This is a message to the terminal\n````\n\n# Text Styles\n\nFor text colorization and styling, this package utilizes the `pycolorecho` package. You can find additional details\nabout its usage and features by following this\nlink: [pycolorecho](https://github.com/coldsofttech/pycolorecho/blob/main/README.md) package.\n\n# License\n\nPlease refer to the [MIT license](LICENSE) within the project for more information.\n\n# Contributing\n\nWe welcome contributions from the community! Whether you have ideas for new features, bug fixes, or enhancements, feel\nfree to open an issue or submit a pull request on [GitHub](https://github.com/coldsofttech/pyloggermanager).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The pyloggermanager package is a vital logging framework for Python applications, providing developers with essential",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/coldsofttech/pyloggermanager"
},
"split_keywords": [
"logger",
" logging",
" logging-framework",
" logger-manager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "feba75519e303312c20e16d8d5212716d077789b40e8294c2859589b47b85c9b",
"md5": "97bd1a0cc316e83a4517fa52b6580f38",
"sha256": "782f8f6ce6a60f21f9e573c087c3a9cfea22143872538f9a368f9062c1147cae"
},
"downloads": -1,
"filename": "pyloggermanager-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97bd1a0cc316e83a4517fa52b6580f38",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 35807,
"upload_time": "2024-05-05T09:18:39",
"upload_time_iso_8601": "2024-05-05T09:18:39.668516Z",
"url": "https://files.pythonhosted.org/packages/fe/ba/75519e303312c20e16d8d5212716d077789b40e8294c2859589b47b85c9b/pyloggermanager-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 09:18:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coldsofttech",
"github_project": "pyloggermanager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyloggermanager"
}
JSON
