Add RelationshipInfo typed return model for relationship methods

Introduces RelationshipInfo dataclass as the return type for all
relationship operations (create_one_to_many_relationship,
create_many_to_many_relationship, get_relationship, create_lookup_field).

Factory methods: from_one_to_many(), from_many_to_many(), from_api_response()
which detects 1:N vs N:N from @odata.type in API responses.

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

Author: tpellissier

src/PowerPlatform/Dataverse/models/relationship_info.py

@@ -0,0 +1,163 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Typed return model for relationship metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+__all__ = ["RelationshipInfo"]
+
+_OTM_ODATA_TYPE = "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata"
+_MTM_ODATA_TYPE = "Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata"
+
+
+@dataclass
+class RelationshipInfo:
+    """Typed return model for relationship metadata.
+
+    Returned by :meth:`~PowerPlatform.Dataverse.operations.tables.TableOperations.create_one_to_many_relationship`,
+    :meth:`~PowerPlatform.Dataverse.operations.tables.TableOperations.create_many_to_many_relationship`,
+    :meth:`~PowerPlatform.Dataverse.operations.tables.TableOperations.get_relationship`, and
+    :meth:`~PowerPlatform.Dataverse.operations.tables.TableOperations.create_lookup_field`.
+
+    :param relationship_id: Relationship metadata GUID.
+    :type relationship_id: :class:`str` or None
+    :param relationship_schema_name: Relationship schema name.
+    :type relationship_schema_name: :class:`str`
+    :param relationship_type: Either ``"one_to_many"`` or ``"many_to_many"``.
+    :type relationship_type: :class:`str`
+    :param lookup_schema_name: Lookup field schema name (one-to-many only).
+    :type lookup_schema_name: :class:`str` or None
+    :param referenced_entity: Parent entity logical name (one-to-many only).
+    :type referenced_entity: :class:`str` or None
+    :param referencing_entity: Child entity logical name (one-to-many only).
+    :type referencing_entity: :class:`str` or None
+    :param entity1_logical_name: First entity logical name (many-to-many only).
+    :type entity1_logical_name: :class:`str` or None
+    :param entity2_logical_name: Second entity logical name (many-to-many only).
+    :type entity2_logical_name: :class:`str` or None
+
+    Example::
+
+        result = client.tables.create_one_to_many_relationship(lookup, relationship)
+        print(result.relationship_schema_name)
+        print(result.lookup_schema_name)
+    """
+
+    relationship_id: Optional[str] = None
+    relationship_schema_name: str = ""
+    relationship_type: str = ""
+
+    # One-to-many specific
+    lookup_schema_name: Optional[str] = None
+    referenced_entity: Optional[str] = None
+    referencing_entity: Optional[str] = None
+
+    # Many-to-many specific
+    entity1_logical_name: Optional[str] = None
+    entity2_logical_name: Optional[str] = None
+
+    @classmethod
+    def from_one_to_many(
+        cls,
+        *,
+        relationship_id: Optional[str],
+        relationship_schema_name: str,
+        lookup_schema_name: str,
+        referenced_entity: str,
+        referencing_entity: str,
+    ) -> RelationshipInfo:
+        """Create from a one-to-many relationship result.
+
+        :param relationship_id: Relationship metadata GUID.
+        :type relationship_id: :class:`str` or None
+        :param relationship_schema_name: Relationship schema name.
+        :type relationship_schema_name: :class:`str`
+        :param lookup_schema_name: Lookup field schema name.
+        :type lookup_schema_name: :class:`str`
+        :param referenced_entity: Parent entity logical name.
+        :type referenced_entity: :class:`str`
+        :param referencing_entity: Child entity logical name.
+        :type referencing_entity: :class:`str`
+        :rtype: :class:`RelationshipInfo`
+        """
+        return cls(
+            relationship_id=relationship_id,
+            relationship_schema_name=relationship_schema_name,
+            relationship_type="one_to_many",
+            lookup_schema_name=lookup_schema_name,
+            referenced_entity=referenced_entity,
+            referencing_entity=referencing_entity,
+        )
+
+    @classmethod
+    def from_many_to_many(
+        cls,
+        *,
+        relationship_id: Optional[str],
+        relationship_schema_name: str,
+        entity1_logical_name: str,
+        entity2_logical_name: str,
+    ) -> RelationshipInfo:
+        """Create from a many-to-many relationship result.
+
+        :param relationship_id: Relationship metadata GUID.
+        :type relationship_id: :class:`str` or None
+        :param relationship_schema_name: Relationship schema name.
+        :type relationship_schema_name: :class:`str`
+        :param entity1_logical_name: First entity logical name.
+        :type entity1_logical_name: :class:`str`
+        :param entity2_logical_name: Second entity logical name.
+        :type entity2_logical_name: :class:`str`
+        :rtype: :class:`RelationshipInfo`
+        """
+        return cls(
+            relationship_id=relationship_id,
+            relationship_schema_name=relationship_schema_name,
+            relationship_type="many_to_many",
+            entity1_logical_name=entity1_logical_name,
+            entity2_logical_name=entity2_logical_name,
+        )
+
+    @classmethod
+    def from_api_response(cls, response_data: Dict[str, Any]) -> RelationshipInfo:
+        """Create from a raw Dataverse Web API response.
+
+        Detects one-to-many vs many-to-many from the ``@odata.type`` field
+        in the response and maps PascalCase keys to snake_case attributes.
+
+        :param response_data: Raw relationship metadata from the Web API.
+        :type response_data: :class:`dict`
+        :rtype: :class:`RelationshipInfo`
+        """
+        odata_type = response_data.get("@odata.type", "")
+        rel_id = response_data.get("MetadataId")
+        schema_name = response_data.get("SchemaName", "")
+
+        if _OTM_ODATA_TYPE in odata_type:
+            return cls(
+                relationship_id=rel_id,
+                relationship_schema_name=schema_name,
+                relationship_type="one_to_many",
+                referenced_entity=response_data.get("ReferencedEntity"),
+                referencing_entity=response_data.get("ReferencingEntity"),
+                lookup_schema_name=response_data.get("ReferencingEntityNavigationPropertyName"),
+            )
+
+        if _MTM_ODATA_TYPE in odata_type:
+            return cls(
+                relationship_id=rel_id,
+                relationship_schema_name=schema_name,
+                relationship_type="many_to_many",
+                entity1_logical_name=response_data.get("Entity1LogicalName"),
+                entity2_logical_name=response_data.get("Entity2LogicalName"),
+            )
+
+        # Fallback: unknown type, populate what we can
+        return cls(
+            relationship_id=rel_id,
+            relationship_schema_name=schema_name,
+        )

