Generic logging utilities for consistent log formatting across Python projects.

ALT-logging-utils provides a collection of reusable logging functions to reduce duplication and maintain consistency across Python projects. These utilities help format log messages in a structured and readable way.

• Test Logging: Log test starts and ends with clear visual separators
• File Operations: Log file saves, reads, and errors with consistent formatting
• Component Lifecycle: Log initialization and configuration of components
• Error Context: Log errors with additional context information
• Operation Status: Log operation status with automatic level selection
• Debug Values: Log debug values with optional prefixes
• Collection Operations: Log collection completion with item counts

pip install ALT-logging-utils

import logging
from pathlib import Path
from alt_logging_utils import (
    log_test_start,
    log_test_end,
    log_saved_file,
    log_error_with_context,
    log_operation_status,
)

# Set up your logger
logger = logging.getLogger(__name__)

# Log test execution
log_test_start(logger, "test_user_authentication", "AuthenticationModule")
# ... test code ...
log_test_end(logger, "test_user_authentication")

# Log file operations
log_saved_file(logger, "configuration", Path("/etc/app/config.yml"))

# Log errors with context
try:
    result = risky_operation()
except Exception as e:
    log_error_with_context(
        logger, 
        e, 
        "processing user request",
        user_id=12345,
        operation="data_sync"
    )

# Log operation status
log_operation_status(logger, "Database backup", "completed", "5GB in 2 minutes")

Logs the start of a test with visual separators.

log_test_start(logger, "test_login", "UserAuthTests")

Logs the end of a test.

log_test_end(logger, "test_login")

Logs that a file has been saved.

log_saved_file(logger, "report", Path("./reports/monthly.pdf"), level=logging.INFO)

Logs that a file was found.

log_found_file(logger, "config file", Path("/etc/app/config.yml"))

Logs a file operation error.

try:
    content = file.read()
except IOError as e:
    log_file_operation_error(logger, "read", Path("data.json"), e)

Logs component initialization.

log_initialization(logger, "Database Connection", "postgres://localhost:5432/mydb")

Logs component configuration with key-value pairs.

log_configuration(
    logger, 
    "API Client",
    base_url="https://api.example.com",
    timeout=30,
    retry_count=3
)

Logs an error with contextual information.

log_error_with_context(
    logger,
    exception,
    "processing payment",
    user_id=user.id,
    amount=150.00,
    currency="USD"
)

Logs operation status with automatic level selection based on status.

log_operation_status(logger, "Data sync", "completed", "1000 records processed")
log_operation_status(logger, "Connection", "failed", "timeout after 30s")

Logs completion of a collection operation.

log_collection_completed(logger, "Users", 42)

Logs a debug value with consistent formatting.

log_debug_value(logger, "cache_size", 1024)
log_debug_value(logger, "requests", 42, prefix="Stats: ")

The package exports formatting constants that can be used in your own logging:

from alt_logging_utils import (
    LOG_SEPARATOR_LENGTH,    # Length of separator lines (60)
    LOG_SEPARATOR_CHAR,      # Character for major separators ('=')
    LOG_SUBSEPARATOR_CHAR,   # Character for minor separators ('-')
)

# Use in your own logging
logger.info("=" * LOG_SEPARATOR_LENGTH)

1. Consistent Formatting: Use these utilities throughout your project for consistent log formatting
2. Appropriate Levels: Use the level parameter to control log verbosity
3. Rich Context: Provide meaningful context with errors using log_error_with_context
4. Structured Data: Use log_configuration to log configuration in a structured way

• Python 3.8 or higher
• No external dependencies (uses only Python standard library)

Full documentation is available at:

• Read the Docs (coming soon)
• GitHub Wiki
• API Reference

# Clone the repository
git clone https://github.com/avilayani/ALT-logging-utils.git
cd ALT-logging-utils

# Set up development environment
make setup

# Or manually:
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Run all tests with coverage
make test

# Run specific tests
pytest tests/test_logging_utils.py

# Run with coverage report
pytest --cov=alt_logging_utils --cov-report=html

# Run all quality checks
make all

# Individual checks
make lint        # Run linting
make format      # Format code
make type-check  # Type checking

# Build HTML documentation
make docs

# Serve documentation locally
make docs-live

We welcome contributions! Please see our Contributing Guide for details on:

• Code style and standards
• Development workflow
• Submitting pull requests
• Reporting issues

• Add structured logging support (JSON output)
• Add async logging utilities
• Add performance metrics logging
• Add log aggregation helpers
• Add more customization options

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

This project is licensed under the MIT License - see the LICENSE file for details.

• Thanks to all contributors who have helped improve this package
• Inspired by the need for consistent logging across multiple projects

Avi Layani

• Email: [email protected]
• GitHub: @avilayani