Update migration tool and update related documentation

Samson Gebre · Samson Gebre · commit 2b456329c2b6 · 2026-05-17T21:58:09.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `QueryResult.__getitem__` — index access (`result[0]`) returns a `Record`; slice access (`result[1:5]`) returns a new `QueryResult` (#175)
 - `DataverseModel` structural `Protocol` (`models/protocol.py`) — implement on any entity class to enable typed integration with CRUD operations without specifying table names or serializing manually (#175)
 - `col()`, `raw()`, `QueryResult`, and `DataverseModel` exported from the top-level `PowerPlatform.Dataverse` package (#175)
-- v0→v1 migration tool: `tools/migrate_v0_to_v1.py` rewrites v0 call sites to the v1 API with `--dry-run` support; covers `create`, `update`, `delete`, `get`, `list`, `fetchxml`, and query builder patterns (#175)
+- v0→v1 migration tool: installed as the `dataverse-migrate` console script (also runnable via `python -m PowerPlatform.Dataverse.migration.migrate_v0_to_v1`); rewrites v0 call sites to the v1 API with `--dry-run` support; covers `create`, `update`, `delete`, `get`, `list`, `fetchxml`, and query builder patterns; requires the `[migration]` optional extra (`pip install PowerPlatform-Dataverse-Client[migration]`) (#175)
 - Migration tool now auto-rewrites `QueryBuilder.to_dataframe()` → `.execute().to_dataframe()` (inserts `.execute()` when receiver is a recognised builder chain); output improved with `[NEEDS-MANUAL]` label for files that have no auto-rewrites but require manual attention, and a trailing note on `[MIGRATED]` lines when manual items remain (#175)
 
 ### Changed
diff --git a/README.md b/README.md
@@ -450,7 +450,7 @@ for page_num, page in enumerate(
         print(record["name"])
 ```
 
-> **Deprecation note:** `execute(by_page=True)` and `execute(by_page=False)` are deprecated and emit a `UserWarning`. Replace with `execute_pages()` (streaming) or plain `execute()` (eager). `QueryBuilder.to_dataframe()` is also deprecated; use `.execute().to_dataframe()` instead. The migration tool (`tools/migrate_v0_to_v1.py`) rewrites all of these automatically.
+> **Deprecation note:** `execute(by_page=True)` and `execute(by_page=False)` are deprecated and emit a `UserWarning`. Replace with `execute_pages()` (streaming) or plain `execute()` (eager). `QueryBuilder.to_dataframe()` is also deprecated; use `.execute().to_dataframe()` instead. The migration tool rewrites all of these automatically — install with `pip install PowerPlatform-Dataverse-Client[migration]` and run `dataverse-migrate path/to/your/scripts/` (or `python -m PowerPlatform.Dataverse.migration.migrate_v0_to_v1` for development checkouts).
 
 **Record count** -- include `$count=true` in the request:
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -40,7 +40,7 @@ dependencies = [
 
 [project.scripts]
 dataverse-install-claude-skill = "PowerPlatform.Dataverse._skill_installer:main"
-dataverse-migrate = "tools.migrate_v0_to_v1:main"
+dataverse-migrate = "PowerPlatform.Dataverse.migration.migrate_v0_to_v1:main"
 
 [project.optional-dependencies]
 dev = [
@@ -54,12 +54,12 @@ dev = [
 migration = ["libcst>=1.0.0"]
 
 [tool.setuptools]
-package-dir = {"" = "src", "tools" = "tools"}
+package-dir = {"" = "src"}
 zip-safe = false
 
 [tool.setuptools.packages.find]
-where = ["src", "."]
-include = ["PowerPlatform*", "tools"]
+where = ["src"]
+include = ["PowerPlatform*"]
 namespaces = false
 
 [tool.setuptools.package-data]
diff --git a/src/PowerPlatform/Dataverse/migration/__init__.py b/src/PowerPlatform/Dataverse/migration/__init__.py
diff --git a/src/PowerPlatform/Dataverse/migration/migrate_v0_to_v1.py b/src/PowerPlatform/Dataverse/migration/migrate_v0_to_v1.py
@@ -16,7 +16,7 @@
     dataverse-migrate path/to/your/scripts/ --client-var=svc   # if client is named 'svc'
 
     # Or via module for development installs:
-    python -m tools.migrate_v0_to_v1 path/to/your/scripts/
+    python -m PowerPlatform.Dataverse.migration.migrate_v0_to_v1 path/to/your/scripts/
 
 Transformations applied
 -----------------------
@@ -763,6 +763,10 @@ def _collect_targets(paths: List[str]) -> List[Path]:
 
 def main(argv: Optional[List[str]] = None) -> int:
     args = sys.argv[1:] if argv is None else list(argv)
+    if "--help" in args or "-h" in args:
+        print(__doc__)
+        print("\nUsage: dataverse-migrate [--dry-run] [--client-var=NAME] <path> [<path> ...]")
+        return 0
     dry_run = "--dry-run" in args
     client_var = "client"
     remaining = []
diff --git a/tests/unit/test_migration_tool.py b/tests/unit/test_migration_tool.py
@@ -1,7 +1,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
 
-"""Unit tests for tools/migrate_v0_to_v1.py.
+"""Unit tests for PowerPlatform/Dataverse/migration/migrate_v0_to_v1.py.
 
 Covers:
 - QueryBuilder.to_dataframe() -> .execute().to_dataframe()  (auto-rewrite)
@@ -31,13 +31,13 @@
 
 
 def _migrate(source: str, *, client_var: str = "client") -> str:
-    from tools.migrate_v0_to_v1 import migrate_source
+    from PowerPlatform.Dataverse.migration.migrate_v0_to_v1 import migrate_source
 
     return migrate_source(textwrap.dedent(source), client_var=client_var)
 
 
 def _find_manual(source: str, *, client_var: str = "client") -> list:
-    from tools.migrate_v0_to_v1 import find_manual_patterns
+    from PowerPlatform.Dataverse.migration.migrate_v0_to_v1 import find_manual_patterns
 
     return find_manual_patterns(textwrap.dedent(source), client_var=client_var)
 
diff --git a/tests/unit/test_phase4_ga.py b/tests/unit/test_phase4_ga.py
@@ -505,15 +505,15 @@ class TestCodemodByPage(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         try:
-            from tools.migrate_v0_to_v1 import migrate_source
+            from PowerPlatform.Dataverse.migration.migrate_v0_to_v1 import migrate_source
 
             cls.migrate = staticmethod(migrate_source)
         except ImportError:
             cls.migrate = None
 
     def setUp(self):
         if self.migrate is None:
-            self.skipTest("libcst not installed or tools package not on path")
+            self.skipTest("libcst not installed")
 
     def test_execute_by_page_true_becomes_execute_pages(self):
         src = "result = builder.execute(by_page=True)\n"
@@ -573,15 +573,15 @@ class TestManualReviewFinder(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         try:
-            from tools.migrate_v0_to_v1 import find_manual_patterns
+            from PowerPlatform.Dataverse.migration.migrate_v0_to_v1 import find_manual_patterns
 
             cls.find = staticmethod(find_manual_patterns)
         except ImportError:
             cls.find = None
 
     def setUp(self):
         if self.find is None:
-            self.skipTest("libcst not installed or tools package not on path")
+            self.skipTest("libcst not installed")
 
     def test_records_get_flagged(self):
         src = "result = client.records.get('account', record_id)\n"
