pylogkit 0.1.0__tar.gz

pylogkit-0.1.0/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:browniebroke.com)",
+      "WebFetch(domain:nhairs.github.io)",
+      "WebFetch(domain:www.structlog.org)",
+      "WebFetch(domain:betterstack.com)",
+      "WebFetch(domain:www.toptal.com)",
+      "WebFetch(domain:docs.slack.dev)",
+      "WebFetch(domain:www.core27.co)",
+      "WebFetch(domain:rednafi.com)",
+      "Read(//opt/homebrew/bin/**)",
+      "Read(//usr/local/bin/**)",
+      "Bash(python3.12 -m venv .venv)",
+      "Bash(source .venv/bin/activate)",
+      "Bash(pip install:*)",
+      "Bash(python -m pytest tests/ -v)",
+      "Bash(python -m pytest tests/ --cov=pylogkit --cov-report=term-missing)",
+      "Bash(ruff check:*)",
+      "Bash(ruff format:*)",
+      "Bash(mypy src/pylogkit/)",
+      "Bash(python -m pytest tests/ -v --cov=pylogkit --cov-report=term-missing)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)"
+    ]
+  }
+}

pylogkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" mypy
+      - run: mypy src/pylogkit/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ --cov=pylogkit --cov-report=term-missing --cov-fail-under=80

pylogkit-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

pylogkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-31
+
+### Added
+
+- `setup_logging()` — one-call logging configuration with auto-format detection
+- `get_logger()` — get logger with optional bound context fields
+- `JsonFormatter` — structured JSON output for production (ISO 8601 UTC timestamps)
+- `ColoredFormatter` — human-readable colored output for development
+- `ContextFilter` — inject static context fields into every log record
+- `ContextVarsFilter` — inject request-scoped context via `contextvars`
+- `RateLimitFilter` — token bucket rate limiting per unique message
+- `DeduplicationFilter` — suppress duplicate messages within a time window
+- `SlackHandler` — async Slack notifications with background thread, queue, and exponential backoff
+- Support for both Slack Bot token and incoming webhook authentication
+- Auto-detection of output format (JSON for non-TTY, colored for TTY)
+- Per-logger level overrides
+- Graceful degradation when optional dependencies are missing
+- Comprehensive test suite (71 tests, 85% coverage)

pylogkit-0.1.0/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.

pylogkit-0.1.0/PKG-INFO

@@ -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)