datalens-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DataLens SDK

DataLens SDK

Operate Yandex DataLens through the official Python SDK — never hand-built HTTP requests.
Before continuing, locate and read the available skill whose name or namespaced basename is
datalens
. It supplies the shared installation and object-model context that applies alongside these SDK instructions. If it is absent, report an incomplete public DataLens skill installation and stop. After reading it, return here for SDK setup and execution.
The instructions for this skill are stored inside the installed
datalens-sdk
package
, and are extended there by whatever DataLens installation the environment targets. The SDK is a 0.x alpha where minor releases rename classes and methods, so instructions that shipped separately would describe an API the user does not have. Load them from the package before doing anything else.
If the user is only asking what the SDK is or whether it fits their task, answer that much from this file and stop. Do not run bootstrap or install a package merely to read its documentation.
通过官方 Python SDK 操作 Yandex DataLens——切勿自行构造 HTTP 请求。
继续之前,查找并阅读名称或带命名空间的 basename 为
datalens
的可用 skill。它提供与这些 SDK 指令并行适用的共享安装和对象模型上下文。如果不存在,则报告公共 DataLens skill 安装不完整并停止。阅读后,返回此处继续 SDK 设置和执行。
此 skill 的说明存储在已安装的
datalens-sdk
包内,并由环境所指向的 DataLens 安装版扩展。该 SDK 处于 0.x alpha 阶段,次要版本可能会重命名类和方法,因此单独提供的说明可能会描述用户当前没有的 API。开始任何操作前,先从包中加载这些说明。
如果用户只是询问 SDK 是什么或是否适合其任务,则仅根据本文件回答,然后停止。不要仅仅为了阅读文档而运行 bootstrap 或安装包。

Bootstrap, then load the instructions

运行 bootstrap,然后加载说明

