databricks360 0.1.0__tar.gz

databricks360-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+# Publishes to PyPI on a version tag, using Trusted Publishing (OIDC).
+#
+# No API token exists anywhere — not in repo secrets, not on a laptop. PyPI
+# verifies the workflow's short-lived OIDC identity instead. A leaked token is
+# the usual way a package supply chain gets compromised, so the best token is
+# one that was never created.
+#
+# One-time PyPI setup is described in README.md → Publishing.
+
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run tests
+        run: python run_tests.py
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+
+      - name: Fail if the tag does not match the package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python -c "import tomllib,pathlib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          echo "tag=$TAG  pyproject=$VER"
+          test "$TAG" = "$VER" || { echo "::error::Tag v$TAG does not match pyproject version $VER"; exit 1; }
+        if: startsWith(github.ref, 'refs/tags/v')
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Requires a GitHub environment named "pypi". Add required reviewers to it
+    # if you want a human approval gate before anything reaches the index.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

databricks360-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e .
+      - name: Run tests
+        run: python run_tests.py
+      - name: Verify the built wheel ships its SQL
+        run: |
+          python -m pip install --upgrade build
+          python -m build --wheel
+          python - <<'PY'
+          import glob, zipfile
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          sql = [n for n in names if n.endswith(".sql")]
+          assert len(sql) >= 3, f"expected the lab SQL in the wheel, found {sql}"
+          assert len(names) == len(set(names)), "duplicate entries in the wheel"
+          print(f"ok: {len(sql)} SQL files, no duplicates")
+          PY

databricks360-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+venv/
+.DS_Store

databricks360-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lakehouse Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

