fix: address Copilot review - reject filter+typed, document typed/dict-spec in docstrings + README

Author: arorashivam96

README.md

@@ -111,7 +111,7 @@ df = results.to_dataframe()          # same rows as a pandas DataFrame
 
 ### Define and evolve schema
 
-`client.tables` creates and inspects tables, columns, relationships, and alternate keys. Column types are simple strings (`"string"`, `"int"`, `"decimal"`, `"money"`, `"datetime"`, `"bool"`, `"memo"`); pass an `IntEnum` subclass to create a choice column. `tables.get` returns `None` when the table does not exist, which makes schema setup idempotent. Every table gets a primary name column automatically — `<prefix>_Name` unless you pass `primary_column` — so do not list it in `columns`.
+`client.tables` creates and inspects tables, columns, relationships, and alternate keys. Column types are simple strings (`"string"`, `"int"`, `"decimal"`, `"money"`, `"datetime"`, `"bool"`, `"memo"`); pass an `IntEnum` subclass to create a choice column, or a dict spec (e.g. `{"type": "memo", "max_length": 2000}`) to set constraints like length, range, format, required level, or display name. `tables.get` returns `None` when the table does not exist, which makes schema setup idempotent. Every table gets a primary name column automatically — `<prefix>_Name` unless you pass `primary_column` — so do not list it in `columns`.
 
 ```python
 # Create a custom table with typed columns
@@ -136,6 +136,30 @@ client.tables.create_lookup_field(
 )
 ```
 
