dbx-sync 0.1.0__tar.gz

dbx_sync-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @gramhagen

dbx_sync-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v1.2.3
+      - v*
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      - name: Install project and dev dependencies
+        run: uv sync --dev
+
+      - name: Run test suite
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish dist/*

dbx_sync-0.1.0/.github/workflows/test-release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v1.2.3
+      - v*
+
+jobs:
+  test-pypi:
+    name: Publish to Test PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      name: test-pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      - name: Install project and dev dependencies
+        run: uv sync --dev
+
+      - name: Run test suite
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --index test-pypi dist/*

dbx_sync-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Editor settings
+.DS_Store
+.vscode/

dbx_sync-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

dbx_sync-0.1.0/AGENTS.md

@@ -0,0 +1,42 @@
+# Agent Workflow Notes
+
+This repository uses a single shared instruction file for coding agents.
+
+## Default workflow
+
+1. Sync dependencies with `uv sync --dev`.
+2. Implement code inside `src/dbx_sync/` using typed functions and small modules.
+3. Add or update tests in `tests/` for each user-visible change.
+4. Run `uv run ruff format .`, `uv run ruff check .`, `uv run ty check`, and `uv run pytest` before handing work back.
+5. Use `uv build` and `uv publish` for packaging and release operations.
+
+## Guardrails
+
+- Keep configuration centralized in `pyproject.toml` where practical.
+- Prefer extending the package API instead of adding loose scripts at repository root.
+- Evolve behavior incrementally with tests rather than broad rewrites.
+- Keep agent-specific workflow guidance here instead of splitting it across multiple files.
+
+## Python Conventions
+
+- Write readable, maintainable Python with descriptive names and explicit type hints.
+- Break down complex logic into smaller helper functions instead of growing large multi-purpose functions.
+- Use docstrings for non-trivial public functions and classes, following PEP 257 and concise Google-style sections when helpful.
+- Prefer clear exception handling and cover edge cases such as missing inputs, invalid data, and empty results.
+- Keep comments focused on intent or non-obvious design decisions; avoid narrating obvious code.
+- Use logging module formatting for log messages instead of f-strings in logging calls.
+
+## Python Style
+
+- Follow PEP 8 with 4-space indentation.
+- Keep code consistent with the repository toolchain: Ruff formatting, Ty type checking, and the line-length configured in `pyproject.toml`.
+- Use modern built-in generics and standard typing features appropriate for Python 3.10+.
+- Place docstrings immediately after function, class, or module declarations.
+- Prefer straightforward, idiomatic Python over clever or overly abstract patterns.
+
+## Testing Expectations
+
+- Add unit tests for critical paths and behavior changes.
+- Include edge-case coverage for empty inputs, invalid state, and error handling when those paths matter.
+- Keep tests readable and focused on behavior rather than implementation detail.
+- When adapting logic from another codebase, translate the relevant tests into this repo's current API instead of copying obsolete cases unchanged.

dbx_sync-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+## Local Setup
+
+Local development targets Python 3.12.
+
+```bash
+uv sync --dev
+```
+
+The Databricks CLI is required for running the tool against a real workspace.
+
+- Install or update the Databricks CLI: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/cli/install>
+- Configure a Databricks CLI profile: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/cli/reference/configure-commands#create-a-configuration-profile>
+
+## Development Workflow
+
+- Implement changes inside `src/dbx_sync/`.
+- Add or update tests in `tests/` for behavior changes.
+- Keep changes typed, readable, and small enough to review comfortably.
+- Use `uv run` for project commands so the local environment and lockfile stay authoritative.
+
+## Validation
+
+Run the full local validation suite before finishing non-trivial changes.
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+Generate a line-by-line HTML coverage report when needed.
+
+```bash
+uv run pytest --cov=dbx_sync --cov-report term-missing --cov-report html
+```
+
+The HTML coverage report is written to `htmlcov/`.
+
+## CLI Notes
+
+- Required positional arguments: local directory, workspace path.
+- Optional flags: `--profile`, `--poll-interval`, `--log-level`, `--dry-run`, `--watch`, `--force`.
+- The current sync scope is a single folder level only; local discovery is not recursive.
+- The current local tracking scope is Databricks notebook files with supported notebook extensions.
+- Use `--force` to clear saved sync state and trigger a fresh comparison.
+
+## Packaging And Release
+
+Build and publish with uv.
+
+```bash
+uv build
+uv publish
+```
+
+If you want to test the packaged CLI experience locally, install it as a uv tool:
+
+```bash
+uv tool install .
+```
+
+## License
+
+This repository is released under the MIT license. See `LICENSE` for the full text.
+
+## Agent Guidance
+
+- Shared coding-agent instructions live in `AGENTS.md`.
+- Keep repository-specific conventions there rather than creating overlapping instruction files.

dbx_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbx-sync contributors
+
+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.

dbx_sync-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dbx-sync
+Version: 0.1.0
+Summary: Synchronize Databricks workspace content with a local directory.
+Author: gramhagen
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dbx-sync
+
+```text
+         __ __
+    ,___/ // /____   __      _____ __  ______  _____
+   / __  // __ \\ \ / /_____/ ___// / / / __ \/ ___/
+  / /_/ // /_/ //  X  \____(__  )/ /_/ / / / / /__
+ /_____//_____//__/ \__\  /____/ \__, /_/ /_/\___/
+                                 /____/
+```
+
+Are you tired of bouncing between the Databricks workspace UI and your local editor, copying changes by hand, and pretending that counts as a workflow? Well now there's `dbx-sync`.
+
+`dbx-sync` keeps a single Databricks workspace folder and a single local directory in sync so you can work with your favorite tools and still stay aligned with what is running in Databricks.
+
+Build locally, run in Databricks, tweak it there, then jump back to local coding. Skip the usual copy-paste ritual or one-way imports to weird folders.
+
+Great for AI coding-agent workflows, including GitHub Copilot and Claude-based setups that work best against a real local folder.
+
+Worried about losing files? `dbx-sync` does not delete files locally or remotely, but it can overwrite content if both sides changed while you were not syncing. Use version control locally and Databricks revision history remotely when you need rollback.
+
+Current scope notes:
+
+- Sync is limited to a single local folder and a single Databricks workspace folder.
+- File and folder discovery is not recursive.
+- Local tracking currently covers notebook files with Databricks notebook extensions: `.py`, `.sql`, `.scala`, `.r`, and `.ipynb`.
+
+## Prerequisites
+
+- Databricks CLI 0.205 or newer
+  - With a configured Databricks CLI profile
+
+## Install
+
+### Recommended: install as a uv tool
+
+Install `dbx-sync` as a tool so you can run it directly from your shell:
+
+```bash
+uv tool install dbx-sync
+```
+
+### Alternative: install with pip
+
+If you prefer a standard virtual environment workflow, install the package with `pip`:
+
+```bash
+python -m pip install dbx-sync
+```
+
+### Alternative: run from a local checkout
+
+If you are developing on the project itself, install the local environment and run it with `uv run`:
+
+```bash
+uv sync --dev
+uv run dbx-sync ./local-project /Workspace/Users/me/project
+```
+
+## Usage
+
+Sync a single workspace folder with a single local folder (one-time):
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project
+```
+
+Preview actions without applying them:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --dry-run
+```
+
+Continuously watch and resync (default polling happens every second):
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --watch
+```
+
+Override optional settings when needed:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project \
+	--profile WORKSPACE \
+	--poll-interval 5 \
+	--log-level DEBUG \
+	--force
+```
+
+Use `--force` to clear saved sync state before a fresh pass.
+
+The local directory may start empty or not exist yet. On a non-dry-run sync, the tool creates what it needs under that directory when files or sync state are written.
+
+## Alternatives
+Yes, I recognize there are a variety of official ways to do something close to this, but none of them fit my desired workflow well. So here are some references for alternatives.
+
+- Databricks CLI workspace commands (`import`, `import-dir`, `export`, `export-dir`, `sync`, and related commands): <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/cli/commands/>
+- Databricks extension for Visual Studio Code: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/vscode-ext/>
+- Databricks Asset Bundles documentation: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/bundles/>
+- Databricks Git folders: <https://learn.microsoft.com/en-us/azure/databricks/repos/>
+
+## Development
+
+See [CONTRIBUTING.md](/home/scgraham/repos/dbx-sync/CONTRIBUTING.md) for local development, testing, release, and repository workflow details.
+
+## License
+
+MIT. See [LICENSE](/home/scgraham/repos/dbx-sync/LICENSE).

dbx_sync-0.1.0/README.md

@@ -0,0 +1,108 @@
+# dbx-sync
+
+```text
+         __ __
+    ,___/ // /____   __      _____ __  ______  _____
+   / __  // __ \\ \ / /_____/ ___// / / / __ \/ ___/
+  / /_/ // /_/ //  X  \____(__  )/ /_/ / / / / /__
+ /_____//_____//__/ \__\  /____/ \__, /_/ /_/\___/
+                                 /____/
+```
+
+Are you tired of bouncing between the Databricks workspace UI and your local editor, copying changes by hand, and pretending that counts as a workflow? Well now there's `dbx-sync`.
+
+`dbx-sync` keeps a single Databricks workspace folder and a single local directory in sync so you can work with your favorite tools and still stay aligned with what is running in Databricks.
+
+Build locally, run in Databricks, tweak it there, then jump back to local coding. Skip the usual copy-paste ritual or one-way imports to weird folders.
+
+Great for AI coding-agent workflows, including GitHub Copilot and Claude-based setups that work best against a real local folder.
+
+Worried about losing files? `dbx-sync` does not delete files locally or remotely, but it can overwrite content if both sides changed while you were not syncing. Use version control locally and Databricks revision history remotely when you need rollback.
+
+Current scope notes:
+
+- Sync is limited to a single local folder and a single Databricks workspace folder.
+- File and folder discovery is not recursive.
+- Local tracking currently covers notebook files with Databricks notebook extensions: `.py`, `.sql`, `.scala`, `.r`, and `.ipynb`.
+
+## Prerequisites
+
+- Databricks CLI 0.205 or newer
+  - With a configured Databricks CLI profile
+
+## Install
+
+### Recommended: install as a uv tool
+
+Install `dbx-sync` as a tool so you can run it directly from your shell:
+
+```bash
+uv tool install dbx-sync
+```
+
+### Alternative: install with pip
+
+If you prefer a standard virtual environment workflow, install the package with `pip`:
+
+```bash
+python -m pip install dbx-sync
+```
+
+### Alternative: run from a local checkout
+
+If you are developing on the project itself, install the local environment and run it with `uv run`:
+
+```bash
+uv sync --dev
+uv run dbx-sync ./local-project /Workspace/Users/me/project
+```
+
+## Usage
+
+Sync a single workspace folder with a single local folder (one-time):
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project
+```
+
+Preview actions without applying them:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --dry-run
+```
+
+Continuously watch and resync (default polling happens every second):
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --watch
+```
+
+Override optional settings when needed:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project \
+	--profile WORKSPACE \
+	--poll-interval 5 \
+	--log-level DEBUG \
+	--force
+```
+
+Use `--force` to clear saved sync state before a fresh pass.
+
+The local directory may start empty or not exist yet. On a non-dry-run sync, the tool creates what it needs under that directory when files or sync state are written.
+
+## Alternatives
+Yes, I recognize there are a variety of official ways to do something close to this, but none of them fit my desired workflow well. So here are some references for alternatives.
+
+- Databricks CLI workspace commands (`import`, `import-dir`, `export`, `export-dir`, `sync`, and related commands): <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/cli/commands/>
+- Databricks extension for Visual Studio Code: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/vscode-ext/>
+- Databricks Asset Bundles documentation: <https://learn.microsoft.com/en-us/azure/databricks/dev-tools/bundles/>
+- Databricks Git folders: <https://learn.microsoft.com/en-us/azure/databricks/repos/>
+
+## Development
+
+See [CONTRIBUTING.md](/home/scgraham/repos/dbx-sync/CONTRIBUTING.md) for local development, testing, release, and repository workflow details.
+
+## License
+
+MIT. See [LICENSE](/home/scgraham/repos/dbx-sync/LICENSE).

dbx_sync-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dbx-sync"
+version = "0.1.0"
+description = "Synchronize Databricks workspace content with a local directory."
+authors = [{ name = "gramhagen" }]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+dbx-sync = "dbx_sync.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.11.0",
+    "ty>=0.0.23",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dbx_sync"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers --strict-config"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["dbx_sync"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "SIM", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+name = "test-pypi"
+url = "https://test.pypi.org/legacy/"
+publish-url = "https://test.pypi.org/legacy/"

dbx_sync-0.1.0/src/dbx_sync/__init__.py

@@ -0,0 +1,5 @@
+"""dbx-sync package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

dbx_sync-0.1.0/src/dbx_sync/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dbx_sync-0.1.0/src/dbx_sync/cli.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from pathlib import Path
+
+from dbx_sync.sync import run_sync
+
+DEFAULT_POLL_INTERVAL_SECONDS = 1
+LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def positive_int(value: str) -> int:
+    """Parse a strictly positive integer argument.
+
+    Args:
+        value: Raw command-line argument text.
+
+    Returns:
+        int: Parsed positive integer value.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a positive integer.
+    """
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for the sync tool."""
+    parser = argparse.ArgumentParser(
+        prog="dbx-sync",
+        description="Synchronize Databricks workspace files to a local directory.",
+    )
+    parser.add_argument("local_dir", help="Local directory to sync")
+    parser.add_argument("workspace", help="Databricks workspace folder to sync")
+    parser.add_argument("--profile", default="DEFAULT", help="Databricks CLI profile name")
+    parser.add_argument(
+        "-p",
+        "--poll-interval",
+        type=positive_int,
+        default=DEFAULT_POLL_INTERVAL_SECONDS,
+        help="Polling interval in seconds when running in watch mode",
+    )
+    parser.add_argument(
+        "-l",
+        "--log-level",
+        choices=LOG_LEVELS,
+        default="INFO",
+        help="Logging level",
+    )
+    parser.add_argument(
+        "-d",
+        "--dry-run",
+        action="store_true",
+        help="Plan the sync without applying changes.",
+    )
+    parser.add_argument(
+        "-w",
+        "--watch",
+        action="store_true",
+        help="Watch for changes and sync continuously",
+    )
+    parser.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Force a refresh by clearing saved sync state before running",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse CLI arguments and run a sync operation.
+
+    Args:
+        argv: Optional argument vector used instead of sys.argv.
+
+    Returns:
+        int: Process exit code from the sync operation.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return run_sync(
+        local_dir=Path(args.local_dir).expanduser().resolve(),
+        remote_path=args.workspace,
+        profile=args.profile,
+        poll_interval_seconds=args.poll_interval,
+        log_level=args.log_level,
+        dry_run=args.dry_run,
+        watch=args.watch,
+        force=args.force,
+    )