dbx-sync 0.2.0__tar.gz → 0.4.0__tar.gz

{dbx_sync-0.2.0 → dbx_sync-0.4.0}/AGENTS.md

@@ -6,9 +6,9 @@ This repository uses a single shared instruction file for coding agents.
 
 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.
+3. Update README.md to document new or changed functionality.
+4. Add or update tests in `tests/` for each user-visible change.
+5. Run `uv run ruff format .`, `uv run ruff check .`, `uv run ty check`, and `uv run pytest` before handing work back.
 
 ## Guardrails
 
@@ -39,4 +39,3 @@ This repository uses a single shared instruction file for coding agents.
 - 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.2.0 → dbx_sync-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbx-sync
-Version: 0.2.0
+Version: 0.4.0
 Summary: Synchronize Databricks workspace content with a local directory.
 Project-URL: Repository, https://github.com/gramhagen/dbx-sync
 Author: gramhagen
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 
 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.
+`dbx-sync` keeps a Databricks workspace folder or file and a local directory or file 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.
 
@@ -32,9 +32,10 @@ Worried about losing files? `dbx-sync` does not delete files locally or remotely
 
 Current scope notes:
 
-- Sync is limited to a single local folder and a single Databricks workspace folder.
+- Sync is limited to a single local folder/workspace folder pair or one local/workspace file pair.
 - File and folder discovery is not recursive.
 - Local tracking currently covers notebook files with Databricks notebook extensions: `.py`, `.sql`, `.scala`, `.r`, and `.ipynb`.
+- When syncing a single local file, notebook extensions are imported as notebooks and other files are imported as workspace files.
 
 ## Prerequisites
 
@@ -83,6 +84,24 @@ Sync a single workspace folder with a single local folder (one-time):
 dbx-sync ./local-project /Workspace/Users/me/project
 ```
 
+Sync a single local file to a workspace folder, using the source filename for the target object:
+
+```bash
+dbx-sync ./local-project/notebook.py /Workspace/Users/me/project
+```
+
+Sync a single workspace file or notebook to a local folder, using the source filename locally:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project/notebook
+```
+
+Sync explicit local and workspace file paths:
+
+```bash
+dbx-sync ./local-project/notebook.py /Workspace/Users/me/project/notebook
+```
+
 Preview actions without applying them:
 
 ```bash
@@ -95,6 +114,19 @@ Continuously watch and resync (default polling happens every second):
 dbx-sync ./local-project /Workspace/Users/me/project --watch
 ```
 
+Use `--force` to clear saved sync state before a fresh pass. This can be useful to handle conflicts. 
+Pro-tip: Add --dry-run to check force behavior before running it for real.
+
+Force options are mutually exclusive and only apply to a single sync pass:
+
+- `--force` clears saved sync state before comparing local and remote files.
+- `--force-upload` uploads matching local files even when saved sync state would otherwise skip them.
+- `--force-download` downloads matching remote files even when saved sync state would otherwise skip them.
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --force
+```
+
 Override optional settings when needed:
 
 ```bash
@@ -102,10 +134,9 @@ 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.
+Watch mode cannot be combined with force options or dry-run mode. Use `--watch` for continuous syncing, or use `--dry-run`, `--force`, `--force-upload`, and `--force-download` for one-time sync passes.
 
 If your local directory does not exist, the tool will attempt to create it for you (when not in dry-run mode).
 

{dbx_sync-0.2.0 → dbx_sync-0.4.0}/README.md

@@ -11,7 +11,7 @@
 
 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.
+`dbx-sync` keeps a Databricks workspace folder or file and a local directory or file 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.
 
@@ -21,9 +21,10 @@ Worried about losing files? `dbx-sync` does not delete files locally or remotely
 
 Current scope notes:
 
-- Sync is limited to a single local folder and a single Databricks workspace folder.
+- Sync is limited to a single local folder/workspace folder pair or one local/workspace file pair.
 - File and folder discovery is not recursive.
 - Local tracking currently covers notebook files with Databricks notebook extensions: `.py`, `.sql`, `.scala`, `.r`, and `.ipynb`.
+- When syncing a single local file, notebook extensions are imported as notebooks and other files are imported as workspace files.
 
 ## Prerequisites
 