src/PowerPlatform/Dataverse/operations/tables.py

@@ -16,6 +16,7 @@
     CascadeConfiguration,
 )
 from ..common.constants import CASCADE_BEHAVIOR_REMOVE_LINK
+from ..models.relationship_info import RelationshipInfo
 
 if TYPE_CHECKING:
     from ..client import DataverseClient
@@ -268,7 +269,7 @@ def create_one_to_many_relationship(
         relationship: OneToManyRelationshipMetadata,
         *,
         solution: Optional[str] = None,
-    ) -> Dict[str, Any]:
+    ) -> RelationshipInfo:
         """Create a one-to-many relationship between tables.
 
         This operation creates both the relationship and the lookup attribute
@@ -281,9 +282,9 @@ def create_one_to_many_relationship(
         :param solution: Optional solution unique name to add relationship to.
         :type solution: :class:`str` or None
 
-        :return: Dictionary with ``relationship_id``, ``lookup_schema_name``,
-            and related metadata.
-        :rtype: :class:`dict`
+        :return: Relationship metadata with ``relationship_id``,
+            ``lookup_schema_name``, and entity names.
+        :rtype: :class:`~PowerPlatform.Dataverse.models.relationship_info.RelationshipInfo`
 
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.
@@ -322,14 +323,21 @@ def create_one_to_many_relationship(
                 )
 
                 result = client.tables.create_one_to_many_relationship(lookup, relationship)
-                print(f"Created lookup field: {result['lookup_schema_name']}")
+                print(f"Created lookup field: {result.lookup_schema_name}")
         """
         with self._client._scoped_odata() as od:
