Address PR review: refactor QueryBuilder to delegate to filters module, remove filter_in (OData 4.01 not supported by Dataverse)

Author: Abel Milash

README.md

@@ -13,24 +13,34 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 
 ## Table of contents
 
-- [Key features](#key-features)
-- [Getting started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [Install the package](#install-the-package)  
-  - [Authenticate the client](#authenticate-the-client)
-- [Key concepts](#key-concepts)
-- [Examples](#examples)
-  - [Quick start](#quick-start)
-  - [Basic CRUD operations](#basic-crud-operations)
-  - [Bulk operations](#bulk-operations)
-  - [Upsert operations](#upsert-operations)
-  - [Query data](#query-data) *(QueryBuilder, SQL, raw OData)*
-  - [Table management](#table-management)
-  - [Relationship management](#relationship-management)
-  - [File operations](#file-operations)
-- [Next steps](#next-steps)
-- [Troubleshooting](#troubleshooting)
-- [Contributing](#contributing)
+- [PowerPlatform Dataverse Client for Python](#powerplatform-dataverse-client-for-python)
+  - [Table of contents](#table-of-contents)
+  - [Key features](#key-features)
+  - [Getting started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Install the package](#install-the-package)
+    - [Authenticate the client](#authenticate-the-client)
+  - [Key concepts](#key-concepts)
+  - [Examples](#examples)
+    - [Quick start](#quick-start)
+    - [Basic CRUD operations](#basic-crud-operations)
+    - [Bulk operations](#bulk-operations)
+    - [Upsert operations](#upsert-operations)
+    - [Query data](#query-data)
+    - [Table management](#table-management)
+    - [Relationship management](#relationship-management)
+    - [File operations](#file-operations)
+  - [Next steps](#next-steps)
+    - [More sample code](#more-sample-code)
+    - [Additional documentation](#additional-documentation)
+  - [Troubleshooting](#troubleshooting)
+    - [General](#general)
+    - [Authentication issues](#authentication-issues)
+    - [Performance considerations](#performance-considerations)
+    - [Limitations](#limitations)
+  - [Contributing](#contributing)
+    - [API Design Guidelines](#api-design-guidelines)
+  - [Trademarks](#trademarks)
 
 ## Key features
 
@@ -258,7 +268,6 @@ query = (client.query.builder("contact")
          .filter_eq("statecode", 0)          # statecode eq 0
          .filter_gt("revenue", 1000000)      # revenue gt 1000000
          .filter_contains("name", "Corp")    # contains(name, 'Corp')
-         .filter_in("statecode", [0, 1])     # statecode in (0, 1)
          .filter_between("revenue", 100000, 500000)  # (revenue ge 100000 and revenue le 500000)
          .filter_null("telephone1")          # telephone1 eq null
          )
@@ -267,7 +276,7 @@ query = (client.query.builder("contact")
 For complex logic (OR, NOT, grouping), use the composable expression tree with `where()`:
 
 ```python
-from PowerPlatform.Dataverse.models.filters import eq, gt, filter_in, between
+from PowerPlatform.Dataverse.models.filters import eq, gt, between
 
 # OR conditions: (statecode = 0 OR statecode = 1) AND revenue > 100k
 for record in (client.query.builder("account")

examples/advanced/walkthrough.py

@@ -278,21 +278,6 @@ def _run_walkthrough(client):
     for rec in qb_records[:5]:
         print(f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')}")
 
-    # filter_in: records with specific priorities
-    log_call("client.query.builder(...).filter_in('new_Priority', [HIGH, LOW]).execute()")
-    print("Querying records with HIGH or LOW priority (filter_in)...")
-    priority_records = list(
-        backoff(
-            lambda: client.query.builder(table_name)
-            .select("new_Title", "new_Priority")
-            .filter_in("new_Priority", [Priority.HIGH, Priority.LOW])
-            .execute()
-        )
-    )
-    print(f"[OK] Found {len(priority_records)} records with HIGH or LOW priority")
-    for rec in priority_records[:5]:
-        print(f"  - '{rec.get('new_title')}' Priority={rec.get('new_priority')}")
-
     # filter_between: amount in a range
     log_call("client.query.builder(...).filter_between('new_Amount', 500, 1500).execute()")
     print("Querying records with amount between 500 and 1500 (filter_between)...")
@@ -447,7 +432,7 @@ def _run_walkthrough(client):
     print("  [OK] Reading records by ID and with filters")
     print("  [OK] Single and multiple record updates")
     print("  [OK] Paging through large result sets")
-    print("  [OK] QueryBuilder fluent queries (filter_eq, filter_in, filter_between, where)")
+    print("  [OK] QueryBuilder fluent queries (filter_eq, filter_between, where)")
     print("  [OK] SQL queries")
     print("  [OK] Picklist label-to-value conversion")
     print("  [OK] Column management")

src/PowerPlatform/Dataverse/models/filters.py

@@ -10,7 +10,7 @@
 
 Example::
 
-    from PowerPlatform.Dataverse.models.filters import eq, gt, filter_in
+    from PowerPlatform.Dataverse.models.filters import eq, gt, between
 
     # Simple comparison
     expr = eq("statecode", 0)
@@ -21,10 +21,6 @@
     print(expr.to_odata())
     # ((statecode eq 0 or statecode eq 1) and revenue gt 100000)
 
-    # In operator
-    expr = filter_in("statecode", [0, 1, 2])
-    print(expr.to_odata())  # statecode in (0, 1, 2)
-
     # Negation
     expr = ~eq("statecode", 1)
     print(expr.to_odata())  # not (statecode eq 1)
@@ -35,7 +31,7 @@
 import enum
 import uuid
 from datetime import date, datetime, timezone
-from typing import Any, Sequence
+from typing import Any
 
 __all__ = [
     "FilterExpression",
@@ -48,7 +44,6 @@
     "contains",
     "startswith",
     "endswith",
-    "filter_in",
     "between",
     "is_null",
     "is_not_null",
@@ -174,22 +169,6 @@ def to_odata(self) -> str:
         return f"{self.func_name}({self.column}, {_format_value(self.value)})"
 
 
-class _InFilter(FilterExpression):
-    """In filter: ``column in (val1, val2, ...)``."""
-
-    __slots__ = ("column", "values")
-
-    def __init__(self, column: str, values: Sequence[Any]) -> None:
-        if not values:
-            raise ValueError("filter_in requires at least one value")
-        self.column = column.lower()
-        self.values = list(values)
-
-    def to_odata(self) -> str:
-        formatted = ", ".join(_format_value(v) for v in self.values)
-        return f"{self.column} in ({formatted})"
-
-
 class _AndFilter(FilterExpression):
     """Logical AND: ``(left and right)``."""
 
@@ -339,24 +318,6 @@ def endswith(column: str, value: str) -> FilterExpression:
     return _FunctionFilter("endswith", column, value)
 
 
-def filter_in(column: str, values: Sequence[Any]) -> FilterExpression:
-    """In filter: ``column in (val1, val2, ...)``.
-
-    Named ``filter_in`` because ``in`` is a Python keyword.
-
-    :param column: Column name (will be lowercased).
-    :param values: Non-empty sequence of values.
-    :return: A filter expression.
-    :raises ValueError: If ``values`` is empty.
-
-    Example::
-
-        filter_in("statecode", [0, 1, 2]).to_odata()
-        # "statecode in (0, 1, 2)"
-    """
-    return _InFilter(column, values)
-
-
 def between(column: str, low: Any, high: Any) -> FilterExpression:
     """Between filter: ``(column ge low and column le high)``.
 

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -39,9 +39,9 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+from typing import Any, Dict, Iterable, List, Optional, Union
 
-from .filters import FilterExpression, _format_value
+from . import filters
 
 __all__ = ["QueryBuilder"]
 
@@ -75,7 +75,7 @@ def __init__(self, table: str) -> None:
             raise ValueError("table name is required")
         self.table = table
         self._select: List[str] = []
-        self._filter_parts: List[Union[str, FilterExpression]] = []
+        self._filter_parts: List[Union[str, filters.FilterExpression]] = []
         self._orderby: List[str] = []
         self._expand: List[str] = []
         self._top: Optional[int] = None
@@ -109,7 +109,7 @@ def filter_eq(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} eq {_format_value(value)}")
+        self._filter_parts.append(filters.eq(column, value))
         return self
 
     def filter_ne(self, column: str, value: Any) -> QueryBuilder:
@@ -119,7 +119,7 @@ def filter_ne(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} ne {_format_value(value)}")
+        self._filter_parts.append(filters.ne(column, value))
         return self
 
     def filter_gt(self, column: str, value: Any) -> QueryBuilder:
@@ -129,7 +129,7 @@ def filter_gt(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} gt {_format_value(value)}")
+        self._filter_parts.append(filters.gt(column, value))
         return self
 
     def filter_ge(self, column: str, value: Any) -> QueryBuilder:
@@ -139,7 +139,7 @@ def filter_ge(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} ge {_format_value(value)}")
+        self._filter_parts.append(filters.ge(column, value))
         return self
 
     def filter_lt(self, column: str, value: Any) -> QueryBuilder:
@@ -149,7 +149,7 @@ def filter_lt(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} lt {_format_value(value)}")
+        self._filter_parts.append(filters.lt(column, value))
         return self
 
     def filter_le(self, column: str, value: Any) -> QueryBuilder:
@@ -159,7 +159,7 @@ def filter_le(self, column: str, value: Any) -> QueryBuilder:
         :param value: Value to compare against.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} le {_format_value(value)}")
+        self._filter_parts.append(filters.le(column, value))
         return self
 
     # --------------------------------------------------------- filter: string functions
@@ -171,7 +171,7 @@ def filter_contains(self, column: str, value: str) -> QueryBuilder:
         :param value: Substring to search for.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"contains({column.lower()}, {_format_value(value)})")
+        self._filter_parts.append(filters.contains(column, value))
         return self
 
     def filter_startswith(self, column: str, value: str) -> QueryBuilder:
@@ -181,7 +181,7 @@ def filter_startswith(self, column: str, value: str) -> QueryBuilder:
         :param value: Prefix to match.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"startswith({column.lower()}, {_format_value(value)})")
+        self._filter_parts.append(filters.startswith(column, value))
         return self
 
     def filter_endswith(self, column: str, value: str) -> QueryBuilder:
@@ -191,7 +191,7 @@ def filter_endswith(self, column: str, value: str) -> QueryBuilder:
         :param value: Suffix to match.
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"endswith({column.lower()}, {_format_value(value)})")
+        self._filter_parts.append(filters.endswith(column, value))
         return self
 
     # --------------------------------------------------------- filter: null checks
@@ -202,7 +202,7 @@ def filter_null(self, column: str) -> QueryBuilder:
         :param column: Column name (will be lowercased).
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} eq null")
+        self._filter_parts.append(filters.is_null(column))
         return self
 
     def filter_not_null(self, column: str) -> QueryBuilder:
@@ -211,30 +211,11 @@ def filter_not_null(self, column: str) -> QueryBuilder:
         :param column: Column name (will be lowercased).
         :return: Self for method chaining.
         """
-        self._filter_parts.append(f"{column.lower()} ne null")
+        self._filter_parts.append(filters.is_not_null(column))
         return self
 
     # --------------------------------------------------------- filter: special
 
-    def filter_in(self, column: str, values: Sequence[Any]) -> QueryBuilder:
-        """Add an ``in`` filter: ``column in (val1, val2, ...)``.
-
-        :param column: Column name (will be lowercased).
-        :param values: Non-empty list of values for the ``in`` clause.
-        :return: Self for method chaining.
-        :raises ValueError: If ``values`` is empty.
-
-        Example::
-
-            query = QueryBuilder("account").filter_in("statecode", [0, 1, 2])
-            # Produces: statecode in (0, 1, 2)
-        """
-        if not values:
-            raise ValueError("filter_in requires at least one value")
-        formatted = ", ".join(_format_value(v) for v in values)
-        self._filter_parts.append(f"{column.lower()} in ({formatted})")
-        return self
-
     def filter_between(self, column: str, low: Any, high: Any) -> QueryBuilder:
         """Add a between filter: ``(column ge low and column le high)``.
 
@@ -248,8 +229,7 @@ def filter_between(self, column: str, low: Any, high: Any) -> QueryBuilder:
             query = QueryBuilder("account").filter_between("revenue", 100000, 500000)
             # Produces: (revenue ge 100000 and revenue le 500000)
         """
-        col = column.lower()
-        self._filter_parts.append(f"({col} ge {_format_value(low)} and {col} le {_format_value(high)})")
+        self._filter_parts.append(filters.between(column, low, high))
         return self
 
     def filter_raw(self, filter_string: str) -> QueryBuilder:
@@ -267,12 +247,12 @@ def filter_raw(self, filter_string: str) -> QueryBuilder:
                 "(statecode eq 0 or statecode eq 1)"
             )
         """
-        self._filter_parts.append(filter_string)
+        self._filter_parts.append(filters.raw(filter_string))
         return self
 
     # ------------------------------------------------------ filter: expression tree
 
-    def where(self, expression: FilterExpression) -> QueryBuilder:
+    def where(self, expression: filters.FilterExpression) -> QueryBuilder:
         """Add a composable filter expression.
 
         Accepts a :class:`~PowerPlatform.Dataverse.models.filters.FilterExpression`
@@ -295,7 +275,7 @@ def where(self, expression: FilterExpression) -> QueryBuilder:
                      .where((eq("statecode", 0) | eq("statecode", 1))
                             & gt("revenue", 100000)))
         """
-        if not isinstance(expression, FilterExpression):
+        if not isinstance(expression, filters.FilterExpression):
             raise TypeError(f"where() requires a FilterExpression, got {type(expression).__name__}")
         self._filter_parts.append(expression)
         return self
@@ -376,7 +356,7 @@ def build(self) -> dict:
         if self._filter_parts:
             parts: List[str] = []
             for part in self._filter_parts:
-                if isinstance(part, FilterExpression):
+                if isinstance(part, filters.FilterExpression):
                     parts.append(part.to_odata())
                 else:
                     parts.append(part)