Replace _QB TypeVar with Self in _QueryBuilderBase fluent methods

Self (from typing, under TYPE_CHECKING) is the idiomatic replacement for
the self-referential TypeVar pattern. With `from __future__ import annotations`
already in place, Self is never evaluated at runtime — only used by type
checkers. Method signatures in docs now show `Self` instead of the private
`_QB` TypeVar.

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

Author: Abel Milash

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -50,7 +50,10 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any, Iterator, List, Optional, TypeVar, TypedDict, Union
+from typing import TYPE_CHECKING, Any, Iterator, List, Optional, TypedDict, Union
+
+if TYPE_CHECKING:
+    from typing import Self
 
 import pandas as pd
 
@@ -62,8 +65,6 @@
 # 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`.
@@ -203,7 +204,7 @@ def __init__(self, table: str) -> None:
 
     # ----------------------------------------------------------------- select
 
-    def select(self: _QB, *columns: str) -> _QB:
+    def select(self, *columns: str) -> Self:
         """Select specific columns to retrieve.
 
         Column names are passed as-is; the OData layer lowercases them
@@ -221,7 +222,7 @@ def select(self: _QB, *columns: str) -> _QB:
 
     # ------------------------------------------------------ filter: expression tree
 
-    def where(self: _QB, expression: filters.FilterExpression) -> _QB:
+    def where(self, expression: filters.FilterExpression) -> Self:
         """Add a composable filter expression.
 
         Accepts a :class:`~PowerPlatform.Dataverse.models.filters.FilterExpression`
@@ -250,7 +251,7 @@ def where(self: _QB, expression: filters.FilterExpression) -> _QB:
 
     # --------------------------------------------------------------- ordering
 
-    def order_by(self: _QB, column: str, descending: bool = False) -> _QB:
+    def order_by(self, column: str, descending: bool = False) -> Self:
         """Add sorting order.
 
         Can be called multiple times for multi-column sorting.
@@ -265,7 +266,7 @@ def order_by(self: _QB, column: str, descending: bool = False) -> _QB:
 
     # --------------------------------------------------------------- pagination
 
-    def top(self: _QB, count: int) -> _QB:
+    def top(self, count: int) -> Self:
         """Limit the total number of results.
 
         :param count: Maximum number of records to return (must be >= 1).
@@ -277,7 +278,7 @@ def top(self: _QB, count: int) -> _QB:
         self._top = count
         return self
 
-    def page_size(self: _QB, size: int) -> _QB:
+    def page_size(self, size: int) -> Self:
         """Set the number of records per page.
 
         Controls how many records are returned in each page/batch
@@ -292,7 +293,7 @@ def page_size(self: _QB, size: int) -> _QB:
         self._page_size = size
         return self
 
-    def count(self: _QB) -> _QB:
+    def count(self) -> Self:
         """Request a count of matching records in the response.
 
         Adds ``$count=true`` to the query, causing the server to include
@@ -311,7 +312,7 @@ def count(self: _QB) -> _QB:
         self._count = True
         return self
 
-    def include_formatted_values(self: _QB) -> _QB:
+    def include_formatted_values(self) -> Self:
         """Request formatted values in the response.
 
         Adds ``Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"``
@@ -341,7 +342,7 @@ def include_formatted_values(self: _QB) -> _QB:
         self._include_annotations = "OData.Community.Display.V1.FormattedValue"
         return self
 
-    def include_annotations(self: _QB, annotation: str = "*") -> _QB:
+    def include_annotations(self, annotation: str = "*") -> Self:
         """Request specific OData annotations in the response.
 
         Sets the ``Prefer: odata.include-annotations`` header. Use ``"*"``
@@ -369,7 +370,7 @@ def include_annotations(self: _QB, annotation: str = "*") -> _QB:
 
     # --------------------------------------------------------------- expand
 
-    def expand(self: _QB, *relations: Union[str, ExpandOption]) -> _QB:
+    def expand(self, *relations: Union[str, ExpandOption]) -> Self:
         """Expand navigation properties.
 
         Accepts plain navigation property names (case-sensitive, passed