THCustomLogger 0.3.5

A custom logging package with multiline formatting

THCustomLogger

A powerful and flexible Python logging package with colorized output, multiline formatting, rate limiting, and git integration.

✨ Features

• 🎨 Colorized Console Output - Beautiful, color-coded log levels using colorlog
• 😃 Emoji Support - Optional emoji prefixes for log levels (🐛 DEBUG, ℹ️ INFO, ⚠️ WARNING, ❌ ERROR, 🔥 CRITICAL)
• 📝 Multiline Message Formatting - Properly indented multiline log messages
• 🚦 Rate Limiting - Prevent log spam with configurable rate limiting
• 🔄 Log Rotation - Automatic time-based log file rotation
• 🔧 Flexible Configuration - Configure via code or environment variables
• 🌳 Git Integration - Built-in methods to log commit hashes and tags
• 🧵 Thread-Safe - Safe to use in multi-threaded applications
• 📊 Custom Formatters - Support for custom message breaks and formatting

Table of Contents

• THCustomLogger
  • ✨ Features
  • Table of Contents
  • Installation
  • Quick Start
  • Configure logger globally
    • Configuration Options
  • 📖 Usage Examples
    • Multiline Logging
    • Rate Limiting
    • Git Integration
    • Environment-Based Configuration
  • ⚙️ Configuration Options
    • Programmatic Configuration
    • Environment Variables
  • 🎯 Advanced Usage
    • Using LoggerFactory
    • Colored Output
    • Multiline Formatting
    • Thread Safety
    • Type Hints
  • 🧪 Testing
  • 📝 Examples
    • Example: Web Application Logging
    • Example: Data Processing with Rate Limiting
  • 🤝 Contributing
  • 📄 License
  • 🔗 Links
  • 👤 Author
  • 🙏 Acknowledgments

Installation

pip install THCustomLogger

Quick Start

Usage example

from THCustomLogger import get_logger

# Get a logger instance
logger = get_logger(__name__)

# Basic logging
logger.info("Hello, World!")
logger.debug("Debug message")
logger.warning("Warning message")
logger.error("Error message")

# Multiline logging with custom formatting
logger.info("Multiple\nline\nmessage")

# Git information
logger.info(f"Current commit: {logger.get_commit_hash()}")
logger.info(f"Latest tag: {logger.get_latest_tag()}")

# Logging with break lines
logger.info("Message with break line", extra={'msg_break': '*'})

Output

2025-04-29 11:00:00.625 | Line: 186 logger_setup.<module>             | INFO    : Hello, World!
2025-04-29 11:00:00.625 | Line: 188 logger_setup.<module>             | WARNING : Warning message
2025-04-29 11:00:00.625 | Line: 189 logger_setup.<module>             | ERROR   : Error message
2025-04-29 11:00:00.625 | Line: 192 logger_setup.<module>             | INFO    : Multiple
                                                                                  line
                                                                                  message
2025-04-29 11:00:00.632 | Line: 195 logger_setup.<module>             | INFO    : Current commit: afba168c52d65a621139c3b3e072a1fd991b26bd
2025-04-29 11:00:00.639 | Line: 107 logger_setup.get_latest_tag       | ERROR   : Error getting latest tag: fatal: No names found, cannot describe anything.

2025-04-29 11:00:00.640 | Line: 196 logger_setup.<module>             | INFO    : Latest tag: unknown
2025-04-29 11:00:00.640 | Line: 199 logger_setup.<module>             | INFO    : Message with break line
**********************************************************************************

2025-04-29 11:05:17.340 | Line: 172 logger_setup.example              | ERROR   : division by zero
Traceback (most recent call last):
  File "/Users/tylerhaunreiter/Desktop/Python/CustomLogger/src/THCustomLogger/logger_setup.py", line 170, in example
    1 / 0
    ~~^~~
ZeroDivisionError: division by zero

Configure logger globally

configure( log_level=logging.DEBUG, log_dir="logs", file_name_prefix="myapp", console_enabled=True, file_enabled=True ) logger = get_logger(name) logger.info("Logger configured!")

Configuration Options

Option	Description	Default
console_enabled	Enable console output	True
file_enabled	Enable file output	True
log_level	Logging level	"INFO"
emoji_enabled_console	Enable emojis for console output	False
emoji_enabled_file	Enable emojis for file output	False
rotation_when	Log rotation interval type (S/M/H/D/W)	"D"
rotation_interval	Number of intervals before rotation	1
backup_count	Number of backup files to keep	7
encoding	Log file encoding	"utf-8"