+Columns can carry constraints, be updated in place, and be read back with their
+type-specific metadata in a single request:
+
+```python
+# Create columns with constraints -- pass a dict spec instead of a bare type.
+# Keys: max_length, min_value, max_value, precision, format, required, display_name.
+client.tables.create("new_Feedback", {
+    "new_Rating":  {"type": "int",  "min_value": 1, "max_value": 5},
+    "new_Comment": {"type": "memo", "max_length": 2000, "display_name": "Comment"},
+})
+
+# Update an existing column's constraints (same override keys as create).
+client.tables.update_column("new_Feedback", "new_Comment", {"max_length": 4000})
+client.tables.update_columns("new_Feedback", {
+    "new_Rating":  {"max_value": 10},
+    "new_Comment": {"display_name": "Customer Comment"},
+})
+
+# Read a column (or all columns) with typed fields in one request (typed=True).
+col = client.tables.get_column("new_Feedback", "new_Comment", typed=True)
+print(col["MaxLength"])  # -> 4000
+cols = client.tables.list_columns("new_Feedback", typed=True)
+```
+
 Relationship methods take logical names, which are always the schema name in lowercase. For choice columns, many-to-many relationships, and alternate keys, see [Customize tables and columns](https://learn.microsoft.com/power-apps/developer/data-platform/sdk-python/metadata) and [Manage table relationships](https://learn.microsoft.com/power-apps/developer/data-platform/sdk-python/relationships).
 
 ### Work in bulk

src/PowerPlatform/Dataverse/aio/data/_async_odata.py

@@ -945,6 +945,12 @@ async def _list_columns(
         :raises HttpError: If the Web API request fails.
         """
         if typed:
+            if filter:
+                raise ValueError(
+                    "The 'filter' argument is not supported with typed=True: RetrieveMetadataChanges "
+                    "projects typed fields but does not accept an OData $filter. Use typed=False to "
+                    "filter, or drop filter when typed=True."
+                )
             return await self._retrieve_metadata_changes(table_schema_name, properties=select)
         ent = await self._get_entity_by_table_schema_name(table_schema_name)
         if not ent or not ent.get("MetadataId"):

src/PowerPlatform/Dataverse/aio/operations/async_tables.py

@@ -721,9 +721,15 @@ async def list_columns(
         :param select: Optional list of property names to project via
             ``$select``.  Values are passed as-is (PascalCase).
         :type select: list[str] or None
-        :param filter: Optional OData ``$filter`` expression.  For example,
-            ``"AttributeType eq 'String'"`` returns only string columns.
+        :param filter: Optional OData ``$filter`` expression (only when
+            ``typed=False``).  For example, ``"AttributeType eq 'String'"``
+            returns only string columns.
         :type filter: :class:`str` or None
+        :param typed: When ``True``, read via ``RetrieveMetadataChanges`` so
+            type-specific fields (``MaxLength``, ``MinValue``/``MaxValue``, ...)
+            come back in one request without the ``@odata.type`` URL cast.
+            ``filter`` is not supported in this mode.
+        :type typed: :class:`bool`
 
         :return: List of raw attribute metadata dictionaries.
         :rtype: list[dict[str, typing.Any]]
@@ -732,6 +738,8 @@ async def list_columns(
             If the table is not found.
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.
+        :raises ValueError:
+            If ``filter`` is combined with ``typed=True``.
 
         Example::
 

src/PowerPlatform/Dataverse/data/_odata.py

@@ -924,6 +924,12 @@ def _list_columns(
         :raises HttpError: If the Web API request fails.
         """
         if typed:
+            if filter:
+                raise ValueError(
+                    "The 'filter' argument is not supported with typed=True: RetrieveMetadataChanges "
+                    "projects typed fields but does not accept an OData $filter. Use typed=False to "
+                    "filter, or drop filter when typed=True."
+                )
             return self._retrieve_metadata_changes(table_schema_name, properties=select)
         ent = self._get_entity_by_table_schema_name(table_schema_name)
         if not ent or not ent.get("MetadataId"):

src/PowerPlatform/Dataverse/operations/batch.py

@@ -527,7 +527,10 @@ def create(
 
         :param table: Schema name of the new table (e.g. ``"new_Product"``).
         :type table: :class:`str`
-        :param columns: Mapping of column schema names to type strings or Enum subclasses.
+        :param columns: Mapping of column schema name to a type string, an
+            :class:`~enum.Enum` subclass, or a dict constraint spec (e.g.
+            ``{"type": "memo", "max_length": 2000}``) -- the same shape accepted
+            by :meth:`PowerPlatform.Dataverse.operations.tables.TableOperations.create`.
         :type columns: dict[str, typing.Any]
         :param solution: Optional solution unique name.
         :type solution: str or None
@@ -601,7 +604,10 @@ def add_columns(self, table: str, columns: Dict[str, Any]) -> None:
 
         :param table: Schema name of the target table.
         :type table: :class:`str`
-        :param columns: Mapping of column schema names to type strings or Enum subclasses.
+        :param columns: Mapping of column schema name to a type string, an
+            :class:`~enum.Enum` subclass, or a dict constraint spec (e.g.
+            ``{"type": "memo", "max_length": 2000}``) -- the same shape accepted
+            by :meth:`PowerPlatform.Dataverse.operations.tables.TableOperations.add_columns`.
         :type columns: dict[str, typing.Any]
         """
         self._batch._items.append(_TableAddColumns(table=table, columns=columns))

src/PowerPlatform/Dataverse/operations/tables.py

@@ -722,9 +722,15 @@ def list_columns(
         :param select: Optional list of property names to project via
             ``$select``.  Values are passed as-is (PascalCase).
         :type select: list[str] or None
-        :param filter: Optional OData ``$filter`` expression.  For example,
-            ``"AttributeType eq 'String'"`` returns only string columns.
+        :param filter: Optional OData ``$filter`` expression (only when
+            ``typed=False``).  For example, ``"AttributeType eq 'String'"``
+            returns only string columns.
         :type filter: :class:`str` or None
+        :param typed: When ``True``, read via ``RetrieveMetadataChanges`` so
+            type-specific fields (``MaxLength``, ``MinValue``/``MaxValue``, ...)
+            come back in one request without the ``@odata.type`` URL cast.
+            ``filter`` is not supported in this mode.
+        :type typed: :class:`bool`
 
         :return: List of raw attribute metadata dictionaries.
         :rtype: list[dict[str, typing.Any]]
@@ -733,6 +739,8 @@ def list_columns(
             If the table is not found.
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.
+        :raises ValueError:
+            If ``filter`` is combined with ``typed=True``.
 
         Example::
 

tests/unit/aio/data/test_async_odata_internal.py

@@ -1946,6 +1946,12 @@ async def test_get_column_typed_empty_returns_none(self):
         client._retrieve_metadata_changes = AsyncMock(return_value=[])
         assert await client._get_column("account", "ghost", typed=True) is None
 
+    async def test_list_columns_typed_with_filter_raises(self):
+        """filter + typed=True is rejected (not silently dropped)."""
+        client = _make_client()
+        with pytest.raises(ValueError):
+            await client._list_columns("account", typed=True, filter="AttributeType eq 'String'")
+
 
 class TestAsyncGetColumn:
     """_AsyncODataClient._get_column non-typed paths (#203)."""

tests/unit/data/test_odata_internal.py

@@ -3305,6 +3305,21 @@ def test_get_column_typed_returns_single_attr(self):
         self.assertEqual(col["LogicalName"], "emailaddress1")
         self.assertEqual(col["MaxLength"], 100)
 
+    def test_list_columns_typed_with_filter_raises(self):
+        """filter + typed=True is rejected (not silently dropped)."""
+        with self.assertRaises(ValueError):
+            self.od._list_columns("account", typed=True, filter="AttributeType eq 'String'")
+
+
+class TestBuildCreateColumnDictSpec(unittest.TestCase):
+    """Batch create/add-columns reaches dict constraint specs via the shared builder."""
+
+    def test_build_create_column_accepts_dict_spec(self):
+        od = _make_odata_client()
+        req = od._build_create_column("meta-1", "new_Comment", {"type": "memo", "max_length": 2000})
+        self.assertEqual(req.method, "POST")
+        self.assertEqual(json.loads(req.body)["MaxLength"], 2000)
+
 
 if __name__ == "__main__":
     unittest.main()