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

@@ -49,8 +49,16 @@
 
 from __future__ import annotations
 
+import sys
 import warnings
-from typing import Any, Iterator, List, Optional, TypeVar, TypedDict, Union
+from typing import Any, Iterator, List, Optional, TypedDict, Union
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing import TypeVar
+
+    Self = TypeVar("Self", bound="_QueryBuilderBase")  # type: ignore[assignment]
 
 import pandas as pd
 
@@ -62,8 +70,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 +209,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 +227,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 +256,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 +271,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 +283,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 +298,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 +317,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 +347,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 +375,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