Refactor: add _BatchContext Protocol and extract _QueryBuilderBase

- Add _BatchContext Protocol to _batch_base.py; re-type BatchRecordOperations,
  BatchTableOperations, BatchQueryOperations, BatchDataFrameOperations __init__
  from BatchRequest to _BatchContext — removes type: ignore on AsyncBatchRequest
- Extract _QueryBuilderBase from QueryBuilder with all fluent methods and build();
  QueryBuilder inherits base and keeps execute/execute_pages/to_dataframe;
  AsyncQueryBuilder will inherit base directly, eliminating deprecated sync surface

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Abel Milash

src/PowerPlatform/Dataverse/data/_batch_base.py

@@ -12,7 +12,7 @@
 import re
 import uuid
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Protocol, Tuple, Union
 
 from ..core.errors import HttpError, ValidationError
 from ..core._error_codes import _http_subcode
@@ -235,6 +235,23 @@ class _ChangeSetBatchItem:
     requests: List[_RawRequest]
 
 
+# ---------------------------------------------------------------------------
+# Shared interface for batch operation namespaces
+# ---------------------------------------------------------------------------
+
+
+class _BatchContext(Protocol):
+    """Structural interface required by batch operation namespaces.
+
+    Both :class:`~PowerPlatform.Dataverse.operations.batch.BatchRequest` and
+    :class:`~PowerPlatform.Dataverse.aio.operations.async_batch.AsyncBatchRequest`
+    satisfy this protocol — no explicit inheritance needed on either class.
+    """
+
+    _items: List[Any]
+    records: Any  # used by BatchDataFrameOperations to delegate create/update/delete
+
+
 # ---------------------------------------------------------------------------
 # Multipart parsing helpers
 # ---------------------------------------------------------------------------

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -50,7 +50,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any, Dict, Iterator, List, Optional, TypedDict, Union
+from typing import Any, Iterator, List, Optional, TypeVar, TypedDict, Union
 
 import pandas as pd
 
@@ -62,6 +62,8 @@
 # Sentinel for detecting when by_page is explicitly passed to execute()
 _BY_PAGE_UNSET = object()
 
+_QB = TypeVar("_QB", bound="_QueryBuilderBase")
+
 
 class QueryParams(TypedDict, total=False):
     """Typed dictionary returned by :meth:`QueryBuilder.build`.
@@ -171,29 +173,17 @@ def to_odata(self) -> str:
         return self.relation
 
 
-class QueryBuilder:
-    """Fluent interface for building OData queries.
-
-    Provides method chaining for constructing complex queries with
-    composable filter expressions. Can be used standalone (via :meth:`build`)
-    or bound to a client (via :meth:`execute`).
-
-    :param table: Table schema name to query.
-    :type table: str
-    :raises ValueError: If ``table`` is empty.
-
-    Example:
-        Standalone query construction::
+class _QueryBuilderBase:
+    """Pure fluent interface for building OData queries — no I/O.
 
-            from PowerPlatform.Dataverse.models.filters import col
+    Holds all query state and chaining methods (``select``, ``where``,
+    ``order_by``, ``top``, ``page_size``, ``count``, ``expand``,
+    ``include_annotations``, ``include_formatted_values``) and
+    :meth:`build`.
 
-            query = (QueryBuilder("account")
-                     .select("name")
-                     .where(col("statecode") == 0)
-                     .top(10))
-            params = query.build()
-            # {"table": "account", "select": ["name"],
-            #  "filter": "statecode eq 0", "top": 10}
+    Subclasses add execution: :class:`QueryBuilder` for sync clients,
+    :class:`~PowerPlatform.Dataverse.aio.models.async_query_builder.AsyncQueryBuilder`
+    for async clients.
     """
 
     def __init__(self, table: str) -> None:
@@ -213,7 +203,7 @@ def __init__(self, table: str) -> None:
 
     # ----------------------------------------------------------------- select
 
-    def select(self, *columns: str) -> QueryBuilder:
+    def select(self: _QB, *columns: str) -> _QB:
         """Select specific columns to retrieve.
 
         Column names are passed as-is; the OData layer lowercases them
@@ -231,7 +221,7 @@ def select(self, *columns: str) -> QueryBuilder:
 
     # ------------------------------------------------------ filter: expression tree
 
-    def where(self, expression: filters.FilterExpression) -> QueryBuilder:
+    def where(self: _QB, expression: filters.FilterExpression) -> _QB:
         """Add a composable filter expression.
 
         Accepts a :class:`~PowerPlatform.Dataverse.models.filters.FilterExpression`
@@ -260,7 +250,7 @@ def where(self, expression: filters.FilterExpression) -> QueryBuilder:
 
     # --------------------------------------------------------------- ordering
 
