🎨 SmartLogger

Beautiful, colorful logging for Python with zero configuration

Transform your boring Python logs into beautiful, colorful masterpieces!

✨ Why SmartLogger?

Transform Your Logs Instantly!

Just one line of code transforms boring logs into beautiful, colorful masterpieces!

Before SmartLogger:

2024-01-06 10:30:45 - myapp - DEBUG - Processing user data...
2024-01-06 10:30:45 - myapp - INFO - User authenticated successfully
2024-01-06 10:30:45 - myapp - WARNING - API rate limit approaching
2024-01-06 10:30:45 - myapp - ERROR - Database connection failed
2024-01-06 10:30:45 - myapp - CRITICAL - System shutting down

After SmartLogger:

import smartlogger.auto  # One line = Colorful logs! 🎨

Your logs instantly become beautiful and easy to read with distinctive colors for each level!

🚀 Features

🎨 Beautiful Colors

Each log level gets its distinctive color:

🔵 DEBUG - Blue (development info)
🟢 INFO - Green (general info)
🟡 WARNING - Yellow (potential issues)
🔴 ERROR - Red (actual errors)
🔥 CRITICAL - Bright Red + Bold (urgent!)

⚡ Zero Configuration

import logging
import smartlogger.auto  # ← Right after logging!

No setup, no configuration files, no complex initialization. Just remember the import order!

🖥️ Universal Compatibility

✅ Windows (CMD, PowerShell, Windows Terminal)
✅ macOS (Terminal, iTerm2)
✅ Linux (bash, zsh, fish)
✅ IDEs (VS Code, PyCharm, Jupyter)
✅ Python 3.8+

🛡️ Production Ready

🚀 Zero dependencies - No external packages required
⚡ Performance optimized - Minimal overhead
🔒 Safe - Won't break existing logging code
🧠 Smart detection - Auto-detects color support

📦 Installation

Choose your preferred method:

🏎️ Quick Install

pip install pysmartlogger

🔧 From Source

git clone https://github.com/DeepPythonist/smartlogger.git
cd smartlogger
pip install .

🚀 Quick Start

30-Second Setup

⚠️ IMPORTANT: Import Order Matters!
smartlogger.auto must be imported immediately after importing logging and before any logging configuration or usage.

# 1. Import logging first
import logging

# 2. Import SmartLogger IMMEDIATELY after logging (THIS IS CRITICAL!)
import smartlogger.auto

# 3. Now configure your logging (BasicConfig, handlers, etc.)
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# 4. Your logs are now colorful! 🎨
logger.debug("🔍 Debug: Investigating user behavior")
logger.info("✅ Info: User login successful")
logger.warning("⚠️ Warning: API rate limit at 80%")
logger.error("❌ Error: Payment processing failed")
logger.critical("🚨 Critical: Database connection lost!")

✅ Correct Import Order vs ❌ Wrong Import Order

✅ CORRECT

import logging
import smartlogger.auto  # ← Right after logging!

logging.basicConfig()
logger = logging.getLogger(__name__)
logger.info("✅ Colors work!")

❌ WRONG

import logging
logging.basicConfig()  # ← Configuration before SmartLogger
import smartlogger.auto  # ← Too late!

logger = logging.getLogger(__name__)
logger.info("❌ No colors...")

Advanced Usage

🎛️ Custom Configuration

import logging
from smartlogger.core.formatter import ColorFormatter
from smartlogger.core.handler import ColorHandler

# Create a custom logger with SmartLogger
logger = logging.getLogger('my_custom_app')
logger.setLevel(logging.DEBUG)

# Use SmartLogger's handler and formatter
handler = ColorHandler()
formatter = ColorFormatter(
    '%(asctime)s | %(name)s | %(levelname)s | %(message)s'
)
handler.setFormatter(formatter)
logger.addHandler(handler)

# Your beautiful custom logs!
logger.info("🎨 Custom formatting with colors!")

🏢 Enterprise Integration

# ⚠️ Remember: Import order is critical!
import logging
import smartlogger.auto  # ← Must be imported before any logging configuration!

# Now configure your existing enterprise logging setup
LOGGING_CONFIG = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'standard': {
            'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
        },
    },
    'handlers': {
        'default': {
            'level': 'INFO',
            'formatter': 'standard',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        '': {
            'handlers': ['default'],
            'level': 'INFO',
            'propagate': False
        }
    }
}

logging.config.dictConfig(LOGGING_CONFIG)

# SmartLogger automatically enhances ALL your existing loggers!
logger = logging.getLogger('enterprise.module')
logger.info("🏢 Enterprise logging is now colorful!")

🎨 Color Palette

Log Level	Color	Visual	Use Case	Example
🔵 DEBUG	Blue	`🔍`	Development & debugging	`"Processing user input: email@example.com"`
🟢 INFO	Green	`ℹ️`	General information	`"User authenticated successfully"`
🟡 WARNING	Yellow	`⚠️`	Potential issues	`"API rate limit approaching (80%)"`
🔴 ERROR	Red	`❌`	Actual errors	`"Failed to connect to database"`
🔥 CRITICAL	Bright Red + Bold	`🚨`	Urgent attention needed	`"System memory critically low!"`

