kamori-sdk 0.1.1__tar.gz

kamori_sdk-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest

kamori_sdk-0.1.1/.github/workflows/pr.yml

@@ -0,0 +1,50 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, edited]
+
+concurrency:
+  group: pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate-title:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            chore
+            docs
+            refactor
+            test
+            ci
+            perf
+            revert
+            build
+          requireScope: false
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest

kamori_sdk-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+# Triggered by pushing a semver tag (e.g. git tag v1.1.0 && git push --tags).
+# The version in pyproject.toml must be bumped and committed before tagging
+# (scripts/release.sh handles this automatically).
+#
+# PyPI authentication — OIDC Trusted Publishers (no PYPI_TOKEN secret needed).
+# One-time setup on pypi.org:
+#   Account → Publishing → Add a new pending publisher
+#   → owner: usekamori, repo: kamori-python, workflow: release.yml, environment: pypi
+#
+# Pipeline:
+#   test         → install + pytest (blocks publish if failing)
+#   publish-pypi → build + push to PyPI via OIDC
+#   github-release → GitHub Release with auto-generated changelog
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write   # OIDC for PyPI provenance
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          body: |
+            ## Install
+
+            ```bash
+            pip install kamori-sdk==${{ github.ref_name }}
+            ```
+
+            ## Usage
+
+            ```python
+            from kamori_sdk import KamoriClient
+
+            client = KamoriClient(
+                url="https://your-kamori-server.com",
+                token="your-ingest-token",
+            )
+            client.log({"level": "info", "message": "hello"})
+            client.flush()
+            ```

kamori_sdk-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+dist/
+*.egg-info/
+.DS_Store

kamori_sdk-0.1.1/MIT-LICENSE

@@ -0,0 +1,98 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+**You may not provide the software to third parties as a hosted or managed
+service**, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or chooses to license, to make, have made, use, sell, offer for sale,
+import and have imported the software, in each case subject to the limitations
+and conditions in this license. This license does not cover any patent claims
+that you cause to be infringed by modifications or additions to the software.
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+_As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim._
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and legal affairs.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** includes anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Note: The Kamori client SDKs (@kamori/sdk, kamori-go, kamori-sdk, kamori-php)
+are separately licensed under the MIT License to allow unrestricted use in
+any application.