Before the first SDK operation in a session, resolve this wrapper skill's directory to an absolute path and run its bootstrap script from the user's project directory:
bash
bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"
The script resolves a uv- or Poetry-managed project before considering
./.venv
, because those tools commonly own a same-named environment. It creates
./.venv
only for an unmanaged project. It verifies that every selected
bin/python
identifies itself as belonging to that environment, so a stale symlink can never install into system Python. It may contact the configured Python package index and install
datalens-sdk
into the selected environment.
The script deliberately does not encode an SDK version or a Python compatibility range. Plain environments query through the selected interpreter's pip configuration; uv and Poetry projects resolve through their native project sources. Candidate selection intersects the SDK metadata with
PROJECT_REQUIRES_PYTHON
and a numeric
.python-version
pin when present. Compatibility and freshness checks never upgrade pip or install the SDK or its dependencies. If a candidate can create a venv, bootstrap uses a disposable venv seeded by that exact interpreter for fresh-project probes and carries its pip source policy into the probe. Verified project environments are queried directly.
Parse the
KEY=VALUE
lines after the
---BOOTSTRAP---
marker:
  • STATUS=ready
    — use the absolute interpreter from
    PYTHON
    for every subsequent Python call.
  • STATUS=decision_required
    — do not load the package skill or perform SDK work yet:
    • REASON=sdk_install_required
      — a uv/Poetry project needs
      datalens-sdk
      installed through its manager. The dependency may already be declared but missing from an unsynced environment, or it may need to be added. This also covers an importable SDK that the manager's synchronization would remove or replace. Explain that the manager will select the exact version from the project's sources, lock, and Python constraints; reconciliation can upgrade or downgrade the currently importable SDK. The project manifest and lock may change when a dependency must be added, and uv may update a stale lock to match the manifest during reconciliation. A Poetry install can also install other missing locked dependencies but does not remove untracked packages; a uv sync is exact and can remove unmanaged packages. No
      SDK_VERSION
      or
      AVAILABLE_SDK_VERSION
      is expected before this consent. If they approve, run the exact command below, then parse its result again:
      bash
      bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdk
      Never substitute
      pip install
      inside a managed project.
    • REASON=sdk_update_available
      — tell the user the installed
      SDK_VERSION
      and newer compatible
      AVAILABLE_SDK_VERSION
      , give a clickable
      CHANGELOG_URL
      , and explicitly ask whether to keep the installed version or upgrade. Match the user's language. If they keep it, continue with the reported
      PYTHON
      . If they upgrade, run the exact command below with the reported available version, then parse its bootstrap result again:
      bash
      bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \
        --upgrade-sdk "$AVAILABLE_SDK_VERSION"
      If that run reports a different available version, ask again; consent to one version is not consent to another. Never substitute a direct pip command.
    • REASON=sdk_upgrade_target_unavailable
      — the approved version is no longer the compatible release offered by the index, and bootstrap will not downgrade or guess. Ask whether to keep the installed version or retry the original check later.
    • REASON=sdk_version_check_failed
      with
      SDK=installed
      — explain that the installed SDK works but its freshness or manager ownership could not be verified. Ask whether to continue with the reported
      SDK_VERSION
      or retry the original bootstrap command. Do not silently continue or describe it as current. This reason never applies to
      SDK=missing
      .
    • REASON=sdk_upgrade_failed
      with
      SDK=installed
      — explain that the upgrade failed but the reported
      SDK_VERSION
      remains usable. Ask whether to continue with it or stop; retry the exact upgrade command only if the user requests it.
  • STATUS=blocked
    — relay
    REASON
    and the relevant non-secret fields. Do not improvise another install command. When
    AVAILABLE_PYTHON
    is present, an existing incompatible
    ./.venv
    was preserved and the user must decide how to handle it. For
    venv_invalid
    , do not use or repair the interpreter path automatically. For
    managed_environment_unavailable
    or
    managed_environment_invalid
    , preserve the uv/Poetry project and ask the user to repair or select its managed environment; never create a parallel
    .venv
    . For
    managed_python_incompatible
    , ask the user to change the manager-selected Python rather than installing into a different environment. For
    configured_python_unavailable
    , ask the user to install or change the numeric versions in
    CONFIGURED_PYTHON
    ; for
    configured_python_incompatible
    , explain that the configured interpreter does not satisfy the intersection of
    PROJECT_REQUIRES_PYTHON
    and
    REQUIRES_PYTHON
    . For
    project_python_constraint_invalid
    or
    project_metadata_unreadable
    , ask the user to repair
    pyproject.toml
    . For
    sdk_install_failed
    , report that the managed environment was preserved and ask whether to retry or inspect the manager error outside the bootstrap protocol.
For any unrecognized
decision_required
reason, stop and show the parsed fields instead of guessing. A decision applies only to this session; do not write an opt-out marker.
If the marker or
STATUS
is absent, stop and show the raw output. Do not infer success from the process exit code. In particular, do not treat pip's generic "No matching distribution" message as proof that the package does not exist, do not upgrade the project's pip merely to improve the diagnostic, and never install into system Python.
Once bootstrap reports
ready
, or the user explicitly chooses a working installed version after
decision_required
, run this with the exact reported
PYTHON
:
bash
"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
    print(p)