📖 Usage Examples

Emoji Support

from THCustomLogger import configure, get_logger
import logging

# Enable emojis for console output (recommended)
configure(
    log_level=logging.DEBUG,
    emoji_enabled_console=True,  # Emojis in console
    emoji_enabled_file=False     # Plain text in files (recommended)
)

logger = get_logger(__name__)

# Your logs will now have visual emoji indicators
logger.debug("Starting debugging session")     # 🐛 DEBUG
logger.info("Application started")             # ℹ️ INFO
logger.warning("Low disk space")               # ⚠️ WARNING
logger.error("Failed to connect")              # ❌ ERROR
logger.critical("System shutdown required")    # 🔥 CRITICAL

Output with emojis enabled:

2026-02-14 01:33:06.628 | 191: test_colors._log | 🐛 DEBUG  : Starting debugging session
2026-02-14 01:33:06.628 | 191: test_colors._log | ℹ️ INFO   : Application started
2026-02-14 01:33:06.628 | 191: test_colors._log | ⚠️ WARNING: Low disk space
2026-02-14 01:33:06.628 | 191: test_colors._log | ❌ ERROR  : Failed to connect
2026-02-14 01:33:06.628 | 191: test_colors._log | 🔥 CRITICAL: System shutdown required

Multiline Logging

from THCustomLogger import get_logger

logger = get_logger(__name__)

# Multiline messages are automatically indented
logger.info("Processing items:\n- Item 1\n- Item 2\n- Item 3")

# Add custom message breaks
logger.info("Section completed", extra={'msg_break': '='})

# Disable indentation for specific messages
logger.info("Line 1\nLine 2", extra={'no_indent': True})

Rate Limiting

from THCustomLogger import get_logger

logger = get_logger(__name__)

# Configure rate limiting
logger.configure_rate_limit(
    enabled=True,
    window_seconds=60,  # Time window in seconds
    max_count=10  # Max occurrences per window
)

# Only first 10 occurrences within 60 seconds will be logged
for i in range(100):
    logger.info("Repeated message")

Git Integration

from THCustomLogger import get_logger

logger = get_logger(__name__)

# Log current git commit hash
logger.info(f"Running on commit: {logger.get_commit_hash()}")

# Log latest git tag
logger.info(f"Version: {logger.get_latest_tag()}")

Environment-Based Configuration

Set environment variables to configure the logger:

export LOGGER_LEVEL=DEBUG
export LOGGER_DIR=logs
export LOGGER_FILE_PREFIX=myapp
export LOGGER_CONSOLE_ENABLED=true
export LOGGER_FILE_ENABLED=true
export LOGGER_EMOJI_CONSOLE=true
export LOGGER_EMOJI_FILE=false
export LOGGER_ROTATION_WHEN=midnight
export LOGGER_ROTATION_INTERVAL=1
export LOGGER_BACKUP_COUNT=30

from THCustomLogger import get_logger

# Logger will automatically use environment variables
logger = get_logger(__name__)
logger.info("Configured from environment!")

⚙️ Configuration Options

Programmatic Configuration

from THCustomLogger import configure
import logging

configure(
    log_level=logging.INFO,  # Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
    log_dir="logs",  # Directory for log files
    file_name_prefix="app",  # Prefix for log file names
    console_enabled=True,  # Enable console output
    file_enabled=True,  # Enable file output
    emoji_enabled_console=True,  # Enable emojis for console
    emoji_enabled_file=False,  # Disable emojis for file logs (recommended)
    rotation_when="midnight",  # When to rotate logs
    rotation_interval=1,  # Rotation interval
    backup_count=30,  # Number of backup files to keep
    encoding="utf-8",  # File encoding
)

Environment Variables

Variable	Description	Default
LOGGER_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	INFO
LOGGER_DIR	Directory for log files	logs
LOGGER_FILE_PREFIX	Prefix for log filenames	app
LOGGER_CONSOLE_ENABLED	Enable console logging	true
LOGGER_FILE_ENABLED	Enable file logging	true
LOGGER_EMOJI_CONSOLE	Enable emojis for console output	false
LOGGER_EMOJI_FILE	Enable emojis for file output	false
LOGGER_EMOJIS	Custom emoji mapping (JSON format)	See below
LOGGER_ROTATION_WHEN	When to rotate (midnight, H, D, W0-W6)	midnight
LOGGER_ROTATION_INTERVAL	Rotation interval	1
LOGGER_BACKUP_COUNT	Number of backup files	30
LOGGER_ENCODING	File encoding	utf-8

