watchup 0.1.0__py3-none-any.whl

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/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()

watchup/client.py

@@ -0,0 +1,249 @@
+"""
+watchup · main client
+"""
+
+from __future__ import annotations
+
+import os
+import traceback
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Literal, Optional
+
+from .batcher import Batcher
+from .transport import Transport
+from .types import ErrorPayload, EventPayload, TracePayload, WatchupUser
+
+_DEFAULTS = {
+    "base_url": "https://api.watchup.site",
+    "flush_interval": 5.0,
+    "max_batch_size": 100,
+    "debug": False,
+    "sample_rate": 1.0,
+    "release": None,
+}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class Watchup:
+    """
+    Watchup monitoring client.
+
+    Parameters
+    ----------
+    api_key : str
+        Your project API key (``wup_live_…``).
+    base_url : str
+        Override for self-hosted deployments.
+        Default: ``https://api.watchup.site``.
+    environment : str
+        Runtime label attached to every payload.
+        Default: ``WATCHUP_ENV`` env var, or ``"production"``.
+    release : str, optional
+        App version / git SHA for deploy correlation.
+    flush_interval : float
+        Seconds between automatic queue flushes. Default: ``5.0``.
+    max_batch_size : int
+        Item count per type that triggers an immediate flush. Default: ``100``.
+    sample_rate : float
+        Fraction of requests to trace (0–1). Default: ``1.0``.
+    debug : bool
+        Log SDK warnings to stderr. Default: ``False``.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULTS["base_url"],           # type: ignore[assignment]
+        environment: Optional[str] = None,
+        release: Optional[str] = None,
+        flush_interval: float = _DEFAULTS["flush_interval"],  # type: ignore[assignment]
+        max_batch_size: int = _DEFAULTS["max_batch_size"],    # type: ignore[assignment]
+        sample_rate: float = _DEFAULTS["sample_rate"],        # type: ignore[assignment]
+        debug: bool = _DEFAULTS["debug"],                     # type: ignore[assignment]
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "[watchup] api_key is required. "
+                "Find it in your Watchup dashboard → Project Settings → API Keys."
+            )
+
+        self.environment: str = (
+            environment
+            or os.environ.get("WATCHUP_ENV")
+            or os.environ.get("WATCHUP_ENVIRONMENT")
+            or "production"
+        )
+        self.release: Optional[str] = release
+        self._sample_rate = sample_rate
+
+        transport = Transport(base_url, api_key, debug)
+        self._batcher = Batcher(transport, flush_interval, max_batch_size)
+        self._batcher.start()
+
+        self._user: Optional[WatchupUser] = None
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _user_dict(self) -> Optional[Dict[str, Any]]:
+        return self._user.to_dict() if self._user else None
+
+    # ── User identification ───────────────────────────────────────────────────
+
+    def set_user(
+        self,
+        id: str | int,
+        *,
+        email: Optional[str] = None,
+        name: Optional[str] = None,
+        **extra: Any,
+    ) -> None:
+        """
+        Attach a user to all subsequent errors and traces.
+
+        Example::
+
+            watchup.set_user("usr_42", email="alice@example.com", name="Alice", plan="pro")
+        """
+        self._user = WatchupUser(id=id, email=email, name=name, extra=extra or None)
+
+    def clear_user(self) -> None:
+        """Remove the current user context."""
+        self._user = None
+
+    # ── Flask integration ─────────────────────────────────────────────────────
+
+    def init_app(self, app: Any) -> None:
+        """
+        Register Watchup on a Flask application instance.
+
+        Example::
+
+            app = Flask(__name__)
+            watchup.init_app(app)
+
+        Registers ``before_request``, ``after_request``, and ``errorhandler``
+        hooks automatically.
+        """
+        from .middleware import _flask_init_app
+        _flask_init_app(self, app)
+
+    # ── Manual tracking ───────────────────────────────────────────────────────
+
+    def track(self, name: str, properties: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Send a custom analytics event.
+
+        Example::
+
+            watchup.track("user.signed_up", {"plan": "pro", "source": "invite"})
+            watchup.track("order.placed", {"amount": 4999, "currency": "NGN"})
+        """
+        if not name:
+            return
+        event = EventPayload(
+            name=name,
+            occurred_at=_now(),
+            properties=properties or None,
+        )
+        self._batcher.add_event(event)
+
+    def capture_error(
+        self,
+        error: BaseException | str,
+        *,
+        route: Optional[str] = None,
+        level: Literal["debug", "info", "warning", "error", "fatal"] = "error",
+        **context: Any,
+    ) -> None:
+        """
+        Manually capture an error — use this for background jobs, queue
+        consumers, cron tasks, or anywhere outside a request context.
+
+        Example::
+
+            try:
+                process_order(order_id)
+            except Exception as exc:
+                watchup.capture_error(exc, route="job.process_order", order_id=order_id)
+        """
+        if isinstance(error, BaseException):
+            message = str(error)
+            stack = "".join(
+                traceback.format_exception(type(error), error, error.__traceback__)
+            )
+        else:
+            message = str(error)
+            stack = None
+
+        payload = ErrorPayload(
+            message=message,
+            level=level,
+            route=route,
+            stack=stack,
+            context=context or None,
+            timestamp=_now(),
+            environment=self.environment,
+            release=self.release,
+            user=self._user_dict(),
+        )
+        self._batcher.add_error(payload)
+
+    def start_trace(self, span: str) -> Callable[..., None]:
+        """
+        Time a non-HTTP operation and record it as a trace.
+
+        Returns an ``end()`` callable. Call it when the operation finishes.
+
+        Example::
+
+            end = watchup.start_trace("db.query_users")
+            try:
+                rows = db.query(sql)
+                end()                      # status defaults to "ok"
+            except Exception as exc:
+                end(status="err")
+                raise
+
+        The ``end()`` callable accepts optional keyword arguments:
+            - ``status``: ``"ok"`` (default), ``"warn"``, or ``"err"``
+            - ``meta``: arbitrary dict of extra context
+        """
+        import time as _time
+        start = _time.time()
+
+        def end(
+            *,
+            status: Literal["ok", "warn", "err"] = "ok",
+            meta: Optional[Dict[str, Any]] = None,
+        ) -> None:
+            ms = (_time.time() - start) * 1000
+            status_code = 500 if status == "err" else 400 if status == "warn" else 200
+            trace = TracePayload(
+                span=span,
+                ms=ms,
+                status_code=status_code,
+                status=status,
+                timestamp=_now(),
+                environment=self.environment,
+                release=self.release,
+                meta=meta,
+                user=self._user_dict(),
+            )
+            self._batcher.add_trace(trace)
+
+        return end
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def flush(self) -> None:
+        """Immediately flush all queued items."""
+        self._batcher.flush()
+
+    def shutdown(self) -> None:
+        """Stop the background flush timer and send remaining items."""
+        self._batcher.stop()
+        self._batcher.flush()

