Add optional filter parameter to client.tables.list()

Allow callers to pass an OData $filter expression to narrow the list of
returned tables.  The user-supplied filter is combined with the existing
IsPrivate eq false guard using 'and', so private tables remain excluded.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tpellissier

src/PowerPlatform/Dataverse/data/_odata.py

@@ -1423,16 +1423,29 @@ def _get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
             "columns_created": [],
         }
 
-    def _list_tables(self) -> List[Dict[str, Any]]:
+    def _list_tables(self, filter: Optional[str] = None) -> List[Dict[str, Any]]:
         """List all non-private tables (``IsPrivate eq false``).
 
+        :param filter: Optional additional OData ``$filter`` expression that is
+            combined with the default ``IsPrivate eq false`` clause using
+            ``and``.  For example, ``"SchemaName eq 'Account'"`` becomes
+            ``"IsPrivate eq false and SchemaName eq 'Account'"``.
+            When ``None`` (the default), only the ``IsPrivate eq false`` filter
+            is applied.
+        :type filter: ``str`` or ``None``
+
         :return: Metadata entries for non-private tables (may be empty).
         :rtype: ``list[dict[str, Any]]``
 
         :raises HttpError: If the metadata request fails.
         """
         url = f"{self.api}/EntityDefinitions"
-        params = {"$filter": "IsPrivate eq false"}
+        base_filter = "IsPrivate eq false"
+        if filter:
+            combined_filter = f"{base_filter} and {filter}"
+        else:
+            combined_filter = base_filter
+        params = {"$filter": combined_filter}
         r = self._request("get", url, params=params)
         return r.json().get("value", [])
 

src/PowerPlatform/Dataverse/operations/tables.py

@@ -179,20 +179,38 @@ def get(self, table: str) -> Optional[Dict[str, Any]]:
 
     # ------------------------------------------------------------------- list
 
-    def list(self) -> List[Dict[str, Any]]:
+    def list(self, *, filter: Optional[str] = None) -> List[Dict[str, Any]]:
         """List all non-private tables in the Dataverse environment.
 
+        By default returns every table where ``IsPrivate eq false``.  Supply
+        an optional OData ``$filter`` expression to further narrow the results.
+        The expression is combined with the default ``IsPrivate eq false``
+        clause using ``and``.
+
+        :param filter: Optional OData ``$filter`` expression to further narrow
+            the list of returned tables (e.g.
+            ``"SchemaName eq 'Account'"``).  Column names in filter
+            expressions must use the exact property names from the
+            ``EntityDefinitions`` metadata (typically PascalCase).
+        :type filter: :class:`str` or None
+
         :return: List of EntityDefinition metadata dictionaries.
         :rtype: :class:`list` of :class:`dict`
 
         Example::
 
+            # List all non-private tables
             tables = client.tables.list()
             for table in tables:
                 print(table["LogicalName"])
+
+            # List only tables whose schema name starts with "new_"
+            custom_tables = client.tables.list(
+                filter="startswith(SchemaName, 'new_')"
+            )
         """
         with self._client._scoped_odata() as od:
-            return od._list_tables()
+            return od._list_tables(filter=filter)
 
     # ------------------------------------------------------------- add_columns
 

tests/unit/data/test_odata_internal.py

@@ -125,6 +125,61 @@ def test_non_string_key_raises_type_error(self):
             self.od._build_alternate_key_str({1: "ACC-001"})
 
 
+class TestListTables(unittest.TestCase):
+    """Unit tests for _ODataClient._list_tables filter parameter."""
+
+    def setUp(self):
+        self.od = _make_odata_client()
+
+    def _setup_response(self, value):
+        """Configure _request to return a response with the given value list."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"value": value}
+        self.od._request.return_value = mock_response
+
+    def test_no_filter_uses_default(self):
+        """_list_tables() without filter sends only IsPrivate eq false."""
+        self._setup_response([])
+        self.od._list_tables()
+
+        self.od._request.assert_called_once()
+        call_kwargs = self.od._request.call_args
+        params = call_kwargs.kwargs.get("params") or call_kwargs[1].get("params", {})
+        self.assertEqual(params["$filter"], "IsPrivate eq false")
+
+    def test_filter_combined_with_default(self):
+        """_list_tables(filter=...) combines user filter with IsPrivate eq false."""
+        self._setup_response([{"LogicalName": "account"}])
+        self.od._list_tables(filter="SchemaName eq 'Account'")
+
+        self.od._request.assert_called_once()
+        call_kwargs = self.od._request.call_args
+        params = call_kwargs.kwargs.get("params") or call_kwargs[1].get("params", {})
+        self.assertEqual(
+            params["$filter"],
+            "IsPrivate eq false and SchemaName eq 'Account'",
+        )
+
+    def test_filter_none_same_as_no_filter(self):
+        """_list_tables(filter=None) is equivalent to _list_tables()."""
+        self._setup_response([])
+        self.od._list_tables(filter=None)
+
+        call_kwargs = self.od._request.call_args
+        params = call_kwargs.kwargs.get("params") or call_kwargs[1].get("params", {})
+        self.assertEqual(params["$filter"], "IsPrivate eq false")
+
+    def test_returns_value_list(self):
+        """_list_tables returns the 'value' array from the response."""
+        expected = [
+            {"LogicalName": "account"},
+            {"LogicalName": "contact"},
+        ]
+        self._setup_response(expected)
+        result = self.od._list_tables()
+        self.assertEqual(result, expected)
+
+
 class TestUpsert(unittest.TestCase):
     """Unit tests for _ODataClient._upsert."""
 

tests/unit/test_tables_operations.py

@@ -100,10 +100,35 @@ def test_list(self):
 
         result = self.client.tables.list()
 
-        self.client._odata._list_tables.assert_called_once()
+        self.client._odata._list_tables.assert_called_once_with(filter=None)
         self.assertIsInstance(result, list)
         self.assertEqual(result, expected_tables)
 
+    def test_list_with_filter(self):
+        """list(filter=...) should pass the filter expression to _list_tables."""
+        expected_tables = [
+            {"LogicalName": "account", "SchemaName": "Account"},
+        ]
+        self.client._odata._list_tables.return_value = expected_tables
+
+        result = self.client.tables.list(filter="SchemaName eq 'Account'")
+
+        self.client._odata._list_tables.assert_called_once_with(filter="SchemaName eq 'Account'")
+        self.assertIsInstance(result, list)
+        self.assertEqual(result, expected_tables)
+
+    def test_list_with_filter_none_explicit(self):
+        """list(filter=None) should behave identically to list() with no args."""
+        expected_tables = [
+            {"LogicalName": "account", "SchemaName": "Account"},
+        ]
+        self.client._odata._list_tables.return_value = expected_tables
+
+        result = self.client.tables.list(filter=None)
+
+        self.client._odata._list_tables.assert_called_once_with(filter=None)
+        self.assertEqual(result, expected_tables)
+
     # ------------------------------------------------------------ add_columns
 
     def test_add_columns(self):