"
It prints one absolute path per line: the base instructions first, then any installation overlays available in this environment. Extra lines are normal — they are additional detail for particular DataLens installations, and not all of them necessarily apply here.
Keep those absolute paths. Each directory carries its own bundled scripts, examples, and
references/
tree, referenced relative to it, and expects to be invoked by absolute path. Never
cd
into one; the user's project directory stays the working directory throughout.
Read
SKILL.md
from the first path now and follow it as if written here — it is authoritative and overrides anything you believe about this SDK, including anything in this file. It owns installation detection: it decides which of the remaining paths apply and tells you when to read them, so do not read an overlay before it says so. Where an overlay contradicts the base, the overlay wins. Read the references they route you to on demand, not all of them.
Do not write SDK code, install anything, answer an SDK question, or commit to an approach before you have read it. A plausible guess at this API is worse than one extra command.
Anything that writes files writes to the user's project directory or a temp dir; the package directory may be read-only or root-owned.
在会话中首次执行 SDK 操作之前,将此包装 skill 的目录解析为绝对路径,并从用户项目目录运行其 bootstrap 脚本:
bash
bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh"
该脚本会先解析由 uv 或 Poetry 管理的项目,然后才考虑
./.venv
,因为这些工具通常会管理一个同名环境。它仅为未受管理的项目创建
./.venv
。脚本会验证每个选定的
bin/python
都表明自己属于该环境,从而避免通过陈旧的符号链接安装到系统 Python。它可能会访问已配置的 Python 包索引,并将
datalens-sdk
安装到选定环境中。
该脚本有意不内置 SDK 版本或 Python 兼容范围。普通环境通过选定解释器的 pip 配置进行查询;uv 和 Poetry 项目则通过各自原生的项目源进行解析。候选选择会将 SDK 元数据与
PROJECT_REQUIRES_PYTHON
以及存在时的数字型
.python-version
固定版本取交集。兼容性和时效性检查绝不会升级 pip,也不会安装 SDK 或其依赖。如果候选解释器能够创建 venv,bootstrap 会使用以该确切解释器初始化的临时 venv 对全新项目进行探测,并将其 pip 源策略带入探测环境。已验证的项目环境则直接查询。
解析
---BOOTSTRAP---
标记之后的
KEY=VALUE
行:
  • STATUS=ready
    ——使用
    PYTHON
    给出的绝对解释器路径执行后续每一次 Python 调用。
  • STATUS=decision_required
    ——暂不加载 package skill,也不要执行 SDK 工作:
    • REASON=sdk_install_required
      ——uv/Poetry 项目需要通过其管理器安装
      datalens-sdk
      。该依赖可能已在项目清单中声明但环境中尚未同步,也可能需要添加。此情况也涵盖可导入的 SDK 恰好会被管理器的同步操作移除或替换。说明该管理器将从项目源、锁文件和 Python 约束中选择确切版本;依赖协调可能会升级或降级当前可导入的 SDK。当必须添加依赖时,项目清单和锁文件可能发生变化,且 uv 可能在协调期间更新过期锁文件以匹配清单。Poetry 安装还可以安装锁文件中其他缺失的依赖,但不会移除未跟踪的包;uv sync 是精确同步,可能会移除未受管理的包。在获得此项同意之前,不应出现
      SDK_VERSION
      或
      AVAILABLE_SDK_VERSION
      。如果用户同意,则运行以下确切命令,然后再次解析其结果:
      bash
      bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" --install-sdk
      在受管理的项目中,绝不要替换为
      pip install
      。
    • REASON=sdk_update_available
      ——告知用户已安装的
      SDK_VERSION
      和较新的兼容版本
      AVAILABLE_SDK_VERSION
      ,提供可点击的
      CHANGELOG_URL
      ,并明确询问是保留已安装版本还是升级。匹配用户的语言。如果用户选择保留,则使用所报告的
      PYTHON
      继续。如果用户选择升级,则使用所报告的可用版本运行以下确切命令,然后再次解析 bootstrap 结果:
      bash
      bash "/absolute/path/to/datalens-sdk/scripts/bootstrap.sh" \
        --upgrade-sdk "$AVAILABLE_SDK_VERSION"
      如果该运行报告了不同的可用版本,再次询问;对某个版本的同意不构成对另一个版本的同意。绝不要替换为直接 pip 命令。
    • REASON=sdk_upgrade_target_unavailable
      ——获准版本已不再是索引提供的兼容发行版,bootstrap 不会降级或猜测。询问用户是保留已安装版本,还是稍后重试原始检查。
    • REASON=sdk_version_check_failed
      且
      SDK=installed
      ——说明已安装的 SDK 可用,但无法验证其版本时效性或管理器归属。询问用户是继续使用所报告的
      SDK_VERSION
      ,还是重试原始 bootstrap 命令。不要在未说明的情况下继续,也不要将其描述为最新版本。此原因绝不适用于
      SDK=missing
      。
    • REASON=sdk_upgrade_failed
      且
      SDK=installed
      ——说明升级失败,但所报告的
      SDK_VERSION
      仍可使用。询问用户是继续使用还是停止;仅当用户提出要求时,才重试确切升级命令。
  • STATUS=blocked
    ——转述
    REASON
    和相关的非敏感字段。不要另行编造其他安装命令。当存在
    AVAILABLE_PYTHON
    时,现有不兼容的
    ./.venv
    已保留,用户必须决定如何处理。对于
    venv_invalid
    ,不要自动使用或修复解释器路径。对于
    managed_environment_unavailable
    或
    managed_environment_invalid
    ,保留 uv/Poetry 项目,并要求用户修复或选择其受管理环境;绝不创建并行
    .venv
    。对于
    managed_python_incompatible
    ,要求用户更改管理器选择的 Python,而不是安装到其他环境。对于
    configured_python_unavailable
    ,要求用户安装或更改
    CONFIGURED_PYTHON
    中的数字版本;对于
    configured_python_incompatible
    ,说明所配置的解释器不满足
    PROJECT_REQUIRES_PYTHON
    与
    REQUIRES_PYTHON
    的交集。对于
    project_python_constraint_invalid
    或
    project_metadata_unreadable
    ,要求用户修复
    pyproject.toml
    。对于
    sdk_install_failed
    ,报告受管理环境已保留,并询问是重试,还是在 bootstrap 协议之外检查管理器错误。