🌟 Real-world Examples

🚀 Web Application

import logging
import smartlogger.auto  # ← Immediately after logging import!
from flask import Flask

app = Flask(__name__)
logger = logging.getLogger('webapp')

@app.route('/users/<user_id>')
def get_user(user_id):
    logger.info(f"🔍 Fetching user data for ID: {user_id}")
    
    try:
        user = database.get_user(user_id)
        logger.info(f"✅ User found: {user.email}")
        return user.to_json()
    except UserNotFound:
        logger.warning(f"⚠️ User {user_id} not found in database")
        return {"error": "User not found"}, 404
    except DatabaseError as e:
        logger.error(f"❌ Database error: {e}")
        return {"error": "Internal server error"}, 500

🤖 Machine Learning Pipeline

import logging
import smartlogger.auto  # ← Import right after logging!

logger = logging.getLogger('ml_pipeline')

def train_model(dataset_path):
    logger.info(f"🚀 Starting model training with dataset: {dataset_path}")
    
    try:
        data = load_dataset(dataset_path)
        logger.info(f"📊 Dataset loaded: {len(data)} samples")
        
        if len(data) < 1000:
            logger.warning(f"⚠️ Small dataset detected ({len(data)} samples)")
        
        model = train_neural_network(data)
        accuracy = evaluate_model(model)
        
        if accuracy > 0.95:
            logger.info(f"🎯 Excellent model performance: {accuracy:.2%}")
        elif accuracy > 0.80:
            logger.warning(f"📈 Good model performance: {accuracy:.2%}")
        else:
            logger.error(f"📉 Poor model performance: {accuracy:.2%}")
            
    except Exception as e:
        logger.critical(f"🚨 Model training failed: {e}")
        raise

📊 Data Processing

import logging
import smartlogger.auto  # ← Critical: Import immediately after logging!
import pandas as pd

logger = logging.getLogger('data_processor')

def process_customer_data(file_path):
    logger.info(f"📁 Processing customer data from: {file_path}")
    
    try:
        df = pd.read_csv(file_path)
        logger.debug(f"🔍 Raw data shape: {df.shape}")
        
        # Data validation
        missing_data = df.isnull().sum().sum()
        if missing_data > 0:
            logger.warning(f"⚠️ Found {missing_data} missing values")
        
        # Process data
        cleaned_df = clean_data(df)
        logger.info(f"✅ Data cleaning completed: {cleaned_df.shape}")
        
        # Save results
        cleaned_df.to_csv('processed_data.csv')
        logger.info("💾 Processed data saved successfully")
        
    except FileNotFoundError:
        logger.error(f"❌ Data file not found: {file_path}")
    except pd.errors.EmptyDataError:
        logger.critical(f"🚨 Data file is empty: {file_path}")

🖥️ Compatibility Matrix

Tested and Verified ✅

🐍 Python Versions

✅ Python 3.8
✅ Python 3.9
✅ Python 3.10
✅ Python 3.11
✅ Python 3.12

💻 Operating Systems

✅ Windows 10/11
✅ macOS (Intel & Apple Silicon)
✅ Linux (Ubuntu, CentOS, Alpine)
✅ Docker containers
✅ Cloud environments

🔧 Development Tools

✅ VS Code (+ extensions)
✅ PyCharm (Pro & Community)
✅ Jupyter Notebooks
✅ Google Colab
✅ Terminal/CMD/PowerShell

🌐 Terminal Support

Terminal	Windows	macOS	Linux	Notes
Windows Terminal	✅	-	-	Full color support
PowerShell	✅	✅	✅	Core & 7+
Command Prompt	✅	-	-	Windows 10+
iTerm2	-	✅	-	Recommended for macOS
Terminal.app	-	✅	-	Built-in macOS terminal
bash/zsh/fish	✅	✅	✅	Universal support

🔬 How It Works

The Magic Behind SmartLogger ✨

import logging
import smartlogger.auto  # ← This triggers the magic! 🪄
# IMPORTANT: Must be imported right after logging and before any configuration!

🔧 Technical Implementation

SmartLogger uses intelligent monkey-patching to enhance Python's logging module:

# 1. 🕵️ Environment Detection
def detect_color_support():
    """Detects if the current environment supports ANSI colors"""
    # Checks terminal type, environment variables, IDE support
    return is_terminal_supports_color()

# 2. 🎨 Smart Color Application
def apply_colors(log_record):
    """Applies appropriate colors based on log level"""
    if not supports_colors:
        return original_format(log_record)
    
    color = get_color_for_level(log_record.levelname)
    return f"{color}{log_record.levelname}{RESET}"

# 3. 🔄 Safe Monkey-Patching
def patch_logging():
    """Safely patches logging without breaking existing code"""
    original_formatter = logging.Formatter
    logging.Formatter = EnhancedColorFormatter
    # Maintains 100% backward compatibility!

