pylogkit-dev 0.2.0

A superstructure over structlog that simplifies the configuration and use of structured logging in Python.

pylogkit

Надстройка над structlog, упрощающая настройку и использование структурированного логирования в Python.

---

✨ Возможности

• Простое объявление логгеров проекта через синтаксис, похожий на dataclass
• Автоматическая настройка logging + structlog одним вызовом
• Удобный вывод в консоль для разработки или JSON-логи для продакшена (в зависимости от режима)
• Расширяемая цепочка процессоров (метки времени, информация о стеке, данные о вызывающем коде и т.д.)
• Поддержка нескольких именованных логгеров в одном месте
• Async/await поддержка — нативная работа в асинхронном коде через async_mode=True
• Файловые обработчики с возможностью ротации логов

---

📦 Установка

pip install pylogkit-dev

---

🚀 Быстрый старт

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

import structlog
from pylogkit import InitLoggers, LoggerReg

class Loggers(InitLoggers):
    app = LoggerReg(name="APP", level=LoggerReg.Level.INFO)
    db = LoggerReg(name="DATABASE", level=LoggerReg.Level.DEBUG)

# Инициализация системы логирования
loggers = Loggers(developer_mode=True)

# Использование логгера
logger = structlog.getLogger(Loggers.app.name)
logger.info("Приложение запущено", version="1.0.0")

---

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

import structlog
from pylogkit import InitLoggers, LoggerReg

class Loggers(InitLoggers):
    app = LoggerReg(name="APP", level=LoggerReg.Level.INFO)
    access = LoggerReg(name="ACCESS", level=LoggerReg.Level.INFO)

# developer_mode=False => вывод в формате JSON
loggers = Loggers(developer_mode=False)

logger = structlog.getLogger(Loggers.access.name)
logger.info("Запрос обработан", status=200, path="/login")

Пример вывода в формате JSON:

{
  "timestamp": "2025-09-21 03:09:46",
  "level": "info",
  "logger": "json_logging:logger:14",
  "_msg": "Запрос обработан",
  "status": 200,
  "path": "/login"
}

---

Несколько логгеров

import structlog
from pylogkit import InitLoggers, LoggerReg

class Loggers(InitLoggers):
    auth = LoggerReg(name="AUTH", level=LoggerReg.Level.DEBUG)
    router = LoggerReg(name="ROUTER", level=LoggerReg.Level.INFO)
    utils = LoggerReg(name="UTILS", level=LoggerReg.Level.DEBUG)

loggers = Loggers(developer_mode=True)

auth_logger = structlog.getLogger(Loggers.auth.name)
auth_logger.debug("Проверка токена", token="abc123")

router_logger = structlog.getLogger(Loggers.router.name)
router_logger.info("Новый запрос", path="/api/v1/resource")

---

Async logging

import asyncio
import structlog
from pylogkit import InitLoggers, LoggerReg

class Loggers(InitLoggers):
    app = LoggerReg(name="APP", level=LoggerReg.Level.INFO)

# async_mode=True => методы логгера становятся awaitable
loggers = Loggers(developer_mode=True, async_mode=True)

async def main():
    logger = structlog.getLogger(Loggers.app.name)
    await logger.info("Асинхронное приложение запущена", version="1.0.0")
    await logger.debug("Запрос к БД", query="SELECT * FROM users")

asyncio.run(main())

---

Файловое логирование

from pylogkit import InitLoggers, LoggerReg

class Loggers(InitLoggers):
    app = LoggerReg(name="APP", level=LoggerReg.Level.INFO)

# log_file => запись в файл вместо stderr
loggers = Loggers(developer_mode=False, log_file="app.log")

# С ротацией файлов
loggers = Loggers(
    developer_mode=False,
    log_file="app.log",
    max_bytes=10_000_000,  # 10 MB
    backup_count=3,
)

---

🔧 Как это работает

pylogkit предоставляет два основных класса:

• LoggerReg — объявляет отдельный логгер с именем и уровнем логирования
• InitLoggers — базовый класс, от которого вы наследуетесь, чтобы определить все логгеры проекта в одном месте; он автоматически инициализирует logging и structlog

При создании экземпляра вашего подкласса InitLoggers все зарегистрированные логгеры настраиваются и готовы к использованию через structlog.getLogger(name).

Режим разработки и продакшена

Режим	developer_mode=True	developer_mode=False
Вывод	Красивая консоль (через ConsoleRenderer)	JSON-строки (через JSONRenderer)
Применение	Локальная разработка, отладка	Продакшен, агрегация логов (ELK, Loki и т.д.)

Также можно принудительно включить режим разработки через переменную окружения MODE_DEV=1.

---

📂 Примеры

Больше примеров доступно в директории examples/:

• basic_usage.py — минимальная настройка
• json_logging.py — режим вывода в JSON
• multiple_loggers.py — работа с несколькими именованными логгерами
• async_logging.py — асинхронное логирование с InitLoggers
• async_quick.py — асинхронное логирование с get_logger()
• file_logging.py — запись логов в файл с ротацией

---

📜 Лицензия

MIT License — подробности в файле LICENSE.