exlog 0.1.0

A flexible logging system with colorized output and file rotation support.

ExLog

A lightweight, colorful, customizable Python logging utility with support for terminal output, file rotation, and asynchronous logging; built for the Ex Projects, and YOURs too!

Table of Contents

1. Overview
2. Installation
3. Usage Examples
4. Feature Demonstrations
5. Configuration
6. Available Colors
7. Contributing
8. License

---

Overview

ExLog is a flexible logging utility that supports both console and file-based logging with:

• Customizable log levels (debug, info, warning, error, critical).
• Colored output for better readability.
• File rotation by time (daily, hourly) and size.
• Asynchronous logging with minimal overhead.

---

Installation

Ensure that termcolor is installed for colored console output:

pip install termcolor

Alternatively, you can include it in your requirements.txt.

To clone the repository:

git clone https://github.com/onedavidwilliams/ExLog.git
cd ExLog

---

Minimum Python Version

ExLog requires Python 3.7 or higher. for asyncio.run() to work correctly

---

How It Works:

• When you instantiate ExLog, you can set the minimum log_level. Only messages with a numeric value greater than or equal to the set level will be printed.
• You can specify the log_level using a string (e.g., "debug", "info", etc.) or number (1, 2, etc.).

Usage Examples:

1. Log Level: info (1)

logger = ExLog(log_level="info")  # Same as log_level=1
logger.dprint("Info message", level="info")  # Printed
logger.dprint("Debug message", level=2)  # Not printed - Same as "debug"

2. Log Level: debug (2)

logger = ExLog(log_level="debug")  # Same as log_level=2
logger.dprint("Debug message", level="debug")  # Printed
logger.dprint("Info message", level="info")  # Not Printed

3. Log Level: warning (3)

logger = ExLog(log_level="warning")  # Same as log_level=3
logger.dprint("Warning message", level="warning")  # Printed
logger.dprint("Info message", level="info")  # Not Printed
logger.dprint("Debug message", level="debug")  # Not printed

4. Basic Console Logging

from ExLog import ExLog

logger = ExLog()  # Default log level: info, console-only
logger.dprint("Hello, World!", level="info")

Output:

[03:15:20 PM] [INFO] Hello, World!

---

5. Logging to File with Daily Rotation

logger = ExLog(log_dir="my_logs", rotation="daily")
logger.dprint("Logging to file and terminal.", level="debug")

• Logs are saved in the my_logs/ directory.
• New files are created daily.

---

6. Async Logging

import asyncio
from ExLog import ExLog

async def main():
    logger = ExLog(log_dir="my_logs", rotation="hourly")
    await logger.adprint("Async log message", level="info")

asyncio.run(main())

• Async-friendly logging for concurrent applications.

---

Feature Demonstrations

1. Size-Based Log File Rotation

logger = ExLog(log_dir="my_logs", max_file_size=1024 * 5)  # 5 KB max size
for i in range(100):
    logger.dprint(f"Message {i}", level="info")

• Automatically creates new log files when the size exceeds 5 KB.

---

2. Custom Color Formatting

logger = ExLog(custom_colors={
    "info": {"color": ExLog.color.magenta},
    "warning": {"color": ExLog.color.blue, "background_color": ExLog.bg_color.yellow}
})
logger.dprint("Custom color for info.", level="info")
logger.dprint("Custom color for warning.", level="warning")

---

3. Critical Log with Program Exit

def critical_exit_example(error=None):
    logger = ExLog()
    error = error if error else "No error specified"
    logger.dprint(f"Critical failure! Exiting program...\nError: {error}", level="critical")
    exit(1)

critical_exit_example("Test")

• Prints a critical log message and the error if one is passed and exits the program.

---

4. Different Log Levels in Loop

log_levels = ["debug", "info", "warning", "error", "critical"]
logger = ExLog(log_dir="my_logs")

for i, level in enumerate(log_levels):
    logger.dprint(f"This is a {level.upper()} message", level=level)

• Cycles through all log levels to demonstrate their output.

---

Configuration

Initialization Parameters

Parameter	Type	Default	Description
log_level	int	1	Minimum log level to display (1 for "info", 2 for "debug", etc.).
log_dir	str	None	Directory for log files. If None, logs only print to the console.
log_file_prefix	str	"log"	Prefix for log filenames.
rotation	str	"daily"	Log rotation type: "daily", "hourly", or "none".
max_file_size	int	None	Maximum log file size (in bytes) before rotating to a new file.
custom_colors	dict	None	Dictionary for custom foreground and background colors.

---

Available Colors

You can set colors using ExLog.color (foreground) and ExLog.bg_color (background):

Foreground Colors (ExLog.color)	Background Colors (ExLog.bg_color)
black	on_black
red	on_red
green	on_green
yellow	on_yellow
blue	on_blue
magenta	on_magenta
cyan	on_cyan
white	on_white
grey	on_grey

---

Contributing

1. Fork the repository.
2. Create a feature branch:

   git checkout -b my-feature-branch
   

3. Commit your changes:

   git commit -m "Added new feature"
   

4. Push your branch:

   git push origin my-feature-branch
   

5. Open a pull request.

---