Metadata-Version: 2.1
Name: clickzetta-studio-utils
Version: 0.1.1
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`
