watchup 0.1.0__tar.gz

watchup-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: watchup
+Version: 0.1.0
+Summary: Official Watchup SDK for Python — error tracking, request tracing, and custom analytics
+Author: Watchup Ltd
+License: MIT
+Project-URL: Homepage, https://watchup.site
+Project-URL: Documentation, https://watchup.site/docs/sdks/python
+Project-URL: Repository, https://github.com/watchupltd/watchup-sdk
+Project-URL: Issues, https://github.com/watchupltd/watchup-sdk/issues
+Keywords: watchup,monitoring,observability,apm,tracing,error-tracking,flask,django,fastapi
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: flask>=2.0; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+
+# watchup
+
+Official Python SDK for [Watchup](https://watchup.site) — error tracking, request tracing, and custom analytics for Python web applications.
+
+Works with **Flask**, **Django**, **FastAPI**, and any **WSGI** framework. Zero required dependencies — uses the Python standard library only.
+
+---
+
+## Installation
+
+```bash
+pip install watchup
+```
+
+Requires Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+from watchup import Watchup
+
+watchup = Watchup(
+    api_key="wup_live_xxxxxxxxxxxx",   # Dashboard → Project Settings → API Keys
+    environment="production",
+    release="v1.2.3",                  # optional: git SHA or version tag
+)
+```
+
+---
+
+## Flask
+
+```python
+from flask import Flask
+from watchup import Watchup
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+app = Flask(__name__)
+
+watchup.init_app(app)   # registers before_request, after_request, errorhandler hooks
+```
+
+`init_app` wires up:
+
+- **Request tracing** — every request is recorded with method, route, status code, and duration
+- **Error capture** — unhandled exceptions are reported with stack trace and request context
+- **Transparent re-raise** — errors still propagate to your own error handlers
+
+---
+
+## Django
+
+Add `WatchupDjangoMiddleware` to your `MIDDLEWARE` list and set `WATCHUP_API_KEY` in `settings.py`:
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "watchup.WatchupDjangoMiddleware",
+    # ... rest of your middleware
+]
+
+WATCHUP_API_KEY     = "wup_live_xxxxxxxxxxxx"
+WATCHUP_ENVIRONMENT = "production"  # optional
+WATCHUP_RELEASE     = "v1.2.3"     # optional
+```
+
+The middleware initialises the client once on first request and reuses it for the lifetime of the process.
+
+---
+
+## FastAPI / Starlette
+
+Use the WSGI wrapper or instrument manually with `before` / `after` logic via Starlette middleware:
+
+```python
+from fastapi import FastAPI, Request
+from watchup import Watchup
+import time
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+app = FastAPI()
+
+@app.middleware("http")
+async def watchup_middleware(request: Request, call_next):
+    start = time.time()
+    response = await call_next(request)
+    ms = (time.time() - start) * 1000
+    # record trace manually
+    end = watchup.start_trace(f"{request.method} {request.url.path}")
+    end()
+    return response
+```
+
+---
+
+## WSGI middleware (framework-agnostic)
+
+```python
+from watchup import Watchup, WatchupWSGI
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+
+# Flask example
+from flask import Flask
+flask_app = Flask(__name__)
+flask_app.wsgi_app = WatchupWSGI(flask_app.wsgi_app, watchup)
+
+# Any WSGI app
+application = WatchupWSGI(application, watchup)
+```
+
+---
+
+## Manual tracking
+
+### Capture an error
+
+```python
+try:
+    process_order(order_id)
+except Exception as exc:
+    watchup.capture_error(exc, route="job.process_order", order_id=order_id)
+```
+
+### Track a custom event
+
+```python
+watchup.track("user.signed_up", {"plan": "pro", "source": "invite"})
+watchup.track("order.placed", {"amount": 4999, "currency": "NGN"})
+```
+
+### Time an operation
+
+```python
+end = watchup.start_trace("db.query_users")
+try:
+    rows = db.query("SELECT * FROM users")
+    end()                       # status defaults to "ok"
+except Exception as exc:
+    end(status="err", meta={"query": "SELECT * FROM users"})
+    raise
+```
+
+---
+
+## User identification
+
+Attach user identity to errors and traces:
+
+```python
+# After authentication — in a middleware or login view
+watchup.set_user("usr_42", email="alice@example.com", name="Alice", plan="pro")
+
+# On logout
+watchup.clear_user()
+```
+
+Once set, every `capture_error`, `start_trace`, and request trace will include the user context.
+
+---
+
+## Configuration reference
+
+| Parameter | Default | Description |
+|---|---|---|
+| `api_key` | *(required)* | Project API key (`wup_live_…`) |
+| `base_url` | `https://api.watchup.site` | Override for self-hosted deployments |
+| `environment` | `WATCHUP_ENV` env var, or `"production"` | Runtime label on every payload |
+| `release` | `None` | App version / git SHA |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+| `max_batch_size` | `100` | Item count that triggers an immediate flush |
+| `sample_rate` | `1.0` | Fraction of requests to trace (0–1) |
+| `debug` | `False` | Log SDK warnings to stderr |
+
+---
+
+## Lifecycle
+
+```python
+# Force an immediate flush
+watchup.flush()
+
+# Stop the background timer and flush remaining items (graceful shutdown)
+watchup.shutdown()
+```
+
+The batcher runs on a daemon thread and registers an `atexit` handler, so queued items are flushed automatically when the process exits normally.
+
+---
+
+## Links
+
+- **Website:** [watchup.site](https://watchup.site)
+- **Documentation:** [watchup.site/docs](https://watchup.site/docs)
+- **Python SDK docs:** [watchup.site/docs/sdks/python](https://watchup.site/docs/sdks/python)
+- **Getting started:** [watchup.site/docs/getting-started](https://watchup.site/docs/getting-started)
+- **Pricing:** [watchup.site/pricing](https://watchup.site/pricing)
+- **Dashboard:** [app.watchup.site](https://watchup.site/login)
+
+---
+
+## License
+
+MIT © Watchup Ltd

watchup-0.1.0/README.md

@@ -0,0 +1,206 @@
+# watchup
+
+Official Python SDK for [Watchup](https://watchup.site) — error tracking, request tracing, and custom analytics for Python web applications.
+
+Works with **Flask**, **Django**, **FastAPI**, and any **WSGI** framework. Zero required dependencies — uses the Python standard library only.
+
+---
+
+## Installation
+
+```bash
+pip install watchup
+```
+
+Requires Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+from watchup import Watchup
+
+watchup = Watchup(
+    api_key="wup_live_xxxxxxxxxxxx",   # Dashboard → Project Settings → API Keys
+    environment="production",
+    release="v1.2.3",                  # optional: git SHA or version tag
+)
+```
+
+---
+
+## Flask
+
+```python
+from flask import Flask
+from watchup import Watchup
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+app = Flask(__name__)
+
+watchup.init_app(app)   # registers before_request, after_request, errorhandler hooks
+```
+
+`init_app` wires up:
+
+- **Request tracing** — every request is recorded with method, route, status code, and duration
+- **Error capture** — unhandled exceptions are reported with stack trace and request context
+- **Transparent re-raise** — errors still propagate to your own error handlers
+
+---
+
+## Django
+
+Add `WatchupDjangoMiddleware` to your `MIDDLEWARE` list and set `WATCHUP_API_KEY` in `settings.py`:
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "watchup.WatchupDjangoMiddleware",
+    # ... rest of your middleware
+]
+
+WATCHUP_API_KEY     = "wup_live_xxxxxxxxxxxx"
+WATCHUP_ENVIRONMENT = "production"  # optional
+WATCHUP_RELEASE     = "v1.2.3"     # optional
+```
+
+The middleware initialises the client once on first request and reuses it for the lifetime of the process.
+
+---
+
+## FastAPI / Starlette
+
+Use the WSGI wrapper or instrument manually with `before` / `after` logic via Starlette middleware:
+
+```python
+from fastapi import FastAPI, Request
+from watchup import Watchup
+import time
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+app = FastAPI()
+
+@app.middleware("http")
+async def watchup_middleware(request: Request, call_next):
+    start = time.time()
+    response = await call_next(request)
+    ms = (time.time() - start) * 1000
+    # record trace manually
+    end = watchup.start_trace(f"{request.method} {request.url.path}")
+    end()
+    return response
+```
+
+---
+
+## WSGI middleware (framework-agnostic)
+
+```python
+from watchup import Watchup, WatchupWSGI
+
+watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+
+# Flask example
+from flask import Flask
+flask_app = Flask(__name__)
+flask_app.wsgi_app = WatchupWSGI(flask_app.wsgi_app, watchup)
+
+# Any WSGI app
+application = WatchupWSGI(application, watchup)
+```
+
+---
+
+## Manual tracking
+
+### Capture an error
+
+```python
+try:
+    process_order(order_id)
+except Exception as exc:
+    watchup.capture_error(exc, route="job.process_order", order_id=order_id)
+```
+
+### Track a custom event
+
+```python
+watchup.track("user.signed_up", {"plan": "pro", "source": "invite"})
+watchup.track("order.placed", {"amount": 4999, "currency": "NGN"})
+```
+
+### Time an operation
+
+```python
+end = watchup.start_trace("db.query_users")
+try:
+    rows = db.query("SELECT * FROM users")
+    end()                       # status defaults to "ok"
+except Exception as exc:
+    end(status="err", meta={"query": "SELECT * FROM users"})
+    raise
+```
+
+---
+
+## User identification
+
+Attach user identity to errors and traces:
+
+```python
+# After authentication — in a middleware or login view
+watchup.set_user("usr_42", email="alice@example.com", name="Alice", plan="pro")
+
+# On logout
+watchup.clear_user()
+```
+
+Once set, every `capture_error`, `start_trace`, and request trace will include the user context.
+
+---
+
+## Configuration reference
+
+| Parameter | Default | Description |
+|---|---|---|
+| `api_key` | *(required)* | Project API key (`wup_live_…`) |
+| `base_url` | `https://api.watchup.site` | Override for self-hosted deployments |
+| `environment` | `WATCHUP_ENV` env var, or `"production"` | Runtime label on every payload |
+| `release` | `None` | App version / git SHA |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+| `max_batch_size` | `100` | Item count that triggers an immediate flush |
+| `sample_rate` | `1.0` | Fraction of requests to trace (0–1) |
+| `debug` | `False` | Log SDK warnings to stderr |
+
+---
+
+## Lifecycle
+
+```python
+# Force an immediate flush
+watchup.flush()
+
+# Stop the background timer and flush remaining items (graceful shutdown)
+watchup.shutdown()
+```
+
+The batcher runs on a daemon thread and registers an `atexit` handler, so queued items are flushed automatically when the process exits normally.
+
+---
+
+## Links
+
+- **Website:** [watchup.site](https://watchup.site)
+- **Documentation:** [watchup.site/docs](https://watchup.site/docs)
+- **Python SDK docs:** [watchup.site/docs/sdks/python](https://watchup.site/docs/sdks/python)
+- **Getting started:** [watchup.site/docs/getting-started](https://watchup.site/docs/getting-started)
+- **Pricing:** [watchup.site/pricing](https://watchup.site/pricing)
+- **Dashboard:** [app.watchup.site](https://watchup.site/login)
+
+---
+
+## License
+
+MIT © Watchup Ltd

watchup-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watchup"
+version = "0.1.0"
+description = "Official Watchup SDK for Python — error tracking, request tracing, and custom analytics"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Watchup Ltd" }]
+requires-python = ">=3.9"
+keywords = [
+  "watchup",
+  "monitoring",
+  "observability",
+  "apm",
+  "tracing",
+  "error-tracking",
+  "flask",
+  "django",
+  "fastapi",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Monitoring",
+]
+
+# No required dependencies — stdlib only.
+# Framework integrations (Flask, Django) import lazily and raise ImportError
+# with a helpful message if the framework is not installed.
+dependencies = []
+
+[project.optional-dependencies]
+flask   = ["flask>=2.0"]
+django  = ["django>=3.2"]
+fastapi = ["fastapi>=0.95", "starlette>=0.27"]
+dev     = ["pytest>=8", "flask>=2.0", "responses>=0.25"]
+
+[project.urls]
+Homepage      = "https://watchup.site"
+Documentation = "https://watchup.site/docs/sdks/python"
+Repository    = "https://github.com/watchupltd/watchup-sdk"
+Issues        = "https://github.com/watchupltd/watchup-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["watchup*"]

watchup-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

watchup-0.1.0/watchup/__init__.py

@@ -0,0 +1,28 @@
+"""
+watchup — application monitoring SDK for Python
+
+Quick start::
+
+    from watchup import Watchup
+
+    watchup = Watchup(api_key="wup_live_xxxxxxxxxxxx")
+
+    # Flask
+    watchup.init_app(app)
+
+    # Manual error capture
+    watchup.capture_error(exc, route="job.process_order")
+
+    # Custom events
+    watchup.track("user.signed_up", {"plan": "pro"})
+
+    # Trace any operation
+    end = watchup.start_trace("db.query")
+    end()
+"""
+
+from .client import Watchup
+from .middleware import WatchupDjangoMiddleware, WatchupWSGI
+
+__all__ = ["Watchup", "WatchupDjangoMiddleware", "WatchupWSGI"]
+__version__ = "0.1.0"

watchup-0.1.0/watchup/batcher.py

@@ -0,0 +1,105 @@
+"""
+watchup · batcher
+
+Accumulates traces/errors/events and flushes them in batches via a
+background daemon thread. The thread is daemonised so it never prevents
+the interpreter from exiting.
+"""
+
+from __future__ import annotations
+
+import atexit
+import threading
+from typing import List
+
+from .transport import Transport
+from .types import ErrorPayload, EventPayload, IngestBatch, TracePayload
+
+
+class Batcher:
+    def __init__(
+        self,
+        transport: Transport,
+        flush_interval: float,
+        max_batch_size: int,
+    ) -> None:
+        self._transport = transport
+        self._flush_interval = flush_interval
+        self._max_batch_size = max_batch_size
+
+        self._lock = threading.Lock()
+        self._traces: List[TracePayload] = []
+        self._errors: List[ErrorPayload] = []
+        self._events: List[EventPayload] = []
+
+        self._timer: threading.Timer | None = None
+        self._started = False
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        self._schedule()
+        atexit.register(self.flush)
+
+    def stop(self) -> None:
+        self._started = False
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _schedule(self) -> None:
+        if not self._started:
+            return
+        self._timer = threading.Timer(self._flush_interval, self._tick)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _tick(self) -> None:
+        self.flush()
+        self._schedule()
+
+    # ── Enqueue ───────────────────────────────────────────────────────────────
+
+    def add_trace(self, trace: TracePayload) -> None:
+        with self._lock:
+            self._traces.append(trace)
+            should_flush = len(self._traces) >= self._max_batch_size
+        if should_flush:
+            self.flush()
+
+    def add_error(self, error: ErrorPayload) -> None:
+        with self._lock:
+            self._errors.append(error)
+            # Errors are higher priority — flush at half capacity
+            should_flush = len(self._errors) >= max(1, self._max_batch_size // 2)
+        if should_flush:
+            self.flush()
+
+    def add_event(self, event: EventPayload) -> None:
+        with self._lock:
+            self._events.append(event)
+            should_flush = len(self._events) >= self._max_batch_size
+        if should_flush:
+            self.flush()
+
+    # ── Flush ─────────────────────────────────────────────────────────────────
+
+    def flush(self) -> None:
+        with self._lock:
+            traces = self._traces[:]
+            errors = self._errors[:]
+            events = self._events[:]
+            self._traces.clear()
+            self._errors.clear()
+            self._events.clear()
+
+        if not traces and not errors and not events:
+            return
+
+        batch = IngestBatch(traces=traces, errors=errors, events=events)
+        # Run in a daemon thread so it never blocks the caller
+        t = threading.Thread(target=self._transport.send, args=(batch,), daemon=True)
+        t.start()