-            return od._create_one_to_many_relationship(
+            raw = od._create_one_to_many_relationship(
                 lookup,
                 relationship,
                 solution,
             )
+            return RelationshipInfo.from_one_to_many(
+                relationship_id=raw.get("relationship_id"),
+                relationship_schema_name=raw.get("relationship_schema_name", ""),
+                lookup_schema_name=raw.get("lookup_schema_name", ""),
+                referenced_entity=raw.get("referenced_entity", ""),
+                referencing_entity=raw.get("referencing_entity", ""),
+            )
 
     # ----------------------------------------------------- create_many_to_many
 
@@ -338,7 +346,7 @@ def create_many_to_many_relationship(
         relationship: ManyToManyRelationshipMetadata,
         *,
         solution: Optional[str] = None,
-    ) -> Dict[str, Any]:
+    ) -> RelationshipInfo:
         """Create a many-to-many relationship between tables.
 
         This operation creates a many-to-many relationship and an intersect
@@ -349,9 +357,9 @@ def create_many_to_many_relationship(
         :param solution: Optional solution unique name to add relationship to.
         :type solution: :class:`str` or None
 
-        :return: Dictionary with ``relationship_id``,
+        :return: Relationship metadata with ``relationship_id``,
             ``relationship_schema_name``, and entity names.
-        :rtype: :class:`dict`
+        :rtype: :class:`~PowerPlatform.Dataverse.models.relationship_info.RelationshipInfo`
 
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.
@@ -370,13 +378,19 @@ def create_many_to_many_relationship(
                 )
 
                 result = client.tables.create_many_to_many_relationship(relationship)
-                print(f"Created: {result['relationship_schema_name']}")
+                print(f"Created: {result.relationship_schema_name}")
         """
         with self._client._scoped_odata() as od:
-            return od._create_many_to_many_relationship(
+            raw = od._create_many_to_many_relationship(
                 relationship,
                 solution,
             )
+            return RelationshipInfo.from_many_to_many(
+                relationship_id=raw.get("relationship_id"),
+                relationship_schema_name=raw.get("relationship_schema_name", ""),
+                entity1_logical_name=raw.get("entity1_logical_name", ""),
+                entity2_logical_name=raw.get("entity2_logical_name", ""),
+            )
 
     # ------------------------------------------------------- delete_relationship
 
@@ -404,14 +418,15 @@ def delete_relationship(self, relationship_id: str) -> None:
 
     # -------------------------------------------------------- get_relationship
 
-    def get_relationship(self, schema_name: str) -> Optional[Dict[str, Any]]:
+    def get_relationship(self, schema_name: str) -> Optional[RelationshipInfo]:
         """Retrieve relationship metadata by schema name.
 
         :param schema_name: The schema name of the relationship.
         :type schema_name: :class:`str`
 
-        :return: Relationship metadata dictionary, or None if not found.
-        :rtype: :class:`dict` or None
+        :return: Relationship metadata, or ``None`` if not found.
+        :rtype: :class:`~PowerPlatform.Dataverse.models.relationship_info.RelationshipInfo`
+            or None
 
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.
@@ -420,10 +435,13 @@ def get_relationship(self, schema_name: str) -> Optional[Dict[str, Any]]:
 
             rel = client.tables.get_relationship("new_Department_Employee")
             if rel:
-                print(f"Found: {rel['SchemaName']}")
+                print(f"Found: {rel.relationship_schema_name}")
         """
         with self._client._scoped_odata() as od:
-            return od._get_relationship(schema_name)
+            raw = od._get_relationship(schema_name)
+            if raw is None:
+                return None
+            return RelationshipInfo.from_api_response(raw)
 
     # ------------------------------------------------------- create_lookup_field
 
@@ -439,7 +457,7 @@ def create_lookup_field(
         cascade_delete: str = CASCADE_BEHAVIOR_REMOVE_LINK,
         solution: Optional[str] = None,
         language_code: int = 1033,
-    ) -> Dict[str, Any]:
+    ) -> RelationshipInfo:
         """Create a simple lookup field relationship.
 
         This is a convenience method that wraps :meth:`create_one_to_many_relationship`
@@ -471,9 +489,9 @@ def create_lookup_field(
             (English).
         :type language_code: :class:`int`
 
-        :return: Dictionary with ``relationship_id``, ``lookup_schema_name``,
-            and related metadata.
-        :rtype: :class:`dict`
+        :return: Relationship metadata with ``relationship_id``,
+            ``lookup_schema_name``, and entity names.
+        :rtype: :class:`~PowerPlatform.Dataverse.models.relationship_info.RelationshipInfo`
 
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
             If the Web API request fails.