logstack-py 1.0.1__py3-none-any.whl

logstack/__init__.py

@@ -0,0 +1,17 @@
+"""
+LogStack Python SDK
+
+A Python SDK for the LogStack logging platform.
+"""
+
+from .client import LogStackClient, normalize_api_url
+from .middleware import DjangoMiddleware, FastAPIMiddleware, create_fastapi_middleware
+
+__version__ = "1.0.1"
+__all__ = [
+    "LogStackClient",
+    "normalize_api_url",
+    "DjangoMiddleware",
+    "FastAPIMiddleware",
+    "create_fastapi_middleware",
+]

logstack/client.py

@@ -0,0 +1,164 @@
+"""
+LogStack Client module.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger("logstack")
+
+OnErrorCallback = Callable[[Exception, List[Dict[str, Any]]], None]
+
+
+def normalize_api_url(raw: str) -> str:
+    """Strip trailing slashes and a redundant /v1 suffix."""
+    url = raw.rstrip("/")
+    if url.endswith("/v1"):
+        url = url[:-3]
+    return url.rstrip("/")
+
+
+class LogStackClient:
+    """
+    Main LogStack client for sending logs to the LogStack API.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str = "https://api.logstack.tech",
+        environment: str = "production",
+        flush_interval: float = 5.0,
+        batch_size: int = 100,
+        on_error: Optional[OnErrorCallback] = None,
+    ):
+        self.api_key = api_key
+        self.api_url = normalize_api_url(api_url)
+        self.environment = environment
+        self.flush_interval = flush_interval
+        self.batch_size = batch_size
+        self.on_error = on_error
+
+        self._batch: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._flush_timer: Optional[threading.Timer] = None
+        self._running = True
+        self._closed = False
+
+        self._start_flush_timer()
+
+    def _start_flush_timer(self) -> None:
+        if not self._running:
+            return
+        if self._flush_timer:
+            self._flush_timer.cancel()
+
+        self._flush_timer = threading.Timer(self.flush_interval, self._flush_callback)
+        self._flush_timer.daemon = True
+        self._flush_timer.start()
+
+    def _flush_callback(self) -> None:
+        if self._running:
+            self.flush()
+            self._start_flush_timer()
+
+    def _add_to_batch(self, level: str, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        entry = {
+            "level": level,
+            "message": message,
+            "metadata": metadata or {},
+            "source": "python-sdk",
+        }
+
+        batch_to_send: Optional[List[Dict[str, Any]]] = None
+        with self._lock:
+            if self._closed:
+                return
+            self._batch.append(entry)
+            if len(self._batch) >= self.batch_size:
+                batch_to_send = self._batch.copy()
+                self._batch.clear()
+
+        if batch_to_send:
+            self._send_batch(batch_to_send)
+
+    def info(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("info", message, metadata)
+
+    def debug(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("debug", message, metadata)
+
+    def warn(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("warn", message, metadata)
+
+    def error(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("error", message, metadata)
+
+    def critical(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("critical", message, metadata)
+
+    def fatal(self, message: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self._add_to_batch("fatal", message, metadata)
+        self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._batch:
+                return
+            batch = self._batch.copy()
+            self._batch.clear()
+
+        self._send_batch(batch)
+
+    def _send_batch(self, batch: List[Dict[str, Any]]) -> None:
+        if not batch:
+            return
+
+        payload = {
+            "logs": batch,
+            "environment": self.environment,
+        }
+
+        try:
+            response = requests.post(
+                f"{self.api_url}/v1/logs",
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.api_key}",
+                },
+                timeout=10,
+            )
+            if response.status_code not in (200, 201):
+                err = requests.HTTPError(
+                    f"Logstack API error ({response.status_code}): {response.text}",
+                    response=response,
+                )
+                raise err
+        except requests.RequestException as exc:
+            logger.error("Failed to send logs to Logstack: %s", exc)
+            if self.on_error:
+                self.on_error(exc, batch)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self._running = False
+        if self._flush_timer:
+            self._flush_timer.cancel()
+        self.flush()
+
+    def __enter__(self) -> "LogStackClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

logstack/middleware.py

@@ -0,0 +1,102 @@
+"""
+LogStack middleware for Django and FastAPI.
+"""
+
+import traceback
+from typing import Any, Callable, Optional
+
+from .client import LogStackClient
+
+
+class DjangoMiddleware:
+    """
+    Django middleware to automatically log unhandled exceptions.
+    """
+
+    def __init__(self, get_response: Callable, client: Optional[LogStackClient] = None):
+        self.get_response = get_response
+        self.client = client
+
+    def __call__(self, request):
+        try:
+            return self.get_response(request)
+        except Exception:
+            self._log_exception(request)
+            raise
+
+    def _log_exception(self, request) -> None:
+        if not self.client:
+            return
+
+        exc_type, exc_value, exc_traceback = traceback.exc_info()
+        traceback_str = "".join(
+            traceback.format_exception(exc_type, exc_value, exc_traceback)
+        )
+
+        metadata = {
+            "path": request.path,
+            "method": request.method,
+            "user": str(request.user) if hasattr(request, "user") else "anonymous",
+            "ip": self._get_client_ip(request),
+            "traceback": traceback_str,
+        }
+
+        self.client.error(
+            f"Unhandled exception in {request.path}",
+            metadata=metadata,
+        )
+
+    def _get_client_ip(self, request) -> str:
+        x_forwarded_for = request.META.get("HTTP_X_FORWARDED_FOR")
+        if x_forwarded_for:
+            return x_forwarded_for.split(",")[0].strip()
+        return request.META.get("REMOTE_ADDR", "")
+
+
+def create_fastapi_middleware(client: LogStackClient):
+    """
+    Return a Starlette-compatible middleware class that logs unhandled exceptions.
+    """
+
+    try:
+        from starlette.middleware.base import BaseHTTPMiddleware
+        from starlette.requests import Request
+        from starlette.responses import Response
+    except ImportError as exc:
+        raise ImportError(
+            "FastAPI/Starlette is required for create_fastapi_middleware. "
+            "Install with: pip install logstack-py[fastapi]"
+        ) from exc
+
+    class LogStackExceptionMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request: Request, call_next: Callable) -> Response:
+            try:
+                return await call_next(request)
+            except Exception as exc:
+                metadata = {
+                    "path": request.url.path,
+                    "method": request.method,
+                    "traceback": str(exc),
+                }
+                client.error(
+                    f"Unhandled exception in {request.url.path}",
+                    metadata=metadata,
+                )
+                raise
+
+    return LogStackExceptionMiddleware
+
+
+class FastAPIMiddleware:
+    """
+    Deprecated alias — use create_fastapi_middleware(client) instead.
+    """
+
+    def __init__(self, app, client: Optional[LogStackClient] = None):
+        if client is None:
+            raise ValueError("client is required for FastAPIMiddleware")
+        middleware_cls = create_fastapi_middleware(client)
+        self.app = middleware_cls(app)
+
+    async def __call__(self, scope, receive, send):
+        await self.app(scope, receive, send)

logstack_py-1.0.1.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: logstack-py
+Version: 1.0.1
+Summary: A Python SDK for the Logstack logging platform
+Home-page: https://github.com/Mosesedem/logstack
+Author: Mosesedem
+Author-email: Mosesedem <team@logstack.tech>
+License: MIT
+Project-URL: Homepage, https://github.com/Mosesedem/logstack
+Project-URL: Repository, https://github.com/Mosesedem/logstack
+Project-URL: Issues, https://github.com/Mosesedem/logstack/issues
+Keywords: logstack,logging,logs,monitoring,observability
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95.0; extra == "fastapi"
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Logstack Python SDK
+
+A Python SDK for the Logstack logging platform.
+
+## Installation
+
+```bash
+pip install logstack-py
+```
+
+## v1.0.1
+
+- Fix batch-flush deadlock when `batch_size` is reached
+- Normalize API URL (strips redundant `/v1` suffix)
+- Optional `on_error` callback; accepts HTTP 201 from ingest API
+- `create_fastapi_middleware(client)` for proper FastAPI/Starlette integration
+
+## Usage
+
+### Basic Usage
+
+```python
+from logstack import LogStackClient
+
+# Create a client
+client = LogStackClient(
+    api_key="your-api-key",
+    environment="production",
+)
+
+# Send logs
+client.info("Application started", metadata={"version": "1.0.0"})
+client.error("Database connection failed", metadata={"error": "connection refused"})
+
+# Flush and close
+client.close()
+```
+
+### Using Context Manager
+
+```python
+from logstack import LogStackClient
+
+with LogStackClient(api_key="your-api-key") as client:
+    client.info("Application started")
+    client.error("Something went wrong")
+```
+
+### Django Integration
+
+```python
+# settings.py
+MIDDLEWARE = [
+    # ...
+    'logstack.middleware.DjangoMiddleware',
+    # ...
+]
+
+# Or with custom client
+MIDDLEWARE = [
+    # ...
+    'logstack.middleware.DjangoMiddleware',
+    # ...
+]
+
+# In your code
+from logstack import DjangoMiddleware, LogStackClient
+
+client = LogStackClient(api_key="your-api-key")
+middleware = DjangoMiddleware(get_response, client=client)
+```
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from logstack import LogStackClient, FastAPIMiddleware
+
+app = FastAPI()
+client = LogStackClient(api_key="your-api-key")
+FastAPIMiddleware(app, client=client)
+```
+
+## API Reference
+
+### `LogStackClient(api_key, api_url="https://api.logstack.tech", environment="production", flush_interval=5.0, batch_size=100)`
+
+Create a new Logstack client.
+
+### `info(message, metadata=None)`
+
+Send an info level log.
+
+### `debug(message, metadata=None)`
+
+Send a debug level log.
+
+### `warn(message, metadata=None)`
+
+Send a warn level log.
+
+### `error(message, metadata=None)`
+
+Send an error level log.
+
+### `critical(message, metadata=None)`
+
+Send a critical level log.
+
+### `fatal(message, metadata=None)`
+
+Send a fatal level log and flush immediately.
+
+### `flush()`
+
+Manually flush the batch of logs.
+
+### `close()`
+
+Close the client and flush any pending logs.
+
+## License
+
+MIT

logstack_py-1.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+logstack/__init__.py,sha256=o57yeva2-FLcN3AiC5vJUaMqb9HZVSwdWmSNC1tA4QU,385
+logstack/client.py,sha256=G7mupxqyEWMjM2-gO24ZE6fvdPOQiDAxjkyuZgqISGo,4968
+logstack/middleware.py,sha256=RpGD6EYHG2ZsUX1hZ-XPqLi7r8hZquPs-KtVY6x4P2U,3189
+logstack_py-1.0.1.dist-info/licenses/LICENSE,sha256=mk8ItkvPbWO0HU8ePJP-ARQob65rKYUkpwe9daGGIys,1066
+logstack_py-1.0.1.dist-info/METADATA,sha256=N5m7Z2mlGdXB-yWJEVoj7uspkLjYVAklsrm_1-u82qE,3727
+logstack_py-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+logstack_py-1.0.1.dist-info/top_level.txt,sha256=mRSQZBXuD3C_9qQA3MWkQ_tg8-G1UMXG66aDZOJWAxc,9
+logstack_py-1.0.1.dist-info/RECORD,,

logstack_py-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

logstack_py-1.0.1.dist-info/licenses/LICENSE

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

logstack_py-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+logstack