@@ -72,6 +73,24 @@ Sync a single workspace folder with a single local folder (one-time):
 dbx-sync ./local-project /Workspace/Users/me/project
 ```
 
+Sync a single local file to a workspace folder, using the source filename for the target object:
+
+```bash
+dbx-sync ./local-project/notebook.py /Workspace/Users/me/project
+```
+
+Sync a single workspace file or notebook to a local folder, using the source filename locally:
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project/notebook
+```
+
+Sync explicit local and workspace file paths:
+
+```bash
+dbx-sync ./local-project/notebook.py /Workspace/Users/me/project/notebook
+```
+
 Preview actions without applying them:
 
 ```bash
@@ -84,6 +103,19 @@ Continuously watch and resync (default polling happens every second):
 dbx-sync ./local-project /Workspace/Users/me/project --watch
 ```
 
+Use `--force` to clear saved sync state before a fresh pass. This can be useful to handle conflicts. 
+Pro-tip: Add --dry-run to check force behavior before running it for real.
+
+Force options are mutually exclusive and only apply to a single sync pass:
+
+- `--force` clears saved sync state before comparing local and remote files.
+- `--force-upload` uploads matching local files even when saved sync state would otherwise skip them.
+- `--force-download` downloads matching remote files even when saved sync state would otherwise skip them.
+
+```bash
+dbx-sync ./local-project /Workspace/Users/me/project --force
+```
+
 Override optional settings when needed:
 
 ```bash
@@ -91,10 +123,9 @@ 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.
+Watch mode cannot be combined with force options or dry-run mode. Use `--watch` for continuous syncing, or use `--dry-run`, `--force`, `--force-upload`, and `--force-download` for one-time sync passes.
 
 If your local directory does not exist, the tool will attempt to create it for you (when not in dry-run mode).
 

{dbx_sync-0.2.0 → dbx_sync-0.4.0}/src/dbx_sync/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{dbx_sync-0.2.0 → dbx_sync-0.4.0}/src/dbx_sync/cli.py

@@ -4,7 +4,8 @@ import argparse
 from collections.abc import Sequence
 from pathlib import Path
 
-from dbx_sync.sync import run_sync
+from dbx_sync import __version__
+from dbx_sync.sync import ForceType, run_sync
 
 DEFAULT_POLL_INTERVAL_SECONDS = 1
 LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
@@ -29,10 +30,11 @@ def main(argv: Sequence[str] | None = None) -> int:
     """
     parser = argparse.ArgumentParser(
         prog="dbx-sync",
-        description="Synchronize Databricks workspace files to a local directory.",
+        description="Synchronize Databricks workspace files with a local path.",
     )
-    parser.add_argument("local_dir", help="Local directory to sync")
-    parser.add_argument("workspace", help="Databricks workspace folder to sync")
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("local_dir", help="Local file or directory to sync")
+    parser.add_argument("workspace", help="Databricks workspace file or folder to sync")
     parser.add_argument("--profile", default="DEFAULT", help="Databricks CLI profile name")
     parser.add_argument(
         "-p",
@@ -60,14 +62,35 @@ def main(argv: Sequence[str] | None = None) -> int:
         action="store_true",
         help="Watch for changes and sync continuously",
     )
-    parser.add_argument(
+    force_group = parser.add_mutually_exclusive_group()
+    force_group.add_argument(
         "-f",
         "--force",
         action="store_true",
         help="Force a refresh by clearing saved sync state before running",
     )
+    force_group.add_argument(
+        "-fu",
+        "--force-upload",
+        action="store_true",
+        help="Force upload of all local files, ignoring sync state",
+    )
+    force_group.add_argument(
+        "-fd",
+        "--force-download",
+        action="store_true",
+        help="Force download of all remote files, ignoring sync state",
+    )
     args = parser.parse_args(argv)
 
+    force_type = None
+    if args.force:
+        force_type = ForceType.CLEAR
+    elif args.force_upload:
+        force_type = ForceType.UPLOAD
+    elif args.force_download:
+        force_type = ForceType.DOWNLOAD
+
     try:
         return run_sync(
             local_dir=Path(args.local_dir).expanduser().resolve(),
@@ -77,7 +100,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             log_level=args.log_level,
             dry_run=args.dry_run,
             watch=args.watch,
-            force=args.force,
+            force_type=force_type,
         )
     except RuntimeError as exc:
         # print user-friendly instructions if error is reauthentication-related, otherwise re-raise