uptic 0.1.0__tar.gz

uptic-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+dist
+__pycache__
+*.egg-info

uptic-0.1.0/LICENSE

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

uptic-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: uptic
+Version: 0.1.0
+Summary: Report errors and structured logs to Uptic from Python scripts and services
+Project-URL: Homepage, https://uptic.run
+Project-URL: Repository, https://github.com/thevedus/uptic
+Project-URL: Issues, https://github.com/thevedus/uptic/issues
+Author-email: Vedus <hello@vedus.in>
+License: MIT
+License-File: LICENSE
+Keywords: error-tracking,logging,observability,uptic
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# uptic
+
+Report errors and structured logs to Uptic from Python.
+
+No runtime dependencies — one `urllib` POST.
+
+## Install
+
+```bash
+pip install uptic
+```
+
+## Inside an Uptic script
+
+The script runner injects credentials, so there is nothing to configure:
+
+```python
+from uptic import uptic
+
+def fetch(payload, context):
+    client = uptic()
+
+    client.info("starting", {"trigger": context.get("type")})
+
+    with client.catching():
+        result = do_the_work(payload)
+
+    client.info("done", {"count": len(result)})
+    return result
+```
+
+`catching()` reports whatever is raised and then re-raises, so the execution is
+still recorded as failed. Pass `reraise=False` to swallow it instead.
+
+## In a service
+
+There is no injected environment, so pass a **public ingest key** (`pk_…`,
+created under Settings → API Keys → Public Ingest Keys). Never use an `sk_` API
+key here — it carries full workspace permissions.
+
+```python
+from uptic import UpticClient
+
+client = UpticClient(
+    base_url="https://app.uptic.run",
+    ingest_key="pk_your_public_key",
+    service="billing-worker",
+    environment="production",
+    release=os.environ.get("GIT_SHA"),
+)
+
+try:
+    charge(order)
+except Exception as err:
+    client.capture_error(err, tags={"order": order.id})
+    raise
+```
+
+## API
+
+| Method | What it does |
+| --- | --- |
+| `uptic(**config)` | Get (and configure) the shared client |
+| `capture_error(error, **options)` | Report one error. Returns `True` if accepted |
+| `capture_batch(events)` | Report several in one request |
+| `catching(reraise=True, **options)` | Context manager: report, then re-raise |
+| `log(level, message, meta=None)` | One JSON line to stdout/stderr |
+| `debug` / `info` / `warn` / `error` | Shorthands for `log` |
+| `config(name, fallback=None)` | Read an injected env value |
+
+`capture_error` accepts an exception or a plain string, plus `level`, `tags`,
+`context`, `fingerprint` and `service`.
+
+### Config
+
+Every field falls back to an environment variable, which is what the script
+runner sets:
+
+| Argument | Env var |
+| --- | --- |
+| `base_url` | `UPTIC_BASE_URL` |
+| `ingest_key` | `UPTIC_INGEST_KEY` |
+| `service` | `UPTIC_WORKER_ID` (else `"default"`) |
+| `environment` | `UPTIC_ENVIRONMENT` |
+| `release` | `UPTIC_RELEASE` |
+
+## Two guarantees
+
+**Reporting never raises.** `capture_error` returns `False` on a network
+failure. A monitoring call that takes down the thing it monitors is worse than
+a missing data point.
+
+**Logging makes no network call.** `log()` writes one JSON line to
+stdout/stderr; the script runner already captures both into the execution
+record, so logging works offline and costs nothing.
+
+## Development
+
+```bash
+python -m pytest packages/python-sdk/tests -q
+```

uptic-0.1.0/README.md

