Architecture

LazyDatabricks is built with Textual, a Python TUI framework.

Project Structure

src/lazydatabricks/
├── app.py               # CLI entry point
├── models/              # Data models — stable internal structs
│   ├── cluster.py       # ClusterSummary, ClusterState, ClusterFlag
│   ├── job.py           # JobSummary, RunSummary, RunDetail
│   ├── warehouse.py     # WarehouseSummary, WarehouseState
│   ├── health.py        # HealthSnapshot, SparkStatus
│   └── config.py        # LazyDatabricksConfig, DatabricksProfile
├── api/                 # API client layer
│   ├── client.py        # DatabricksClient (SDK wrapper)
│   ├── clusters.py      # ClusterOps
│   ├── jobs.py          # JobOps
│   ├── pipelines.py     # PipelineOps
│   ├── warehouses.py    # WarehouseOps
│   ├── health.py        # HealthBuilder
│   ├── logs.py          # LogOps
│   └── guard.py         # ArmedGuard (safety model)
├── tui/                 # Textual TUI
│   ├── app.py           # LazyDatabricksApp main class
│   ├── theme_config.py  # Theme configuration and CSS generation
│   ├── screens/         # Screen implementations
│   │   ├── base.py      # BaseScreen with common behavior
│   │   ├── home.py      # Health dashboard
│   │   ├── clusters.py  # Cluster management
│   │   ├── jobs.py      # Job/run management
│   │   ├── pipelines.py # Pipeline management
│   │   ├── warehouses.py# Warehouse management
│   │   ├── logs.py      # Log viewer
│   │   └── config.py    # Profile switcher
│   └── widgets/         # Reusable widgets
│       ├── header.py    # App header with workspace info
│       ├── footer_bar.py# Context-sensitive keybindings
│       ├── help_overlay.py
│       └── confirm_dialog.py
└── extensions/          # Optional feature extensions
    ├── base.py          # BaseExtension class
    └── billing/         # Billing extension

Key Components

Entry Point (`app.py`)

The CLI entry point handles:

Argument parsing
Client initialization
Command dispatch (TUI vs CLI mode)

Models (`models/`)

Stable internal data structures:

Decoupled from Databricks SDK types
Consistent interfaces for TUI consumption
Type-safe with dataclasses

API Layer (`api/`)

Wraps the Databricks SDK:

Background operations with Textual's @work decorator
Error handling and retries
ArmedGuard for destructive action safety

TUI (`tui/`)

The Textual application:

Screen-based navigation
Global keybindings for screen switching
Context-sensitive keybindings per screen

Extensions (`extensions/`)

Optional feature sets:

Loaded from config file
Self-contained screen and ops classes
Runtime requirement checking

Safety Model

The ArmedGuard class implements the armed mode:

class ArmedGuard:
    def __init__(self, ttl_seconds: int = 30):
        self._armed_until: datetime | None = None
        self._ttl_seconds = ttl_seconds

    @property
    def is_armed(self) -> bool:
        return self._armed_until and datetime.now() < self._armed_until

    def arm(self) -> None:
        self._armed_until = datetime.now() + timedelta(seconds=self._ttl_seconds)

    def disarm(self) -> None:
        self._armed_until = None

Styling

Theme-aware CSS generated from configuration:

Uses Textual design tokens ($background, $primary, etc.)
Terminal-aware defaults with textual-ansi theme
User-customizable via ~/.lazydatabricks/config.toml

On this page