Custom Emoji Mapping Example:

export LOGGER_EMOJIS='{"DEBUG":"🐛","INFO":"ℹ️","WARNING":"⚠️","ERROR":"❌","CRITICAL":"🔥"}'

🎯 Advanced Usage

Using LoggerFactory

from THCustomLogger import LoggerFactory
import logging

# Get the configuration instance
config = LoggerFactory.get_config()
print(config.as_dict)

# Create multiple loggers
logger1 = LoggerFactory.get_logger("module1")
logger2 = LoggerFactory.get_logger("module2")

# Reconfigure all loggers
LoggerFactory.configure(log_level=logging.DEBUG)

Colored Output

Console output is automatically colored based on log level:

• DEBUG: Green
• INFO: Light White
• WARNING: Light Yellow
• ERROR: Light Red
• CRITICAL: Bold Light Purple

from THCustomLogger import MultilineFormatter, ColoredMultilineFormatter
import logging

# Use custom formatters
handler = logging.StreamHandler()
handler.setFormatter(ColoredMultilineFormatter(
    "%(log_color)s%(levelname)-8s%(reset)s %(message)s",
    log_colors={
        'DEBUG': 'cyan',
        'INFO': 'green',
        'WARNING': 'yellow',
        'ERROR': 'red',
        'CRITICAL': 'red,bg_white',
    }
))

Multiline Formatting

Messages with multiple lines are automatically formatted with proper indentation:

2025-04-29 11:00:00.622 | Line: 165 logger_setup.main                 | INFO    : Commit hash: afba168c52d65a621139c3b3e072a1fd991b26bd
                                                                                  Latest tag:unknown

from THCustomLogger import get_logger

logger = get_logger(__name__)
logger.info("Message with custom break", extra={'msg_break': '*'})
logger.info("No indent message\nSecond line", extra={'no_indent': True})

2025-04-29 11:05:17.343 | Line: 185 logger_setup.<module>             | INFO    : Message with custom break
**********************************************************************************
2025-04-29 11:05:17.343 | Line: 186 logger_setup.<module>             | INFO    : No indent message
Second line

Thread Safety

The logger is thread-safe and can be used in multi-threaded applications:

python import threading def worker(): logger = LoggerFactory.get_logger(name) logger.info("Working in thread") threads = [threading.Thread(target=worker) for _ in range(3)] for thread in threads: thread.start()

Type Hints

from THCustomLogger import CustomLogger, get_logger


def my_function() -> None:
    logger: CustomLogger = get_logger(__name__)
    logger.info("Type-safe logging!")

    # Access CustomLogger-specific methods
    logger.configure_rate_limit(enabled=True, window_seconds=30)
    commit = logger.get_commit_hash()

🧪 Testing

The package includes comprehensive tests. Run them with:

# Install dev dependencies
pip install pytest pytest-cov

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=THCustomLogger --cov-report=html

📝 Examples

Example: Web Application Logging

from THCustomLogger import configure, get_logger
import logging

# Configure at application startup
configure(
    log_level=logging.INFO,
    log_dir="/var/log/myapp",
    file_name_prefix="webapp",
    console_enabled=True,
    file_enabled=True,
    rotation_when="midnight",
    backup_count=90
)

# Use in different modules
logger = get_logger(__name__)


def process_request(request_id: str):
    logger.info(f"Processing request: {request_id}")
    try:
        # ... process request ...
        logger.info(f"Request {request_id} completed successfully")
    except Exception as e:
        logger.exception(f"Error processing request {request_id}: {e}")

Example: Data Processing with Rate Limiting

from THCustomLogger import get_logger

logger = get_logger(__name__)
logger.configure_rate_limit(enabled=True, window_seconds=60, max_count=5)


def process_data(items):
    for item in items:
        try:
            # ... process item ...
            pass
        except ValueError as e:
            # This error won't spam logs if it occurs frequently
            logger.error(f"Invalid item: {e}")

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

📄 License

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

🔗 Links

• GitHub Repository: https://github.com/TabgoHotel/CustomLogger
• PyPI Package: https://pypi.org/project/THCustomLogger/
• **Issue Tracker **: https://github.com/TabgoHotel/CustomLogger/issues
• Changelog: CHANGELOG.md

👤 Author

Tyler Haunreiter

• Email: [e-mail]
• GitHub: @TabgoHotel

🙏 Acknowledgments

• Built with colorlog for colorized output
• Inspired by Python's built-in logging module

---

Made with ❤️ by Tyler Haunreiter