clickzetta-studio-utils 0.1.0__py3-none-any.whl

clickzetta_studio_utils/__init__.py

@@ -0,0 +1,5 @@
+from clickzetta_studio_utils.dbutils import Dbutils, TaskValueNotFoundError, WidgetNotFoundError, init_dbutils
+
+__version__ = "0.1.0"
+
+__all__ = ["Dbutils", "TaskValueNotFoundError", "WidgetNotFoundError", "init_dbutils", "__version__"]

clickzetta_studio_utils/_utils.py

@@ -0,0 +1,11 @@
+from clickzetta.connector.v0.connection import Connection
+from clickzetta.connector.v0._fsutil import FsUtil
+
+
+class _Utils:
+    def __init__(self, connection: Connection):
+        self._fs = FsUtil(connection)
+
+    @property
+    def fs(self) -> FsUtil:
+        return self._fs

clickzetta_studio_utils/dbutils.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+import builtins
+import json
+import logging
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+LOGGER = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT_SECONDS = 3
+
+
+class WidgetNotFoundError(KeyError):
+    pass
+
+
+class TaskValueNotFoundError(KeyError):
+    pass
+
+
+@dataclass
+class DbutilsRuntimeConfig:
+    runtime: dict[str, Any] = field(default_factory=dict)
+    widget_values: dict[str, str] = field(default_factory=dict)
+    dbutils_api: dict[str, Any] = field(default_factory=dict)
+    task_values: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, config: dict[str, Any] | None) -> "DbutilsRuntimeConfig":
+        if isinstance(config, list):
+            config = {"connections": config}
+        config = config or {}
+        return cls(
+            runtime=dict(config.get("runtime") or {}),
+            widget_values=_string_map(config.get("widgetValues") or {}),
+            dbutils_api=dict(config.get("dbutilsApi") or {}),
+            task_values=dict(config.get("taskValues") or {}),
+        )
+
+
+class _HttpClient:
+    def __init__(self, base_url: str | None, timeout_seconds: int = _DEFAULT_TIMEOUT_SECONDS):
+        self._base_url = (base_url or "").rstrip("/")
+        self._timeout_seconds = timeout_seconds
+
+    def post_json(self, path: str, payload: dict[str, Any]) -> Any:
+        if not self._base_url:
+            LOGGER.debug("Skip dbutils HTTP call because dbutilsApi.baseUrl is not configured")
+            return None
+        url = f"{self._base_url}{path}"
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=self._timeout_seconds) as response:
+            body = response.read()
+        if not body:
+            return None
+        return json.loads(body.decode("utf-8"))
+
+    def post_widget_event(self, payload: dict[str, Any]) -> None:
+        if not self._base_url:
+            LOGGER.debug("Skip widget event because dbutilsApi.baseUrl is not configured")
+            return
+        try:
+            self.post_json("/v1/dbutils/widgets/events", payload)
+        except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
+            LOGGER.warning("Failed to write dbutils widget event: %s", exc)
+
+    def set_task_value(self, payload: dict[str, Any]) -> None:
+        if not self._base_url:
+            LOGGER.debug("Skip task value set because dbutilsApi.baseUrl is not configured")
+            return
+        try:
+            self.post_json("/v1/dbutils/task-values/set", payload)
+        except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
+            LOGGER.warning("Failed to write dbutils task value: %s", exc)
+
+    def get_task_value(self, payload: dict[str, Any]) -> Any:
+        if not self._base_url:
+            return None
+        return self.post_json("/v1/dbutils/task-values/get", payload)
+
+
+class Widgets:
+    def __init__(self, runtime_config: DbutilsRuntimeConfig):
+        self._runtime = runtime_config.runtime
+        self._values = dict(runtime_config.widget_values)
+        self._client = _HttpClient(runtime_config.dbutils_api.get("baseUrl"))
+        self._event_order = 0
+
+    def text(self, name: str, defaultValue: str = "", label: str | None = None) -> None:
+        self._register("text", name, defaultValue, None, label)
+
+    def dropdown(
+        self,
+        name: str,
+        defaultValue: str,
+        choices: list[str] | tuple[str, ...],
+        label: str | None = None,
+    ) -> None:
+        self._register("dropdown", name, defaultValue, choices, label)
+
+    def combobox(
+        self,
+        name: str,
+        defaultValue: str,
+        choices: list[str] | tuple[str, ...],
+        label: str | None = None,
+    ) -> None:
+        self._register("combobox", name, defaultValue, choices, label)
+
+    def multiselect(
+        self,
+        name: str,
+        defaultValue: str,
+        choices: list[str] | tuple[str, ...],
+        label: str | None = None,
+    ) -> None:
+        self._register("multiselect", name, defaultValue, choices, label)
+
+    def get(self, name: str) -> str:
+        if name not in self._values:
+            raise WidgetNotFoundError(f"Widget not found: {name}")
+        return self._values[name]
+
+    def getAll(self) -> dict[str, str]:
+        return dict(self._values)
+
+    def remove(self, name: str) -> None:
+        self._values.pop(name, None)
+        self._emit(
+            {
+                "eventType": "REMOVE",
+                "widgetKey": name,
+            }
+        )
+
+    def removeAll(self) -> None:
+        self._values.clear()
+        self._emit({"eventType": "REMOVE_ALL"})
+
+    def _register(
+        self,
+        widget_type: str,
+        name: str,
+        default_value: Any,
+        choices: list[str] | tuple[str, ...] | None,
+        label: str | None,
+    ) -> None:
+        key = _require_name(name)
+        default_str = _to_widget_value(default_value)
+        if key not in self._values:
+            self._values[key] = default_str
+        self._emit(
+            {
+                "eventType": "CREATE",
+                "widgetKey": key,
+                "widgetType": widget_type,
+                "label": label,
+                "defaultValue": default_str,
+                "choices": [_to_widget_value(choice) for choice in choices] if choices is not None else [],
+            }
+        )
+
+    def _emit(self, payload: dict[str, Any]) -> None:
+        self._event_order += 1
+        event = {
+            **self._runtime_fields(),
+            **payload,
+            "eventOrder": self._event_order,
+            "timestamp": int(time.time() * 1000),
+        }
+        self._client.post_widget_event(event)
+
+    def _runtime_fields(self) -> dict[str, Any]:
+        return {
+            "tenantId": self._runtime.get("tenantId"),
+            "projectId": self._runtime.get("projectId"),
+            "scheduleTaskId": self._runtime.get("scheduleTaskId"),
+            "scheduleInstanceId": self._runtime.get("scheduleInstanceId"),
+            "executeLogId": self._runtime.get("executeLogId"),
+            "paragraphId": self._runtime.get("paragraphId"),
+        }
+
+    def _update_runtime(self, values: dict[str, Any]) -> None:
+        self._runtime.update({key: value for key, value in values.items() if value is not None})
+
+
+class Dbutils:
+    def __init__(self, runtime_config: DbutilsRuntimeConfig | dict[str, Any] | None = None):
+        if not isinstance(runtime_config, DbutilsRuntimeConfig):
+            runtime_config = DbutilsRuntimeConfig.from_mapping(runtime_config)
+        self.widgets = Widgets(runtime_config)
+        self.jobs = Jobs(runtime_config)
+
+    def set_runtime_context(self, **values: Any) -> None:
+        self.widgets._update_runtime(values)
+        self.jobs.taskValues._update_runtime(values)
+
+
+class Jobs:
+    def __init__(self, runtime_config: DbutilsRuntimeConfig):
+        self.taskValues = TaskValues(runtime_config)
+
+
+class TaskValues:
+    _NO_DEFAULT = object()
+
+    def __init__(self, runtime_config: DbutilsRuntimeConfig):
+        self._runtime = runtime_config.runtime
+        self._client = _HttpClient(runtime_config.dbutils_api.get("baseUrl"))
+        task_values_config = runtime_config.task_values
+        self._current_producer = dict(task_values_config.get("currentProducer") or {})
+        self._producers = dict(task_values_config.get("producers") or {})
+        self._local_values: dict[str, Any] = {}
+
+    def set(self, key: str | None = None, value: Any = None, **kwargs: Any) -> None:
+        if key is None:
+            key = kwargs.get("key")
+        if "value" in kwargs:
+            value = kwargs["value"]
+        value_key = _require_name(key)
+        value_json, value_type = _serialize_task_value(value)
+        self._local_values[value_key] = value
+        payload = {
+            **self._runtime_fields(),
+            "producerInstanceType": self._current_producer.get("producerInstanceType"),
+            "producerInstanceId": self._current_producer.get("producerInstanceId"),
+            "key": value_key,
+            "valueJson": value_json,
+            "valueType": value_type,
+        }
+        self._client.set_task_value(payload)
+
+    def get(
+        self,
+        taskKey: str | None = None,
+        key: str | None = None,
+        default: Any = _NO_DEFAULT,
+        **kwargs: Any,
+    ) -> Any:
+        if taskKey is None:
+            taskKey = kwargs.get("taskKey")
+        if key is None:
+            key = kwargs.get("key")
+        if key is None and taskKey is not None:
+            key = taskKey
+            taskKey = None
+        value_key = _require_name(key)
+        if taskKey is None or taskKey == self._current_producer.get("taskKey"):
+            return self._get_local(value_key, default)
+        producer = self._producers.get(str(taskKey))
+        if not producer:
+            return self._missing(value_key, default)
+        payload = {
+            "tenantId": self._runtime.get("tenantId"),
+            "producerInstanceType": producer.get("producerInstanceType"),
+            "producerInstanceId": producer.get("producerInstanceId"),
+            "key": value_key,
+        }
+        try:
+            response = self._client.get_task_value(payload)
+        except (urllib.error.URLError, TimeoutError, OSError, json.JSONDecodeError) as exc:
+            LOGGER.warning("Failed to read dbutils task value: %s", exc)
+            return self._missing(value_key, default)
+        data = _extract_common_result_data(response)
+        if not data:
+            return self._missing(value_key, default)
+        if isinstance(data, dict) and "valueJson" in data:
+            return json.loads(data["valueJson"])
+        return self._missing(value_key, default)
+
+    def _get_local(self, key: str, default: Any) -> Any:
+        if key in self._local_values:
+            return self._local_values[key]
+        return self._missing(key, default)
+
+    def _missing(self, key: str, default: Any) -> Any:
+        if default is not self._NO_DEFAULT:
+            return default
+        raise TaskValueNotFoundError(f"Task value not found: {key}")
+
+    def _runtime_fields(self) -> dict[str, Any]:
+        return {
+            "tenantId": self._runtime.get("tenantId"),
+            "projectId": self._runtime.get("projectId"),
+            "scheduleTaskId": self._runtime.get("scheduleTaskId"),
+            "scheduleInstanceId": self._runtime.get("scheduleInstanceId"),
+            "executeLogId": self._runtime.get("executeLogId"),
+        }
+
+    def _update_runtime(self, values: dict[str, Any]) -> None:
+        self._runtime.update({key: value for key, value in values.items() if value is not None})
+
+
+def init_dbutils(config: dict[str, Any] | None = None, *, bind_builtins: bool = True) -> Dbutils:
+    existing = getattr(builtins, "dbutils", None)
+    if config is None and isinstance(existing, Dbutils):
+        if bind_builtins:
+            builtins.czutils = existing
+        return existing
+    runtime_config = DbutilsRuntimeConfig.from_mapping(config or {})
+    dbutils = Dbutils(runtime_config)
+    if bind_builtins:
+        builtins.dbutils = dbutils
+        builtins.czutils = dbutils
+    return dbutils
+
+
+def _require_name(name: str) -> str:
+    if name is None or str(name).strip() == "":
+        raise ValueError("Widget name is required")
+    return str(name)
+
+
+def _to_widget_value(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _string_map(values: dict[str, Any]) -> dict[str, str]:
+    return {str(key): _to_widget_value(value) for key, value in values.items()}
+
+
+def _serialize_task_value(value: Any) -> tuple[str, str]:
+    value_json = json.dumps(value, ensure_ascii=False)
+    if len(value_json.encode("utf-8")) > 48 * 1024:
+        raise ValueError("Task value JSON size must be <= 48 KiB")
+    if value is None:
+        value_type = "NULL"
+    elif isinstance(value, bool):
+        value_type = "BOOLEAN"
+    elif isinstance(value, (int, float)):
+        value_type = "NUMBER"
+    elif isinstance(value, str):
+        value_type = "STRING"
+    else:
+        value_type = "JSON"
+    return value_json, value_type
+
+
+def _extract_common_result_data(response: Any) -> Any:
+    if response is None:
+        return None
+    if not isinstance(response, dict):
+        return response
+    if "data" in response:
+        return response.get("data")
+    return response

clickzetta_studio_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.1
+Name: clickzetta-studio-utils
+Version: 0.1.0
+Summary: clickzetta-studio-utils
+Requires-Python: >=3.10
+Requires-Dist: clickzetta-connector>=1.0.28
+Description-Content-Type: text/markdown
+
+# clickzetta-studio-utils
+
+`clickzetta-studio-utils` is a Python utility package built on top of `clickzetta-connector`. It currently provides a lightweight wrapper around ClickZetta's `FsUtil`, making it convenient to work with Volume files from Studio or scripts.
+
+## Installation
+
+This project requires Python `>=3.10`.
+
+```bash
+pip install clickzetta-studio-utils
+```
+
+For local development, use `uv` to install dependencies:
+
+```bash
+uv sync --dev
+```
+
+## Basic Usage
+
+```python
+from clickzetta.connector.v0.connection import connect
+from clickzetta_studio_utils._utils import _Utils
+
+conn = connect(
+    username="<USERNAME>",
+    password="<PASSWORD>",
+    service="<SERVICE>",
+    instance="<INSTANCE>",
+    workspace="<WORKSPACE>",
+    schema="<SCHEMA>",
+    vcluster="<VCLUSTER>",
+)
+
+try:
+    dbutils = _Utils(conn)
+
+    dbutils.fs.put("volume://<VOLUME>/data/1.txt", "hello clickzetta")
+    print(dbutils.fs.ls("volume://<VOLUME>/data/"))
+    print(dbutils.fs.head("volume://<VOLUME>/data/1.txt"))
+    dbutils.fs.rm("volume://<VOLUME>/data/1.txt")
+finally:
+    conn.close()
+```
+
+`dbutils.fs` returns a `clickzetta.connector.v0._fsutil.FsUtil` instance, so you can continue using the filesystem capabilities provided by `clickzetta-connector`.
+
+## Notebook `dbutils.widgets`
+
+Notebook runtimes can initialize a Databricks-like `dbutils.widgets` object from scheduler-provided runtime config.
+
+```python
+from clickzetta_studio_utils import init_dbutils
+
+dbutils = init_dbutils(
+    {
+        "runtime": {
+            "tenantId": 1,
+            "projectId": 2,
+            "scheduleTaskId": 3,
+            "scheduleInstanceId": 4,
+            "executeLogId": 5,
+        },
+        "dbutilsApi": {
+            "baseUrl": "http://scheduler-worker:8080",
+        },
+        "widgetValues": {
+            "biz_date": "2026-07-27",
+        },
+    }
+)
+
+dbutils.widgets.text("biz_date", "2026-07-20", "Business Date")
+print(dbutils.widgets.get("biz_date"))  # keeps the runtime value: 2026-07-27
+```
+
+Supported APIs:
+
+```python
+dbutils.widgets.text(name, defaultValue="", label=None)
+dbutils.widgets.dropdown(name, defaultValue, choices, label=None)
+dbutils.widgets.combobox(name, defaultValue, choices, label=None)
+dbutils.widgets.multiselect(name, defaultValue, choices, label=None)
+dbutils.widgets.get(name)
+dbutils.widgets.getAll()
+dbutils.widgets.remove(name)
+dbutils.widgets.removeAll()
+```
+
+Widget declaration and removal events are posted to `POST /v1/dbutils/widgets/events` when `dbutilsApi.baseUrl` is configured. Event write failures are logged as warnings and do not change local widget behavior.
+
+## Notebook `dbutils.jobs.taskValues`
+
+Notebook runtimes can use `dbutils.jobs.taskValues` to persist values for downstream task instances and to share values across cells in the current Python kernel.
+
+```python
+dbutils.jobs.taskValues.set("row_count", 100)
+
+print(dbutils.jobs.taskValues.get("row_count"))
+print(dbutils.jobs.taskValues.get(taskKey="extract_orders", key="row_count", default=0))
+```
+
+`set()` writes local in-memory state first, then posts serialized JSON to `POST /v1/dbutils/task-values/set` when `dbutilsApi.baseUrl` is configured. `get(taskKey=...)` reads upstream values through `POST /v1/dbutils/task-values/get` using scheduler-provided producer mappings.
+
+## Development
+
+Common commands:
+
+```bash
+# Check code style and lint issues
+uv run ruff check .
+
+# Format Python files
+uv run ruff format .
+
+# Run tests
+uv run pytest
+
+# Build source and wheel distributions
+uv build
+```
+
+## Testing Notes
+
+The test suite includes integration tests that connect to a real ClickZetta service and operate on temporary Volumes. Before running them, make sure that:
+
+- Connection parameters are valid, and the account has permission to create and delete Volumes and read/write files.
+- Personal, production, or long-lived credentials are not committed. Prefer environment variables or local untracked configuration when credentials are needed.
+- You run targeted tests for the code you changed first, then run the full test suite when appropriate.
+
+## Project Information
+
+- Package name: `clickzetta-studio-utils`
+- Import module: `clickzetta_studio_utils`
+- Runtime dependency: `clickzetta-connector>=1.0.25`
+- Build backend: `pdm-backend`

clickzetta_studio_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+clickzetta_studio_utils-0.1.0.dist-info/METADATA,sha256=MTZ2-X1YLNCIA-OpO0i7Nr9JU_f2Lo-UEOmo7tS2WvM,4473
+clickzetta_studio_utils-0.1.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+clickzetta_studio_utils-0.1.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+clickzetta_studio_utils/__init__.py,sha256=qCqPbw5lrellgRQRKI6FLmUmmXJPPdpDxl167ZIdXSQ,237
+clickzetta_studio_utils/_utils.py,sha256=UF_MyHPDuOX2kf0wV1s-67DkNvroIaLF541bA8WpYks,278
+clickzetta_studio_utils/dbutils.py,sha256=JPX7m5wYbUS790F83lWQgiG8V-VvzHz7_S-MfrRb3Ao,12682
+clickzetta_studio_utils-0.1.0.dist-info/RECORD,,

clickzetta_studio_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

clickzetta_studio_utils-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+