watchup/middleware.py

@@ -0,0 +1,255 @@
+"""
+watchup · middleware integrations
+
+Flask
+-----
+    from watchup import Watchup
+    watchup = Watchup(api_key="wup_live_...")
+    watchup.init_app(app)
+
+Django
+------
+    # settings.py
+    MIDDLEWARE = [
+        "watchup.middleware.WatchupDjangoMiddleware",
+        ...
+    ]
+    WATCHUP_API_KEY = "wup_live_..."
+
+WSGI (framework-agnostic)
+------
+    app.wsgi_app = WatchupWSGI(app.wsgi_app, watchup)
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import traceback
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional
+
+from .types import ErrorPayload, TracePayload
+
+if TYPE_CHECKING:
+    from .client import Watchup
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _trace_status(status_code: int) -> str:
+    if status_code >= 500:
+        return "err"
+    if status_code >= 400:
+        return "warn"
+    return "ok"
+
+
+def _normalise_path(path: str) -> str:
+    import re
+    path = re.sub(r"/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "/:id", path, flags=re.I)
+    path = re.sub(r"/\d+", "/:id", path)
+    return path.rstrip("/") or "/"
+
+
+# ── Flask integration ─────────────────────────────────────────────────────────
+
+def _flask_init_app(watchup_client: "Watchup", app: Any) -> None:
+    """Register Watchup before/after/teardown hooks on a Flask app."""
+    try:
+        from flask import g, request
+    except ImportError as exc:
+        raise ImportError(
+            "Flask is not installed. Run: pip install flask"
+        ) from exc
+
+    @app.before_request
+    def _before() -> None:
+        g._watchup_start = time.time()
+
+    @app.after_request
+    def _after(response: Any) -> Any:
+        start = getattr(g, "_watchup_start", None)
+        if start is None:
+            return response
+
+        ms = (time.time() - start) * 1000
+        route = request.endpoint or _normalise_path(request.path)
+        span = f"{request.method} {route}"
+
+        trace = TracePayload(
+            span=span,
+            ms=ms,
+            status_code=response.status_code,
+            status=_trace_status(response.status_code),  # type: ignore[arg-type]
+            timestamp=_now(),
+            environment=watchup_client.environment,
+            release=watchup_client.release,
+            user=watchup_client._user_dict(),
+        )
+        watchup_client._batcher.add_trace(trace)
+        return response
+
+    @app.errorhandler(Exception)
+    def _on_error(exc: Exception) -> Any:
+        error = ErrorPayload(
+            message=str(exc),
+            level="error",
+            route=f"{request.method} {_normalise_path(request.path)}",
+            stack=traceback.format_exc(),
+            context={
+                "method": request.method,
+                "url": request.url,
+            },
+            timestamp=_now(),
+            environment=watchup_client.environment,
+            release=watchup_client.release,
+            user=watchup_client._user_dict(),
+        )
+        watchup_client._batcher.add_error(error)
+        raise exc  # re-raise so Flask still handles it normally
+
+
+# ── Django middleware class ───────────────────────────────────────────────────
+
+class WatchupDjangoMiddleware:
+    """
+    Django middleware. Add to MIDDLEWARE in settings.py:
+
+        MIDDLEWARE = [
+            "watchup.middleware.WatchupDjangoMiddleware",
+            ...
+        ]
+
+    Requires WATCHUP_API_KEY in Django settings (or the WATCHUP_API_KEY env var).
+    Optionally set WATCHUP_ENVIRONMENT and WATCHUP_RELEASE in Django settings.
+    """
+
+    _instance: Optional["Watchup"] = None
+
+    def __init__(self, get_response: Callable) -> None:
+        self.get_response = get_response
+        if WatchupDjangoMiddleware._instance is None:
+            from django.conf import settings as django_settings
+            from .client import Watchup
+
+            api_key = (
+                getattr(django_settings, "WATCHUP_API_KEY", None)
+                or os.environ.get("WATCHUP_API_KEY", "")
+            )
+            environment = (
+                getattr(django_settings, "WATCHUP_ENVIRONMENT", None)
+                or os.environ.get("WATCHUP_ENVIRONMENT", "production")
+            )
+            release = getattr(django_settings, "WATCHUP_RELEASE", None)
+            WatchupDjangoMiddleware._instance = Watchup(
+                api_key=api_key,
+                environment=environment,
+                release=release,
+            )
+
+    def __call__(self, request: Any) -> Any:
+        start = time.time()
+        try:
+            response = self.get_response(request)
+        except Exception as exc:
+            client = WatchupDjangoMiddleware._instance
+            if client:
+                error = ErrorPayload(
+                    message=str(exc),
+                    level="error",
+                    route=f"{request.method} {_normalise_path(request.path)}",
+                    stack=traceback.format_exc(),
+                    context={"method": request.method, "path": request.path},
+                    timestamp=_now(),
+                    environment=client.environment,
+                    release=client.release,
+                    user=client._user_dict(),
+                )
+                client._batcher.add_error(error)
+            raise
+
+        ms = (time.time() - start) * 1000
+        client = WatchupDjangoMiddleware._instance
+        if client:
+            route = getattr(getattr(request, "resolver_match", None), "route", None)
+            span = f"{request.method} {route or _normalise_path(request.path)}"
+            trace = TracePayload(
+                span=span,
+                ms=ms,
+                status_code=response.status_code,
+                status=_trace_status(response.status_code),  # type: ignore[arg-type]
+                timestamp=_now(),
+                environment=client.environment,
+                release=client.release,
+                user=client._user_dict(),
+            )
+            client._batcher.add_trace(trace)
+        return response
+
+
+# ── WSGI middleware (framework-agnostic) ──────────────────────────────────────
+
+class WatchupWSGI:
+    """
+    WSGI middleware wrapper — works with any WSGI framework.
+
+    Example (Flask):
+        app.wsgi_app = WatchupWSGI(app.wsgi_app, watchup)
+
+    Example (bare WSGI):
+        application = WatchupWSGI(application, watchup)
+    """
+
+    def __init__(self, wsgi_app: Callable, watchup_client: "Watchup") -> None:
+        self._app = wsgi_app
+        self._client = watchup_client
+
+    def __call__(self, environ: Dict, start_response: Callable) -> Any:
+        start = time.time()
+        status_holder: list = []
+
+        def _start_response(status: str, headers: Any, exc_info: Any = None) -> Any:
+            status_holder.append(int(status.split(" ", 1)[0]))
+            return start_response(status, headers, exc_info)
+
+        try:
+            result = self._app(environ, _start_response)
+        except Exception as exc:
+            ms = (time.time() - start) * 1000
+            path = environ.get("PATH_INFO", "/")
+            method = environ.get("REQUEST_METHOD", "GET")
+            error = ErrorPayload(
+                message=str(exc),
+                level="error",
+                route=f"{method} {_normalise_path(path)}",
+                stack=traceback.format_exc(),
+                context={"method": method, "path": path},
+                timestamp=_now(),
+                environment=self._client.environment,
+                release=self._client.release,
+                user=self._client._user_dict(),
+            )
+            self._client._batcher.add_error(error)
+            raise
+
+        ms = (time.time() - start) * 1000
+        status_code = status_holder[0] if status_holder else 200
+        path = environ.get("PATH_INFO", "/")
+        method = environ.get("REQUEST_METHOD", "GET")
+        trace = TracePayload(
+            span=f"{method} {_normalise_path(path)}",
+            ms=ms,
+            status_code=status_code,
+            status=_trace_status(status_code),  # type: ignore[arg-type]
+            timestamp=_now(),
+            environment=self._client.environment,
+            release=self._client.release,
+            user=self._client._user_dict(),
+        )
+        self._client._batcher.add_trace(trace)
+        return result

watchup/transport.py

@@ -0,0 +1,57 @@
+"""
+watchup · HTTP transport
+
+Posts ingest batches to the Watchup API. All failures are swallowed —
+the SDK must never crash the host application.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from typing import Any, Dict
+
+from .types import IngestBatch
+
+log = logging.getLogger("watchup")
+
+
+class Transport:
+    def __init__(self, base_url: str, api_key: str, debug: bool = False) -> None:
+        self._url = f"{base_url.rstrip('/')}/api/v1/ingest/batch"
+        self._headers = {
+            "Content-Type": "application/json",
+            "X-Api-Key": api_key,
+            "User-Agent": "watchup-python",
+        }
+        self._debug = debug
+
+    def send(self, batch: IngestBatch) -> None:
+        payload: Dict[str, Any] = {}
+        if batch.traces:
+            payload["traces"] = [t.to_dict() for t in batch.traces]
+        if batch.errors:
+            payload["errors"] = [e.to_dict() for e in batch.errors]
+        if batch.events:
+            payload["events"] = [ev.to_dict() for ev in batch.events]
+
+        if not payload:
+            return
+
+        try:
+            body = json.dumps(payload).encode()
+            req = urllib.request.Request(
+                self._url,
+                data=body,
+                headers=self._headers,
+                method="POST",
+            )
+            with urllib.request.urlopen(req, timeout=8) as resp:
+                if self._debug and resp.status >= 400:
+                    log.warning("[watchup] ingest %s", resp.status)
+        except Exception as exc:
+            if self._debug:
+                log.warning("[watchup] send failed: %s", exc)
+            # Intentionally no re-raise.