-    def order_by(self, column: str, descending: bool = False) -> QueryBuilder:
+    def order_by(self: _QB, column: str, descending: bool = False) -> _QB:
         """Add sorting order.
 
         Can be called multiple times for multi-column sorting.
@@ -275,7 +265,7 @@ def order_by(self, column: str, descending: bool = False) -> QueryBuilder:
 
     # --------------------------------------------------------------- pagination
 
-    def top(self, count: int) -> QueryBuilder:
+    def top(self: _QB, count: int) -> _QB:
         """Limit the total number of results.
 
         :param count: Maximum number of records to return (must be >= 1).
@@ -287,7 +277,7 @@ def top(self, count: int) -> QueryBuilder:
         self._top = count
         return self
 
-    def page_size(self, size: int) -> QueryBuilder:
+    def page_size(self: _QB, size: int) -> _QB:
         """Set the number of records per page.
 
         Controls how many records are returned in each page/batch
@@ -302,7 +292,7 @@ def page_size(self, size: int) -> QueryBuilder:
         self._page_size = size
         return self
 
-    def count(self) -> QueryBuilder:
+    def count(self: _QB) -> _QB:
         """Request a count of matching records in the response.
 
         Adds ``$count=true`` to the query, causing the server to include
@@ -321,7 +311,7 @@ def count(self) -> QueryBuilder:
         self._count = True
         return self
 
-    def include_formatted_values(self) -> QueryBuilder:
+    def include_formatted_values(self: _QB) -> _QB:
         """Request formatted values in the response.
 
         Adds ``Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"``
@@ -351,7 +341,7 @@ def include_formatted_values(self) -> QueryBuilder:
         self._include_annotations = "OData.Community.Display.V1.FormattedValue"
         return self
 
-    def include_annotations(self, annotation: str = "*") -> QueryBuilder:
+    def include_annotations(self: _QB, annotation: str = "*") -> _QB:
         """Request specific OData annotations in the response.
 
         Sets the ``Prefer: odata.include-annotations`` header. Use ``"*"``
@@ -379,7 +369,7 @@ def include_annotations(self, annotation: str = "*") -> QueryBuilder:
 
     # --------------------------------------------------------------- expand
 
-    def expand(self, *relations: Union[str, ExpandOption]) -> QueryBuilder:
+    def expand(self: _QB, *relations: Union[str, ExpandOption]) -> _QB:
         """Expand navigation properties.
 
         Accepts plain navigation property names (case-sensitive, passed
@@ -448,6 +438,32 @@ def build(self) -> QueryParams:
             params["include_annotations"] = self._include_annotations
         return params
 
+
+class QueryBuilder(_QueryBuilderBase):
+    """Fluent interface for building and executing OData queries against a sync client.
+
+    Provides method chaining for constructing complex queries with
+    composable filter expressions. Can be used standalone (via :meth:`build`)
+    or bound to a client (via :meth:`execute`).
+
+    :param table: Table schema name to query.
+    :type table: str
+    :raises ValueError: If ``table`` is empty.
+
+    Example:
+        Standalone query construction::
+
+            from PowerPlatform.Dataverse.models.filters import col
+
+            query = (QueryBuilder("account")
+                     .select("name")
+                     .where(col("statecode") == 0)
+                     .top(10))
+            params = query.build()
+            # {"table": "account", "select": ["name"],
+            #  "filter": "statecode eq 0", "top": 10}
+    """
+
     # --------------------------------------------------------------- execute
 
     def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterator[QueryResult]]:

src/PowerPlatform/Dataverse/operations/batch.py

@@ -12,6 +12,7 @@
 
 from ..core.errors import ValidationError
 from ..core._error_codes import VALIDATION_SQL_EMPTY
+from ..data._batch_base import _BatchContext
 from ..data._batch import (
     _BatchClient,
     _ChangeSet,
@@ -180,7 +181,7 @@ class BatchRecordOperations:
     Do not instantiate directly; use ``batch.records``.
     """
 
-    def __init__(self, batch: "BatchRequest") -> None:
+    def __init__(self, batch: "_BatchContext") -> None:
         self._batch = batch
 
     def create(
@@ -482,7 +483,7 @@ class BatchTableOperations:
     Do not instantiate directly; use ``batch.tables``.
     """
 
-    def __init__(self, batch: "BatchRequest") -> None:
+    def __init__(self, batch: "_BatchContext") -> None:
         self._batch = batch
 
     def create(
@@ -720,7 +721,7 @@ class BatchQueryOperations:
     Do not instantiate directly; use ``batch.query``.
     """
 
-    def __init__(self, batch: "BatchRequest") -> None:
+    def __init__(self, batch: "_BatchContext") -> None:
         self._batch = batch
 
     def sql(self, sql: str) -> None:
@@ -774,7 +775,7 @@ class BatchDataFrameOperations:
         result = batch.execute()
     """
 
-    def __init__(self, batch: "BatchRequest") -> None:
+    def __init__(self, batch: "_BatchContext") -> None:
         self._batch = batch
 
     def create(self, table: str, records: pd.DataFrame) -> None: