Update CHANGELOG.md with new features, changes, deprecations, and removals; modify prodev_quick_start.py for additional parameter; enhance pyproject.toml for migration tool; refine migrate_v0_to_v1.py documentation and usage instructions.

Author: Samson Gebre

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `client.records.retrieve(table, record_id)` — fetch a single record by GUID; returns `None` on 404 instead of raising (#175)
+- `client.records.list(table, filter, select, top)` — eager fetch returning a flat `QueryResult`; GA replacement for `records.get()` without a record ID (#175)
+- `client.records.list_pages(table, filter, select, top)` — lazy iterator yielding one `QueryResult` per HTTP page; streaming counterpart to `list()` (#175)
+- `client.query.fetchxml(xml)` — FetchXML support returning an inert `FetchXmlQuery`; no HTTP request is made until `.execute()` or `.execute_pages()` is called (#175)
+- `FetchXmlQuery` implements the correct Dataverse paging cookie algorithm: annotation parsed as outer XML, `pagingcookie` attribute double URL-decoded, server-supplied `pagenumber` used for next page, `morerecords` handled as both `bool` and `"true"` string, `UserWarning` emitted on simple paging fallback, 32,768-character URL limit enforced (documented Dataverse GET cap), 10,000-page circuit breaker against runaway iteration (#175)
+- `QueryBuilder.execute_pages()` — lazy per-page streaming returning one `QueryResult` per HTTP page; replaces deprecated `execute(by_page=True)` (#175)
+- `QueryBuilder.where()` — composable filter expressions using `col()` and Python operators (`==`, `>`, `&`, `|`, `~`); replaces deprecated `filter_eq()`, `filter_contains()`, and other `filter_*` helpers (#175)
+- `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)
+
+### Changed
+- `QueryBuilder.execute()` now returns a flat `QueryResult` (all pages collected eagerly) instead of `Iterable[Record]` (#175)
+- `records.get()` deprecation extended: calling with a `record_id` emits `DeprecationWarning` directing callers to `retrieve()`; calling without a `record_id` directs callers to `list()` (#175)
+
+### Deprecated
+- `QueryBuilder.execute(by_page=True)` and `execute(by_page=False)` emit `UserWarning`; use `execute_pages()` and `execute()` respectively (#175)
+- `client.query.odata_select()`, `client.query.odata_expands()`, `client.query.odata_expand()`, `client.query.odata_bind()` emit `DeprecationWarning`; navigation property helpers are replaced by `QueryBuilder.expand()` (#175)
+
+### Removed
+- All v0 flat methods on `DataverseClient` (`create`, `update`, `delete`, `get`, `list`, `query_sql`, etc.) removed (~570 lines); use the `client.records`, `client.query`, and `client.batch` namespaces (#175)
+- `client.query.sql_select()`, `client.query.sql_joins()`, `client.query.sql_join()` removed (#175)
+
 ## [0.1.0b9] - 2026-04-28
 
 ### Added

examples/advanced/prodev_quick_start.py

@@ -116,7 +116,7 @@ def run_demo(client):
     customer_ids, project_ids, task_ids = step3_populate_data(client, primary_name_col)
 
     # -- Step 4: Query and analyze --
-    step4_query_and_analyze(client, customer_ids, primary_name_col)
+    step4_query_and_analyze(client, customer_ids, primary_name_col, primary_id_col)
 
     # -- Step 5: Update and delete --
     step5_update_and_delete(client, task_ids, primary_name_col, primary_id_col)
@@ -385,7 +385,7 @@ def step3_populate_data(client, primary_name_col):
 # ================================================================
 
 
-def step4_query_and_analyze(client, customer_ids, primary_name_col):
+def step4_query_and_analyze(client, customer_ids, primary_name_col, primary_id_col):
     """Query data and demonstrate DataFrame analysis."""
     print("\n" + "-" * 60)
     print("STEP 4: Query and analyze data")

pyproject.toml

@@ -40,6 +40,7 @@ dependencies = [
 
 [project.scripts]
 dataverse-install-claude-skill = "PowerPlatform.Dataverse._skill_installer:main"
+dataverse-migrate = "tools.migrate_v0_to_v1:main"
 
 [project.optional-dependencies]
 dev = [
@@ -53,12 +54,12 @@ dev = [
 migration = ["libcst>=1.0.0"]
 
 [tool.setuptools]
-package-dir = {"" = "src"}
+package-dir = {"" = "src", "tools" = "tools"}
 zip-safe = false
 
 [tool.setuptools.packages.find]
-where = ["src"]
-include = ["PowerPlatform*"]
+where = ["src", "."]
+include = ["PowerPlatform*", "tools"]
 namespaces = false
 
 [tool.setuptools.package-data]

tools/migrate_v0_to_v1.py

@@ -3,77 +3,80 @@
 # Licensed under the MIT license.
 
 """
-DV-Python-SDK v0 → v1 GA migration codemod.
+DV-Python-SDK v0 -> v1 GA migration codemod.
 
 Mechanically rewrites beta (0.1.0b*) call sites to their GA (1.0) equivalents
 using LibCST (concrete syntax tree — preserves all whitespace and comments).
 
 Usage::
 
     pip install PowerPlatform-Dataverse-Client[migration]
-    python -m tools.migrate_v0_to_v1 path/to/scripts/
-    python -m tools.migrate_v0_to_v1 examples/          # _codemon.py files only
+    dataverse-migrate path/to/your/scripts/
+    dataverse-migrate path/to/your/scripts/ --dry-run   # preview changes without writing
+
+    # Or via module for development installs:
+    python -m tools.migrate_v0_to_v1 path/to/your/scripts/
 
 Transformations applied
 -----------------------
-Builder methods (.filter_*  →  .where(col(...)...))::
-
-    .filter_eq("col", v)               →  .where(col("col") == v)
-    .filter_ne("col", v)               →  .where(col("col") != v)
-    .filter_gt("col", v)               →  .where(col("col") > v)
-    .filter_ge("col", v)               →  .where(col("col") >= v)
-    .filter_lt("col", v)               →  .where(col("col") < v)
-    .filter_le("col", v)               →  .where(col("col") <= v)
-    .filter_contains("col", v)         →  .where(col("col").contains(v))
-    .filter_startswith("col", v)       →  .where(col("col").startswith(v))
-    .filter_endswith("col", v)         →  .where(col("col").endswith(v))
-    .filter_in("col", vals)            →  .where(col("col").in_(vals))
-    .filter_not_in("col", vals)        →  .where(col("col").not_in(vals))
-    .filter_null("col")                →  .where(col("col").is_null())
-    .filter_not_null("col")            →  .where(col("col").is_not_null())
-    .filter_between("col", lo, hi)     →  .where(col("col").between(lo, hi))
-    .filter_not_between("col", lo, hi) →  .where(col("col").not_between(lo, hi))
-    .filter_raw("expr")                →  .where(raw("expr"))
-    .filter("expr")                    →  .where(raw("expr"))
-    .execute(by_page=True)             →  .execute_pages()
-    .execute(by_page=False)            →  .execute()  (flag removed)
+Builder methods (.filter_*  ->  .where(col(...)...))::
+
+    .filter_eq("col", v)               ->  .where(col("col") == v)
+    .filter_ne("col", v)               ->  .where(col("col") != v)
+    .filter_gt("col", v)               ->  .where(col("col") > v)
+    .filter_ge("col", v)               ->  .where(col("col") >= v)
+    .filter_lt("col", v)               ->  .where(col("col") < v)
+    .filter_le("col", v)               ->  .where(col("col") <= v)
+    .filter_contains("col", v)         ->  .where(col("col").contains(v))
+    .filter_startswith("col", v)       ->  .where(col("col").startswith(v))
+    .filter_endswith("col", v)         ->  .where(col("col").endswith(v))
+    .filter_in("col", vals)            ->  .where(col("col").in_(vals))
+    .filter_not_in("col", vals)        ->  .where(col("col").not_in(vals))
+    .filter_null("col")                ->  .where(col("col").is_null())
+    .filter_not_null("col")            ->  .where(col("col").is_not_null())
+    .filter_between("col", lo, hi)     ->  .where(col("col").between(lo, hi))
+    .filter_not_between("col", lo, hi) ->  .where(col("col").not_between(lo, hi))
+    .filter_raw("expr")                ->  .where(raw("expr"))
+    .filter("expr")                    ->  .where(raw("expr"))
+    .execute(by_page=True)             ->  .execute_pages()
+    .execute(by_page=False)            ->  .execute()  (flag removed)
 
 Record namespace::
 
-    batch.records.get(t, id)     →  batch.records.retrieve(t, id)
+    batch.records.get(t, id)     ->  batch.records.retrieve(t, id)
 
 Top-level shortcuts (removed at GA)::
 
-    client.create(t, d)           →  client.records.create(t, d)
-    client.update(t, id, d)       →  client.records.update(t, id, d)
-    client.delete(t, id)          →  client.records.delete(t, id)
-    client.get(t, id)             →  client.records.retrieve(t, id)
-    client.query_sql(sql)         →  client.query.sql(sql)
-    client.get_table_info(t)      →  client.tables.get(t)
-    client.create_table(t, …)     →  client.tables.create(t, …)
-    client.delete_table(t)        →  client.tables.delete(t)
-    client.list_tables()          →  client.tables.list()
-    client.create_columns(t, …)   →  client.tables.add_columns(t, …)
-    client.delete_columns(t, …)   →  client.tables.remove_columns(t, …)
-    client.upload_file(…)         →  client.files.upload(…)
+    client.create(t, d)           ->  client.records.create(t, d)
+    client.update(t, id, d)       ->  client.records.update(t, id, d)
+    client.delete(t, id)          ->  client.records.delete(t, id)
+    client.get(t, id)             ->  client.records.retrieve(t, id)
+    client.query_sql(sql)         ->  client.query.sql(sql)
+    client.get_table_info(t)      ->  client.tables.get(t)
+    client.create_table(t, …)     ->  client.tables.create(t, …)
+    client.delete_table(t)        ->  client.tables.delete(t)
+    client.list_tables()          ->  client.tables.list()
+    client.create_columns(t, …)   ->  client.tables.add_columns(t, …)
+    client.delete_columns(t, …)   ->  client.tables.remove_columns(t, …)
+    client.upload_file(…)         ->  client.files.upload(…)
 
 Import management:
     Adds ``from PowerPlatform.Dataverse.models.filters import col`` when a
     .filter_* method is rewritten (if col is not already imported).
     Adds ``raw`` to the same import when .filter_raw or .filter is rewritten.
 
 NOT handled by this codemod (manual migration required):
-    execute(by_page=variable)      →  manual review required (variable argument, not literal)
-    client.records.get(t, id)     →  client.records.retrieve(t, id)
+    execute(by_page=variable)      ->  manual review required (variable argument, not literal)
+    client.records.get(t, id)     ->  client.records.retrieve(t, id)
         Return type changes: beta returns Record (raises on 404); GA retrieve() returns
         Record | None. Callers that do not guard against None will fail silently.
-    client.records.get(t, kw=…)  →  client.records.list(t, kw=…)
+    client.records.get(t, kw=…)  ->  client.records.list(t, kw=…)
         Return type changes: beta returns Iterable[List[Record]] (pages); GA list()
         returns QueryResult (flat iterable over Records). Any ``for page in result:
         for rec in page:`` iteration pattern breaks after a mechanical rename.
-    client.dataframe.get()        →  client.query.builder(…).execute().to_dataframe()
+    client.dataframe.get()        ->  client.query.builder(…).execute().to_dataframe()
         Expression reconstruction requires understanding caller intent.
-    client.query.sql_select()/sql_join()/sql_joins()  →  removed (no mechanical replacement)
+    client.query.sql_select()/sql_join()/sql_joins()  ->  removed (no mechanical replacement)
 """
 
 from __future__ import annotations
@@ -95,7 +98,7 @@
 
 
 # ---------------------------------------------------------------------------
-# Filter-method → .where(col(...)) mapping
+# Filter-method -> .where(col(...)) mapping
 # ---------------------------------------------------------------------------
 
 _UNARY_FILTER_MAP = {
@@ -124,8 +127,8 @@
 
 _ALL_FILTER_METHODS: Set[str] = set(_UNARY_FILTER_MAP) | set(_BINARY_OP_MAP) | set(_METHOD_FILTER_MAP) | {"filter_raw"}
 
-# Standalone filter functions from filters module (beta API) → col() equivalents
-# eq("f", v) → col("f") == v, between("f", lo, hi) → col("f").between(lo, hi), etc.
+# Standalone filter functions from filters module (beta API) -> col() equivalents
+# eq("f", v) -> col("f") == v, between("f", lo, hi) -> col("f").between(lo, hi), etc.
 _FUNC_BINARY_OP_MAP = {
     "eq": cst.Equal(),
     "ne": cst.NotEqual(),
@@ -149,7 +152,7 @@
 }
 _ALL_FILTER_FUNCS: Set[str] = set(_FUNC_BINARY_OP_MAP) | set(_FUNC_METHOD_MAP) | set(_FUNC_UNARY_MAP)
 
-# Top-level client shortcut → (new_namespace, new_method)
+# Top-level client shortcut -> (new_namespace, new_method)
 _CLIENT_SHORTCUTS = {
     "create": ("records", "create"),
     "update": ("records", "update"),
@@ -233,7 +236,7 @@ def _positional_count(args: Sequence[cst.Arg]) -> int:
 
 
 class _V1Migrator(cst.CSTTransformer):
-    """LibCST transformer rewriting DV-Python-SDK beta → v1 GA."""
+    """LibCST transformer rewriting DV-Python-SDK beta -> v1 GA."""
 
     def __init__(self, client_var: str = "client") -> None:
         self._client_var = client_var
@@ -271,7 +274,7 @@ def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Bas
         func = updated_node.func
 
         # ----------------------------------------------------------------
-        # Standalone filter functions: eq("f", v) → col("f") == v, etc.
+        # Standalone filter functions: eq("f", v) -> col("f") == v, etc.
         # Only transform names that were actually imported from filters module.
         # Wrap Comparison nodes in explicit parentheses so that combining with
         # & / | doesn't hit Python precedence bugs (& binds tighter than ==/>).
@@ -289,7 +292,7 @@ def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Bas
         method_name = func.attr.value if isinstance(func.attr, cst.Name) else ""
 
         # ----------------------------------------------------------------
-        # .filter_*(...) → .where(col(...) ...)
+        # .filter_*(...) -> .where(col(...) ...)
         # ----------------------------------------------------------------
         if method_name in _ALL_FILTER_METHODS:
             where_arg = self._build_filter_arg(method_name, updated_node.args)
@@ -300,7 +303,7 @@ def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Bas
                 )
 
         # ----------------------------------------------------------------
-        # .filter("expr") → .where(raw("expr"))
+        # .filter("expr") -> .where(raw("expr"))
         # QueryBuilder.filter() was removed at GA (not deprecated). Wrapping
         # in raw() preserves the OData string exactly for string-literal callers.
         # ----------------------------------------------------------------
@@ -314,8 +317,8 @@ def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Bas
                 )
 
         # ----------------------------------------------------------------
-        # .execute(by_page=True)  → .execute_pages()
-        # .execute(by_page=False) → .execute()  (flag removed)
+        # .execute(by_page=True)  -> .execute_pages()
+        # .execute(by_page=False) -> .execute()  (flag removed)
         # Only literal True/False are codemod-able; variable by_page requires
         # manual review per section 8.5 of the GA spec.
         # ----------------------------------------------------------------
@@ -335,7 +338,7 @@ def leave_Call(self, original_node: cst.Call, updated_node: cst.Call) -> cst.Bas
                 return updated_node.with_changes(args=other_args)
 
         # ----------------------------------------------------------------
-        # batch.records.get(table, id) → batch.records.retrieve(table, id)
+        # batch.records.get(table, id) -> batch.records.retrieve(table, id)
         # NOTE: client.records.get() is NOT codemodded — the return type changes
         # between beta and GA (Record | None vs Record for single-id; QueryResult vs
         # Iterable[List[Record]] for multi-record). Surrounding iteration patterns
@@ -394,18 +397,18 @@ def _build_filter_arg(
         if field_node is None:
             return None
 
-        # .filter_raw(expr) → raw(expr)
+        # .filter_raw(expr) -> raw(expr)
         if method_name == "filter_raw":
             self._needs_raw = True
             return _call(_name("raw"), field_node)
 
-        # .filter_null / .filter_not_null → col("f").is_null() / .is_not_null()
+        # .filter_null / .filter_not_null -> col("f").is_null() / .is_not_null()
         if method_name in _UNARY_FILTER_MAP:
             self._needs_col = True
             proxy = _UNARY_FILTER_MAP[method_name]
             return _call(_attr(_col_call(field_node), proxy))
 
-        # .filter_eq / .filter_ne / ... → col("f") OP val
+        # .filter_eq / .filter_ne / ... -> col("f") OP val
         if method_name in _BINARY_OP_MAP:
             val_node = _pos_arg(args, 1)
             if val_node is None:
@@ -421,7 +424,7 @@ def _build_filter_arg(
                 ],
             )
 
-        # .filter_between / .filter_not_between → col("f").between(lo, hi)
+        # .filter_between / .filter_not_between -> col("f").between(lo, hi)
         if method_name in ("filter_between", "filter_not_between"):
             lo = _pos_arg(args, 1)
             hi = _pos_arg(args, 2)
@@ -443,7 +446,7 @@ def _build_filter_arg(
         return None
 
     # ------------------------------------------------------------------
-    # Standalone filter function: eq("f", v) → col("f") == v, etc.
+    # Standalone filter function: eq("f", v) -> col("f") == v, etc.
     # ------------------------------------------------------------------
 
     def _build_filter_func_arg(
@@ -642,7 +645,7 @@ def main(argv: Optional[List[str]] = None) -> int:
 
     if not remaining:
         print(__doc__)
-        print("\nUsage: python -m tools.migrate_v0_to_v1 [--dry-run] <path> [<path> ...]")
+        print("\nUsage: dataverse-migrate [--dry-run] <path> [<path> ...]")
         return 1
 
     targets = _collect_targets(remaining)