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.

pip install clickzetta-studio-utils

For local development, use uv to install dependencies:

uv sync --dev

Basic Usage

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.

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:

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.

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:

# 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