Key Features:

🔍 Smart Detection: Automatically detects color support
🛡️ Safe Patching: Won't break existing logging configurations
⚡ Performance: Minimal overhead (~0.1ms per log message)
🔄 Reversible: Can be disabled at runtime if needed

🎯 Zero Dependencies Philosophy

SmartLogger is built with zero external dependencies by design:

📦 Pure Python: Only uses standard library modules
🚀 Fast Installation: No compilation or external packages
🔒 Secure: No third-party code vulnerabilities
📱 Lightweight: Total package size < 50KB

# Compare installation times:
pip install some-logging-lib    # Downloads 20+ dependencies 😴
pip install pysmartlogger      # Just SmartLogger! ⚡

🤝 Contributing

We love contributions! SmartLogger is an open-source project and we welcome contributions of all kinds.

🚀 How to Contribute

Quick Start for Contributors

🍴 Fork the repository

git clone https://github.com/DeepPythonist/smartlogger.git
cd smartlogger

🌟 Create a feature branch

git checkout -b feature/amazing-new-feature

🧪 Run tests

python -m pytest tests/ -v
python demo_smartlogger.py

📝 Make your changes and commit

git add .
git commit -m "✨ Add amazing new feature"

🚀 Push and create PR

git push origin feature/amazing-new-feature
# Then create a Pull Request on GitHub!

🎯 Areas We Need Help With

🌍 Cross-platform testing (especially Windows variations)
🎨 New color schemes and themes
📚 Documentation improvements
🐛 Bug reports and fixes
💡 Feature suggestions

📋 Development Guidelines

✅ Code style: We use black for formatting
🧪 Testing: Add tests for new features
📝 Documentation: Update README for new features
🔍 Type hints: Use type annotations where possible

⚠️ Common Mistakes

🚫 Avoid These Import Order Mistakes!

❌ MISTAKE 1: Late Import

import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Too late! SmartLogger can't patch existing config
import smartlogger.auto

Result: No colors, plain text logging

❌ MISTAKE 2: Missing logging import

# Missing: import logging
import smartlogger.auto

logging.basicConfig(level=logging.INFO)  
logger = logging.getLogger(__name__)

Result: Import error or unexpected behavior

❌ MISTAKE 3: Config Before Import

import logging

# Configuration happens first
logging.getLogger().setLevel(logging.DEBUG)
logging.getLogger().addHandler(handler)

import smartlogger.auto  # Too late!

Result: SmartLogger can't enhance existing loggers

✅ CORRECT WAY

import logging
import smartlogger.auto  # Perfect timing!

# All configuration after SmartLogger
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
logger.info("🎨 Beautiful colors!")

Result: Beautiful, colorful logs!

❓ FAQ

Q: Why is import order important?

A: SmartLogger uses monkey-patching to enhance Python's logging module. It must be imported immediately after logging and before any logging configuration to work properly:

# ✅ CORRECT ORDER
import logging
import smartlogger.auto  # ← Must be here!
logging.basicConfig()   # ← Configuration after SmartLogger

# ❌ WRONG ORDER  
import logging
logging.basicConfig()   # ← Configuration before SmartLogger
import smartlogger.auto  # ← Too late! Colors won't work

Q: Does SmartLogger affect performance?

A: Minimal impact! SmartLogger adds ~0.1ms overhead per log message. Color detection is cached, so there's virtually no performance penalty after initialization.

Q: Can I use SmartLogger in production?

A: Absolutely! SmartLogger is designed for production use:

🛡️ Safe: Won't break existing logging
🚀 Zero dependencies: No external vulnerabilities
⚡ Performance optimized: Minimal overhead
🔄 Reversible: Can be disabled if needed

Q: What if my terminal doesn't support colors?

A: SmartLogger automatically detects color support and gracefully falls back to plain text in non-color environments. No configuration needed!

Q: Can I customize the colors?

A: Yes! You can customize colors using the advanced configuration:

from smartlogger.config.colors import Colors

# Customize colors
Colors.INFO = Colors.CYAN  # Make INFO messages cyan
Colors.DEBUG = Colors.MAGENTA  # Make DEBUG messages magenta

Q: Does it work with existing logging configurations?

A: Yes! SmartLogger is designed to work seamlessly with existing logging setups. Just add import smartlogger.auto and your existing loggers become colorful.

📄 License

MIT License - see LICENSE file for details.

Feel free to use SmartLogger in your projects, both personal and commercial!

👨‍💻 Author

Mohammad Rasol Esfandiari

🐍 Python Developer & Open Source Enthusiast

🌟 If SmartLogger made your logging beautiful, please give it a star!

Made with ❤️ for the Python community

Transform your logs from boring to beautiful in seconds! 🎨

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
docs		docs
examples		examples
smartlogger		smartlogger
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
demo_smartlogger.py		demo_smartlogger.py
image.png		image.png
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py

License

DeepPythonist/smartlogger

Folders and files

Latest commit

History

Repository files navigation