DataLens Python SDK

datalens-sdk is the typed Python SDK for the DataLens API. It provides clients and domain models for working with connections, datasets, charts, dashboards, collections, workbooks, folders, and navigation in Yandex Cloud DataLens and DataLens Enterprise.

Requirements

• Python 3.10 or newer
• A Yandex Cloud organization with DataLens enabled, or a DataLens Enterprise installation

Project status

The 0.X series is an alpha release. Until a major release is published, breaking API changes may be made in minor releases.

Installation

The package is available from PyPI:

pip install datalens-sdk

Using the SDK with coding agents

Install the datalens-skills plugin when using this SDK through Claude Code, Codex, OpenCode, or another Agent Skills-compatible coding agent. Its root datalens-sdk skill selects a safe project environment, installs or updates this package with explicit version decisions, and then loads the version-matched instructions bundled in the installed SDK. Do not install or invoke the bundled skill directly; follow the plugin repository's installation instructions instead.

Quick start

DataLensClientYC uses the active yc CLI profile by default. Configure the organization once; the SDK will then obtain and refresh IAM tokens automatically:

yc config set organization-id <organization-id>

Use clients as context managers so their HTTP connections are closed promptly:

from datalens_sdk import DataLensClientYC

with DataLensClientYC() as client:
    dataset = client.get.dataset(by_id="<dataset-id>")
    print(dataset.name)

For DataLens Enterprise, provide the installation's API base URL:

from datalens_sdk import DataLensClientEnterprise

with DataLensClientEnterprise(base_url="https://datalens.example.com") as client:
    workbook = client.get.workbook(by_id="<workbook-id>")
    print(workbook.name)

Authentication

Yandex Cloud users can choose among the following providers:

• YCIAMAuthProvider uses a yc CLI profile and refreshes IAM tokens automatically. This is the default for DataLensClientYC; DATALENS_YC_BIN, DATALENS_YC_PROFILE, and DATALENS_ORG_ID configure its defaults, while explicit constructor arguments take precedence. Its CLI invocations share one configurable timeout value, which defaults to 30 seconds.
• YCServiceAccountCredentialsAuthProvider exchanges service-account credentials for refreshable IAM tokens.
• StaticYCIAMAuthProvider accepts an existing IAM token and organization ID.

import os

from datalens_sdk import StaticYCIAMAuthProvider, DataLensClientYC

auth = StaticYCIAMAuthProvider(
    org_id=os.environ["DATALENS_ORG_ID"],
    token=os.environ["DATALENS_IAM_TOKEN"],
)

with DataLensClientYC(auth=auth) as client:
    dashboard = client.get.dashboard(by_id="<dashboard-id>")

Pass auth=None explicitly for access without authentication. For Enterprise service accounts, sign and exchange credentials automatically:

import os
from pathlib import Path

from datalens_sdk import DataLensClientEnterprise, EnterpriseServiceAccountCredentialsAuthProvider

base_url = os.environ["DATALENS_BASE_URL"]
auth = EnterpriseServiceAccountCredentialsAuthProvider(
    key_id="<private-key-id>",
    service_account_id="<service-account-id>",
    private_key=Path("/secure/path/private-key.pem").read_text(),
)

with DataLensClientEnterprise(base_url=base_url, auth=auth) as client:
    dashboard = client.get.dashboard(by_id="<dashboard-id>")

The provider signs a five-minute PS256 JWT, exchanges it for an Enterprise access token, and refreshes the access token automatically before it expires. Client JWT lifetimes are configurable up to the Enterprise limit of 10 minutes.

Core concepts

The client groups operations by intent:

• client.get loads resources such as datasets, charts, and dashboards.
• client.create exposes typed builders. Configure a builder fluently and call .build() to send it.
• Returned resources provide operations such as .rename(), .update, and .delete().
• EntryLocation identifies a destination path, workbook, or collection.

For example, create a workbook and use the returned object directly as a destination:

from datalens_sdk import DataLensClientYC

with DataLensClientYC() as client:
    workbook = client.create.workbook(name="SDK workbook").build()
    dataset = client.create.dataset(name="SDK dataset", location=workbook).build()

Wizard-owned fields use immutable, GUID-bearing handles. Register each handle once and reuse the same object in placeholders, filters, sorting, and decorations:

from datalens_sdk import WizardAggregatedMeasure, WizardHierarchy, WizardLocalField

dataset = client.get.dataset(by_id=dataset.id)
country = dataset.fields.by_name("Country")
city = dataset.fields.by_name("City")
customer = dataset.fields.by_name("Customer")

revenue_per_order = WizardLocalField.measure(
    guid="customer-revenue-per-order",
    title="Revenue per order",
    formula="SUM([Revenue]) / SUM([Orders])",
    cast="float",
)
unique_customers = WizardAggregatedMeasure(
    guid="customer-unique-customers",
    field=customer,
    aggregation="countunique",
    title="Unique customers",
)
geo = WizardHierarchy(guid="customer-country-city", title="Country → City", fields=[country, city])

