renart 0.3.2__py3-none-any.whl

renart/__init__.py

@@ -0,0 +1,28 @@
+"""Renart Python SDK.
+
+Available inside renart Python assets. `query()` runs read-only SQL against
+the project's connections through the renart runner — credentials never enter
+the Python process — and `context` exposes the run window and metadata.
+
+    from renart import query, context
+
+    def materialize():
+        games = query("select * from chess_games").to_pandas()
+        return games.groupby("winner").size().reset_index(name="wins")
+"""
+
+from ._client import (
+    BrokerUnavailableError,
+    QueryError,
+    RenartError,
+    query,
+)
+from .context import context
+
+__all__ = [
+    "query",
+    "context",
+    "RenartError",
+    "QueryError",
+    "BrokerUnavailableError",
+]

renart/__init__.pyi

@@ -0,0 +1,7 @@
+from ._client import BrokerUnavailableError as BrokerUnavailableError
+from ._client import QueryError as QueryError
+from ._client import RenartError as RenartError
+from ._client import query as query
+from .context import _Context as _Context
+
+context: _Context

renart/_client.py

@@ -0,0 +1,129 @@
+"""HTTP client for the renart run broker.
+
+The runner starts a loopback broker per task and injects RENART_API_URL and
+RENART_API_TOKEN. Queries execute inside the runner on the project's
+connections; results stream back as Arrow IPC. Only the token crosses the
+process boundary — never credentials.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+
+class RenartError(Exception):
+    """Base class for renart SDK errors."""
+
+
+class BrokerUnavailableError(RenartError):
+    """The run broker is not reachable (not running inside a renart run?)."""
+
+
+class QueryError(RenartError):
+    """The broker rejected or failed to execute a query."""
+
+    def __init__(self, message: str, code: Optional[str] = None):
+        super().__init__(message)
+        self.code = code
+
+
+def _broker_address() -> "tuple[str, str]":
+    url = os.environ.get("RENART_API_URL", "").strip()
+    token = os.environ.get("RENART_API_TOKEN", "").strip()
+    if not url or not token:
+        raise BrokerUnavailableError(
+            "renart.query() needs the run broker, which is only available while "
+            "the asset runs through renart (RENART_API_URL / RENART_API_TOKEN "
+            "are not set)."
+        )
+    return url, token
+
+
+def _raise_from_response(exc: urllib.error.HTTPError) -> "None":
+    code = None
+    message = f"broker request failed with HTTP {exc.code}"
+    try:
+        payload = json.loads(exc.read().decode("utf-8"))
+        error = payload.get("error") or {}
+        message = error.get("message") or message
+        code = error.get("code")
+    except Exception:  # noqa: BLE001 - keep the HTTP error as the message
+        pass
+    raise QueryError(message, code) from None
+
+
+def query(sql: str, connection: Optional[str] = None, format: str = "arrow") -> Any:
+    """Run a read-only SQL query through the renart runner.
+
+    Args:
+        sql: a single SELECT statement. It may reference other assets of the
+            project; if a referenced asset is being materialized right now,
+            the runner waits for it to finish before executing the query.
+        connection: a project connection name; defaults to the asset's own
+            connection.
+        format: ``"arrow"`` (default) returns a pyarrow.Table,
+            ``"pandas"`` returns a pandas.DataFrame.
+
+    Credentials never enter the Python process; the query executes inside
+    the renart runner.
+    """
+    if format not in ("pandas", "arrow"):
+        raise ValueError(f'format must be "pandas" or "arrow", got {format!r}')
+
+    url, token = _broker_address()
+    body = {"sql": sql}
+    if connection:
+        body["connection"] = connection
+    request = urllib.request.Request(
+        url + "/v1/query",
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Authorization": "Bearer " + token,
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    import pyarrow.ipc as ipc
+
+    try:
+        response = urllib.request.urlopen(request)
+    except urllib.error.HTTPError as exc:
+        _raise_from_response(exc)
+    except urllib.error.URLError as exc:
+        raise BrokerUnavailableError(f"cannot reach the run broker: {exc.reason}") from None
+
+    with response:
+        table = ipc.open_stream(response).read_all()
+
+    if format == "arrow":
+        return table
+    try:
+        return table.to_pandas()
+    except ImportError as exc:
+        raise RenartError(
+            'query(format="pandas") needs pandas installed in the asset '
+            'environment; add pandas to the asset dependencies or use '
+            'format="arrow".'
+        ) from exc
+
+
+def _fetch_context() -> "dict[str, Any]":
+    """Fetch the run context document from the broker (internal)."""
+    url, token = _broker_address()
+    request = urllib.request.Request(
+        url + "/v1/context",
+        headers={"Authorization": "Bearer " + token},
+    )
+    try:
+        with urllib.request.urlopen(request) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        _raise_from_response(exc)
+        raise  # unreachable; _raise_from_response always raises
+    except urllib.error.URLError as exc:
+        raise BrokerUnavailableError(f"cannot reach the run broker: {exc.reason}") from None

renart/_client.pyi

@@ -0,0 +1,15 @@
+from typing import Any, Literal
+
+class RenartError(Exception): ...
+
+class BrokerUnavailableError(RenartError): ...
+
+class QueryError(RenartError):
+    code: str | None
+    def __init__(self, message: str, code: str | None = None) -> None: ...
+
+def query(
+    sql: str,
+    connection: str | None = None,
+    format: Literal["arrow", "pandas"] = "arrow",
+) -> Any: ...

renart/context.py

@@ -0,0 +1,107 @@
+"""Typed access to the run context.
+
+Backed by the BRUIN_* environment variables the runner injects, so it works
+in any execution mode (and stays compatible with scripts that read the env
+vars directly). Every property returns None when the value is absent, except
+``is_full_refresh`` (False) and ``vars`` (``{}``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import date, datetime
+from typing import Any, Optional
+
+
+def _env(name: str) -> Optional[str]:
+    value = os.environ.get(name, "").strip()
+    return value or None
+
+
+def _parse_date(value: Optional[str]) -> Optional[date]:
+    if not value:
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _parse_datetime(value: Optional[str]) -> Optional[datetime]:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+class _Context:
+    """Runtime information about the current renart run."""
+
+    @property
+    def start_date(self) -> Optional[date]:
+        """Start of the run window."""
+        return _parse_date(_env("BRUIN_START_DATE"))
+
+    @property
+    def start_datetime(self) -> Optional[datetime]:
+        return _parse_datetime(_env("BRUIN_START_DATETIME"))
+
+    @property
+    def end_date(self) -> Optional[date]:
+        """End of the run window."""
+        return _parse_date(_env("BRUIN_END_DATE"))
+
+    @property
+    def end_datetime(self) -> Optional[datetime]:
+        return _parse_datetime(_env("BRUIN_END_DATETIME"))
+
+    @property
+    def execution_date(self) -> Optional[datetime]:
+        return _parse_datetime(_env("BRUIN_EXECUTION_DATETIME"))
+
+    @property
+    def pipeline(self) -> Optional[str]:
+        return _env("BRUIN_PIPELINE")
+
+    @property
+    def asset_name(self) -> Optional[str]:
+        return _env("BRUIN_ASSET")
+
+    @property
+    def connection(self) -> Optional[str]:
+        """The asset's default connection name."""
+        return _env("BRUIN_CONNECTION")
+
+    @property
+    def run_id(self) -> Optional[str]:
+        return _env("BRUIN_RUN_ID")
+
+    @property
+    def is_full_refresh(self) -> bool:
+        value = (_env("BRUIN_FULL_REFRESH") or "").lower()
+        return value in ("1", "true", "yes")
+
+    @property
+    def vars(self) -> "dict[str, Any]":
+        """Pipeline variables, types preserved from their JSON schema."""
+        raw = _env("BRUIN_VARS")
+        if not raw:
+            return {}
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            return {}
+        return parsed if isinstance(parsed, dict) else {}
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging nicety
+        return (
+            f"renart.context(pipeline={self.pipeline!r}, asset={self.asset_name!r}, "
+            f"start_date={self.start_date!r}, end_date={self.end_date!r}, "
+            f"run_id={self.run_id!r}, is_full_refresh={self.is_full_refresh!r})"
+        )
+
+
+context = _Context()

renart/context.pyi

@@ -0,0 +1,28 @@
+from datetime import date, datetime
+from typing import Any
+
+class _Context:
+    @property
+    def start_date(self) -> date | None: ...
+    @property
+    def start_datetime(self) -> datetime | None: ...
+    @property
+    def end_date(self) -> date | None: ...
+    @property
+    def end_datetime(self) -> datetime | None: ...
+    @property
+    def execution_date(self) -> datetime | None: ...
+    @property
+    def pipeline(self) -> str | None: ...
+    @property
+    def asset_name(self) -> str | None: ...
+    @property
+    def connection(self) -> str | None: ...
+    @property
+    def run_id(self) -> str | None: ...
+    @property
+    def is_full_refresh(self) -> bool: ...
+    @property
+    def vars(self) -> dict[str, Any]: ...
+
+context: _Context

renart/py.typed

@@ -0,0 +1 @@
+

renart-0.3.2.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.1
+Name: renart
+Version: 0.3.2
+Summary: Renart SDK for Python assets: query project data through the renart runner.
+Home-page: https://getrenart.com
+Project-URL: Documentation, https://getrenart.com/docs/asset-types/python-assets/
+Project-URL: Source, https://github.com/renart-data/renart
+License: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: pyarrow>=15.0.0
+Requires-Dist: pandas>=1.5
+Description-Content-Type: text/markdown
+
+# Renart Python SDK
+
+renart provides the Python package used by Python assets and Python
+notebook cells in Renart. Renart injects its matching SDK wheel automatically
+at runtime; the PyPI distribution is available for type checking, editors, and
+CI environments that inspect project code outside the Renart process.
+
+query() connects to a token-scoped broker started by the Renart runner. It
+does not contain database credentials and is not a standalone database client.

renart-0.3.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+renart/__init__.py,sha256=i3gPwcZoHzzkoSaqyvlOrTrI42BcPvLGdCIS6EqZ6DQ,691
+renart/__init__.pyi,sha256=1Drc_oITmRq35yYrwr3fJ1ir-aVE2PRfPEb9K5ERHKk,261
+renart/_client.py,sha256=goGCSSxqJRdnIR_3vCS5r5hVOdq_6OE6Qc-av9CNaC4,4387
+renart/_client.pyi,sha256=s0QhbqBlRstNPgNNfXZL3qnXK0VxRa61r5_Np_sSEVM,368
+renart/context.py,sha256=lLBf_khFT2CEfWPPtZJJYlfd3lU0Q5HvslU4wzsVkUs,3027
+renart/context.pyi,sha256=ZUeog2ZUES8lI2XvnZMsnNQIshHYyK4UA02waNvWnpY,749
+renart/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+renart-0.3.2.dist-info/METADATA,sha256=0Zf5LfhZR-Z_TWzjFBUvWR1V6tlhUrBQlBPrsfBUGsQ,922
+renart-0.3.2.dist-info/WHEEL,sha256=iAQXzXWZKPhmEBuSL_3wqpOatQ9An7mT6wPP1Py91F0,77
+renart-0.3.2.dist-info/top_level.txt,sha256=AOLaNFL0wxJOm6mSttggaCfHcZecQznwf8R3AnyzxM4,7
+renart-0.3.2.dist-info/RECORD,,

renart-0.3.2.dist-info/WHEEL

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

renart-0.3.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+renart