"""Logging configuration utilities.
Author: @TexasCoding
Date: 2025-08-02
Overview:
Provides basic logging configuration utilities for the ProjectX SDK.
Includes simple logging setup with configurable levels, formats, and
file output options for basic logging requirements.
Key Features:
- Basic logging configuration with customizable levels
- Configurable log format strings
- Optional file logging support
- Simple setup for basic logging needs
- Consistent logger naming across the SDK
- Easy integration with existing logging systems
Logging Setup:
- Configurable logging levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- Custom format strings for log messages
- Optional file output for log persistence
- Consistent logger naming with "project_x_py" prefix
- Basic logging configuration for simple use cases
Example Usage:
```python
from project_x_py.utils import setup_logging
# Basic setup with default configuration
logger = setup_logging()
# Custom level and format
logger = setup_logging(
level="DEBUG",
format_string="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
# With file output
logger = setup_logging(level="INFO", filename="projectx.log")
# Use the logger
logger.info("Application started")
logger.error("An error occurred")
```
Configuration Options:
- level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
- format_string: Custom format for log messages
- filename: Optional file path for log output
- Consistent logger naming and configuration
Performance Characteristics:
- Minimal overhead for basic logging setup
- Efficient logging configuration
- Memory-efficient logger management
- Thread-safe logging operations
- Optimized for simple logging requirements
See Also:
- `utils.logging_config`: Advanced logging configuration and monitoring
- `utils.error_handler`: Error handling with logging integration
"""
import logging
[docs]
def setup_logging(
level: str = "INFO",
format_string: str | None = None,
filename: str | None = None,
) -> logging.Logger:
"""
Set up logging configuration for the ProjectX client.
Args:
level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
format_string: Custom format string for log messages
filename: Optional filename to write logs to
Returns:
Logger instance
"""
if format_string is None:
format_string = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
logging.basicConfig(
level=getattr(logging, level.upper()), format=format_string, filename=filename
)
return logging.getLogger("project_x_py")