watchup/types.py

@@ -0,0 +1,116 @@
+"""
+watchup · payload types
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional
+
+
+# ── User ──────────────────────────────────────────────────────────────────────
+
+@dataclass
+class WatchupUser:
+    id: str | int
+    email: Optional[str] = None
+    name: Optional[str] = None
+    extra: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"id": self.id}
+        if self.email is not None:
+            d["email"] = self.email
+        if self.name is not None:
+            d["name"] = self.name
+        if self.extra:
+            d.update(self.extra)
+        return d
+
+
+# ── Ingest payloads ───────────────────────────────────────────────────────────
+
+@dataclass
+class TracePayload:
+    span: str
+    ms: float
+    status_code: int
+    status: Literal["ok", "warn", "err"]
+    timestamp: str
+    environment: Optional[str] = None
+    release: Optional[str] = None
+    meta: Optional[Dict[str, Any]] = None
+    user: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "span": self.span,
+            "ms": round(self.ms, 2),
+            "status_code": self.status_code,
+            "status": self.status,
+            "timestamp": self.timestamp,
+        }
+        if self.environment is not None:
+            d["environment"] = self.environment
+        if self.release is not None:
+            d["release"] = self.release
+        if self.meta:
+            d["meta"] = self.meta
+        if self.user:
+            d["user"] = self.user
+        return d
+
+
+@dataclass
+class ErrorPayload:
+    message: str
+    level: Literal["debug", "info", "warning", "error", "fatal"]
+    timestamp: str
+    route: Optional[str] = None
+    stack: Optional[str] = None
+    context: Optional[Dict[str, Any]] = None
+    environment: Optional[str] = None
+    release: Optional[str] = None
+    user: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "message": self.message,
+            "level": self.level,
+            "timestamp": self.timestamp,
+        }
+        if self.route is not None:
+            d["route"] = self.route
+        if self.stack is not None:
+            d["stack"] = self.stack
+        if self.context:
+            d["context"] = self.context
+        if self.environment is not None:
+            d["environment"] = self.environment
+        if self.release is not None:
+            d["release"] = self.release
+        if self.user:
+            d["user"] = self.user
+        return d
+
+
+@dataclass
+class EventPayload:
+    name: str
+    occurred_at: str
+    properties: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"name": self.name, "occurred_at": self.occurred_at}
+        if self.properties:
+            d["properties"] = self.properties
+        return d
+
+
+# ── Batch ─────────────────────────────────────────────────────────────────────
+
+@dataclass
+class IngestBatch:
+    traces: List[TracePayload] = field(default_factory=list)
+    errors: List[ErrorPayload] = field(default_factory=list)
+    events: List[EventPayload] = field(default_factory=list)

watchup-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+watchup/__init__.py,sha256=MWTtlFu61AtpQK-i7mq_uwANPIFsmdJjxgwx1FmOato,617
+watchup/batcher.py,sha256=OCSmiQtdOF19lBvvlW1opmjC3apOsGPF7h_XI15AgkU,3564
+watchup/client.py,sha256=A4vrJYfFIFmVM8rDF6HFh0Jhw5wxLnpLjOE4BuK36rk,8366
+watchup/middleware.py,sha256=AABaqxN8w6M95vbZiqKzLLAIqSoglyvaLHdcxcw6cLo,8852
+watchup/transport.py,sha256=tsdYxAAgqwirRWDA-I--ljPLdpSmfjsXem_cgzVoSHo,1719
+watchup/types.py,sha256=YXvG40-WK1MQ7ji_hWf2LqtjE8WBjKM65MO8F92BsTs,3678
+watchup-0.1.0.dist-info/METADATA,sha256=-7SJVC8hVhBGoMUFQS78H7cyT0Z7eah8SGwxSFbYGaQ,6816
+watchup-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+watchup-0.1.0.dist-info/top_level.txt,sha256=BKuy0-hljNjMZG9ug8r0akTV2bfT6EYT24SQRirXOT4,8
+watchup-0.1.0.dist-info/RECORD,,

watchup-0.1.0.dist-info/WHEEL

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

watchup-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+watchup