docstring merge

tpellissier · tpellissier · commit d861410bda9b · 2025-11-14T00:53:52.000-08:00
diff --git a/README.md b/README.md
@@ -100,7 +100,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 |---------|-------------|
 | **DataverseClient** | Main entry point for all operations with environment connection |
 | **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) |  
+| **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 |
diff --git a/examples/advanced/file_upload.py b/examples/advanced/file_upload.py
@@ -166,7 +166,6 @@ def backoff(op, *, delays=(0,2,5,10), retry_status=(400,403,404,409,412,429,500,
 
 # --------------------------- Table ensure ---------------------------
 TABLE_SCHEMA_NAME = "new_FileSample"
-# If user wants new customization prefix value / naming, adjust above.
 
 def ensure_table():
     # Check by schema
diff --git a/src/PowerPlatform/Dataverse/client.py b/src/PowerPlatform/Dataverse/client.py
@@ -104,7 +104,7 @@ def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dic
         """
         Create one or more records by table name.
 
-        :param table_schema_name: Table schema name (e.g. ``"account"``, ``"contact"``, or ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"account"``, ``"contact"``, or ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param records: A single record dictionary or a list of record dictionaries.
             Each dictionary should contain column schema names as keys.
@@ -157,7 +157,7 @@ def update(self, table_schema_name: str, ids: Union[str, List[str]], changes: Un
         2. Broadcast update: ``update("account", [id1, id2], {"status": 1})`` - applies same changes to all IDs
         3. Paired updates: ``update("account", [id1, id2], [changes1, changes2])`` - one-to-one mapping
 
-        :param table_schema_name:  Table schema name (e.g. ``"account"`` or ``"new_MyTestTable"``).
+        :param table_schema_name:  Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param ids: Single GUID string or list of GUID strings to update.
         :type ids: ``str`` or ``list[str]``
@@ -210,7 +210,7 @@ def delete(
         """
         Delete one or more records by GUID.
 
-        :param table_schema_name: Table schema name (e.g. ``"account"`` or ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param ids: Single GUID string or list of GUID strings to delete.
         :type ids: ``str`` or ``list[str]``
@@ -266,19 +266,19 @@ def get(
         When ``record_id`` is provided, returns a single record dictionary.
         When ``record_id`` is None, returns a generator yielding batches of records.
 
-        :param table_schema_name: Table schema name (e.g. ``"account"`` or ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
         :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 case-insensitive and automatically lowercased (e.g. ``["new_Title", "new_Amount"]`` becomes ``"new_title,new_amount"``).
         :type select: ``list[str]`` or ``None``
-        :param filter: Optional OData filter string, e.g. ``"name eq 'Contoso'"`` or ``"new_quantity gt 5"``. **IMPORTANT: Column names in filter expressions must use exact lowercase logical names** (e.g. ``"new_quantity"``, not ``"new_Quantity"``). The filter string is passed directly to the Dataverse Web API without transformation.
+        :param filter: Optional OData filter string, e.g. ``"name eq 'Contoso'"`` or ``"new_quantity gt 5"``. Column names in filter expressions must use exact lowercase logical names (e.g. ``"new_quantity"``, not ``"new_Quantity"``). The filter string is passed directly to the Dataverse Web API without transformation.
         :type filter: ``str`` or ``None``
         :param orderby: Optional list of attributes to sort by, e.g. ``["name asc", "createdon desc"]``. Column names are automatically lowercased.
         :type orderby: ``list[str]`` or ``None``
         :param top: Optional maximum number of records to return.
         :type top: ``int`` or ``None``
-        :param expand: Optional list of navigation properties to expand, e.g. ``["primarycontactid"]``. **IMPORTANT: Navigation property names are case-sensitive and must match the server-defined  names exactly.**. These are NOT automatically transformed. Consult entity metadata for correct casing.
+        :param expand: Optional list of navigation properties to expand, e.g. ``["primarycontactid"]``. Navigation property names are case-sensitive and must match the server-defined  names exactly. These are NOT automatically transformed. Consult entity metadata for correct casing.
         :type expand: ``list[str]`` or ``None``
         :param page_size: Optional number of records per page for pagination.
         :type page_size: ``int`` or ``None``
@@ -386,7 +386,7 @@ def get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
         """
         Get basic metadata for a table if it exists.
 
-        :param table_schema_name: Table schema name (e.g. ``"new_MyTestTable"`` or ``"account"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"`` or ``"account"``).
         :type table_schema_name: ``str``
 
         :return: Dictionary containing table metadata with keys ``table_schema_name``,
@@ -414,7 +414,7 @@ def create_table(
         """
         Create a simple custom table with specified columns.
 
-        :param table_schema_name: Table schema name with customization prefix value (e.g. ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table with customization prefix value (e.g. ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param columns: Dictionary mapping column names (with customization prefix value) to their types. All custom column names must include the customization prefix value (e.g. ``"new_Title"``).
             Supported types:
@@ -431,7 +431,7 @@ class ItemStatus(IntEnum):
                           1036: {"Active": "Actif", "Inactive": "Inactif"}
                       }
 
-        :type schema: dict[str, Any]
+        :type columns: dict[str, Any]
         :param solution_unique_name: Optional solution unique name that should own the new table. When omitted the table is created in the default solution.
         :type solution_unique_name: ``str`` or ``None``
         :param primary_column_schema_name: Optional primary name column schema name with customization prefix value (e.g. ``"new_MyTestTable"``). If not provided, defaults to ``"{customization prefix value}_Name"``.
@@ -483,7 +483,7 @@ def delete_table(self, table_schema_name: str) -> None:
         """
         Delete a custom table by name.
 
-        :param table_schema_name: Table schema name (e.g. ``"new_MyTestTable"`` or ``"account"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"`` or ``"account"``).
         :type table_schema_name: ``str``
 
         :raises ~PowerPlatform.Dataverse.core.errors.MetadataError: If the table does not exist or deletion fails.
@@ -523,7 +523,7 @@ def create_columns(
         """
         Create one or more columns on an existing table using a schema-style mapping.
 
-        :param table_schema_name: Table schema name (e.g. ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param columns: Mapping of column schema names (with customization prefix value) to supported types. All custom column names must include the customization prefix value** (e.g. ``"new_Notes"``). Primitive types include
             ``string``, ``int``, ``decimal``, ``float``, ``datetime``, and ``bool``. Enum subclasses (IntEnum preferred)
@@ -556,7 +556,7 @@ def delete_columns(
         """
         Delete one or more columns from a table.
 
-        :param table_schema_name: Table schema name (e.g. ``"new_MyTestTable"``).
+        :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"``).
         :type table_schema_name: ``str``
         :param columns: Column name or list of column names to remove. Must include customization prefix value (e.g. ``"new_TestColumn"``).
         :type columns: ``str`` | ``list[str]``
@@ -590,7 +590,7 @@ def upload_file(
         """
         Upload a file to a Dataverse file column.
 
-        :param table_schema_name: Table schema name, e.g. ``"account"`` or ``"new_MyTestTable"``.
+        :param table_schema_name: Schema name of the table, e.g. ``"account"`` or ``"new_MyTestTable"``.
         :type table_schema_name: ``str``
         :param record_id: GUID of the target record.
         :type record_id: ``str``
diff --git a/src/PowerPlatform/Dataverse/data/odata.py b/src/PowerPlatform/Dataverse/data/odata.py
@@ -178,7 +178,7 @@ def _create(self, entity_set: str, table_schema_name: str, record: Dict[str, Any
 
         :param entity_set: Resolved entity set (plural) name.
         :type entity_set: ``str``
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param record: Attribute payload mapped by logical column names.
         :type record: ``dict[str, Any]``
@@ -215,7 +215,7 @@ def _create_multiple(self, entity_set: str, table_schema_name: str, records: Lis
 
         :param entity_set: Resolved entity set (plural) name.
         :type entity_set: ``str``
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param records: Payload dictionaries mapped by column schema names.
         :type records: ``list[dict[str, Any]]``
@@ -291,7 +291,7 @@ def _primary_id_attr(self, table_schema_name: str) -> str:
     def _update_by_ids(self, table_schema_name: str, ids: List[str], changes: Union[Dict[str, Any], List[Dict[str, Any]]]) -> None:
         """Update many records by GUID list using the collection-bound ``UpdateMultiple`` action.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param ids: GUIDs of target records.
         :type ids: ``list[str]``
@@ -413,7 +413,7 @@ def esc(match):
     def _update(self, table_schema_name: str, key: str, data: Dict[str, Any]) -> None:
         """Update an existing record by GUID.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param key: Record GUID (with or without parentheses).
         :type key: ``str``
@@ -434,7 +434,7 @@ def _update_multiple(self, entity_set: str, table_schema_name: str, records: Lis
 
         :param entity_set: Resolved entity set (plural) name.
         :type entity_set: ``str``
-        :param table_schema_name: Table schema name, e.g. "new_MyTestTable".
+        :param table_schema_name: Schema name of the table, e.g. "new_MyTestTable".
         :type table_schema_name: ``str``
         :param records: List of patch dictionaries. Each must include the true primary key attribute (e.g. ``accountid``) and one or more fields to update.
         :type records: ``list[dict[str, Any]]``
@@ -475,7 +475,7 @@ def _update_multiple(self, entity_set: str, table_schema_name: str, records: Lis
     def _delete(self, table_schema_name: str, key: str) -> None:
         """Delete a record by GUID.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param key: Record GUID (with or without parentheses)
         :type key: ``str``
@@ -490,7 +490,7 @@ def _delete(self, table_schema_name: str, key: str) -> None:
     def _get(self, table_schema_name: str, key: str, select: Optional[str] = None) -> Dict[str, Any]:
         """Retrieve a single record.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param key: Record GUID (with or without parentheses).
         :type key: ``str``
@@ -521,17 +521,17 @@ def _get_multiple(
     ) -> Iterable[List[Dict[str, Any]]]:
         """Iterate records from an entity set, yielding one page (list of dicts) at a time.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param select: Columns to include (``$select``) or ``None``. Column names are automatically lowercased.
         :type select: ``list[str]`` | ``None``
-        :param filter: OData ``$filter`` expression or ``None``. IMPORTANT: This is passed as-is without transformation. Users must provide lowercase logical column names (e.g., "statecode eq 0").
+        :param filter: OData ``$filter`` expression or ``None``. This is passed as-is without transformation. Users must provide lowercase logical column names (e.g., "statecode eq 0").
         :type filter: ``str`` | ``None``
         :param orderby: Order expressions (``$orderby``) or ``None``. Column names are automatically lowercased.
         :type orderby: ``list[str]`` | ``None``
         :param top: Max total records (applied on first request as ``$top``) or ``None``.
         :type top: ``int`` | ``None``
-        :param expand: Navigation properties to expand (``$expand``) or ``None``. IMPORTANT: These are case-sensitive and passed as-is. Users must provide exact navigation property names from entity metadata.
+        :param expand: Navigation properties to expand (``$expand``) or ``None``. These are case-sensitive and passed as-is. Users must provide exact navigation property names from entity metadata.
         :type expand: ``list[str]`` | ``None``
         :param page_size: Per-page size hint via ``Prefer: odata.maxpagesize``.
         :type page_size: ``int`` | ``None``
@@ -1147,7 +1147,7 @@ def _attribute_payload(self, column_schema_name: str, dtype: Any, *, is_primary_
     def _get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
         """Return basic metadata for a custom table if it exists.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
 
         :return: Metadata summary or ``None`` if not found.
@@ -1180,9 +1180,9 @@ def _list_tables(self) -> List[Dict[str, Any]]:
         return r.json().get("value", [])
 
     def _delete_table(self, table_schema_name: str) -> None:
-        """Delete a table by SchemaName. Case-insensitive.
+        """Delete a table by schema name.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
 
         :return: ``None``
@@ -1210,7 +1210,7 @@ def _create_table(
     ) -> Dict[str, Any]:
         """Create a custom table with specified columns.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param schema: Mapping of column name -> type spec (``str`` or ``Enum`` subclass).
         :type schema: ``dict[str, Any]``
@@ -1281,7 +1281,7 @@ def _create_columns(
     ) -> List[str]:
         """Create new columns on an existing table.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param columns: Mapping of column schema name -> type spec (``str`` or ``Enum`` subclass).
         :type columns: ``dict[str, Any]``
@@ -1333,7 +1333,7 @@ def _delete_columns(
     ) -> List[str]:
         """Delete one or more columns from a table.
 
-        :param table_schema_name: Table schema name.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: ``str``
         :param columns: Single column name or list of column names
         :type columns: ``str`` | ``list[str]``
