centralog-sdk 0.1.0__tar.gz

centralog_sdk-0.1.0/.gitignore

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

centralog_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Yair Juarez
+
+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.

centralog_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: centralog-sdk
+Version: 0.1.0
+Summary: Python SDK for Centralog error monitoring. Captures exceptions and sends a copy to your Centralog platform without breaking your app.
+License: MIT
+License-File: LICENSE
+Keywords: centralog,django,error-monitoring,fastapi,flask
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: flask>=3.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# Centralog SDK — Python
+
+Python SDK for [Centralog](https://github.com/Thejairex/centralog) error monitoring.
+Captures exceptions and sends a copy to your Centralog platform. Never breaks your app.
+
+Supports **FastAPI**, **Flask** and **Django** (plus manual capture anywhere).
+
+## Install
+
+```bash
+pip install centralog-sdk
+# with framework support:
+pip install "centralog-sdk[fastapi]"
+```
+
+## Configure
+
+Env vars:
+
+```env
+CENTRALOG_ENABLED=true
+CENTRALOG_ENDPOINT=https://centralog.tudominio.com/api/v1/ingest/events
+CENTRALOG_API_KEY=clk_tu_api_key
+CENTRALOG_ENVIRONMENT=production
+CENTRALOG_RELEASE=2026.09.30.1
+CENTRALOG_TIMEOUT=2
+```
+
+Generate the API key in Centralog: Projects → API Keys.
+
+## Usage
+
+**FastAPI** (one line):
+
+```python
+from fastapi import FastAPI
+from centralog.frameworks.fastapi import register as centralog_register
+
+app = FastAPI()
+centralog_register(app)
+```
+
+**Flask**:
+
+```python
+from flask import Flask
+from centralog.frameworks.flask import register as centralog_register
+
+app = Flask(__name__)
+centralog_register(app)
+```
+
+**Django** — add to `MIDDLEWARE`:
+
+```python
+MIDDLEWARE = [
+    ...,
+    "centralog.frameworks.django.CentralogMiddleware",
+]
+```
+
+**Manual** (anywhere):
+
+```python
+from centralog import CentralogClient
+
+client = CentralogClient()
+client.context({"tenant": "acme"})
+
+try:
+    charge(order)
+except Exception as exc:
+    client.capture(exc, {"order_id": order.id})
+```
+
+Your local logging keeps working as always — the SDK only sends a **copy** to Centralog.
+
+## Custom errors
+
+Any exception (including your domain exceptions) can be captured manually
+with a level (`error`, `warning`, `info` or `debug`):
+
+```python
+from centralog import CentralogClient
+
+class PaymentFailedError(Exception):
+    pass
+
+client = CentralogClient()
+
+try:
+    charge(order)
+except PaymentFailedError as exc:
+    client.capture(exc, {"order_id": order.id}, level="warning")
+```
+
+Each exception is grouped in Centralog by **class + file + line**, so every
+custom exception in your domain gets its own group in the panel.
+
+Valid levels: `error` (default), `warning`, `info`, `debug`.
+
+## Safety
+
+- Short timeout (2s default), never blocks a request for long.
+- Any network failure is swallowed and logged with `logging.debug`.
+- Disabled automatically when `CENTRALOG_ENABLED=false` or endpoint/key are missing.
+- No workers required (synchronous by design).
+
+## Testing
+
+```bash
+uv run pytest
+```

centralog_sdk-0.1.0/README.md

@@ -0,0 +1,113 @@
+# Centralog SDK — Python
+
+Python SDK for [Centralog](https://github.com/Thejairex/centralog) error monitoring.
+Captures exceptions and sends a copy to your Centralog platform. Never breaks your app.
+
+Supports **FastAPI**, **Flask** and **Django** (plus manual capture anywhere).
+
+## Install
+
+```bash
+pip install centralog-sdk
+# with framework support:
+pip install "centralog-sdk[fastapi]"
+```
+
+## Configure
+
+Env vars:
+
+```env
+CENTRALOG_ENABLED=true
+CENTRALOG_ENDPOINT=https://centralog.tudominio.com/api/v1/ingest/events
+CENTRALOG_API_KEY=clk_tu_api_key
+CENTRALOG_ENVIRONMENT=production
+CENTRALOG_RELEASE=2026.09.30.1
+CENTRALOG_TIMEOUT=2
+```
+
+Generate the API key in Centralog: Projects → API Keys.
+
+## Usage
+
+**FastAPI** (one line):
+
+```python
+from fastapi import FastAPI
+from centralog.frameworks.fastapi import register as centralog_register
+
+app = FastAPI()
+centralog_register(app)
+```
+
+**Flask**:
+
+```python
+from flask import Flask
+from centralog.frameworks.flask import register as centralog_register
+
+app = Flask(__name__)
+centralog_register(app)
+```
+
+**Django** — add to `MIDDLEWARE`:
+
+```python
+MIDDLEWARE = [
+    ...,
+    "centralog.frameworks.django.CentralogMiddleware",
+]
+```
+
+**Manual** (anywhere):
+
+```python
+from centralog import CentralogClient
+
+client = CentralogClient()
+client.context({"tenant": "acme"})
+
+try:
+    charge(order)
+except Exception as exc:
+    client.capture(exc, {"order_id": order.id})
+```
+
+Your local logging keeps working as always — the SDK only sends a **copy** to Centralog.
+
+## Custom errors
+
+Any exception (including your domain exceptions) can be captured manually
+with a level (`error`, `warning`, `info` or `debug`):
+
+```python
+from centralog import CentralogClient
+
+class PaymentFailedError(Exception):
+    pass
+
+client = CentralogClient()
+
+try:
+    charge(order)
+except PaymentFailedError as exc:
+    client.capture(exc, {"order_id": order.id}, level="warning")
+```
+
+Each exception is grouped in Centralog by **class + file + line**, so every
+custom exception in your domain gets its own group in the panel.
+
+Valid levels: `error` (default), `warning`, `info`, `debug`.
+
+## Safety
+
+- Short timeout (2s default), never blocks a request for long.
+- Any network failure is swallowed and logged with `logging.debug`.
+- Disabled automatically when `CENTRALOG_ENABLED=false` or endpoint/key are missing.
+- No workers required (synchronous by design).
+
+## Testing
+
+```bash
+uv run pytest
+```

centralog_sdk-0.1.0/centralog/__init__.py

@@ -0,0 +1,7 @@
+"""Centralog Python SDK — error copies for your Centralog platform."""
+
+from .client import CentralogClient
+from .payload import build_payload
+
+__all__ = ["CentralogClient", "build_payload"]
+__version__ = "0.1.0"

centralog_sdk-0.1.0/centralog/client.py

@@ -0,0 +1,92 @@
+"""Fault-tolerant HTTP client for the Centralog ingest API."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+
+from .payload import build_payload
+
+logger = logging.getLogger("centralog")
+
+
+class CentralogClient:
+    """Send error copies to Centralog. Never raises."""
+
+    def __init__(
+        self,
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        environment: str | None = None,
+        release: str | None = None,
+        timeout: float = 2.0,
+        enabled: bool = True,
+    ) -> None:
+        self.endpoint = endpoint or os.getenv("CENTRALOG_ENDPOINT", "")
+        self.api_key = api_key or os.getenv("CENTRALOG_API_KEY", "")
+        self.environment = environment or os.getenv("CENTRALOG_ENVIRONMENT", "production")
+        self.release = release if release is not None else os.getenv("CENTRALOG_RELEASE")
+        self.timeout = timeout
+        if (env_timeout := os.getenv("CENTRALOG_TIMEOUT")) and timeout == 2.0:
+            try:
+                self.timeout = float(env_timeout)
+            except ValueError:
+                pass
+        self.enabled = enabled and os.getenv("CENTRALOG_ENABLED", "true").lower() not in (
+            "0",
+            "false",
+            "no",
+            "off",
+        )
+        self._extra_context: dict[str, Any] = {}
+
+    def context(self, context: dict[str, Any]) -> None:
+        """Merge extra context into every captured event."""
+        self._extra_context.update(context)
+
+    def get_context(self) -> dict[str, Any]:
+        return dict(self._extra_context)
+
+    def flush_context(self) -> None:
+        self._extra_context = {}
+
+    def capture(
+        self,
+        exception: BaseException,
+        context: dict[str, Any] | None = None,
+        level: str = "error",
+        request: dict[str, Any] | None = None,
+        user: dict[str, Any] | None = None,
+    ) -> bool:
+        """Capture an exception and send a copy to Centralog.
+
+        Returns True on success. Never raises: any failure is logged
+        locally at debug level and swallowed.
+        """
+        if not self.enabled or not self.endpoint or not self.api_key:
+            return False
+
+        try:
+            merged = {**self._extra_context, **(context or {})}
+            payload = build_payload(
+                exception,
+                environment=self.environment,
+                release=self.release,
+                level=level,
+                context=merged,
+                request=request,
+                user=user,
+            )
+            response = httpx.post(
+                self.endpoint,
+                json=payload,
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                timeout=self.timeout,
+            )
+            return 200 <= response.status_code < 300
+        except Exception as exc:  # noqa: BLE001 — reporting must never break the app
+            logger.debug("Centralog reporting failed: %s", exc)
+            return False

centralog_sdk-0.1.0/centralog/frameworks/django.py

@@ -0,0 +1,37 @@
+"""Django integration: middleware that reports unhandled exceptions."""
+
+from __future__ import annotations
+
+import logging
+
+from ..client import CentralogClient
+
+logger = logging.getLogger("centralog")
+
+
+class CentralogMiddleware:
+    """Report unhandled exceptions, then re-raise so Django handles them.
+
+    Add to MIDDLEWARE. Never swallows: the exception always propagates.
+    """
+
+    def __init__(self, get_response):  # type: ignore[no-untyped-def]
+        self.get_response = get_response
+        self.client = CentralogClient()
+
+    def __call__(self, request):  # type: ignore[no-untyped-def]
+        return self.get_response(request)
+
+    def process_exception(self, request, exception) -> None:  # type: ignore[no-untyped-def]
+        try:
+            resolver_match = getattr(request, "resolver_match", None)
+            self.client.capture(
+                exception,
+                request={
+                    "method": request.method,
+                    "url": request.build_absolute_uri(),
+                    "route": getattr(resolver_match, "view_name", None),
+                },
+            )
+        except Exception as exc:  # noqa: BLE001 — reporting must never break the app
+            logger.debug("Centralog Django middleware failed: %s", exc)

centralog_sdk-0.1.0/centralog/frameworks/fastapi.py

@@ -0,0 +1,59 @@
+"""FastAPI integration: register an exception handler that reports 500s."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from fastapi import FastAPI, Request
+    from fastapi.responses import JSONResponse
+except ImportError:  # pragma: no cover
+    FastAPI = None  # type: ignore[assignment]
+    Request = None  # type: ignore[assignment]
+    JSONResponse = None  # type: ignore[assignment]
+
+from ..client import CentralogClient
+
+
+def register(
+    app: FastAPI,
+    client: CentralogClient | None = None,
+    *,
+    capture_http_exceptions: bool = False,
+) -> CentralogClient:
+    """Register Centralog error reporting on a FastAPI app.
+
+    Captures unhandled 500s (and optionally HTTPException) without
+    changing the responses your app returns.
+    """
+    client = client or CentralogClient()
+
+    async def _report(request: Request, exc: BaseException) -> None:
+        route = request.scope.get("route")
+        client.capture(
+            exc,
+            request={
+                "method": request.method,
+                "url": str(request.url),
+                "route": getattr(route, "name", None) or getattr(route, "path", None),
+            },
+        )
+
+    async def _handle_500(request: Request, exc: Exception) -> Any:
+        await _report(request, exc)
+        return JSONResponse({"detail": "Internal Server Error"}, status_code=500)
+
+    async def _handle_http(request: Request, exc: Any) -> Any:
+        from fastapi import HTTPException
+
+        if isinstance(exc, HTTPException) and exc.status_code >= 500:
+            await _report(request, exc)
+        raise exc
+
+    app.add_exception_handler(Exception, _handle_500)
+    if capture_http_exceptions:
+        from fastapi import HTTPException
+
+        app.add_exception_handler(HTTPException, _handle_http)
+
+    return client

centralog_sdk-0.1.0/centralog/frameworks/flask.py

@@ -0,0 +1,38 @@
+"""Flask integration: register an error handler that reports 500s."""
+
+from __future__ import annotations
+
+try:
+    from flask import Flask, Response, request
+    from werkzeug.exceptions import HTTPException
+except ImportError:  # pragma: no cover
+    Flask = None  # type: ignore[assignment]
+    Response = None  # type: ignore[assignment]
+    request = None  # type: ignore[assignment]
+    HTTPException = Exception  # type: ignore[assignment,misc]
+
+from ..client import CentralogClient
+
+
+def register(app: Flask, client: CentralogClient | None = None) -> CentralogClient:
+    """Register Centralog error reporting on a Flask app.
+
+    Captures unhandled 500s. Your error responses stay unchanged.
+    """
+    client = client or CentralogClient()
+
+    @app.errorhandler(Exception)
+    def _report(error: BaseException):  # type: ignore[no-untyped-def]
+        if isinstance(error, HTTPException) and getattr(error, "code", 500) < 500:
+            return error.get_response()
+        client.capture(
+            error,
+            request={
+                "method": request.method,
+                "url": request.url,
+                "route": request.url_rule.endpoint if request.url_rule else None,
+            },
+        )
+        return Response("Internal Server Error", status=500)
+
+    return client

centralog_sdk-0.1.0/centralog/payload.py

@@ -0,0 +1,47 @@
+"""Build ingest payloads matching the Centralog Fase 8 contract."""
+
+from __future__ import annotations
+
+import traceback
+import uuid
+from typing import Any
+
+
+def build_payload(
+    exception: BaseException,
+    environment: str,
+    release: str | None = None,
+    level: str = "error",
+    context: dict[str, Any] | None = None,
+    request: dict[str, Any] | None = None,
+    user: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an ingest payload from an exception and optional context.
+
+    Mirrors the Laravel SDK PayloadBuilder output exactly.
+    """
+    tb = exception.__traceback__
+    # Walk to the deepest user frame for file/line, like Laravel reports throw site.
+    deepest: dict[str, Any] = {"file": "<unknown>", "line": 0}
+    if tb is not None:
+        frames = traceback.extract_tb(tb)
+        if frames:
+            last = frames[-1]
+            deepest = {"file": last.filename, "line": last.lineno or 0}
+
+    return {
+        "event_id": str(uuid.uuid4()),
+        "environment": environment,
+        "release": release,
+        "level": level,
+        "exception": {
+            "class": f"{type(exception).__module__}.{type(exception).__name__}",
+            "message": str(exception) or type(exception).__name__,
+            "file": deepest["file"],
+            "line": deepest["line"],
+            "trace": "".join(traceback.format_exception(exception)),
+        },
+        "request": request,
+        "user": user,
+        "context": context if context else None,
+    }

centralog_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "centralog-sdk"
+version = "0.1.0"
+description = "Python SDK for Centralog error monitoring. Captures exceptions and sends a copy to your Centralog platform without breaking your app."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["centralog", "error-monitoring", "fastapi", "flask", "django"]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+flask = ["flask>=3.0"]
+django = ["django>=4.2"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.4", "fastapi>=0.110", "flask>=3.0", "django>=4.2", "httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["centralog"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"