@@ -0,0 +1,101 @@
+# uptic
+
+Report errors and structured logs to Uptic from Python.
+
+No runtime dependencies — one `urllib` POST.
+
+## Install
+
+```bash
+pip install uptic
+```
+
+## Inside an Uptic script
+
+The script runner injects credentials, so there is nothing to configure:
+
+```python
+from uptic import uptic
+
+def fetch(payload, context):
+    client = uptic()
+
+    client.info("starting", {"trigger": context.get("type")})
+
+    with client.catching():
+        result = do_the_work(payload)
+
+    client.info("done", {"count": len(result)})
+    return result
+```
+
+`catching()` reports whatever is raised and then re-raises, so the execution is
+still recorded as failed. Pass `reraise=False` to swallow it instead.
+
+## In a service
+
+There is no injected environment, so pass a **public ingest key** (`pk_…`,
+created under Settings → API Keys → Public Ingest Keys). Never use an `sk_` API
+key here — it carries full workspace permissions.
+
+```python
+from uptic import UpticClient
+
+client = UpticClient(
+    base_url="https://app.uptic.run",
+    ingest_key="pk_your_public_key",
+    service="billing-worker",
+    environment="production",
+    release=os.environ.get("GIT_SHA"),
+)
+
+try:
+    charge(order)
+except Exception as err:
+    client.capture_error(err, tags={"order": order.id})
+    raise
+```
+
+## API
+
+| Method | What it does |
+| --- | --- |
+| `uptic(**config)` | Get (and configure) the shared client |
+| `capture_error(error, **options)` | Report one error. Returns `True` if accepted |
+| `capture_batch(events)` | Report several in one request |
+| `catching(reraise=True, **options)` | Context manager: report, then re-raise |
+| `log(level, message, meta=None)` | One JSON line to stdout/stderr |
+| `debug` / `info` / `warn` / `error` | Shorthands for `log` |
+| `config(name, fallback=None)` | Read an injected env value |
+
+`capture_error` accepts an exception or a plain string, plus `level`, `tags`,
+`context`, `fingerprint` and `service`.
+
+### Config
+
+Every field falls back to an environment variable, which is what the script
+runner sets:
+
+| Argument | Env var |
+| --- | --- |
+| `base_url` | `UPTIC_BASE_URL` |
+| `ingest_key` | `UPTIC_INGEST_KEY` |
+| `service` | `UPTIC_WORKER_ID` (else `"default"`) |
+| `environment` | `UPTIC_ENVIRONMENT` |
+| `release` | `UPTIC_RELEASE` |
+
+## Two guarantees
+
+**Reporting never raises.** `capture_error` returns `False` on a network
+failure. A monitoring call that takes down the thing it monitors is worse than
+a missing data point.
+
+**Logging makes no network call.** `log()` writes one JSON line to
+stdout/stderr; the script runner already captures both into the execution
+record, so logging works offline and costs nothing.
+
+## Development
+
+```bash
+python -m pytest packages/python-sdk/tests -q
+```

uptic-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uptic"
+version = "0.1.0"
+description = "Report errors and structured logs to Uptic from Python scripts and services"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Vedus", email = "hello@vedus.in" }]
+keywords = ["uptic", "error-tracking", "logging", "observability"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: System :: Monitoring",
+]
+# No runtime dependencies on purpose: this gets installed into whatever
+# environment a user's script already has, and urllib covers one POST.
+dependencies = []
+
+[project.urls]
+Homepage = "https://uptic.run"
+Repository = "https://github.com/thevedus/uptic"
+Issues = "https://github.com/thevedus/uptic/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uptic"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/uptic", "README.md", "LICENSE"]

uptic-0.1.0/src/uptic/__init__.py