chart = (
    client.create.wizard_chart.flat_table(name="Customer geography", location=workbook)
    .dataset(dataset)
    .add_local_field(revenue_per_order)
    .add_aggregated_measure(unique_customers)
    .add_hierarchy(geo)
    .columns([geo, revenue_per_order, unique_customers])
    .build()
)

The remembered handles remain valid after re-fetch because references resolve by GUID. Without a saved handle, use an exact GUID through chart.fields.by_guid(...); chart.fields intentionally returns DatasetField snapshots and does not reconstruct handles.

Examples

Runnable Yandex Cloud examples are available in examples/:

Inspect an example's configuration before running it:

python examples/clickhouse_dashboard.py --help

Resource-creating examples leave their output in place for inspection.

Raw JSON artifacts

to_file(parent) writes a resource's exact server snapshot below an existing parent directory. Artifacts require the resource name and id and use <sanitized name> [<sanitized id>]; export does not synthesize missing identity fields or mutate the resource model.

Raw JSON mutations live under client.raw; typed create and update builders do not accept raw snapshots. Create from a response snapshot with client.raw.create.<resource>(response_snapshot=raw, name=..., location=...).build() or from an exported artifact directory with client.raw.create.<resource>.from_file(path, name=..., location=...).build(). Replace an existing resource with client.raw.replace.<resource>(target=..., response_snapshot=raw).execute(...) or client.raw.replace.<resource>.from_file(path, target=...).execute(...). Dashboard replace requires publish= on execute(); chart replace can select .mode("save") or .mode("publish") before execute(). Replace overwrites the supported mutable content and is last-write-wins: it does not fetch, merge, or check for concurrent changes. Each build() or execute() call performs a new mutation and has no idempotency guarantee.

Dashboard.to_file(parent, with_dependencies=True) adds Charts and Datasets discovered only through the relations API. It never calls getEntries; relation wire types select the specialized Wizard, Editor, or QL getter, and relation workbookId values are forwarded without forcing a branch or revision. The resulting bundle therefore does not promise cross-resource revision consistency.

The Dashboard, Charts, and Datasets are validated before the whole bundle is published with one atomic no-replace rename. Connections are not included. The charts/ and datasets/ directories are export-only: client.raw.create.dashboard.from_file(...) and client.raw.replace.dashboard.from_file(...) read only dashboard.json and do not import or remap dependencies.

Development

The project uses Nox for every development check:

pip install nox

nox -s check         # complete local PR gate, including every supported Python
nox                  # same checks as `nox -s check`
nox -s lint          # Ruff lint
nox -s format        # format Python and JSON and apply safe lint fixes
nox -s format-check  # check formatting without modifying files
nox -s typecheck     # strict mypy
nox -s dependency-lower-bounds  # verify the dependency versions declared as minimums
nox -s tests-3.13    # test with a specific supported interpreter
nox -s update-specs  # update the default public API specification

Pass installation names after -- to update selected specifications:

nox -s update-specs -- yacloud
nox -s update-specs -- enterprise

Specification updates do not regenerate SDK sources. Review the specification diff, then run nox -s generate and the complete nox gate.

Maintainer release process

Every minor line is published from a protected release/X.Y branch. Production tags have the canonical vX.Y.Z or vX.Y.ZrcN form and must point to a commit on the matching release branch. Release-candidate numbering starts at rc1; subsequent candidates increment N, and the final release drops the rcN suffix. The publish workflow rejects a tag from any other branch, runs the complete quality and Python-version matrix, builds and validates one wheel and sdist, publishes those exact files, and attaches them to the GitHub Release. Release-candidate GitHub Releases are marked as pre-releases.

To start a new minor line:

1. Open a release PR against main that sets the final or release-candidate version and adds its dated changelog section. Use the canonical PEP 440 form X.Y.ZrcN, never the SemVer-style X.Y.Z-rc.N form.
2. Merge the PR after every required check passes.
3. Create release/X.Y from that merge commit and wait for the release-branch CI run to pass.
4. Create and push an annotated vX.Y.Z or vX.Y.ZrcN tag at that commit.
5. Approve the pypi deployment, then verify the published metadata, provenance, hashes, installation, and a read-only call.

For a patch on an older line, fix the defect on main first when it still applies there. Open a PR against release/X.Y using git cherry-pick -x, adapt the change if that line has diverged, update the patch version and changelog, and tag the merged release-branch commit. A fix that no longer applies to main may target only the release branch with the reason recorded in the PR.

TestPyPI is separate: manually run the Publish workflow from main. It executes the same complete verification and build path but requires approval of the testpypi environment and does not create a tag or GitHub Release.

Tags and published files are immutable. If a release is unusable, yank it where supported and publish a new patch version. Repository rulesets, deployment environments, and trusted publishers are configured outside the source tree by repository administrators.

Project policies

• Read CONTRIBUTING.md before opening a pull request.
• Report vulnerabilities privately according to SECURITY.md.
• Participation is governed by CODE_OF_CONDUCT.md.
• User-visible changes are recorded in CHANGELOG.md.

For general project questions, use GitHub Issues.

License

Licensed under the Apache License 2.0. See LICENSE.