sdk-garden-python 0.1.0__py3-none-any.whl

sdk_garden/__init__.py

@@ -0,0 +1,3 @@
+from sdk_garden.client import SdkGarden
+
+__all__ = ["SdkGarden"]

sdk_garden/client.py

@@ -0,0 +1,287 @@
+"""
+sdk_garden.client — Lightweight SDK observability client for Python.
+
+Stdlib only, non-blocking, zero runtime dependencies.
+Events are queued on the caller's thread and flushed in batches by a daemon thread.
+All network errors are caught and discarded — no exception ever reaches the caller.
+"""
+
+import functools
+import json
+import platform
+import queue
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ---------------------------------------------------------------------------
+# Module-level constants
+# ---------------------------------------------------------------------------
+
+_DEFAULT_ENDPOINT = "https://ingest.sdkgarden.dev/track"
+
+#: Maximum number of events sent in one HTTP POST.
+_BATCH_SIZE = 10  # Claude's Discretion — per CONTEXT.md
+
+#: Seconds the daemon thread sleeps between flush cycles.
+_FLUSH_INTERVAL = 5.0  # seconds — Claude's Discretion
+
+#: HTTP request timeout in seconds. Locked by CLIENT-02.
+_HTTP_TIMEOUT = 2  # seconds — locked by CLIENT-02
+
+#: Email-address PII pattern ported verbatim from sdk-garden.js lines 174-177.
+#: When this module was imported: the default start of the host SDK's init.
+_MODULE_LOADED_AT = time.time()
+
+_PII_PATTERN = re.compile(
+    r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"
+)
+
+
+class SdkGarden:
+    """Non-blocking SDK observability client — stdlib only.
+
+    Instantiate and call `.start()` to begin flushing:
+
+        sg = SdkGarden(api_key="sgk_...", sdk_name="my-sdk", sdk_version="1.0.0").start()
+
+    ``start()`` sends the ``sdk_initialized`` event (runtime, Python version and
+    ``time_to_init_ms``) for you.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        sdk_name: str,
+        sdk_version: str,
+        endpoint: str = _DEFAULT_ENDPOINT,
+        debug: bool = False,
+        disabled: bool = False,
+        batch_size: int = _BATCH_SIZE,
+        flush_interval: float = _FLUSH_INTERVAL,
+        started_at: Optional[float] = None,
+    ) -> None:
+        """Create a client. Nothing is sent until ``start()``.
+
+        ``started_at`` is when your SDK began initializing, as ``time.time()``;
+        ``start()`` reports the difference as ``time_to_init_ms``. Defaults to
+        when sdk_garden was imported.
+        """
+        self._api_key = api_key
+        self._sdk_name = sdk_name
+        self._sdk_version = sdk_version
+        self._endpoint = endpoint
+        self._debug = debug
+        self._disabled = disabled
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+        self._started_at = started_at if started_at is not None else _MODULE_LOADED_AT
+
+        #: True once start() has sent sdk_initialized for this session.
+        self._init_sent = False
+
+        #: Thread-safe event queue. maxsize=100 locked by D-04/D-05.
+        self._queue: queue.Queue = queue.Queue(maxsize=100)
+
+        #: Per-instance session identifier (UUID4).
+        self._session_id: str = str(uuid.uuid4())
+
+        #: Daemon flush thread — None until start() is called.
+        self._thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> "SdkGarden":
+        """Spawn the daemon flush thread and return self for chaining.
+
+        When disabled=True, returns immediately without spawning a thread.
+        Idempotent — subsequent calls while the thread is alive are no-ops.
+        """
+        if self._disabled:
+            return self
+        if self._thread is not None and self._thread.is_alive():
+            return self
+        if not self._init_sent:
+            self.track(
+                "sdk_initialized",
+                {
+                    "environment": self._get_environment(),
+                    "time_to_init_ms": max(0, int((time.time() - self._started_at) * 1000)),
+                },
+            )
+            self._init_sent = True
+        self._thread = threading.Thread(target=self._flush_loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def track(
+        self,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Enqueue a named event.
+
+        Silently discards if the queue is full (D-05) or disabled.
+        Never blocks the caller.
+        """
+        if self._disabled:
+            return
+        if event_name == "sdk_initialized" and self._init_sent:
+            # start() already reported it; a manual call (as older docs
+            # suggested) would double-count the session.
+            return
+        event = {
+            "event": event_name,
+            "sdk": {"name": self._sdk_name, "version": self._sdk_version},
+            "session_id": self._session_id,
+            "timestamp": int(time.time() * 1000),
+            "properties": properties or {},
+            "meta": {},
+        }
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            pass  # Silent discard — locked by D-05, never blocks caller
+
+    def track_method(self, method_name: str) -> Callable[[F], F]:
+        """Return a decorator that wraps a function with method-call telemetry.
+
+        Always enqueues a ``method_called`` event before the call.
+        On success: also enqueues a ``method_success`` event with ``duration_ms``.
+        On exception: enqueues an ``sdk_error`` event with PII-scrubbed message
+        and re-raises the original exception.
+
+        When disabled, the original function is returned unwrapped.
+        """
+        if self._disabled:
+            def _noop_decorator(fn: F) -> F:
+                return fn
+
+            return _noop_decorator  # type: ignore[return-value]
+
+        def decorator(fn: F) -> F:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                start = time.time()
+                self.track(
+                    "method_called",
+                    {"method": method_name, "args_count": len(args)},
+                )
+                try:
+                    result = fn(*args, **kwargs)
+                    duration_ms = int((time.time() - start) * 1000)
+                    self.track(
+                        "method_success",
+                        {
+                            "method": method_name,
+                            "duration_ms": duration_ms,
+                        },
+                    )
+                    return result
+                except Exception as exc:
+                    duration_ms = int((time.time() - start) * 1000)
+                    self.track_error(exc, {"method": method_name, "duration_ms": duration_ms})
+                    raise
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorator  # type: ignore[return-value]
+
+    def track_error(
+        self,
+        error: Exception,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Enqueue an ``sdk_error`` event with PII-scrubbed error message.
+
+        Silently discards if disabled.
+        """
+        if self._disabled:
+            return
+        props: Dict[str, Any] = {
+            "error_message": self._scrub_pii(str(error)),
+            "error_type": type(error).__name__,
+        }
+        if context:
+            props.update(context)
+        self.track("sdk_error", props)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _flush_loop(self) -> None:
+        """Daemon thread target — wakes every flush_interval and drains the queue."""
+        while True:
+            self._flush_batch()
+            time.sleep(self._flush_interval)
+
+    def _flush_batch(self) -> None:
+        """Drain up to batch_size events from the queue and POST them.
+
+        Silent on all network errors (Pitfall 5: broad except required because
+        socket.timeout is not a subclass of urllib.error.URLError).
+        """
+        events = []
+        try:
+            while len(events) < self._batch_size:
+                events.append(self._queue.get_nowait())
+        except queue.Empty:
+            pass
+
+        if not events:
+            return  # Nothing to flush — no HTTP call
+
+        try:
+            payload = json.dumps(
+                {
+                    "api_key": self._api_key,
+                    "events": events,
+                }
+            ).encode("utf-8")
+            req = urllib.request.Request(
+                self._endpoint,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT)
+        except Exception:
+            pass  # Silent failure — ALL exceptions swallowed (Pitfall 5)
+
+    def _scrub_pii(self, s: Any) -> Any:
+        """Replace email addresses in a string with '[REDACTED]'.
+
+        Non-string values are returned unchanged.
+        Ported verbatim from sdk-garden.js lines 174-177.
+        """
+        if not isinstance(s, str):
+            return s
+        return _PII_PATTERN.sub("[REDACTED]", s)
+
+    def _log(self, *args: Any) -> None:
+        """Print a debug message when debug=True.
+
+        NEVER pass self._api_key directly to this method.
+        """
+        if self._debug:
+            print("[SDK Garden]", *args)
+
+    def _get_environment(self) -> Dict[str, str]:
+        """Return runtime environment metadata for the sdk_initialized event."""
+        return {
+            "runtime": platform.python_implementation().lower(),
+            "runtime_version": platform.python_version(),
+        }
+
+    def _generate_session_id(self) -> str:
+        """Generate a random UUID4 session identifier."""
+        return str(uuid.uuid4())

sdk_garden_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: sdk-garden-python
+Version: 0.1.0
+Summary: Lightweight SDK observability client for Python — stdlib only, non-blocking
+Project-URL: Homepage, https://sdkgarden.dev
+Project-URL: Repository, https://github.com/tjb/SDKGarden
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# sdk-garden-python
+*Lightweight SDK observability client for Python — stdlib only, non-blocking*
+
+Add SDK Garden telemetry to your Python SDK in minutes. Events are sent on a background daemon thread — your users never see a delay or an exception from the instrumentation layer.
+
+## Install
+
+```bash
+pip install sdk-garden-python
+```
+
+## Quick Start
+
+```python
+from sdk_garden import SdkGarden
+
+sg = SdkGarden(api_key="YOUR_API_KEY", sdk_name="my-sdk", sdk_version="1.0.0").start()
+
+@sg.track_method("process_payment")
+def process_payment(amount):
+    ...
+```
+
+Track arbitrary events:
+
+```python
+sg.track("feature_used", properties={"feature": "streaming"})
+```
+
+Track errors with automatic PII scrubbing:
+
+```python
+try:
+    process_payment(100)
+except Exception as e:
+    sg.track_error(e)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your SDK Garden API key (`sgk_...`) |
+| `sdk_name` | `str` | required | Name of your SDK (e.g. `"my-payments-sdk"`) |
+| `sdk_version` | `str` | required | Version of your SDK (e.g. `"1.2.3"`) |
+| `endpoint` | `str` | `https://ingest.sdkgarden.dev/track` | Ingest endpoint URL |
+| `debug` | `bool` | `False` | Print `[SDK Garden]` debug lines to stdout |
+| `disabled` | `bool` | `False` | Disable all tracking (no thread spawned, no network calls) |
+| `batch_size` | `int` | `10` | Maximum events per HTTP POST |
+| `flush_interval` | `float` | `5.0` | Seconds between flush cycles |
+| `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+
+## What gets sent
+
+Each event carries your SDK's name and version, an event type, a random session ID created per client instance, and a timestamp. Depending on the event:
+
+- **`sdk_initialized`** (sent by `start()`): Python implementation and version, and `time_to_init_ms`.
+- **`method_called` / `method_success`**: method name, duration, and the *number* of positional arguments.
+- **`sdk_error`**: error type and message (email addresses are redacted) plus the method and duration.
+
+Never sent: argument or return values, request or response bodies, stack traces, hostnames, environment variables or user identifiers. Nothing is sent when `disabled=True`.
+
+### Telling your users
+
+Copy this into your SDK's README or privacy docs so your users know what's collected (edit the names to match):
+
+> **Telemetry.** This SDK reports anonymous usage data to its maintainers through [SDK Garden](https://github.com/tjb/SDKGarden): the SDK version, runtime version, which SDK methods are called, how long they take, and error types. It never sends your data, request contents or personal information. To opt out, set `YOUR_SDK_TELEMETRY_DISABLED=1` *(wire this environment variable to `disabled=True` in your SDK)*.
+
+## Behaviour Guarantees
+
+**All network errors are caught and discarded. Your program will never see an exception from sdk-garden-python.**
+
+**Runs on a daemon thread — your program exits normally even if events are queued.** When the process exits the daemon thread is killed automatically; any unsent events in the buffer are dropped. This is intentional — sdk-garden-python prioritises zero impact on your SDK over delivery guarantees.
+
+**Pass `disabled=True` in test environments to suppress all network calls.** When disabled, `start()` returns immediately without spawning a thread, and `track()` / `track_method()` / `track_error()` are all no-ops.
+
+**HTTP requests use a 2-second timeout.** Slow or unreachable ingest endpoints are silently abandoned after 2 seconds.
+
+**Queue overflow is silent.** The internal queue holds a maximum of 100 events. If your SDK generates events faster than the flush thread can drain them, new events are discarded without raising an exception.
+
+## Notes
+
+- `start()` must be called before events are flushed. Calling `track()` before `start()` is safe — events are queued and will be flushed once `start()` is called.
+- `track_method()` returns a decorator. The decorated function behaves identically to the original; timing and error telemetry are captured transparently.
+- Error messages passed to `track_error()` are PII-scrubbed: email addresses matching the standard `user@example.com` pattern are replaced with `[REDACTED]` before the event is enqueued.
+
+## License
+
+MIT

sdk_garden_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+sdk_garden/__init__.py,sha256=eV-sbncezEmHiLpv-mC9q7tlhD5U4E0PsWfvm98J7Mc,65
+sdk_garden/client.py,sha256=JpK-kyjoqY1LE2LDjXZZ0zKvvRCoZMOaR969pXF2UF4,10019
+sdk_garden_python-0.1.0.dist-info/METADATA,sha256=8JB8EU_oQIUrxENLnmYJoH7fvXC01Eorw6weTVVWbJk,4744
+sdk_garden_python-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sdk_garden_python-0.1.0.dist-info/RECORD,,

sdk_garden_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any