more logicalName -> schemaName renaming

Author: tpellissier

README.md

@@ -99,12 +99,12 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 | Concept | Description |
 |---------|-------------|
 | **DataverseClient** | Main entry point for all operations with environment connection |
-| **Records** | Dataverse records represented as Python dictionaries with logical field names |
-| **Logical Names** | Use table logical names (`"account"`) and column logical names (`"name"`) |  
+| **Records** | Dataverse records represented as Python dictionaries with column schema names |
+| **Schema Names** | Use table schema names (`"account"`, `"new_MyTestTable"`) and column schema names (`"name"`, `"new_MyTestColumn"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |  
 | **Bulk Operations** | Efficient bulk processing for multiple records with automatic optimization |
 | **Paging** | Automatic handling of large result sets with iterators |
 | **Structured Errors** | Detailed exception hierarchy with retry guidance and diagnostic information |
-| **Customization prefix values** | Custom tables and columns require a customization prefix value to be included for all operations (e.g., `"new_Title"`, not `"Title"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |
+| **Customization prefix values** | Custom tables and columns require a customization prefix value to be included for all operations (e.g., `"new_MyTestTable"`, not `"MyTestTable"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |
 
 ## Examples
 
@@ -176,7 +176,7 @@ for record in results:
     print(record["name"])
 
 # OData query with paging
-# Note: filter and expand parameters require exact casing
+# Note: filter and expand parameters are case sensitive
 pages = client.get(
     "account",
     select=["accountid", "name"],  # select is case-insensitive (automatically lowercased)
@@ -244,7 +244,7 @@ client.delete_table("new_Product")
 ```python
 # Upload a file to a record
 client.upload_file(
-    logical_name="account",
+    table_schema_name="account",
     record_id=account_id,
     file_name_attribute="new_document",
     path="/path/to/document.pdf"

examples/advanced/file_upload.py

@@ -187,7 +187,7 @@ def ensure_table():
     sys.exit(1)
 
 entity_set = table_info.get("entity_set_name")
-table_schema_name = table_info.get("table_schema_name") or entity_set.rstrip("s")
+table_schema_name = table_info.get("table_schema_name")
 attr_prefix = table_schema_name.split('_',1)[0] if '_' in table_schema_name else table_schema_name
 name_attr = f"{attr_prefix}_name"
 small_file_attr_schema = f"{attr_prefix}_SmallDocument"  # second file attribute for small single-request demo
@@ -264,7 +264,7 @@ def ensure_file_attribute_generic(schema_name: str, label: str, key_prefix: str)
         record_id = created_ids[0]
     else:
         raise RuntimeError("Unexpected create return; expected list[str] with at least one GUID")
-    print({"record_created": True, "id": record_id, "logical": table_schema_name})
+    print({"record_created": True, "id": record_id, "table schema name": table_schema_name})
 except Exception as e:  # noqa: BLE001
     print({"record_created": False, "error": str(e)})
     sys.exit(1)

examples/basic/functional_testing.py

@@ -123,9 +123,9 @@ def test_create_record(client: DataverseClient, table_info: Dict[str, Any]) -> s
     """Test record creation."""
     print("\n📝 Record Creation Test")
     print("=" * 50)
-    
-    logical_name = table_info.get("table_logical_name")
-    attr_prefix = logical_name.split("_", 1)[0] if "_" in logical_name else logical_name
+
+    table_schema_name = table_info.get("table_schema_name")
+    attr_prefix = table_schema_name.split("_", 1)[0] if "_" in table_schema_name else table_schema_name
 
     # Create test record data
     test_data = {
@@ -139,7 +139,7 @@ def test_create_record(client: DataverseClient, table_info: Dict[str, Any]) -> s
 
     try:
         print("🚀 Creating test record...")
-        created_ids = client.create(logical_name, test_data)
+        created_ids = client.create(table_schema_name, test_data)
 
         if isinstance(created_ids, list) and created_ids:
             record_id = created_ids[0]
@@ -163,12 +163,12 @@ def test_read_record(client: DataverseClient, table_info: Dict[str, Any], record
     print("\n📖 Record Reading Test")
     print("=" * 50)
 
-    logical_name = table_info.get("table_logical_name")
-    attr_prefix = logical_name.split("_", 1)[0] if "_" in logical_name else logical_name
+    table_schema_name = table_info.get("table_schema_name")
+    attr_prefix = table_schema_name.split("_", 1)[0] if "_" in table_schema_name else table_schema_name
 
     try:
         print(f"🔍 Reading record: {record_id}")
-        record = client.get(logical_name, record_id)
+        record = client.get(table_schema_name, record_id)
 
         if record:
             print("✅ Record retrieved successfully!")
@@ -198,15 +198,15 @@ def test_query_records(client: DataverseClient, table_info: Dict[str, Any]) -> N
     print("\n🔍 Record Query Test")
     print("=" * 50)
 
-    logical_name = table_info.get("table_logical_name")
-    attr_prefix = logical_name.split("_", 1)[0] if "_" in logical_name else logical_name
+    table_schema_name = table_info.get("table_schema_name")
+    attr_prefix = table_schema_name.split("_", 1)[0] if "_" in table_schema_name else table_schema_name
 
     try:
         print("🔍 Querying records from test table...")
 
         # Query with filter and select
         records_iterator = client.get(
-            logical_name,
+            table_schema_name,
             select=[f"{attr_prefix}_name", f"{attr_prefix}_count", f"{attr_prefix}_amount"],
             filter=f"{attr_prefix}_is_active eq true",
             top=5,
@@ -234,14 +234,14 @@ def cleanup_test_data(client: DataverseClient, table_info: Dict[str, Any], recor
     print("\n🧹 Cleanup")
     print("=" * 50)
 
-    logical_name = table_info.get("table_logical_name")
+    table_schema_name = table_info.get("table_schema_name")
 
     # Ask user if they want to clean up
     cleanup_choice = input("Do you want to delete the test record? (y/N): ").strip().lower()
 
     if cleanup_choice in ['y', 'yes']:
         try:
-            client.delete(logical_name, record_id)
+            client.delete(table_schema_name, record_id)
             print("✅ Test record deleted successfully")
         except Exception as e:
             print(f"⚠️  Failed to delete test record: {e}")

src/PowerPlatform/Dataverse/client.py

@@ -108,7 +108,7 @@ def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dic
         :param table_schema_name: Table schema name (e.g. ``"account"``, ``"contact"``, or ``"new_customtable"``).
         :type table_schema_name: str
         :param records: A single record dictionary or a list of record dictionaries.
-            Each dictionary should contain attribute logical names as keys.
+            Each dictionary should contain attribute schema names as keys.
         :type records: dict or list[dict]
 
         :return: List of created record GUIDs. Returns a single-element list for a single input.
@@ -273,7 +273,7 @@ def get(
         :type table_schema_name: str
         :param record_id: Optional GUID to fetch a specific record. If None, queries multiple records.
         :type record_id: str or None
-        :param select: Optional list of attribute logical names to retrieve. Column names are
+        :param select: Optional list of column schema names to retrieve. Column names are
             case-insensitive and automatically lowercased (e.g. ``["new_Title", "new_Amount"]``
             becomes ``"new_title,new_amount"``).
         :type select: list[str] or None
@@ -478,7 +478,7 @@ class ItemStatus(IntEnum):
                 }
 
                 result = client.create_table("new_SampleItem", columns)
-                print(f"Created table: {result['table_logical_name']}")
+                print(f"Created table: {result['table_schema_name']}")
                 print(f"Columns: {result['columns_created']}")
 
             Create a table with a custom primary column name::

src/PowerPlatform/Dataverse/data/odata.py

@@ -169,7 +169,7 @@ def _create(self, entity_set: str, table_schema_name: str, record: Dict[str, Any
         table_schema_name : str
             Table schema name.
         record : dict[str, Any]
-            Attribute payload mapped by logical column names.
+            Attribute payload mapped by column schema names.
 
         Returns
         -------
@@ -212,11 +212,11 @@ def _create_multiple(self, entity_set: str, table_schema_name: str, records: Lis
         table_schema_name : str
             Table schema name.
         records : list[dict[str, Any]]
-            Payloads mapped by logical attribute names.
+            Payloads mapped by column schema names.
 
         Multi-create logical name resolution
         ------------------------------------
-        - If any payload omits ``@odata.type`` the client stamps ``Microsoft.Dynamics.CRM.<table_schema_name>``.
+        - If any payload omits ``@odata.type`` the client stamps ``Microsoft.Dynamics.CRM.<table_logical_name>``.
         - If all payloads already include ``@odata.type`` no modification occurs.
         
         Returns
@@ -666,22 +666,22 @@ def _extract_logical_table(sql: str) -> str:
         return m.group(1).lower()
 
     # ---------------------- Entity set resolution -----------------------
-    def _entity_set_from_schema_name(self, logical: str) -> str:
-        """Resolve entity set name (plural) from a logical (singular) name using metadata.
+    def _entity_set_from_schema_name(self, table_schema_name: str) -> str:
+        """Resolve entity set name (plural) from a schema name (singular) name using metadata.
 
         Caches results for subsequent queries. Case-insensitive.
         """
-        if not logical:
-            raise ValueError("logical name required")
+        if not table_schema_name:
+            raise ValueError("table schema name required")
 
         # Use normalized (lowercase) key for cache lookup
-        cache_key = self._normalize_cache_key(logical)
+        cache_key = self._normalize_cache_key(table_schema_name)
         cached = self._logical_to_entityset_cache.get(cache_key)
         if cached:
             return cached
         url = f"{self.api}/EntityDefinitions"
         # LogicalName in Dataverse is stored in lowercase, so we need to lowercase for the filter
-        logical_lower = logical.lower()
+        logical_lower = table_schema_name.lower()
         logical_escaped = self._escape_odata_quotes(logical_lower)
         params = {
             "$select": "LogicalName,EntitySetName,PrimaryIdAttribute",
@@ -694,16 +694,16 @@ def _entity_set_from_schema_name(self, logical: str) -> str:
         except ValueError:
             items = []
         if not items:
-            plural_hint = " (did you pass a plural entity set name instead of the singular logical name?)" if logical.endswith("s") and not logical.endswith("ss") else ""
+            plural_hint = " (did you pass a plural entity set name instead of the singular table schema name?)" if table_schema_name.endswith("s") and not table_schema_name.endswith("ss") else ""
             raise MetadataError(
-                f"Unable to resolve entity set for logical name '{logical}'. Provide the singular logical name.{plural_hint}",
+                f"Unable to resolve entity set for table schema name '{table_schema_name}'. Provide the singular table schema name.{plural_hint}",
                 subcode=ec.METADATA_ENTITYSET_NOT_FOUND,
             )
         md = items[0]
         es = md.get("EntitySetName")
         if not es:
             raise MetadataError(
-                f"Metadata response missing EntitySetName for logical '{logical}'.",
+                f"Metadata response missing EntitySetName for table schema name '{table_schema_name}'.",
                 subcode=ec.METADATA_ENTITYSET_NAME_MISSING,
             )
         self._logical_to_entityset_cache[cache_key] = es
@@ -730,20 +730,20 @@ def _to_pascal(self, name: str) -> str:
         parts = re.split(r"[^A-Za-z0-9]+", name)
         return "".join(p[:1].upper() + p[1:] for p in parts if p)
 
-    def _get_entity_by_logical_name(
+    def _get_entity_by_table_schema_name(
         self,
-        logical_name: str,
+        table_schema_name: str,
         headers: Optional[Dict[str, str]] = None,
     ) -> Optional[Dict[str, Any]]:
-        """Get entity metadata by LogicalName. Case-insensitive.
+        """Get entity metadata by table schema name. Case-insensitive.
         
         Note: LogicalName is stored lowercase in Dataverse, so we lowercase the input
         for case-insensitive matching. The response includes SchemaName, LogicalName,
         EntitySetName, and MetadataId.
         """
         url = f"{self.api}/EntityDefinitions"
         # LogicalName is stored lowercase, so we lowercase the input for lookup
-        logical_lower = logical_name.lower()
+        logical_lower = table_schema_name.lower()
         logical_escaped = self._escape_odata_quotes(logical_lower)
         params = {
             "$select": "MetadataId,LogicalName,SchemaName,EntitySetName",
@@ -777,7 +777,7 @@ def _create_entity(
         if solution_unique_name:
             params = {"SolutionUniqueName": solution_unique_name}
         self._request("post", url, json=payload, params=params)
-        ent = self._get_entity_by_logical_name(
+        ent = self._get_entity_by_table_schema_name(
             table_schema_name,
             headers={"Consistency": "Strong"},
         )
@@ -1171,7 +1171,7 @@ def _get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
         dict | None
             Metadata summary or ``None`` if not found.
         """
-        ent = self._get_entity_by_logical_name(table_schema_name)
+        ent = self._get_entity_by_table_schema_name(table_schema_name)
         if not ent:
             return None
         return {
@@ -1193,7 +1193,7 @@ def _list_tables(self) -> List[Dict[str, Any]]:
 
     def _delete_table(self, table_schema_name: str) -> None:
         """Delete a table by SchemaName. Case-insensitive."""
-        ent = self._get_entity_by_logical_name(table_schema_name)
+        ent = self._get_entity_by_table_schema_name(table_schema_name)
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{table_schema_name}' not found.",
@@ -1215,7 +1215,7 @@ def _create_table(
         The server will determine the LogicalName automatically (usually lowercased SchemaName).
         """
         # Check if table already exists (case-insensitive)
-        ent = self._get_entity_by_logical_name(table_schema_name)
+        ent = self._get_entity_by_table_schema_name(table_schema_name)
         if ent:
             raise MetadataError(
                 f"Table '{table_schema_name}' already exists.",
@@ -1270,7 +1270,7 @@ def _create_columns(
         if not isinstance(columns, dict) or not columns:
             raise TypeError("columns must be a non-empty dict[name -> type]")
 
-        ent = self._get_entity_by_logical_name(table_schema_name)
+        ent = self._get_entity_by_table_schema_name(table_schema_name)
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{table_schema_name}' not found.",
@@ -1316,7 +1316,7 @@ def _delete_columns(
             if not isinstance(name, str) or not name.strip():
                 raise ValueError("column names must be non-empty strings")
 
-        ent = self._get_entity_by_logical_name(table_schema_name)
+        ent = self._get_entity_by_table_schema_name(table_schema_name)
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{table_schema_name}' not found.",

tests/unit/data/test_logical_crud.py

@@ -38,7 +38,7 @@ class TestableClient(ODataClient):
     def __init__(self, responses):
         super().__init__(DummyAuth(), "https://org.example", None)
         self._http = DummyHTTPClient(responses)
-    def _convert_labels_to_ints(self, logical_name, record):  # pragma: no cover - test shim
+    def _convert_labels_to_ints(self, table_schema_name, record):  # pragma: no cover - test shim
         return record
 
 # Helper metadata response for logical name resolution
@@ -116,7 +116,7 @@ def test_get_multiple_paging():
     assert pages == [[{"accountid": "1"}], [{"accountid": "2"}]]
 
 
-def test_unknown_logical_name_raises():
+def test_unknown_table_schema_name_raises():
     responses = [
         (200, {}, {"value": []}),  # metadata lookup returns empty
     ]