databricks360-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: databricks360
+Version: 0.1.0
+Summary: Install Databricks course lab environments: notebooks, catalogs, datasets and governance objects.
+Project-URL: Homepage, https://github.com/databrickslms/dbxdemos
+Project-URL: Source, https://github.com/databrickslms/dbxdemos
+Project-URL: Issues, https://github.com/databrickslms/dbxdemos/issues
+Author: Lakehouse Academy
+License: MIT
+License-File: LICENSE
+Keywords: databricks,genie,lakehouse,training,unity-catalog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Requires-Dist: databricks-sdk>=0.38.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# databricks360
+
+Installs Databricks course lab environments — notebooks, catalogs, datasets and
+governance objects — into your own workspace.
+
+Modelled on `dbdemos`: you run it **inside a Databricks notebook**, so
+`databricks-sdk` picks up the notebook's own identity. There is no host, token or
+profile to configure.
+
+## Install
+
+Not on PyPI yet, so install from the repo. In a **Databricks notebook**:
+
+```python
+%pip install git+https://github.com/databrickslms/dbxdemos.git
+dbutils.library.restartPython()
+```
+
+Once published, that becomes `%pip install databricks360`.
+
+To pin a version, append a tag or commit:
+
+```python
+%pip install git+https://github.com/databrickslms/dbxdemos.git@v0.1.0
+```
+
+## Usage
+
+```python
+import databricks360 as academy
+
+academy.list_courses()
+academy.install('genie-agents')
+```
+
+`install` writes the lab notebooks into your workspace and prints the run order.
+Then you open them and run each in turn.
+
+```
+Installed 'genie-agents' → /Workspace/Users/you@corp.com/databricks360/genie-agents
+  catalog: mfg    tier: small
+
+  Run these in order:
+    1. 01_catalog_and_schemas
+    2. 02_dimensions
+    3. 03_facts   (slow)
+```
+
+### Options
+
+```python
+academy.install(
+    'genie-agents',
+    path='/Workspace/Shared/labs',   # default: your home folder
+    catalog='training_v2',           # default: the course's own catalog
+    tier='large',                    # default: 'small'
+    overwrite=True,                  # replace existing notebooks
+)
+```
+
+## Why it does not run the notebooks for you
+
+`dbdemos` starts a job and loads the data on your behalf. This deliberately does
+not. Generating the data is the substance of Module 0 — the point is to watch a
+warehouse chew through 20M rows and see the flaws appear, not to have a finished
+catalog materialise. It also means nothing consumes your DBUs without you asking.
+
+## Tiers
+
+| Tier | Transactions | Use |
+|---|---|---|
+| `small` | 20M | default. Every module except 13 |
+| `large` | 900M | Module 13 (latency) only. Left unclustered on purpose |
+
+Start small. The large tier exists because you cannot measure query latency on a
+toy dataset, and nowhere else needs it.
+
+## Adding a course
+
+Each course is a subpackage under `databricks360/courses/`:
+
+```
+databricks360/courses/<course_id>/
+  __init__.py
+  manifest.json      # title, default catalog, tiers, notebooks in run order
+  *.sql              # synced from content/courses/<id>/assets/lab/
+```
+
+Placeholders available in the SQL: `{{CATALOG}}`, plus anything declared under a
+tier's `values` (currently `{{TXN_COUNT}}`). An unresolved placeholder raises rather
+than silently rendering empty.
+
+Dataset documentation lives in [`docs/`](docs/).
+
+## Publishing
+
+Releases go to PyPI via **Trusted Publishing** — GitHub Actions authenticates to
+PyPI with a short-lived OIDC identity, so no API token exists in repo secrets or on
+anyone's laptop. A leaked token is the usual way a package supply chain gets
+compromised; the safest token is one that was never created.
+
+### One-time PyPI setup
+
+1. Sign in at [pypi.org](https://pypi.org) → **Your account → Publishing**
+2. Under *Add a new pending publisher*, choose **GitHub** and enter exactly:
+
+   | Field | Value |
+   |---|---|
+   | PyPI Project Name | `databricks360` |
+   | Owner | `databrickslms` |
+   | Repository name | `dbxdemos` |
+   | Workflow name | `publish.yml` |
+   | Environment name | `pypi` |
+
+3. In GitHub → **Settings → Environments → New environment** → name it `pypi`.
+   Add yourself as a required reviewer if you want to approve each release.
+
+"Pending" publisher is correct — the project does not exist on PyPI yet, and the
+first successful run creates it.
+
+### Cutting a release
+
+```bash
+# bump version in pyproject.toml, commit, then:
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs the tests, builds, checks the tag matches `pyproject.toml`, and
+publishes. A mismatched tag fails before anything reaches the index — versions on
+PyPI are immutable, so a wrong number cannot be taken back, only yanked.
+
+### Publishing by hand instead
+
+```bash
+python -m pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*          # prompts for an API token
+```
+
+Test it against TestPyPI first if you want a dry run:
+`twine upload --repository testpypi dist/*`.
+
+## Tests
+
+```bash
+python3 run_tests.py
+```
+
+Eleven tests, no workspace required: manifest loading, notebook cell structure,
+catalog substitution, tier switching, unresolved-placeholder detection, and a
+`dry_run` install. It also asserts the flaw-teaching column comments survive into
+the generated notebooks — those comments are the curriculum, so losing them in
+rendering would be a silent failure.

databricks360-0.1.0/README.md

@@ -0,0 +1,155 @@
+# databricks360
+
+Installs Databricks course lab environments — notebooks, catalogs, datasets and
+governance objects — into your own workspace.
+
+Modelled on `dbdemos`: you run it **inside a Databricks notebook**, so
+`databricks-sdk` picks up the notebook's own identity. There is no host, token or
+profile to configure.
+
+## Install
+
+Not on PyPI yet, so install from the repo. In a **Databricks notebook**:
+
+```python
+%pip install git+https://github.com/databrickslms/dbxdemos.git
+dbutils.library.restartPython()
+```
+
+Once published, that becomes `%pip install databricks360`.
+
+To pin a version, append a tag or commit:
+
+```python
+%pip install git+https://github.com/databrickslms/dbxdemos.git@v0.1.0
+```
+
+## Usage
+
+```python
+import databricks360 as academy
+
+academy.list_courses()
+academy.install('genie-agents')
+```
+
+`install` writes the lab notebooks into your workspace and prints the run order.
+Then you open them and run each in turn.
+
+```
+Installed 'genie-agents' → /Workspace/Users/you@corp.com/databricks360/genie-agents
+  catalog: mfg    tier: small
+
+  Run these in order:
+    1. 01_catalog_and_schemas
+    2. 02_dimensions
+    3. 03_facts   (slow)
+```
+
+### Options
+
+```python
+academy.install(
+    'genie-agents',
+    path='/Workspace/Shared/labs',   # default: your home folder
+    catalog='training_v2',           # default: the course's own catalog
+    tier='large',                    # default: 'small'
+    overwrite=True,                  # replace existing notebooks
+)
+```
+
+## Why it does not run the notebooks for you
+
+`dbdemos` starts a job and loads the data on your behalf. This deliberately does
+not. Generating the data is the substance of Module 0 — the point is to watch a
+warehouse chew through 20M rows and see the flaws appear, not to have a finished
+catalog materialise. It also means nothing consumes your DBUs without you asking.
+
+## Tiers
+
+| Tier | Transactions | Use |
+|---|---|---|
+| `small` | 20M | default. Every module except 13 |
+| `large` | 900M | Module 13 (latency) only. Left unclustered on purpose |
+
+Start small. The large tier exists because you cannot measure query latency on a
+toy dataset, and nowhere else needs it.
+
+## Adding a course
+
+Each course is a subpackage under `databricks360/courses/`:
+
+```
+databricks360/courses/<course_id>/
+  __init__.py
+  manifest.json      # title, default catalog, tiers, notebooks in run order
+  *.sql              # synced from content/courses/<id>/assets/lab/
+```
+
+Placeholders available in the SQL: `{{CATALOG}}`, plus anything declared under a
+tier's `values` (currently `{{TXN_COUNT}}`). An unresolved placeholder raises rather
+than silently rendering empty.
+
+Dataset documentation lives in [`docs/`](docs/).
+
+## Publishing
+
+Releases go to PyPI via **Trusted Publishing** — GitHub Actions authenticates to
+PyPI with a short-lived OIDC identity, so no API token exists in repo secrets or on
+anyone's laptop. A leaked token is the usual way a package supply chain gets
+compromised; the safest token is one that was never created.
+
+### One-time PyPI setup
+
+1. Sign in at [pypi.org](https://pypi.org) → **Your account → Publishing**
+2. Under *Add a new pending publisher*, choose **GitHub** and enter exactly:
+
+   | Field | Value |
+   |---|---|
+   | PyPI Project Name | `databricks360` |
+   | Owner | `databrickslms` |
+   | Repository name | `dbxdemos` |
+   | Workflow name | `publish.yml` |
+   | Environment name | `pypi` |
+
+3. In GitHub → **Settings → Environments → New environment** → name it `pypi`.
+   Add yourself as a required reviewer if you want to approve each release.
+
+"Pending" publisher is correct — the project does not exist on PyPI yet, and the
+first successful run creates it.
+
+### Cutting a release
+
+```bash
+# bump version in pyproject.toml, commit, then:
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs the tests, builds, checks the tag matches `pyproject.toml`, and
+publishes. A mismatched tag fails before anything reaches the index — versions on
+PyPI are immutable, so a wrong number cannot be taken back, only yanked.
+
+### Publishing by hand instead
+
+```bash
+python -m pip install build twine
+python -m build
+twine check dist/*
+twine upload dist/*          # prompts for an API token
+```
+
+Test it against TestPyPI first if you want a dry run:
+`twine upload --repository testpypi dist/*`.
+
+## Tests
+
+```bash
+python3 run_tests.py
+```
+
+Eleven tests, no workspace required: manifest loading, notebook cell structure,
+catalog substitution, tier switching, unresolved-placeholder detection, and a
+`dry_run` install. It also asserts the flaw-teaching column comments survive into
+the generated notebooks — those comments are the curriculum, so losing them in
+rendering would be a silent failure.

databricks360-0.1.0/databricks360/__init__.py

@@ -0,0 +1,67 @@
+"""Lakehouse Academy — install Databricks course lab environments.
+
+Run inside a Databricks notebook:
+
+    %pip install databricks360
+    dbutils.library.restartPython()
+
+    import databricks360 as academy
+    academy.list_courses()
+    academy.install('genie-agents')
+
+`install` writes the lab notebooks into your workspace. You then run them in
+order. Nothing is executed for you: generating the data is real work on your
+warehouse, and watching it happen is part of the lesson.
+"""
+
+from __future__ import annotations
+
+from ._catalog import Course, available_courses, get_course
+from ._install import Installation, build_notebook_source, install
+
+__version__ = "0.1.0"
+__all__ = [
+    "install",
+    "list_courses",
+    "get_course",
+    "available_courses",
+    "build_notebook_source",
+    "Course",
+    "Installation",
+    "__version__",
+]
+
+
+def list_courses() -> None:
+    """Print the available course labs."""
+    courses = available_courses()
+    if not courses:
+        print("No courses bundled in this build.")
+        return
+
+    for course in courses:
+        print(f"\n{course.id}")
+        print(f"  {course.title}")
+        if course.description:
+            for line in _wrap(course.description, 76):
+                print(f"    {line}")
+        print(f"  catalog: {course.default_catalog}   notebooks: {len(course.notebooks)}")
+        if course.tiers:
+            print("  tiers:")
+            for name, tier in course.tiers.items():
+                marker = " (default)" if name == course.default_tier else ""
+                print(f"    {name}{marker} — {tier.description}")
+    print(f"\nInstall with: academy.install('{courses[0].id}')\n")
+
+
+def _wrap(text: str, width: int) -> list[str]:
+    words, lines, current = text.split(), [], ""
+    for word in words:
+        if len(current) + len(word) + 1 > width:
+            lines.append(current)
+            current = word
+        else:
+            current = f"{current} {word}".strip()
+    if current:
+        lines.append(current)
+    return lines

databricks360-0.1.0/databricks360/_catalog.py

@@ -0,0 +1,99 @@
+"""Course discovery: reads the manifests bundled with the package."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Notebook:
+    """One notebook in a course's lab, in run order."""
+
+    order: int
+    name: str
+    sql: str
+    title: str
+    intro: str = ""
+    requires_admin: bool = False
+    slow: bool = False
+
+
+@dataclass(frozen=True)
+class Tier:
+    name: str
+    values: dict
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class Course:
+    id: str
+    title: str
+    description: str
+    default_catalog: str
+    notebooks: list = field(default_factory=list)
+    tiers: dict = field(default_factory=dict)
+    default_tier: str = "small"
+
+    @property
+    def package(self) -> str:
+        return f"databricks360.courses.{self.id.replace('-', '_')}"
+
+
+def _course_packages() -> list:
+    root = resources.files("databricks360.courses")
+    return sorted(
+        p.name
+        for p in root.iterdir()
+        if p.is_dir() and not p.name.startswith("_") and (p / "manifest.json").is_file()
+    )
+
+
+def _load(pkg_name: str) -> Course:
+    raw: dict = json.loads(
+        (resources.files(f"databricks360.courses.{pkg_name}") / "manifest.json")
+        .read_text(encoding="utf-8")
+    )
+    return Course(
+        id=raw["id"],
+        title=raw["title"],
+        description=raw.get("description", ""),
+        default_catalog=raw.get("default_catalog", "main"),
+        default_tier=raw.get("default_tier", "small"),
+        notebooks=[
+            Notebook(
+                order=n["order"],
+                name=n["name"],
+                sql=n["sql"],
+                title=n["title"],
+                intro=n.get("intro", ""),
+                requires_admin=n.get("requires_admin", False),
+                slow=n.get("slow", False),
+            )
+            for n in sorted(raw["notebooks"], key=lambda n: n["order"])
+        ],
+        tiers={
+            name: Tier(name=name, values=t["values"], description=t.get("description", ""))
+            for name, t in raw.get("tiers", {}).items()
+        },
+    )
+
+
+def available_courses() -> list:
+    return [_load(p) for p in _course_packages()]
+
+
+def get_course(course_id: str) -> Course:
+    wanted = course_id.replace("-", "_")
+    for pkg in _course_packages():
+        if pkg == wanted:
+            return _load(pkg)
+    known = ", ".join(c.id for c in available_courses()) or "none"
+    raise ValueError(f"Unknown course {course_id!r}. Available: {known}")
+
+
+def read_sql(course: Course, filename: str) -> str:
+    return (resources.files(course.package) / filename).read_text(encoding="utf-8")