Add Record and TableInfo typed return models (#115)

## Summary
Introduces typed dataclass return models for record and table metadata
operations, replacing raw `Dict[str, Any]` returns while maintaining
full backward compatibility via dict-like access.

### New models
- **`Record`** — wraps OData record responses with `id`, `table`,
`data`, `etag` fields. `result["key"]` still works via delegation to
`self.data`. Factory `from_api_response()` strips `@odata.*` keys and
extracts etag.
- **`TableInfo`** — wraps table metadata with legacy key mapping
(`result["table_schema_name"]` maps to `result.schema_name`). Factories
`from_dict()` and `from_api_response()`.
- **`ColumnInfo`** — typed column metadata with `from_api_response()`
for PascalCase API responses.

### Changed return types
| Method | Before | After |
|--------|--------|-------|
| `records.get(table, id)` | `Dict[str, Any]` | `Record` |
| `records.get(table, filter=...)` | `Iterable[List[Dict]]` |
`Iterable[List[Record]]` |
| `query.sql(sql)` | `List[Dict]` | `List[Record]` |
| `tables.create(...)` | `Dict[str, Any]` | `TableInfo` |
| `tables.get(...)` | `Optional[Dict]` | `Optional[TableInfo]` |

### Backward compatibility
- `result["key"]` works on all models
- `"key" in result` works
- `for k in result` iterates keys
- `result.get("key", default)` works
- Legacy keys on TableInfo (`table_schema_name`) map to new attributes
(`schema_name`)

## Test plan
- [x] 188 unit tests passing (32 new model tests + updated
operation/deprecation tests)
- [x] Black formatting clean

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: tpellissier <tpellissier@microsoft.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

src/PowerPlatform/Dataverse/models/record.py

@@ -0,0 +1,114 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Record data model for Dataverse entities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, KeysView, Optional, ValuesView, ItemsView
+
+__all__ = ["Record"]
+
+_ODATA_PREFIX = "@odata."
+
+
+@dataclass
+class Record:
+    """Strongly-typed Dataverse record with dict-like backward compatibility.
+
+    Wraps raw OData response data into a structured object while preserving
+    ``result["key"]`` access patterns for existing code.
+
+    :param id: Record GUID. Empty string if not extracted (e.g. paginated
+        results, SQL queries).
+    :type id: :class:`str`
+    :param table: Table schema name used in the request.
+    :type table: :class:`str`
+    :param data: Record field data as key-value pairs.
+    :type data: :class:`dict`
+    :param etag: ETag for optimistic concurrency, extracted from
+        ``@odata.etag`` in the API response.
+    :type etag: :class:`str` or None
+
+    Example::
+
+        record = client.records.get("account", account_id, select=["name"])
+        print(record.id)          # structured access
+        print(record["name"])     # dict-like access (backward compat)
+    """
+
+    id: str = ""
+    table: str = ""
+    data: Dict[str, Any] = field(default_factory=dict)
+    etag: Optional[str] = None
+
+    # --------------------------------------------------------- dict-like access
+
+    def __getitem__(self, key: str) -> Any:
+        return self.data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.data[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.data[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return value for *key*, or *default* if not present."""
+        return self.data.get(key, default)
+
+    def keys(self) -> KeysView[str]:
+        """Return data keys."""
+        return self.data.keys()
+
+    def values(self) -> ValuesView[Any]:
+        """Return data values."""
+        return self.data.values()
+
+    def items(self) -> ItemsView[str, Any]:
+        """Return data items."""
+        return self.data.items()
+
+    # -------------------------------------------------------------- factories
+
+    @classmethod
+    def from_api_response(
+        cls,
+        table: str,
+        response_data: Dict[str, Any],
+        *,
+        record_id: str = "",
+    ) -> Record:
+        """Create a :class:`Record` from a raw OData API response.
+
+        Strips ``@odata.*`` annotation keys from the data and extracts the
+        ``@odata.etag`` value if present.
+
+        :param table: Table schema name.
+        :type table: :class:`str`
+        :param response_data: Raw JSON dict from the OData response.
+        :type response_data: :class:`dict`
+        :param record_id: Known record GUID. Pass explicitly when available
+            (e.g. single-record get). Defaults to empty string.
+        :type record_id: :class:`str`
+        :rtype: :class:`Record`
+        """
+        etag = response_data.get("@odata.etag")
+        data = {k: v for k, v in response_data.items() if not k.startswith(_ODATA_PREFIX)}
+        return cls(id=record_id, table=table, data=data, etag=etag)
+
+    # -------------------------------------------------------------- conversion
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a plain dict copy of the record data (excludes metadata)."""
+        return dict(self.data)

src/PowerPlatform/Dataverse/models/table_info.py

@@ -0,0 +1,224 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Table and column metadata models for Dataverse."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Dict, Iterator, KeysView, List, Optional
+
+__all__ = ["TableInfo", "ColumnInfo"]
+
+
+@dataclass
+class ColumnInfo:
+    """Column metadata from a Dataverse table definition.
+
+    :param schema_name: Column schema name (e.g. ``"new_Price"``).
+    :type schema_name: :class:`str`
+    :param logical_name: Column logical name (lowercase).
+    :type logical_name: :class:`str`
+    :param type: Column type string (e.g. ``"String"``, ``"Integer"``).
+    :type type: :class:`str`
+    :param is_primary: Whether this is the primary name column.
+    :type is_primary: :class:`bool`
+    :param is_required: Whether the column is required.
+    :type is_required: :class:`bool`
+    :param max_length: Maximum length for string columns.
+    :type max_length: :class:`int` or None
+    :param display_name: Human-readable display name.
+    :type display_name: :class:`str` or None
+    :param description: Column description.
+    :type description: :class:`str` or None
+    """
+
+    schema_name: str = ""
+    logical_name: str = ""
+    type: str = ""
+    is_primary: bool = False
+    is_required: bool = False
+    max_length: Optional[int] = None
+    display_name: Optional[str] = None
+    description: Optional[str] = None
+
+    @classmethod
+    def from_api_response(cls, response_data: Dict[str, Any]) -> ColumnInfo:
+        """Create from a raw Dataverse ``AttributeMetadata`` API response.
+
+        :param response_data: Raw attribute metadata dict (PascalCase keys).
+        :type response_data: :class:`dict`
+        :rtype: :class:`ColumnInfo`
+        """
+        # Extract display name from nested structure
+        display_name_obj = response_data.get("DisplayName", {})
+        user_label = display_name_obj.get("UserLocalizedLabel") or {}
+        display_name = user_label.get("Label")
+
+        # Extract description from nested structure
+        desc_obj = response_data.get("Description", {})
+        desc_label = desc_obj.get("UserLocalizedLabel") or {}
+        description = desc_label.get("Label")
+
+        # Extract required level
+        req_level = response_data.get("RequiredLevel", {})
+        is_required = req_level.get("Value", "None") != "None" if isinstance(req_level, dict) else False
+
+        return cls(
+            schema_name=response_data.get("SchemaName", ""),
+            logical_name=response_data.get("LogicalName", ""),
+            type=response_data.get("AttributeTypeName", {}).get("Value", response_data.get("AttributeType", "")),
+            is_primary=response_data.get("IsPrimaryName", False),
+            is_required=is_required,
+            max_length=response_data.get("MaxLength"),
+            display_name=display_name,
+            description=description,
+        )
+
+
+@dataclass
+class TableInfo:
+    """Table metadata with dict-like backward compatibility.
+
+    Supports both new attribute access (``info.schema_name``) and legacy
+    dict-key access (``info["table_schema_name"]``) for backward
+    compatibility with code written against the raw dict API.
+
+    :param schema_name: Table schema name (e.g. ``"Account"``).
+    :type schema_name: :class:`str`
+    :param logical_name: Table logical name (lowercase).
+    :type logical_name: :class:`str`
+    :param entity_set_name: OData entity set name.
+    :type entity_set_name: :class:`str`
+    :param metadata_id: Metadata GUID.
+    :type metadata_id: :class:`str`
+    :param display_name: Human-readable display name.
+    :type display_name: :class:`str` or None
+    :param description: Table description.
+    :type description: :class:`str` or None
+    :param columns: Column metadata (when retrieved).
+    :type columns: :class:`list` of :class:`ColumnInfo` or None
+    :param columns_created: Column schema names created with the table.
+    :type columns_created: :class:`list` of :class:`str` or None
+
+    Example::
+
+        info = client.tables.create("new_Product", {"new_Price": "decimal"})
+        print(info.schema_name)              # new attribute access
+        print(info["table_schema_name"])     # legacy dict-key access
+    """
+
+    schema_name: str = ""
+    logical_name: str = ""
+    entity_set_name: str = ""
+    metadata_id: str = ""
+    display_name: Optional[str] = None
+    description: Optional[str] = None
+    columns: Optional[List[ColumnInfo]] = field(default=None, repr=False)
+    columns_created: Optional[List[str]] = field(default=None, repr=False)
+
+    # Maps legacy dict keys (used by existing code) to attribute names.
+    _LEGACY_KEY_MAP: ClassVar[Dict[str, str]] = {
+        "table_schema_name": "schema_name",
+        "table_logical_name": "logical_name",
+        "entity_set_name": "entity_set_name",
+        "metadata_id": "metadata_id",
+        "columns_created": "columns_created",
+    }
+
+    # --------------------------------------------------------- dict-like access
+
+    def _resolve_key(self, key: str) -> str:
+        """Resolve a legacy or direct key to an attribute name."""
+        return self._LEGACY_KEY_MAP.get(key, key)
+
+    def __getitem__(self, key: str) -> Any:
+        attr = self._resolve_key(key)
+        if hasattr(self, attr):
+            return getattr(self, attr)
+        raise KeyError(key)
+
+    def __contains__(self, key: object) -> bool:
+        if not isinstance(key, str):
+            return False
+        attr = self._resolve_key(key)
+        return hasattr(self, attr)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._LEGACY_KEY_MAP)
+
+    def __len__(self) -> int:
+        return len(self._LEGACY_KEY_MAP)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return value for *key*, or *default* if not present."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def keys(self) -> KeysView[str]:
+        """Return legacy dict keys."""
+        return self._LEGACY_KEY_MAP.keys()
+
+    def values(self) -> List[Any]:
+        """Return values corresponding to legacy dict keys."""
+        return [getattr(self, attr) for attr in self._LEGACY_KEY_MAP.values()]
+
+    def items(self) -> List[tuple]:
+        """Return (legacy_key, value) pairs."""
+        return [(k, getattr(self, attr)) for k, attr in self._LEGACY_KEY_MAP.items()]
+
+    # -------------------------------------------------------------- factories
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> TableInfo:
+        """Create from an SDK internal dict (snake_case keys).
+
+        This handles the dict format returned by ``_create_table`` and
+        ``_get_table_info`` in the OData layer.
+
+        :param data: Dictionary with SDK snake_case keys.
+        :type data: :class:`dict`
+        :rtype: :class:`TableInfo`
+        """
+        return cls(
+            schema_name=data.get("table_schema_name", ""),
+            logical_name=data.get("table_logical_name", ""),
+            entity_set_name=data.get("entity_set_name", ""),
+            metadata_id=data.get("metadata_id", ""),
+            columns_created=data.get("columns_created"),
+        )
+
+    @classmethod
+    def from_api_response(cls, response_data: Dict[str, Any]) -> TableInfo:
+        """Create from a raw Dataverse ``EntityDefinition`` API response.
+
+        :param response_data: Raw entity metadata dict (PascalCase keys).
+        :type response_data: :class:`dict`
+        :rtype: :class:`TableInfo`
+        """
+        # Extract display name from nested structure
+        display_name_obj = response_data.get("DisplayName", {})
+        user_label = display_name_obj.get("UserLocalizedLabel") or {}
+        display_name = user_label.get("Label")
+
+        # Extract description from nested structure
+        desc_obj = response_data.get("Description", {})
+        desc_label = desc_obj.get("UserLocalizedLabel") or {}
+        description = desc_label.get("Label")
+
+        return cls(
+            schema_name=response_data.get("SchemaName", ""),
+            logical_name=response_data.get("LogicalName", ""),
+            entity_set_name=response_data.get("EntitySetName", ""),
+            metadata_id=response_data.get("MetadataId", ""),
+            display_name=display_name,
+            description=description,
+        )
+
+    # -------------------------------------------------------------- conversion
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a dict with legacy keys for backward compatibility."""
+        return {k: getattr(self, attr) for k, attr in self._LEGACY_KEY_MAP.items()}

src/PowerPlatform/Dataverse/operations/query.py

@@ -5,7 +5,9 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, TYPE_CHECKING
+from typing import List, TYPE_CHECKING
+
+from ..models.record import Record
 
 if TYPE_CHECKING:
     from ..client import DataverseClient
@@ -37,7 +39,7 @@ def __init__(self, client: DataverseClient) -> None:
 
     # -------------------------------------------------------------------- sql
 
-    def sql(self, sql: str) -> List[Dict[str, Any]]:
+    def sql(self, sql: str) -> List[Record]:
         """Execute a read-only SQL query using the Dataverse Web API.
 
         The SQL query must follow the supported subset: a single SELECT
@@ -47,9 +49,10 @@ def sql(self, sql: str) -> List[Dict[str, Any]]:
         :param sql: Supported SQL SELECT statement.
         :type sql: :class:`str`
 
-        :return: List of result row dictionaries. Returns an empty list when no
-            rows match.
-        :rtype: :class:`list` of :class:`dict`
+        :return: List of :class:`~PowerPlatform.Dataverse.models.record.Record`
+            objects. Returns an empty list when no rows match.
+        :rtype: :class:`list` of
+            :class:`~PowerPlatform.Dataverse.models.record.Record`
 
         :raises ~PowerPlatform.Dataverse.core.errors.ValidationError:
             If ``sql`` is not a string or is empty.
@@ -72,4 +75,5 @@ def sql(self, sql: str) -> List[Dict[str, Any]]:
                 )
         """
         with self._client._scoped_odata() as od:
-            return od._query_sql(sql)
+            rows = od._query_sql(sql)
+            return [Record.from_api_response("", row) for row in rows]