fnclogger 1.0.0

Простой и мощный логгер для Python с цветным выводом

FancyLogger

Улучшенный логгер для Python приложений с поддержкой цветного вывода, JSON форматирования и гибкой конфигурацией.

🚀 Основные возможности

• ✅ Цветной вывод в консоль с поддержкой Rich (опционально)
• ✅ Несколько режимов работы: консоль, файл, или оба
• ✅ JSON логирование для структурированных данных
• ✅ Ротация файлов по размеру и времени
• ✅ Thread-safe операции
• ✅ Раздельные уровни для консоли и файла
• ✅ Контекстные данные в логах
• ✅ Простая конфигурация через словари
• ✅ Минимальные зависимости (Rich опционально)

📦 Установка

Базовая установка

pip install fancy-logger

С поддержкой Rich (рекомендуется)

pip install fancy-logger[rich]

Для разработки

pip install fancy-logger[dev]

🎯 Быстрый старт

Базовое использование

from fancy_logger import get_logger

# Создание логгера
logger = get_logger("my_app")

# Основные методы
logger.info("Приложение запущено")
logger.warning("Предупреждение")
logger.error("Произошла ошибка")

# Цветные методы
logger.success("Операция завершена успешно!")
logger.highlight("Важная информация")
logger.alert("Требуется внимание")
logger.fail("Критическая ошибка")

Конфигурация режимов

from fancy_logger import FancyLogger, LogMode, LogLevel

# Только в консоль
console_logger = FancyLogger(
    name="console_app",
    mode=LogMode.CONSOLE_ONLY,
    level=LogLevel.DEBUG
)

# Только в файл
file_logger = FancyLogger(
    name="file_app", 
    mode=LogMode.FILE_ONLY,
    log_dir="./logs"
)

# В консоль и файл с разными уровнями
mixed_logger = FancyLogger(
    name="mixed_app",
    mode=LogMode.BOTH,
    console_level=LogLevel.INFO,
    file_level=LogLevel.WARNING
)

JSON логирование

from fancy_logger import FancyLogger, OutputFormat

# JSON в файл, обычный текст в консоль
logger = FancyLogger(
    name="api_server",
    file_format=OutputFormat.JSON,
    console_format=OutputFormat.TEXT
)

# Логирование с контекстными данными
logger.info("Пользователь авторизован", extra={
    "user_id": 12345,
    "email": "[e-mail]", 
    "ip": "192.168.1.1",
    "action": "login"
})

Конфигурация из словаря

config = {
    'name': 'web_app',
    'mode': 'both',
    'level': 20,  # INFO
    'console_level': 20,  # INFO
    'file_level': 30,     # WARNING
    'log_dir': './logs',
    'file_format': 'json',
    'console_format': 'text',
    'use_rich': True,
    'max_file_size': 5 * 1024 * 1024,  # 5MB
    'backup_count': 3
}

logger = FancyLogger.configure_from_dict(config)

📋 Примеры использования

Веб-приложение

from fancy_logger import FancyLogger, LogMode, OutputFormat

# Настройка логгера для веб-приложения
app_logger = FancyLogger(
    name="webapp",
    mode=LogMode.BOTH,
    console_level=LogLevel.INFO,
    file_level=LogLevel.WARNING,
    file_format=OutputFormat.JSON,
    log_dir="./logs",
    max_file_size=10 * 1024 * 1024,  # 10MB
    backup_count=5
)

def handle_request(user_id, endpoint):
    app_logger.info("Обработка запроса", extra={
        "user_id": user_id,
        "endpoint": endpoint,
        "timestamp": datetime.now().isoformat()
    })
    
    try:
        # Обработка запроса
        result = process_request(endpoint)
        app_logger.success(f"Запрос обработан: {endpoint}")
        return result
    except Exception as e:
        app_logger.fail(f"Ошибка обработки: {e}", exc_info=True)
        raise

Микросервис с разными компонентами

# Основной логгер приложения
main_logger = get_logger("service")

# Специализированные логгеры
db_logger = FancyLogger("service.database", mode=LogMode.FILE_ONLY)
api_logger = FancyLogger("service.api", console_level=LogLevel.DEBUG)
auth_logger = FancyLogger("service.auth", file_format=OutputFormat.JSON)

