still200-sdk 0.1.0__tar.gz

still200_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: still200-sdk
+Version: 0.1.0
+Summary: Still200 Monitoring SDK
+Author: Dennis Wainaina
+Author-email: Dennis Wainaina <dennis@byteslab.io>
+Requires-Dist: httpx2>=2.16.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Still200 Python SDK
+
+Monitor Python scheduled jobs with [Still200](https://still200.com) using a
+decorator, without writing repetitive monitoring boilerplate.
+
+```python
+from still200_sdk import monitor
+
+
+@monitor()
+async def generate_report() -> None:
+    ...
+```
+
+When the function runs, the SDK reports when the job starts and whether it
+finishes successfully or fails.
+
+## Installation
+
+Using uv:
+
+```bash
+uv add still200-sdk
+```
+
+Or using pip:
+
+```bash
+pip install still200-sdk
+```
+
+The SDK requires Python 3.12 or later.
+
+## Configuration
+
+Still200 generates a unique ping token when you create a scheduled-job monitor.
+Set that token in the job's environment:
+
+```bash
+export STILL200_PING_TOKEN="your-ping-token"
+```
+
+Keep this token secret. Do not commit it to source control or include it
+directly in your script.
+
+If `STILL200_PING_TOKEN` is missing, the decorated function raises a
+configuration error before the job starts. This prevents a job from silently
+running without monitoring.
+
+The SDK supports both asynchronous and synchronous functions.
+
+## Async jobs
+
+```python
+import asyncio
+
+from still200_sdk import monitor
+
+
+@monitor()
+async def generate_report() -> None:
+    # Run the scheduled task.
+    ...
+
+
+if __name__ == "__main__":
+    asyncio.run(generate_report())
+```
+
+## Synchronous jobs
+
+```python
+from still200_sdk import monitor
+
+
+@monitor()
+def clean_expired_sessions() -> None:
+    # Run the scheduled task.
+    ...
+
+
+if __name__ == "__main__":
+    clean_expired_sessions()
+```
+
+The decorator preserves the function's arguments, return value, and original
+exception behavior.
+
+## Multiple scheduled jobs
+
+For separate scripts or processes, give each process its own value for
+`STILL200_PING_TOKEN`:
+
+```bash
+STILL200_PING_TOKEN="report-token" python report_job.py
+STILL200_PING_TOKEN="cleanup-token" python cleanup_job.py
+```
+
+If multiple monitored jobs run in the same process, load separate secrets and
+pass them explicitly:
+
+```python
+import os
+
+from still200_sdk import monitor
+
+
+@monitor(ping_token=os.environ["REPORT_JOB_PING_TOKEN"])
+def generate_report() -> None:
+    ...
+
+
+@monitor(ping_token=os.environ["CLEANUP_JOB_PING_TOKEN"])
+def clean_expired_sessions() -> None:
+    ...
+```
+
+An explicit `ping_token` takes precedence over `STILL200_PING_TOKEN`.
+
+## Runtime behavior
+
+For each invocation, the SDK sends:
+
+1. A start ping before running the function.
+2. A finish ping if the function returns successfully.
+3. A failure ping if the function raises an exception.
+
+Failure pings include the exception message, limited to 2,000 characters. The
+SDK does not automatically send function arguments because they may contain
+sensitive data.
+
+Still200 reporting errors are logged but do not change the job's behavior:
+
+- If a start ping fails, the job still runs.
+- If a finish ping fails, the job's result is still returned.
+- If a failure ping fails, the job's original exception is still raised.
+
+## Development
+
+Clone this repo and install the project and development dependencies:
+
+```bash
+uv sync --dev
+```
+
+Run the tests and lint checks:
+
+```bash
+uv run pytest
+uv run ruff check src tests
+```

still200_sdk-0.1.0/README.md

@@ -0,0 +1,151 @@
+# Still200 Python SDK
+
+Monitor Python scheduled jobs with [Still200](https://still200.com) using a
+decorator, without writing repetitive monitoring boilerplate.
+
+```python
+from still200_sdk import monitor
+
+
+@monitor()
+async def generate_report() -> None:
+    ...
+```
+
+When the function runs, the SDK reports when the job starts and whether it
+finishes successfully or fails.
+
+## Installation
+
+Using uv:
+
+```bash
+uv add still200-sdk
+```
+
+Or using pip:
+
+```bash
+pip install still200-sdk
+```
+
+The SDK requires Python 3.12 or later.
+
+## Configuration
+
+Still200 generates a unique ping token when you create a scheduled-job monitor.
+Set that token in the job's environment:
+
+```bash
+export STILL200_PING_TOKEN="your-ping-token"
+```
+
+Keep this token secret. Do not commit it to source control or include it
+directly in your script.
+
+If `STILL200_PING_TOKEN` is missing, the decorated function raises a
+configuration error before the job starts. This prevents a job from silently
+running without monitoring.
+
+The SDK supports both asynchronous and synchronous functions.
+
+## Async jobs
+
+```python
+import asyncio
+
+from still200_sdk import monitor
+
+
+@monitor()
+async def generate_report() -> None:
+    # Run the scheduled task.
+    ...
+
+
+if __name__ == "__main__":
+    asyncio.run(generate_report())
+```
+
+## Synchronous jobs
+
+```python
+from still200_sdk import monitor
+
+
+@monitor()
+def clean_expired_sessions() -> None:
+    # Run the scheduled task.
+    ...
+
+
+if __name__ == "__main__":
+    clean_expired_sessions()
+```
+
+The decorator preserves the function's arguments, return value, and original
+exception behavior.
+
+## Multiple scheduled jobs
+
+For separate scripts or processes, give each process its own value for
+`STILL200_PING_TOKEN`:
+
+```bash
+STILL200_PING_TOKEN="report-token" python report_job.py
+STILL200_PING_TOKEN="cleanup-token" python cleanup_job.py
+```
+
+If multiple monitored jobs run in the same process, load separate secrets and
+pass them explicitly:
+
+```python
+import os
+
+from still200_sdk import monitor
+
+
+@monitor(ping_token=os.environ["REPORT_JOB_PING_TOKEN"])
+def generate_report() -> None:
+    ...
+
+
+@monitor(ping_token=os.environ["CLEANUP_JOB_PING_TOKEN"])
+def clean_expired_sessions() -> None:
+    ...
+```
+
+An explicit `ping_token` takes precedence over `STILL200_PING_TOKEN`.
+
+## Runtime behavior
+
+For each invocation, the SDK sends:
+
+1. A start ping before running the function.
+2. A finish ping if the function returns successfully.
+3. A failure ping if the function raises an exception.
+
+Failure pings include the exception message, limited to 2,000 characters. The
+SDK does not automatically send function arguments because they may contain
+sensitive data.
+
+Still200 reporting errors are logged but do not change the job's behavior:
+
+- If a start ping fails, the job still runs.
+- If a finish ping fails, the job's result is still returned.
+- If a failure ping fails, the job's original exception is still raised.
+
+## Development
+
+Clone this repo and install the project and development dependencies:
+
+```bash
+uv sync --dev
+```
+
+Run the tests and lint checks:
+
+```bash
+uv run pytest
+uv run ruff check src tests
+```

still200_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "still200-sdk"
+version = "0.1.0"
+description = "Still200 Monitoring SDK"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["httpx2>=2.16.0"]
+
+[[project.authors]]
+name = "Dennis Wainaina"
+email = "dennis@byteslab.io"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "ruff>=0.17.4",
+]

still200_sdk-0.1.0/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[project]
+name = "still200-sdk"
+version = "0.1.0"
+description = "Still200 Monitoring SDK"
+readme = "README.md"
+authors = [
+    { name = "Dennis Wainaina", email = "dennis@byteslab.io" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx2>=2.16.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "ruff>=0.17.4",
+]

still200_sdk-0.1.0/src/still200_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""Still200 monitoring SDK."""
+
+from still200_sdk._decorator import monitor
+
+__all__ = ["monitor"]

still200_sdk-0.1.0/src/still200_sdk/_client.py

@@ -0,0 +1,139 @@
+"""HTTP client for the Still200 API."""
+
+from types import TracebackType
+from typing import Any, Self
+
+import httpx2
+
+from still200_sdk._config import Config
+
+PING_TOKEN_HEADER = "STILL200_PING_TOKEN"
+PING_PATH = "/jobs/ping"
+
+
+class Client:
+    """Synchronous client for scheduled-job pings."""
+
+    def __init__(
+        self,
+        config: Config,
+        *,
+        transport: httpx2.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx2.Client(
+            base_url=config.base_url,
+            headers={PING_TOKEN_HEADER: config.ping_token},
+            timeout=config.timeout,
+            transport=transport,
+        )
+
+    def start(self) -> None:
+        """Report that the scheduled job has started."""
+        self._ping("start")
+
+    def finish(self) -> None:
+        """Report that the scheduled job completed successfully."""
+        self._ping("finish")
+
+    def fail(
+        self,
+        *,
+        error_message: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        """Report that the scheduled job failed."""
+        data = _failure_data(error_message=error_message, payload=payload)
+        self._ping("fail", json=data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _ping(self, ping_type: str, *, json: dict[str, Any] | None = None) -> None:
+        response = self._client.post(f"{PING_PATH}/{ping_type}", json=json)
+        response.raise_for_status()
+
+
+class AsyncClient:
+    """Asynchronous client for scheduled-job pings."""
+
+    def __init__(
+        self,
+        config: Config,
+        *,
+        transport: httpx2.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._client = httpx2.AsyncClient(
+            base_url=config.base_url,
+            headers={PING_TOKEN_HEADER: config.ping_token},
+            timeout=config.timeout,
+            transport=transport,
+        )
+
+    async def start(self) -> None:
+        """Report that the scheduled job has started."""
+        await self._ping("start")
+
+    async def finish(self) -> None:
+        """Report that the scheduled job completed successfully."""
+        await self._ping("finish")
+
+    async def fail(
+        self,
+        *,
+        error_message: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> None:
+        """Report that the scheduled job failed."""
+        data = _failure_data(error_message=error_message, payload=payload)
+        await self._ping("fail", json=data)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _ping(
+        self,
+        ping_type: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> None:
+        response = await self._client.post(f"{PING_PATH}/{ping_type}", json=json)
+        response.raise_for_status()
+
+
+def _failure_data(
+    *,
+    error_message: str | None,
+    payload: dict[str, Any] | None,
+) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+
+    if error_message is not None:
+        data["error_message"] = error_message
+    if payload is not None:
+        data["payload"] = payload
+
+    return data

still200_sdk-0.1.0/src/still200_sdk/_config.py

@@ -0,0 +1,43 @@
+"""SDK configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+DEFAULT_BASE_URL = "https://api.still200.com"
+DEFAULT_TIMEOUT = 5.0
+PING_TOKEN_ENV_VAR = "STILL200_PING_TOKEN"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Config:
+    """Internal configuration for Still200 API requests."""
+
+    ping_token: str = field(repr=False)
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+
+    def __post_init__(self) -> None:
+        ping_token = self.ping_token.strip()
+        base_url = self.base_url.rstrip("/")
+
+        if not ping_token:
+            raise ValueError("ping_token must not be empty")
+        if not base_url:
+            raise ValueError("base_url must not be empty")
+        if self.timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+        object.__setattr__(self, "ping_token", ping_token)
+        object.__setattr__(self, "base_url", base_url)
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Load configuration from the process environment."""
+        ping_token = os.getenv(PING_TOKEN_ENV_VAR)
+
+        if ping_token is None:
+            raise ValueError(f"{PING_TOKEN_ENV_VAR} is not set")
+
+        return cls(ping_token=ping_token)

still200_sdk-0.1.0/src/still200_sdk/_decorator.py

@@ -0,0 +1,107 @@
+"""Scheduled-job monitoring decorator."""
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+from still200_sdk._client import AsyncClient, Client
+from still200_sdk._config import Config
+
+MAX_ERROR_MESSAGE_LENGTH = 2_000
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+logger = logging.getLogger(__name__)
+
+
+def monitor(*, ping_token: str | None = None) -> Callable[[F], F]:
+    """Monitor a synchronous or asynchronous scheduled job."""
+
+    def decorator(func: F) -> F:
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                config = _resolve_config(ping_token)
+
+                try:
+                    client = AsyncClient(config)
+                except Exception:
+                    logger.warning("Failed to initialize Still200 monitoring", exc_info=True)
+                    return await func(*args, **kwargs)
+
+                try:
+                    await _report_safely_async(client.start)
+
+                    try:
+                        result = await func(*args, **kwargs)
+                    except Exception as error:
+                        error_message = _error_message(error)
+                        await _report_safely_async(
+                            lambda: client.fail(error_message=error_message)
+                        )
+                        raise
+
+                    await _report_safely_async(client.finish)
+                    return result
+                finally:
+                    await _report_safely_async(client.close)
+
+            return cast(F, async_wrapper)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            config = _resolve_config(ping_token)
+
+            try:
+                client = Client(config)
+            except Exception:
+                logger.warning("Failed to initialize Still200 monitoring", exc_info=True)
+                return func(*args, **kwargs)
+
+            try:
+                _report_safely(client.start)
+
+                try:
+                    result = func(*args, **kwargs)
+                except Exception as error:
+                    error_message = _error_message(error)
+                    _report_safely(lambda: client.fail(error_message=error_message))
+                    raise
+
+                _report_safely(client.finish)
+                return result
+            finally:
+                _report_safely(client.close)
+
+        return cast(F, sync_wrapper)
+
+    return decorator
+
+
+def _resolve_config(ping_token: str | None) -> Config:
+    if ping_token is None:
+        return Config.from_env()
+
+    return Config(ping_token=ping_token)
+
+
+def _error_message(error: Exception) -> str:
+    message = str(error) or type(error).__name__
+    return message[:MAX_ERROR_MESSAGE_LENGTH]
+
+
+def _report_safely(operation: Callable[[], None]) -> None:
+    try:
+        operation()
+    except Exception:
+        logger.warning("Failed to report scheduled job status to Still200", exc_info=True)
+
+
+async def _report_safely_async(operation: Callable[[], Awaitable[None]]) -> None:
+    try:
+        await operation()
+    except Exception:
+        logger.warning("Failed to report scheduled job status to Still200", exc_info=True)