kamori_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: kamori-sdk
+Version: 0.1.1
+Summary: Python SDK for Kamori — self-hosted log ingestion
+Project-URL: Homepage, https://github.com/usekamori/kamori-python
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kamori-sdk
+
+Python SDK for [Kamori](https://github.com/usekamori/kamori) — self-hosted log ingestion with MCP support.
+
+Events are buffered in memory and flushed to your Kamori server on a background daemon thread, so logging never blocks your application.
+
+---
+
+## Installation
+
+```bash
+pip install kamori-sdk
+```
+
+---
+
+## Quick start
+
+```python
+import atexit
+from kamori_sdk import KamoriClient
+
+client = KamoriClient(
+    url="https://your-kamori-server.com",
+    token="your-log-token",   # matches INGEST_TOKEN on the server
+)
+atexit.register(client.shutdown)  # flush buffered events on process exit
+
+client.log({"level": "info", "service": "api", "message": "Server started"})
+client.log({"level": "error", "service": "payments", "message": "Stripe timeout", "duration_ms": 5001})
+```
+
+---
+
+## Python `logging` integration
+
+### One-liner (recommended)
+
+```python
+from kamori_sdk import install_logging_handler
+
+handler = install_logging_handler(
+    url="https://your-kamori-server.com",
+    token="your-log-token",
+)
+
+import logging
+logging.getLogger("api").info("Server started")
+logging.getLogger("payments").error("Stripe timeout")
+```
+
+Each `LogRecord` is converted to a structured dict with `level`, `message`, `logger`, `module`, `funcName`, and `lineno` fields. Exception info is serialised as `exc_text` so stack traces are full-text-searchable in Kamori.
+
+### Explicit handler
+
+```python
+import logging
+from kamori_sdk.logging_handler import KamoriHandler
+
+handler = KamoriHandler(
+    url="https://your-kamori-server.com",
+    token="your-log-token",
+    level=logging.WARNING,   # only WARNING and above
+)
+logging.getLogger().addHandler(handler)
+```
+
+### Django
+
+In `settings.py`:
+
+```python
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "handlers": {
+        "kamori": {
+            "class": "kamori_sdk.logging_handler.KamoriHandler",
+            "url": "https://your-kamori-server.com",
+            "token": env("INGEST_TOKEN", default=""),
+        },
+    },
+    "root": {"handlers": ["kamori"], "level": "INFO"},
+}
+```
+
+### FastAPI
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from kamori_sdk import install_logging_handler
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    handler = install_logging_handler(
+        url=settings.KAMORI_URL,
+        token=settings.INGEST_TOKEN,
+    )
+    yield
+    handler.client.shutdown()   # flush before shutdown
+
+app = FastAPI(lifespan=lifespan)
+```
+
+### structlog
+
+```python
+import structlog
+from kamori_sdk import KamoriClient
+
+client = KamoriClient(url="https://your-kamori-server.com", token="your-log-token")
+
+def kamori_sink(logger, method, event_dict):
+    client.log(event_dict)
+    return event_dict
+
+structlog.configure(
+    processors=[
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        kamori_sink,
+        structlog.dev.ConsoleRenderer(),
+    ]
+)
+```
+
+### loguru
+
+```python
+from loguru import logger
+from kamori_sdk import KamoriClient
+
+client = KamoriClient(url="https://your-kamori-server.com", token="your-log-token")
+
+def kamori_sink(message):
+    record = message.record
+    client.log({
+        "level":    record["level"].name.lower(),
+        "message":  record["message"],
+        "module":   record["module"],
+        "function": record["function"],
+        "line":     record["line"],
+    })
+
+logger.add(kamori_sink)
+```
+
+---
+
+## Scoped clients
+
+Add default fields to every log call without repeating them:
+
+```python
+def make_scoped(client: KamoriClient, **defaults):
+    """Return a log function that merges defaults into every event."""
+    def log(event):
+        client.log({**defaults, **event})
+    return log
+
+api_log = make_scoped(client, service="api", version="2.1.0")
+api_log({"level": "info", "message": "Request started", "path": "/checkout"})
+api_log({"level": "error", "message": "DB timeout"})
+```
+
+---
+
+## flush_on_exit
+
+The background thread is a **daemon thread** — it dies automatically when the main thread exits. For guaranteed delivery, register `shutdown()` via `atexit`:
+
+```python
+import atexit
+atexit.register(client.shutdown)   # flush + stop background thread (up to 5s)
+```
+
+Or call explicitly:
+
+```python
+client.shutdown(timeout=5.0)   # blocks up to 5 seconds
+```
+
+For an immediate flush without stopping the thread (useful in request handlers):
+
+```python
+client.flush()   # blocks until the queue drains
+```
+
+---
+
+## on_drop callback
+
+Called when a batch is permanently dropped after all retry attempts:
+
+```python
+import logging
+
+def handle_drop(events):
+    logging.warning("Kamori dropped %d events — check server connectivity", len(events))
+
+client = KamoriClient(
+    url="https://your-kamori-server.com",
+    token="your-log-token",
+    on_drop=handle_drop,
+)
+```
+
+---
+
+## Retry behaviour
+
+Failed requests are retried up to three times with exponential back-off:
+
+| Attempt   | Delay  |
+| --------- | ------ |
+| 1st retry | 0.25 s |
+| 2nd retry | 1 s    |
+| 3rd retry | 4 s    |
+
+`4xx` responses are **not** retried (client error — bad token, oversized batch). The client never raises or crashes the calling thread.
+
+---
+
+## Configuration reference
+
+| Parameter        | Default | Description                                                                                                               |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `url`            | —       | Base URL of your Kamori server (required)                                                                                 |
+| `token`          | `None`  | Auth token (sent as `Authorization: Bearer`). Omit to skip auth.                                                          |
+| `batch_size`     | `50`    | Flush automatically when buffer reaches this size                                                                         |
+| `flush_interval` | `2.0`   | Max seconds between background flushes                                                                                    |
+| `max_queue`      | `0`     | Max events in the in-memory queue. `0` = unlimited. New events are dropped (calling `on_drop`) when the limit is reached. |
+| `on_drop`        | `None`  | `Callable[[list[dict]], None]` — called when a batch is dropped                                                           |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- No external dependencies (uses `urllib.request` and `threading` from the standard library)
+
+## License
+
+MIT