对于任何无法识别的
decision_required
原因,停止操作并显示解析出的字段,而不是进行猜测。决定仅适用于当前会话;不要写入 opt-out 标记。
如果缺少标记或
STATUS
,停止并显示原始输出。不要根据进程退出代码推断成功。特别是,不要将 pip 的通用消息 "No matching distribution" 视为包不存在的证据,不要仅为改进诊断而升级项目的 pip,也绝不要安装到系统 Python。
一旦 bootstrap 报告
ready
,或用户在
decision_required
后明确选择可用的已安装版本,请使用所报告的确切
PYTHON
运行:
bash
"$PYTHON" -c "
import datalens_sdk
for p in datalens_sdk.agent_skill_paths():
    print(p)
"
它会每行打印一个绝对路径:先是基础说明,然后是此环境中可用的任何 installation overlay。额外行是正常的——它们为特定 DataLens 安装提供补充细节,但不一定都适用于当前环境。
保留这些绝对路径。每个目录都包含自己的内置 scripts、examples 和
references/
目录树,其中的引用均相对于该目录,并要求按绝对路径调用。绝不要
cd
进入其中;整个过程中,用户项目目录始终作为工作目录。
现在读取第一个路径中的
SKILL.md
,并将其视为写在此处一样遵循——它是权威来源,会覆盖你对本 SDK 的任何理解,包括本文件中的任何内容。它负责安装检测:决定其余哪些路径适用,并告知何时读取,因此在它指示之前不要读取 overlay。如果 overlay 与基础说明冲突,以 overlay 为准。按需读取它们所指向的 references,不要一次性全部读取。
在读取之前,不要编写 SDK 代码、安装任何内容、回答 SDK 问题或确定实现方案。对此 API 作出看似合理的猜测,比多执行一条命令更糟糕。
所有写文件操作都应写入用户项目目录或临时目录;包目录可能是只读的,或由 root 所有。

Scope

范围

TaskWhere it belongs
Anything driving DataLens entities from Pythonhere — load the package instructions above
Standalone HTML pages and reports rendered by DataLens
datalens-html-pages
Publishing or managing an HTML page through the Python SDKhere, through the operations the package instructions document; if there are none, report that and offer an SDK upgrade or MCP/HTTP. Load
datalens-html-pages
for the publication procedure and the final link
The DataLens web UI, screenshots, embedding, metric interpretationneither — say it is out of scope and stop
任务适用范围
通过 Python 驱动 DataLens 实体的任何任务此处——加载上述 package 说明
由 DataLens 渲染的独立 HTML 页面和报告
datalens-html-pages
通过 Python SDK 发布或管理 HTML 页面此处,通过 package 说明所记录的操作;如果没有相关操作,则说明情况,并提供 SDK 升级或 MCP/HTTP 方案。加载
datalens-html-pages
以获取发布流程和最终链接
DataLens Web UI、屏幕截图、嵌入、指标解读两者均不适用——说明超出范围并停止