@@ -0,0 +1,211 @@
+"""uptic — report errors and structured logs to Uptic from Python.
+
+Mirrors ``uptic-sdk`` (Node/Bun) so the two do not drift: same env
+contract, same wire shape, same no-throw guarantee.
+
+Inside the Uptic script runner this needs no configuration — the runner
+injects ``UPTIC_BASE_URL`` and ``UPTIC_INGEST_KEY``.
+
+    from uptic import uptic
+
+    def fetch(payload, context):
+        client = uptic()
+        client.info("starting", {"payload": payload})
+        with client.catching():
+            do_the_work()
+        return {"ok": True}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import traceback
+import urllib.error
+import urllib.request
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, List, Optional
+
+__all__ = ["UpticClient", "uptic", "capture_error", "log"]
+__version__ = "0.1.0"
+
+_INGEST_PATH = "/open/error/report/public"
+_DEFAULT_TIMEOUT = 5.0
+
+
+def _env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    return value or None
+
+
+class UpticClient:
+    """A configured reporter. Construct once and reuse."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        ingest_key: Optional[str] = None,
+        service: Optional[str] = None,
+        environment: Optional[str] = None,
+        release: Optional[str] = None,
+        tags: Optional[Dict[str, str]] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = (base_url or _env("UPTIC_BASE_URL") or "").rstrip("/")
+        self.ingest_key = ingest_key or _env("UPTIC_INGEST_KEY") or ""
+        self.service = service or _env("UPTIC_WORKER_ID") or "default"
+        self.environment = environment or _env("UPTIC_ENVIRONMENT")
+        self.release = release or _env("UPTIC_RELEASE")
+        self.tags = tags or {}
+        self.timeout = timeout
+
+    @property
+    def is_configured(self) -> bool:
+        """Whether reporting can actually reach a server."""
+        return bool(self.base_url and self.ingest_key)
+
+    def build_event(
+        self,
+        error: BaseException | str,
+        level: str = "error",
+        tags: Optional[Dict[str, str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+        fingerprint: Optional[List[str]] = None,
+        service: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        if isinstance(error, BaseException):
+            message = str(error) or error.__class__.__name__
+            event_type = error.__class__.__name__
+            stack = "".join(
+                traceback.format_exception(
+                    type(error), error, error.__traceback__
+                )
+            )
+        else:
+            message = str(error)
+            event_type = None
+            stack = None
+
+        event: Dict[str, Any] = {
+            "service": service or self.service,
+            "level": level,
+            "message": message,
+            "timestamp": int(time.time() * 1000),
+        }
+        if event_type:
+            event["type"] = event_type
+        if stack:
+            event["stack"] = stack
+        if self.environment:
+            event["environment"] = self.environment
+        if self.release:
+            event["release"] = self.release
+        if fingerprint:
+            event["fingerprint"] = fingerprint
+        if context:
+            event["context"] = context
+
+        merged_tags = {**self.tags, **(tags or {})}
+        if merged_tags:
+            event["tags"] = merged_tags
+
+        return event
+
+    def capture_error(self, error: BaseException | str, **kwargs: Any) -> bool:
+        """Report one error. Never raises — a monitoring call that takes down
+        the thing it monitors is worse than a missing data point."""
+        return self.capture_batch([self.build_event(error, **kwargs)])
+
+    def capture_batch(self, events: List[Dict[str, Any]]) -> bool:
+        if not self.is_configured or not events:
+            return False
+
+        body = json.dumps({"key": self.ingest_key, "events": events}).encode(
+            "utf-8"
+        )
+        request = urllib.request.Request(
+            self.base_url + _INGEST_PATH,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as resp:
+                return 200 <= resp.status < 300
+        except Exception:
+            # includes HTTPError, URLError, socket timeouts and anything else
+            return False
+
+    def log(
+        self,
+        level: str,
+        message: str,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Structured logging: one JSON line on stdout/stderr. The script
+        runner already captures both into the execution record, so this makes
+        no network call and works offline."""
+        line = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "level": level,
+            "service": self.service,
+            "message": message,
+        }
+        if meta is not None:
+            line["meta"] = meta
+
+        stream = sys.stderr if level in ("warn", "error") else sys.stdout
+        print(json.dumps(line, default=str), file=stream, flush=True)
+
+    def debug(self, message: str, meta: Optional[Dict[str, Any]] = None) -> None:
+        self.log("debug", message, meta)
+
+    def info(self, message: str, meta: Optional[Dict[str, Any]] = None) -> None:
+        self.log("info", message, meta)
+
+    def warn(self, message: str, meta: Optional[Dict[str, Any]] = None) -> None:
+        self.log("warn", message, meta)
+
+    def error(self, message: str, meta: Optional[Dict[str, Any]] = None) -> None:
+        self.log("error", message, meta)
+
+    def config(self, name: str, fallback: Optional[str] = None) -> Optional[str]:
+        """Read an injected config value. Scripts get a deliberately narrow
+        environment, so this is a readable accessor rather than a pretence of
+        a secret store."""
+        return _env(name) or fallback
+
+    @contextmanager
+    def catching(self, reraise: bool = True, **kwargs: Any) -> Iterator[None]:
+        """Report anything raised inside the block, then re-raise by default
+        so the script still fails loudly."""
+        try:
+            yield
+        except BaseException as err:  # noqa: BLE001 - reported, then re-raised
+            self.capture_error(err, **kwargs)
+            if reraise:
+                raise
+
+
+_default_client: Optional[UpticClient] = None
+
+
+def uptic(**kwargs: Any) -> UpticClient:
+    """The zero-config entry point. Inside the Uptic script runner this needs
+    no arguments — credentials are already in the environment."""
+    global _default_client
+    if kwargs or _default_client is None:
+        _default_client = UpticClient(**kwargs)
+    return _default_client
+
+
+def capture_error(error: BaseException | str, **kwargs: Any) -> bool:
+    return uptic().capture_error(error, **kwargs)
+
+
+def log(level: str, message: str, meta: Optional[Dict[str, Any]] = None) -> None:
+    uptic().log(level, message, meta)