# Использование
def authenticate_user(token):
    auth_logger.info("Проверка токена", extra={"token_hash": hash(token)})
    
    if not validate_token(token):
        auth_logger.alert("Недействительный токен")
        return False
        
    auth_logger.success("Пользователь авторизован")
    return True

def database_query(query):
    db_logger.debug(f"Выполнение запроса: {query}")
    
    try:
        result = execute_query(query)
        db_logger.info(f"Запрос выполнен, строк: {len(result)}")
        return result
    except Exception as e:
        db_logger.error(f"Ошибка БД: {e}", exc_info=True)
        raise

Обработка исключений

logger = get_logger("error_handler")

def safe_operation():
    try:
        risky_operation()
        logger.success("Операция выполнена успешно")
    except ValueError as e:
        logger.alert(f"Некорректные данные: {e}")
        return None
    except ConnectionError as e:
        logger.fail(f"Ошибка соединения: {e}", exc_info=True)
        raise
    except Exception as e:
        logger.critical(f"Неожиданная ошибка: {e}", exc_info=True)
        raise

🔧 API Reference

Основные классы

FancyLogger

Основной класс логгера.

Параметры конструктора:

• name: str - имя логгера
• mode: LogMode - режим работы (CONSOLE_ONLY, FILE_ONLY, BOTH)
• level: LogLevel - базовый уровень логирования
• console_level: LogLevel - уровень для консоли
• file_level: LogLevel - уровень для файла
• log_dir: str | Path - директория для логов
• file_format: OutputFormat - формат файловых логов
• console_format: OutputFormat - формат консольных логов
• use_rich: bool - использовать Rich для цветного вывода
• max_file_size: int - максимальный размер файла (байты)
• backup_count: int - количество backup файлов
• custom_format: str - кастомный формат сообщений

Методы логирования

# Стандартные методы
logger.debug(message, extra=None, **kwargs)
logger.info(message, extra=None, **kwargs)
logger.warning(message, extra=None, **kwargs)
logger.error(message, extra=None, exc_info=False, **kwargs)
logger.critical(message, extra=None, exc_info=True, **kwargs)

# Цветные методы
logger.success(message, extra=None, **kwargs)  # Зеленый с ✓
logger.highlight(message, extra=None, **kwargs)  # Синий с →
logger.alert(message, extra=None, **kwargs)    # Желтый с ⚠
logger.fail(message, extra=None, **kwargs)     # Красный с ✗

Enum классы

class LogLevel(Enum):
    DEBUG = logging.DEBUG
    INFO = logging.INFO
    WARNING = logging.WARNING
    ERROR = logging.ERROR
    CRITICAL = logging.CRITICAL

class LogMode(Enum):
    CONSOLE_ONLY = "console"
    FILE_ONLY = "file"
    BOTH = "both"

class OutputFormat(Enum):
    TEXT = "text"
    JSON = "json"

Вспомогательные функции

# Быстрое создание логгера
get_logger(name: str, **kwargs) -> FancyLogger

# Базовая настройка
setup_basic_logger(name: str, level: str) -> FancyLogger

🧪 Тестирование

# Запуск всех тестов
pytest

# С покрытием кода
pytest --cov=fancy_logger

# Только быстрые тесты
pytest -m "not slow"

🛣️ Roadmap

• Поддержка асинхронного логирования
• Интеграция с популярными фреймворками (FastAPI, Django)
• Отправка логов в внешние системы (Elasticsearch, Sentry)
• Веб-интерфейс для просмотра логов
• Метрики и мониторинг

🤝 Участие в разработке

1. Fork репозитория
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменения (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Создайте Pull Request

Требования к коду

• Код должен проходить black, flake8 и mypy
• Все новые функции должны быть покрыты тестами
• Документация должна быть обновлена

📝 Changelog

v1.0.0

• Первый релиз
• Базовая функциональность логирования
• Поддержка Rich и JSON форматирования
• Thread-safe операции
• Конфигурация через словари

📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности в файле LICENSE.

🙏 Благодарности

• Rich - за отличную библиотеку для цветного вывода
• Python Logging - за базовую функциональность логирования
• Сообщество Python за вдохновение и обратную связь

---

Создано с ❤️ для Python сообщества