pylogkit 0.1.0__py3-none-any.whl

pylogkit/__init__.py

@@ -0,0 +1,68 @@
+"""pylogkit — structured logging with Slack integration, rate limiting, and deduplication."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pylogkit")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+import logging
+
+from .config import setup_logging
+from .filters import ContextFilter, ContextVarsFilter, DeduplicationFilter, RateLimitFilter
+from .formatters import ColoredFormatter, JsonFormatter
+
+__all__ = [
+    "setup_logging",
+    "get_logger",
+    "JsonFormatter",
+    "ColoredFormatter",
+    "ContextFilter",
+    "ContextVarsFilter",
+    "RateLimitFilter",
+    "DeduplicationFilter",
+]
+
+# Library best practice: NullHandler so library consumers don't get warnings
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def get_logger(name: str, **context) -> logging.Logger:
+    """Get a logger with optional context fields.
+
+    Args:
+        name: Logger name (typically ``__name__``).
+        **context: Static fields added to every record from this logger.
+
+    If called again with the same logger name, the context is updated
+    (merged with existing fields).
+
+    Returns:
+        Configured ``logging.Logger`` instance.
+
+    Example::
+
+        from pylogkit import get_logger
+
+        logger = get_logger(__name__, pipeline="laba_czech")
+        logger.info("Deal processed", extra={"deal_id": "123"})
+    """
+    log = logging.getLogger(name)
+    if context:
+        # Find existing ContextFilter or create a new one
+        for f in log.filters:
+            if isinstance(f, ContextFilter):
+                f.update(**context)
+                return log
+        log.addFilter(ContextFilter(**context))
+    return log
+
+
+# Lazy import — only loaded when explicitly requested
+def __getattr__(name: str):
+    if name == "SlackHandler":
+        from .handlers import SlackHandler
+
+        return SlackHandler
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pylogkit/_constants.py

@@ -0,0 +1,31 @@
+"""Shared constants for pylogkit."""
+
+# Standard logging record attributes to exclude when collecting extra fields.
+# Used by formatters and handlers to identify user-supplied fields.
+BUILTIN_RECORD_ATTRS: frozenset[str] = frozenset(
+    {
+        "args",
+        "asctime",
+        "created",
+        "exc_info",
+        "exc_text",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "message",
+        "module",
+        "msecs",
+        "msg",
+        "name",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "taskName",
+        "thread",
+        "threadName",
+    }
+)

pylogkit/config.py

@@ -0,0 +1,156 @@
+"""One-call logging setup for applications."""
+
+import contextvars
+import logging
+import sys
+
+
+def setup_logging(
+    level: str = "INFO",
+    service_name: str | None = None,
+    json_format: bool | None = None,
+    slack_token: str | None = None,
+    slack_channel: str | None = None,
+    slack_webhook_url: str | None = None,
+    slack_level: str = "ERROR",
+    slack_rate_limit: int = 1,
+    slack_rate_period: float = 60.0,
+    slack_dedupe_window: float = 300.0,
+    extra_context: dict[str, str] | None = None,
+    loggers: dict[str, str] | None = None,
+    ctx_var: contextvars.ContextVar | None = None,
+) -> None:
+    """Configure logging for the application in one call.
+
+    Args:
+        level: Root log level (default: INFO).
+        service_name: Service identifier added to every log record.
+        json_format: Force JSON (True) or colored (False) output.
+            If None, auto-detects: JSON when not a TTY, colored otherwise.
+        slack_token: Slack Bot token for error notifications.
+        slack_channel: Slack channel for error notifications.
+        slack_webhook_url: Slack incoming webhook URL (alternative to token).
+        slack_level: Minimum level for Slack notifications (default: ERROR).
+        slack_rate_limit: Max Slack messages per rate_period (default: 1).
+        slack_rate_period: Rate limit window in seconds (default: 60).
+        slack_dedupe_window: Deduplication window in seconds (default: 300).
+        extra_context: Static fields added to every log record.
+        loggers: Per-logger level overrides, e.g. ``{"httpx": "WARNING"}``.
+        ctx_var: A ``ContextVar[dict]`` for request-scoped fields.
+            If provided, a ``ContextVarsFilter`` is added to all handlers.
+
+    Example::
+
+        from pylogkit import setup_logging
+
+        setup_logging(
+            level="INFO",
+            service_name="my-api",
+            slack_token=os.environ.get("SLACK_BOT_TOKEN"),
+            slack_channel="#errors",
+            loggers={"httpx": "WARNING", "sqlalchemy": "WARNING"},
+        )
+    """
+    from .filters import ContextFilter, ContextVarsFilter
+    from .formatters import ColoredFormatter, JsonFormatter
+
+    root = logging.getLogger()
+
+    # Prevent duplicate setup
+    if any(getattr(h, "_pylogkit", False) for h in root.handlers):
+        return
+
+    resolved_level = getattr(logging, level.upper(), logging.INFO)
+    root.setLevel(resolved_level)
+
+    # ── Console handler ──────────────────────────────────
+    use_json = json_format if json_format is not None else not sys.stdout.isatty()
+
+    console = logging.StreamHandler(sys.stdout)
+    console.setLevel(resolved_level)
+    console._pylogkit = True  # type: ignore[attr-defined]
+
+    if use_json:
+        console.setFormatter(JsonFormatter())
+    else:
+        console.setFormatter(ColoredFormatter())
+
+    # Add context filter (static fields)
+    context = {"service": service_name} if service_name else {}
+    if extra_context:
+        context.update(extra_context)
+    if context:
+        console.addFilter(ContextFilter(**context))
+
+    # Add contextvars filter (request-scoped fields)
+    if ctx_var is not None:
+        console.addFilter(ContextVarsFilter(ctx_var))
+
+    root.addHandler(console)
+
+    # ── Slack handler ────────────────────────────────────
+    if slack_token or slack_webhook_url:
+        _setup_slack_handler(
+            token=slack_token,
+            channel=slack_channel,
+            webhook_url=slack_webhook_url,
+            level=slack_level,
+            rate_limit=slack_rate_limit,
+            rate_period=slack_rate_period,
+            dedupe_window=slack_dedupe_window,
+            context=context,
+            ctx_var=ctx_var,
+            service_name=service_name,
+        )
+
+    # ── Per-logger levels ────────────────────────────────
+    if loggers:
+        for name, lvl in loggers.items():
+            logging.getLogger(name).setLevel(getattr(logging, lvl.upper(), logging.INFO))
+
+
+def _setup_slack_handler(
+    token: str | None,
+    channel: str | None,
+    webhook_url: str | None,
+    level: str,
+    rate_limit: int,
+    rate_period: float,
+    dedupe_window: float,
+    context: dict[str, str],
+    ctx_var: contextvars.ContextVar | None = None,
+    service_name: str | None = None,
+) -> None:
+    """Set up Slack handler with rate limiting and deduplication."""
+    from .filters import ContextFilter, ContextVarsFilter, DeduplicationFilter, RateLimitFilter
+    from .handlers import SlackHandler
+
+    try:
+        handler = SlackHandler(
+            token=token,
+            channel=channel,
+            webhook_url=webhook_url,
+            level=getattr(logging, level.upper(), logging.ERROR),
+            service_name=service_name,
+        )
+        handler._pylogkit = True  # type: ignore[attr-defined]
+
+        # Rate limit: prevent Slack spam
+        handler.addFilter(RateLimitFilter(rate=rate_limit, period=rate_period))
+
+        # Deduplication: suppress identical errors
+        if dedupe_window > 0:
+            handler.addFilter(DeduplicationFilter(window=dedupe_window))
+
+        # Context
+        if context:
+            handler.addFilter(ContextFilter(**context))
+
+        # Contextvars
+        if ctx_var is not None:
+            handler.addFilter(ContextVarsFilter(ctx_var))
+
+        logging.getLogger().addHandler(handler)
+
+    except Exception as e:
+        print(f"[pylogkit] Failed to initialize SlackHandler: {e}", file=sys.stderr)

pylogkit/filters.py

@@ -0,0 +1,207 @@
+"""Log filters: context injection, rate limiting, deduplication, and contextvars."""
+
+import contextvars
+import logging
+import threading
+import time
+from typing import Any
+
+
+class ContextFilter(logging.Filter):
+    """Injects static context fields into every log record.
+
+    Args:
+        **context: Key-value pairs to add to each record.
+
+    Example::
+
+        handler.addFilter(ContextFilter(service="my-api", env="production"))
+        # Every record will have record.service and record.env
+    """
+
+    def __init__(self, **context: Any):
+        super().__init__()
+        self._context = context
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        for key, value in self._context.items():
+            if not hasattr(record, key):
+                setattr(record, key, value)
+        return True
+
+    def update(self, **context: Any) -> None:
+        """Update or add context fields."""
+        self._context.update(context)
+
+
+class ContextVarsFilter(logging.Filter):
+    """Injects context from ``contextvars.ContextVar`` into log records.
+
+    Useful for request-scoped context (request_id, user_id, etc.)
+    without passing ``extra={}`` to every log call.
+
+    Args:
+        ctx_var: A ``ContextVar`` holding a dict of fields to inject.
+
+    Example::
+
+        import contextvars
+        from pylogkit import ContextVarsFilter
+
+        log_context: contextvars.ContextVar[dict] = contextvars.ContextVar(
+            "log_context", default={}
+        )
+
+        # Attach to handler or logger
+        handler.addFilter(ContextVarsFilter(log_context))
+
+        # In request handler:
+        log_context.set({"request_id": "abc-123", "user_id": "42"})
+        logger.info("Processing request")  # includes request_id and user_id
+    """
+
+    def __init__(self, ctx_var: contextvars.ContextVar):
+        super().__init__()
+        self._ctx_var = ctx_var
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        ctx = self._ctx_var.get(None)
+        if ctx is not None:
+            for key, value in ctx.items():
+                if not hasattr(record, key):
+                    setattr(record, key, value)
+        return True
+
+
+class RateLimitFilter(logging.Filter):
+    """Limits how often the same log message can pass through.
+
+    Uses a token bucket per unique message. Each unique message is identified
+    by its ``msg`` template (before formatting) + logger name + level.
+
+    Args:
+        rate: Maximum messages per ``period`` seconds for each unique message.
+        period: Time window in seconds (default: 60).
+
+    Example::
+
+        handler.addFilter(RateLimitFilter(rate=1, period=60))
+        # Each unique message passes at most once per minute.
+    """
+
+    _CLEANUP_EVERY = 100  # prune stale keys every N calls
+
+    def __init__(self, rate: int = 1, period: float = 60.0):
+        super().__init__()
+        self.rate = rate
+        self.period = period
+        self._buckets: dict[str, list] = {}  # key -> [timestamps]
+        self._lock = threading.Lock()
+        self._call_count = 0
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        key = f"{record.name}:{record.levelno}:{record.msg}"
+        now = time.monotonic()
+
+        with self._lock:
+            self._call_count += 1
+            if self._call_count % self._CLEANUP_EVERY == 0:
+                self._prune(now)
+
+            timestamps = self._buckets.get(key)
+            if timestamps is None:
+                self._buckets[key] = [now]
+                return True
+
+            # Remove expired timestamps
+            cutoff = now - self.period
+            timestamps[:] = [t for t in timestamps if t > cutoff]
+
+            if len(timestamps) >= self.rate:
+                return False
+
+            timestamps.append(now)
+            return True
+
+    def _prune(self, now: float) -> None:
+        """Remove keys with only expired timestamps."""
+        cutoff = now - self.period
+        stale = [k for k, ts in self._buckets.items() if all(t <= cutoff for t in ts)]
+        for k in stale:
+            del self._buckets[k]
+
+
+class DeduplicationFilter(logging.Filter):
+    """Suppresses duplicate log messages within a time window.
+
+    Two messages are considered duplicates if they have the same:
+    - logger name
+    - log level
+    - message template (``record.msg``, before formatting)
+
+    On suppression, counts occurrences. When the window expires,
+    the next message passes through with the suppressed count
+    added as ``record._suppressed_count`` (does not mutate ``record.msg``).
+
+    Args:
+        window: Deduplication window in seconds (default: 300 = 5 min).
+
+    Example::
+
+        handler.addFilter(DeduplicationFilter(window=300))
+    """
+
+    _CLEANUP_EVERY = 100  # prune stale keys every N calls
+
+    def __init__(self, window: float = 300.0):
+        super().__init__()
+        self.window = window
+        self._seen: dict[str, _DedupeEntry] = {}
+        self._lock = threading.Lock()
+        self._call_count = 0
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        key = self._make_key(record)
+        now = time.monotonic()
+
+        with self._lock:
+            self._call_count += 1
+            if self._call_count % self._CLEANUP_EVERY == 0:
+                self._prune(now)
+
+            entry = self._seen.get(key)
+
+            if entry is None:
+                self._seen[key] = _DedupeEntry(first_seen=now, count=1)
+                return True
+
+            # Window expired — let it through, reset
+            if now - entry.first_seen >= self.window:
+                suppressed = entry.count - 1
+                self._seen[key] = _DedupeEntry(first_seen=now, count=1)
+                if suppressed > 0:
+                    record._suppressed_count = suppressed  # type: ignore[attr-defined]
+                return True
+
+            # Within window — suppress
+            entry.count += 1
+            return False
+
+    def _prune(self, now: float) -> None:
+        """Remove entries with expired windows."""
+        stale = [k for k, e in self._seen.items() if now - e.first_seen >= self.window]
+        for k in stale:
+            del self._seen[k]
+
+    @staticmethod
+    def _make_key(record: logging.LogRecord) -> str:
+        """Create a deduplication key from the record."""
+        return f"{record.name}:{record.levelno}:{record.msg}"
+
+
+class _DedupeEntry:
+    __slots__ = ("first_seen", "count")
+
+    def __init__(self, first_seen: float, count: int):
+        self.first_seen = first_seen
+        self.count = count

pylogkit/formatters.py

@@ -0,0 +1,125 @@
+"""Log formatters: JSON for production, colored for development."""
+
+import contextlib
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from pythonjsonlogger.json import JsonFormatter as BaseJsonFormatter
+
+from ._constants import BUILTIN_RECORD_ATTRS
+
+
+class JsonFormatter(BaseJsonFormatter):
+    """JSON formatter with clean output for production.
+
+    Produces structured JSON with:
+    - timestamp (ISO 8601 UTC)
+    - level, logger, message
+    - All extra fields passed via ``extra={}``
+    - Exception traceback (if present)
+
+    Strips verbose internal fields for cleaner output.
+    """
+
+    def add_fields(
+        self,
+        log_record: dict[str, Any],
+        record: logging.LogRecord,
+        message_dict: dict[str, Any],
+    ) -> None:
+        super().add_fields(log_record, record, message_dict)
+
+        log_record["timestamp"] = datetime.fromtimestamp(record.created, tz=UTC).isoformat()
+        log_record["level"] = record.levelname
+        log_record["logger"] = record.name
+
+        # Remove verbose internal fields
+        for key in ("levelname", "funcName", "lineno", "pathname", "exc_text", "taskName"):
+            log_record.pop(key, None)
+
+        # Include formatted traceback
+        if record.exc_info and not log_record.get("traceback"):
+            log_record["traceback"] = self.formatException(record.exc_info)
+
+        # Include suppressed duplicate count from DeduplicationFilter
+        suppressed = getattr(record, "_suppressed_count", 0)
+        if suppressed:
+            log_record["suppressed_duplicates"] = suppressed
+
+
+class ColoredFormatter(logging.Formatter):
+    """Colored formatter for development with extras display.
+
+    Falls back to plain text if ``colorlog`` is not installed.
+    Appends extra fields as ``[key=value ...]`` to the message.
+    """
+
+    _MAX_EXTRA_VALUE_LEN = 50
+
+    def __init__(
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        use_color: bool = True,
+    ):
+        self._use_color = use_color
+        self._inner: logging.Formatter
+
+        default_fmt = "%(asctime)s %(levelname)-8s %(name)s — %(message)s"
+
+        if use_color:
+            try:
+                import colorlog
+
+                self._inner = colorlog.ColoredFormatter(
+                    f"%(log_color)s{default_fmt}%(reset)s",
+                    datefmt=datefmt,
+                    log_colors={
+                        "DEBUG": "cyan",
+                        "INFO": "green",
+                        "WARNING": "yellow",
+                        "ERROR": "red",
+                        "CRITICAL": "red,bg_white",
+                    },
+                )
+            except ImportError:
+                self._use_color = False
+                self._inner = logging.Formatter(fmt or default_fmt, datefmt=datefmt)
+        else:
+            self._inner = logging.Formatter(fmt or default_fmt, datefmt=datefmt)
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Work on a copy to avoid mutating the original record
+        # (important when multiple handlers process the same record)
+        record = logging.makeLogRecord(record.__dict__)
+
+        # Collect extra fields
+        extras = {
+            k: v
+            for k, v in record.__dict__.items()
+            if k not in BUILTIN_RECORD_ATTRS and not k.startswith("_")
+        }
+
+        # Format the message first (resolves % args), then append extras
+        # This prevents breakage when extra values contain % characters
+        if record.args:
+            with contextlib.suppress(TypeError, ValueError):
+                record.msg = record.msg % record.args
+            record.args = None
+
+        # Append suppressed duplicate count from DeduplicationFilter
+        suppressed = getattr(record, "_suppressed_count", 0)
+        if suppressed:
+            record.msg = f"{record.msg} (suppressed {suppressed} duplicates)"
+
+        if extras:
+            parts = []
+            for k, v in extras.items():
+                s = str(v)
+                if len(s) > self._MAX_EXTRA_VALUE_LEN:
+                    s = s[: self._MAX_EXTRA_VALUE_LEN] + "…"
+                parts.append(f"{k}={s}")
+            record.msg = f"{record.msg}  [{' '.join(parts)}]"
+
+        return self._inner.format(record)

pylogkit/handlers.py

@@ -0,0 +1,228 @@
+"""Slack log handler with async dispatch and rate limiting."""
+
+import atexit
+import contextlib
+import logging
+import queue
+import threading
+import time
+import traceback
+
+from ._constants import BUILTIN_RECORD_ATTRS
+
+
+class SlackHandler(logging.Handler):
+    """Sends log records to a Slack channel via ``slack_sdk``.
+
+    Features:
+    - **Non-blocking**: dispatches messages via a background thread + queue.
+    - **Built-in rate limiting**: respects Slack's 1 msg/sec limit per channel.
+    - **Exponential backoff**: backs off on consecutive Slack failures.
+    - **Graceful shutdown**: flushes pending messages on interpreter exit.
+    - **Fallback**: logs to stderr if Slack is unreachable.
+
+    Requires ``slack-sdk``: install with ``pip install pylogkit[slack]``.
+
+    Args:
+        token: Slack Bot OAuth token (``xoxb-...``).
+        channel: Slack channel ID or name (e.g. ``#alerts``).
+        level: Minimum log level (default: ERROR).
+        max_queue_size: Max queued messages before dropping (default: 100).
+        webhook_url: Use incoming webhook URL instead of Bot token.
+            If provided, ``token`` and ``channel`` are ignored.
+
+    Example::
+
+        handler = SlackHandler(token="xoxb-...", channel="#errors")
+        handler.setLevel(logging.ERROR)
+        logging.getLogger().addHandler(handler)
+    """
+
+    # Slack rate limit: 1 message per second per channel
+    _MIN_INTERVAL = 1.1
+    # Exponential backoff limits
+    _MAX_BACKOFF = 300.0  # 5 minutes max
+    _BACKOFF_BASE = 2.0
+
+    def __init__(
+        self,
+        token: str | None = None,
+        channel: str | None = None,
+        level: int = logging.ERROR,
+        max_queue_size: int = 100,
+        webhook_url: str | None = None,
+        service_name: str | None = None,
+    ):
+        super().__init__(level)
+
+        self._webhook_url = webhook_url
+        self._token = token
+        self._channel = channel
+        self._service_name = service_name
+
+        if not webhook_url and not token:
+            raise ValueError("Either 'token' or 'webhook_url' must be provided")
+        if not webhook_url and not channel:
+            raise ValueError("'channel' is required when using token auth")
+
+        self._queue: queue.Queue = queue.Queue(maxsize=max_queue_size)
+        self._shutdown = threading.Event()
+
+        self._thread = threading.Thread(
+            target=self._worker,
+            name="pylogkit-slack",
+            daemon=True,
+        )
+        self._thread.start()
+        atexit.register(self.close)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Queue the record for async dispatch. Drops if queue is full."""
+        with contextlib.suppress(queue.Full):
+            self._queue.put_nowait(record)
+
+    def close(self) -> None:
+        """Flush remaining messages and stop the worker thread."""
+        if self._shutdown.is_set():
+            return
+        self._shutdown.set()
+        self._thread.join(timeout=10)
+        super().close()
+
+    def _worker(self) -> None:
+        """Background worker: drain queue and send to Slack."""
+        try:
+            client = self._create_client()
+        except ImportError as e:
+            import sys
+
+            print(f"[pylogkit] SlackHandler worker failed to start: {e}", file=sys.stderr)
+            return
+
+        last_send = 0.0
+        consecutive_failures = 0
+
+        while not self._shutdown.is_set():
+            try:
+                record = self._queue.get(timeout=1.0)
+            except queue.Empty:
+                continue
+
+            # Rate limit
+            elapsed = time.monotonic() - last_send
+            if elapsed < self._MIN_INTERVAL:
+                time.sleep(self._MIN_INTERVAL - elapsed)
+
+            success = self._send(client, record)
+            last_send = time.monotonic()
+            self._queue.task_done()
+
+            if success:
+                consecutive_failures = 0
+            else:
+                consecutive_failures += 1
+                backoff = min(
+                    self._BACKOFF_BASE**consecutive_failures,
+                    self._MAX_BACKOFF,
+                )
+                self._shutdown.wait(timeout=backoff)
+
+        # Flush remaining on shutdown
+        while not self._queue.empty():
+            try:
+                record = self._queue.get_nowait()
+                self._send(client, record)
+                time.sleep(self._MIN_INTERVAL)
+            except queue.Empty:
+                break
+
+    def _create_client(self):
+        """Create Slack client (lazy import to keep slack_sdk optional)."""
+        try:
+            if self._webhook_url:
+                from slack_sdk.webhook import WebhookClient
+
+                return WebhookClient(url=self._webhook_url)
+            else:
+                from slack_sdk import WebClient
+
+                return WebClient(token=self._token)
+        except ImportError as err:
+            raise ImportError(
+                "slack-sdk is required for SlackHandler. Install with: pip install pylogkit[slack]"
+            ) from err
+
+    def _send(self, client, record: logging.LogRecord) -> bool:
+        """Send a single record to Slack. Returns True on success."""
+        try:
+            attachment = self._format_attachment(record)
+
+            if self._webhook_url:
+                client.send(attachments=[attachment])
+            else:
+                client.chat_postMessage(
+                    channel=self._channel,
+                    text=f"[{record.levelname}] {record.getMessage()[:200]}",
+                    attachments=[attachment],
+                )
+            return True
+        except Exception as e:
+            # Never let Slack failures propagate — print to stderr as fallback
+            import sys
+
+            print(
+                f"[pylogkit] Failed to send to Slack: {e}",
+                file=sys.stderr,
+            )
+            return False
+
+    def _format_attachment(self, record: logging.LogRecord) -> dict:
+        """Format log record as a Slack attachment."""
+        color_map = {
+            logging.WARNING: "warning",
+            logging.ERROR: "danger",
+            logging.CRITICAL: "#8B0000",
+        }
+        color = color_map.get(record.levelno, "warning")
+
+        text = record.getMessage()
+        suppressed = getattr(record, "_suppressed_count", 0)
+        if suppressed:
+            text = f"{text} (suppressed {suppressed} duplicates)"
+        if len(text) > 2000:
+            text = text[:2000] + "…"
+
+        fields = [
+            {"title": "Level", "value": record.levelname, "short": True},
+            {"title": "Logger", "value": record.name, "short": True},
+            {"title": "Module", "value": f"{record.pathname}:{record.lineno}", "short": False},
+        ]
+
+        # Include extra fields (structured logging context)
+        extras = {
+            k: v
+            for k, v in record.__dict__.items()
+            if k not in BUILTIN_RECORD_ATTRS and not k.startswith("_")
+        }
+        if extras:
+            extras_text = "\n".join(f"• *{k}*: {v}" for k, v in extras.items())
+            if len(extras_text) > 500:
+                extras_text = extras_text[:500] + "\n… (truncated)"
+            fields.append({"title": "Context", "value": extras_text, "short": False})
+
+        # Only include traceback if there's a real exception
+        if record.exc_info and record.exc_info[0] is not None:
+            tb = "".join(traceback.format_exception(*record.exc_info))
+            if len(tb) > 1000:
+                tb = tb[:1000] + "\n… (truncated)"
+            fields.append({"title": "Traceback", "value": f"```{tb}```", "short": False})
+
+        attachment: dict = {
+            "color": color,
+            "text": text,
+            "fields": fields,
+            "ts": int(record.created),
+        }
+        if self._service_name:
+            attachment["footer"] = self._service_name
+        return attachment

pylogkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: pylogkit
+Version: 0.1.0
+Summary: Structured logging with Slack integration, rate limiting, and deduplication
+Project-URL: Changelog, https://github.com/analytics-team-global/pylogkit/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/analytics-team-global/pylogkit
+Author: Laba
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: python-json-logger<4.0,>=2.0
+Provides-Extra: all
+Requires-Dist: colorlog>=6.0; extra == 'all'
+Requires-Dist: slack-sdk>=3.20; extra == 'all'
+Provides-Extra: color
+Requires-Dist: colorlog>=6.0; extra == 'color'
+Provides-Extra: dev
+Requires-Dist: colorlog>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: slack-sdk>=3.20; extra == 'dev'
+Provides-Extra: slack
+Requires-Dist: slack-sdk>=3.20; extra == 'slack'
+Description-Content-Type: text/markdown
+
+# pylogkit
+
+[![CI](https://github.com/analytics-team-global/pylogkit/actions/workflows/ci.yml/badge.svg)](https://github.com/analytics-team-global/pylogkit/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Structured logging with Slack integration, rate limiting, and deduplication.
+
+Built on top of Python's standard `logging` module — no custom APIs to learn.
+
+## Installation
+
+```bash
+# Core (JSON + colored formatters)
+pip install pylogkit
+
+# With Slack support
+pip install pylogkit[slack]
+
+# With colored output
+pip install pylogkit[color]
+
+# Everything
+pip install pylogkit[all]
+```
+
+Or as a git dependency:
+
+```toml
+# pyproject.toml
+dependencies = [
+    "pylogkit[all] @ git+ssh://git@github.com/analytics-team-global/pylogkit.git",
+]
+```
+
+## Quick Start
+
+```python
+import os
+from pylogkit import setup_logging, get_logger
+
+setup_logging(
+    level="INFO",
+    service_name="my-api",
+    slack_token=os.environ.get("SLACK_BOT_TOKEN"),
+    slack_channel="#errors",
+)
+
+logger = get_logger(__name__)
+
+logger.info("Server started", extra={"port": 8000})
+logger.error("Request failed", extra={"endpoint": "/users", "status": 500})
+```
+
+## Features
+
+### Auto-detect output format
+
+- **TTY (development)**: colored human-readable output with extras
+- **Non-TTY (production/Docker)**: structured JSON
+
+Force a specific format:
+
+```python
+setup_logging(json_format=True)   # always JSON
+setup_logging(json_format=False)  # always colored
+```
+
+### Structured logging with extra fields
+
+Extra fields are included in both JSON and colored output:
+
+```python
+logger.info("Deal processed", extra={
+    "deal_id": "123",
+    "pipeline": "laba_czech",
+    "duration": 1.23,
+})
+```
+
+**JSON output:**
+```json
+{"timestamp": "2026-03-18T12:00:00+00:00", "level": "INFO", "logger": "myapp.deals", "message": "Deal processed", "deal_id": "123", "pipeline": "laba_czech", "duration": 1.23}
+```
+
+**Colored output:**
+```
+2026-03-18 12:00:00 INFO     myapp.deals — Deal processed  [deal_id=123 pipeline=laba_czech duration=1.23]
+```
+
+### Logger with static context
+
+Bind context fields to a logger — they appear in every message:
+
+```python
+logger = get_logger(__name__, pipeline="laba_czech", env="production")
+
+logger.info("Course synced")
+# All messages from this logger will include pipeline= and env=
+```
+
+Calling `get_logger()` again with the same name updates the context:
+
+```python
+logger = get_logger(__name__, pipeline="v2")
+# pipeline is now "v2", env remains from the previous call
+```
+
+### Request-scoped context with contextvars
+
+Inject request-scoped fields (request_id, user_id, etc.) without passing `extra={}` to every log call:
+
+```python
+import contextvars
+from pylogkit import setup_logging
+
+log_context: contextvars.ContextVar[dict] = contextvars.ContextVar(
+    "log_context", default={}
+)
+
+setup_logging(
+    service_name="my-api",
+    ctx_var=log_context,
+)
+
+# In your request handler / middleware:
+log_context.set({"request_id": "abc-123", "user_id": "42"})
+logger.info("Processing request")
+# Output includes request_id and user_id automatically
+```
+
+Works with async frameworks (FastAPI, aiohttp) — each coroutine gets its own context.
+
+### Slack notifications
+
+ERROR and CRITICAL logs go to Slack with:
+- Color-coded attachments (yellow/red/dark red)
+- Module and line number
+- Extra fields as "Context" block
+- Formatted traceback
+
+```python
+setup_logging(
+    slack_token="xoxb-...",
+    slack_channel="#alerts",
+    slack_level="ERROR",          # minimum level (default: ERROR)
+)
+```
+
+Or use incoming webhook (simpler, scoped to one channel):
+
+```python
+setup_logging(
+    slack_webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
+)
+```
+
+**How it works internally:**
+- Messages are queued and sent from a background thread (non-blocking)
+- Respects Slack's 1 msg/sec rate limit
+- Exponential backoff on consecutive failures (up to 5 min)
+- If queue is full (100 messages) — drops silently, never blocks the app
+- If Slack is unreachable — prints to stderr, never crashes
+- Flushes remaining messages on shutdown
+
+### Rate limiting
+
+Prevents Slack spam. Each unique message can fire at most N times per period:
+
+```python
+setup_logging(
+    slack_token="xoxb-...",
+    slack_channel="#alerts",
+    slack_rate_limit=1,       # max 1 message per period (default)
+    slack_rate_period=60.0,   # per 60 seconds (default)
+)
+```
+
+If the same error fires 500 times in a minute — only the first one goes to Slack.
+
+### Deduplication
+
+Suppresses identical errors within a time window. When the window expires, the next message includes the suppressed count:
+
+```python
+setup_logging(
+    slack_token="xoxb-...",
+    slack_channel="#alerts",
+    slack_dedupe_window=300.0,  # 5 minutes (default)
+)
+```
+
+Example: `"Connection refused (suppressed 47 duplicates)"`
+
+Set to `0` to disable deduplication.
+
+### Per-logger level overrides
+
+Silence noisy third-party libraries:
+
+```python
+setup_logging(
+    level="INFO",
+    loggers={
+        "httpx": "WARNING",
+        "sqlalchemy.engine": "WARNING",
+        "celery": "INFO",
+    },
+)
+```
+
+### Static context fields
+
+Add fields to every log record in the application:
+
+```python
+setup_logging(
+    service_name="my-api",
+    extra_context={
+        "env": "production",
+        "region": "eu-west-1",
+    },
+)
+```
+
+## Advanced: using components directly
+
+All components can be used independently without `setup_logging()`:
+
+```python
+import logging
+from pylogkit import JsonFormatter, ColoredFormatter, RateLimitFilter, DeduplicationFilter
+from pylogkit import SlackHandler  # lazy import, requires slack-sdk
+
+# Custom handler with JSON
+handler = logging.StreamHandler()
+handler.setFormatter(JsonFormatter())
+
+# Slack with custom filters
+slack = SlackHandler(token="xoxb-...", channel="#alerts")
+slack.addFilter(RateLimitFilter(rate=3, period=120))
+slack.addFilter(DeduplicationFilter(window=600))
+
+logging.getLogger().addHandler(handler)
+logging.getLogger().addHandler(slack)
+```
+
+## Celery integration
+
+Prevent Celery from hijacking your logging setup:
+
+```python
+from celery.signals import setup_logging as celery_setup_logging
+from pylogkit import setup_logging
+
+@celery_setup_logging.connect
+def configure_celery_logging(**kwargs):
+    setup_logging(
+        service_name="worker",
+        slack_token=os.environ.get("SLACK_BOT_TOKEN"),
+        slack_channel="#worker-errors",
+    )
+```
+
+## `setup_logging()` parameters
+
+| Parameter             | Type           | Default   | Description                                            |
+|-----------------------|----------------|-----------|--------------------------------------------------------|
+| `level`               | `str`          | `"INFO"`  | Root log level                                         |
+| `service_name`        | `str`          | `None`    | Added to every record as `service` field               |
+| `json_format`         | `bool`         | auto      | `True` = JSON, `False` = colored, `None` = auto-detect |
+| `slack_token`         | `str`          | `None`    | Slack Bot token (`xoxb-...`)                           |
+| `slack_channel`       | `str`          | `None`    | Slack channel (required with token)                    |
+| `slack_webhook_url`   | `str`          | `None`    | Incoming webhook URL (alternative to token)            |
+| `slack_level`         | `str`          | `"ERROR"` | Minimum level for Slack                                |
+| `slack_rate_limit`    | `int`          | `1`       | Max messages per period                                |
+| `slack_rate_period`   | `float`        | `60.0`    | Rate limit window (seconds)                            |
+| `slack_dedupe_window` | `float`        | `300.0`   | Deduplication window (seconds), `0` to disable         |
+| `extra_context`       | `dict`         | `None`    | Static fields for every record                         |
+| `loggers`             | `dict`         | `None`    | Per-logger level overrides                             |
+| `ctx_var`             | `ContextVar`   | `None`    | Request-scoped context variable                        |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=pylogkit --cov-report=term-missing
+
+# Lint
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/pylogkit/
+```
+
+## License
+
+[MIT](LICENSE)

pylogkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pylogkit/__init__.py,sha256=wshcBCG8F8vnSAyQCcJwh73XxUPG1OD-9-DNv-DgIAc,1966
+pylogkit/_constants.py,sha256=WoG1vhYPGJAjH1US0Y3rr0ZcfkKqgPCrXQtVTvDaRo8,696
+pylogkit/config.py,sha256=_yM_sT7f25ODLlsWWxIqjZaGE3aaTqg4COjbcijC0rY,5651
+pylogkit/filters.py,sha256=b8TpfKV6BHussP6nkLd8uftcFMvbatuGchrfxuP3zOM,6507
+pylogkit/formatters.py,sha256=aexexkZ_zQin9yOhKA-HT1wFUqB8QtYrVVj-KAjbt_Y,4294
+pylogkit/handlers.py,sha256=5hPMts8ka_TvWx_TFrzw2-Sa2urRxeo6uRv_xADw1A8,7914
+pylogkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylogkit-0.1.0.dist-info/METADATA,sha256=kWp-HQ-T5XzSfs8Dgy7IYdV70C7rmAPOEdZtiQbv2Lw,9960
+pylogkit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pylogkit-0.1.0.dist-info/licenses/LICENSE,sha256=PAVPx9OpZR0-u06tm8GpkwdUgCsvBbTfp0xxso0jKls,1061
+pylogkit-0.1.0.dist-info/RECORD,,

pylogkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pylogkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.