dbrdemo

Reference implementation for a Python library that runs locally through Databricks Connect and as an installed Python wheel on Databricks.

It includes:

• Python 3.12 environments and dependency installation with uv
• Ruff formatting/linting and Pyright type checking
• Test examples for the Databricks SDK for Python, Databricks Connect, and Unity Catalog; Databricks Connect supplies the PySpark client transitively
• wheel-packaged documentation and Genie Code Agent Skills
• Unity Gateway support for compatible coding agents
• a sample Azure DevOps Pipeline

Quick start

1. Install version 2.17 or newer of the Databricks VS Code extension.

2. Authenticate with a clear profile name.

3. Select serverless or classic compute.

4. Prepare the repository with direnv:

   make direnv    # install direnv and its shell hook

5. Open a new terminal, then run:

   direnv allow   # load the extension-generated Databricks environment
   make dev       # create the Python 3.12 development environment
   make flint     # format, lint, and type-check

See Developer setup for details. Windows users should use WSL2.

Key libraries

uv installs these dependencies; their source is not vendored:

• Databricks SDK for Python, and Databricks Connect
• pytest, Databricks Labs pytester, Databricks Labs Blueprint, pytest-xdist, and pytest-cov
• Ruff and Pyright

See Testing for their roles.

Example library

Append a foo/bar row to a Databricks table:

from dbrdemo import install_logger, write_foobar

install_logger()  # Optional: show events emitted by the library.
write_foobar("main.demo.foobar", "hello", "world")

The CLI calls the same function:

dbrdemo-foobar --table main.demo.foobar --foo hello --bar world

See the foo/bar user guide for the DataFrame API and table behavior. The local VS Code notebook guide explains how to run dbrdemo-example.ipynb through Databricks Connect.

Documentation

• User documentation: library and CLI usage
• Admin documentation: skill installation and Azure DevOps
• Developer documentation: setup, testing, packaging, and coding agents

Docs and skills ship in the wheel, so users and agents get guidance matching the installed code.

Display bundled documentation from Python:

from dbrdemo.documentation import read_doc

print(read_doc("README.md"))

Release examples

make release ENV=dev DAILY_BUILD_NUMBER=42   # dbrdemo-0.2.0.dev0+2026.9.25.42.abc123-py3-none-any.whl
make release ENV=test DAILY_BUILD_NUMBER=42  # dbrdemo-0.2.0b0+2026.9.25.42.abc123-py3-none-any.whl
make release ENV=acc DAILY_BUILD_NUMBER=42   # dbrdemo-0.2.0rc0+2026.9.25.42.abc123-py3-none-any.whl
make release ENV=prod                        # dbrdemo-0.2.0-py3-none-any.whl
make release ENV=prod VOLUME=main.packages.prod  # uploads dbrdemo-0.2.0-py3-none-any.whl

Volume policy: dev may overwrite; test, acc, and prod are immutable. See Packaging for details.

Agent Skills

The bundled skill teaches Genie Code how to use the example library. The preferred enterprise deployment installs it for the entire workspace:

from dbrdemo.skills import install_workspace_skills

install_workspace_skills()

User-scoped installation is only for testing and troubleshooting; user skills have lower priority than workspace skills. See Install Agent Skills. Compatible local coding agents can use make install_skills.

Ideas for production projects

Keep this reference small, then add controls your project needs:

• Commit uv.lock when deployments require fully reproducible dependency resolution.
• Add Radon or Xenon complexity limits.
• Run formatting and checks automatically with pre-commit.
• Scan dependencies with pip-audit and Python code with Bandit.
• Automate dependency updates with Dependabot or Renovate.
• Enforce a minimum test coverage percentage in CI.

Use this starter

Follow RENAME.md to rename the package, CLI commands, and Agent Skills for your project.