fnclogger 1.0.3

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

FncLogger

Простой и мощный логгер для Python с красивым цветным выводом и гибкой конфигурацией.

🚀 Установка

pip install fnclogger

Rich входит в комплект! Никаких дополнительных зависимостей - сразу получаете красивый цветной вывод. ✨

📋 Быстрый старт

from fnclogger import get_logger

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

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

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

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

⚙️ Конфигурация

Режимы работы

from fnclogger import FncLogger, LogMode

# Только в консоль (с красивым форматированием)
console_logger = FncLogger(
    name="console_app",
    mode=LogMode.CONSOLE_ONLY
)

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

# В консоль и файл одновременно (по умолчанию)
both_logger = FncLogger(
    name="full_app",
    mode=LogMode.BOTH
)

Уровни логирования

from fnclogger import LogLevel

# Разные уровни для консоли и файла
mixed_logger = FncLogger(
    name="mixed_app",
    console_level=LogLevel.INFO,    # В консоль только INFO и выше
    file_level=LogLevel.WARNING     # В файл только WARNING и выше
)

JSON форматирование

from fnclogger import OutputFormat

# JSON в файле, красивый текст в консоли
json_logger = FncLogger(
    name="api_server",
    file_format=OutputFormat.JSON,
    console_format=OutputFormat.TEXT
)

json_logger.info("API запрос", extra={
    "method": "GET",
    "url": "/api/users",
    "status": 200,
    "response_time": 0.15
})

Отключение Rich (если нужно)

# Если по какой-то причине нужно отключить Rich
plain_logger = FncLogger(
    name="plain_app",
    use_rich=False  # Использует простые ANSI цвета
)

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

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

from fnclogger import FncLogger, LogMode, OutputFormat, LogLevel

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

def process_request(user_id, endpoint):
    app_logger.info("Начало обработки запроса", extra={
        "user_id": user_id,
        "endpoint": endpoint
    })
    
    try:
        # Ваша бизнес-логика здесь
        result = handle_business_logic(endpoint)
        app_logger.success(f"Запрос успешно обработан: {endpoint}")
        return result
    except Exception as e:
        app_logger.fail(f"Ошибка обработки запроса: {e}", exc_info=True)
        raise

Обработка ошибок

logger = get_logger("error_handler")

def safe_operation():
    try:
        # Потенциально опасная операция
        result = risky_function()
        logger.success("Операция выполнена успешно")
        return result
    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

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

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

# Специализированные логгеры для разных компонентов
db_logger = FncLogger("service.database", mode=LogMode.FILE_ONLY)
api_logger = FncLogger("service.api", console_level=LogLevel.DEBUG)

def database_operation(query):
    db_logger.debug(f"Выполнение SQL: {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

def api_endpoint(request):
    api_logger.info("Получен API запрос", extra={
        "method": request.method,
        "path": request.path,
        "user_agent": request.headers.get("User-Agent")
    })
    # Обработка запроса...

🔧 API Reference

Основные классы и функции

# Быстрое создание логгера (с Rich по умолчанию)
get_logger(name: str, **kwargs) -> FncLogger

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

# Создание настраиваемого логгера
FncLogger(
    name: str,
    mode: LogMode = LogMode.BOTH,
    level: LogLevel = LogLevel.INFO,
    console_level: Optional[LogLevel] = None,
    file_level: Optional[LogLevel] = None,
    log_dir: Optional[str] = None,
    file_format: OutputFormat = OutputFormat.TEXT,
    console_format: OutputFormat = OutputFormat.TEXT,
    use_rich: bool = True,  # Rich включен по умолчанию
    max_file_size: int = 10 * 1024 * 1024,  # 10MB
    backup_count: int = 5
)

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

# Стандартные методы
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"

🎨 Особенности

✨ Rich из коробки

• Красивый цветной вывод без дополнительных установок
• Форматированные трейсбеки для ошибок
• Стильные иконки и цвета для разных типов сообщений

📁 Автоматическая ротация файлов

• Файлы логов автоматически ротируются при достижении максимального размера
• По умолчанию: 10MB на файл, 5 backup файлов

🔒 Thread-Safe

• Безопасное использование в многопоточных приложениях
• Синглтон паттерн с блокировками

🔧 Гибкое форматирование

• Разные форматы для консоли и файла
• JSON для структурированных логов
• Поддержка дополнительных данных через extra

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

После установки можете протестировать:

from fnclogger import get_logger

logger = get_logger("test")
logger.success("FncLogger установлен и работает!")
logger.highlight("Rich включен по умолчанию - красиво!")
logger.info("Все системы в норме", extra={"status": "ok"})

Или запустите пример:

# Если клонировали репозиторий
python examples/basic_example.py

📁 Структура логов

По умолчанию логи сохраняются в папку logs/ в текущей директории:

logs/
├── my_app.log        # Основные логи
├── my_app.log.1      # Backup 1
├── my_app.log.2      # Backup 2
└── ...

Формат логов в файле:

[2025-05-30 14:30:25] [INFO    ] [my_app] Приложение запущено
[2025-05-30 14:30:26] [WARNING ] [my_app] ⚠ Требуется внимание
[2025-05-30 14:30:27] [ERROR   ] [my_app] ✗ Произошла ошибка

JSON формат:

{
  "timestamp": "2025-05-30T14:30:25.123456",
  "level": "INFO",
  "logger": "my_app",
  "message": "Пользователь вошел",
  "module": "main",
  "function": "login",
  "line": 42,
  "user_id": 123,
  "action": "login"
}

🚀 Что нового в v1.0.1

• ✅ Rich включен по умолчанию - красивый вывод сразу после установки
• ✅ Упрощенная установка - одна команда pip install fnclogger
• ✅ Улучшенная документация - больше примеров и пояснений

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

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

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

pip install fnclogger[dev]

📝 Changelog

v1.0.1

• Rich теперь основная зависимость (устанавливается автоматически)
• Упрощена установка и использование
• Обновлена документация

v1.0.0

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

📄 Лицензия

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

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

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

---

Красивое логирование из коробки 🪵✨🎨