Add client.files namespace for file upload operations

- Create FileOperations class with upload() method in operations/files.py
- Deprecate client.upload_file() with DeprecationWarning pointing to
  client.files.upload()
- Update file_upload example, README, and both SKILL files
- Add namespace delegation tests and deprecation test

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

Author: tpellissier

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -21,6 +21,7 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - `client.records` -- CRUD and OData queries
 - `client.query` -- query and search operations
 - `client.tables` -- table metadata, columns, and relationships
+- `client.files` -- file upload operations
 
 ### Bulk Operations
 The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `update()` for automatic bulk processing, for `delete()`, set `use_bulk_delete` when passing lists to use bulk operation
@@ -267,11 +268,11 @@ client.tables.delete_relationship(result["relationship_id"])
 
 ```python
 # Upload file to a file column
-client.upload_file(
-    table_schema_name="account",
+client.files.upload(
+    table="account",
     record_id=account_id,
-    file_name_attribute="new_Document",  # If the file column doesn't exist, it will be created automatically
-    path="/path/to/document.pdf"
+    file_column="new_Document",  # If the file column doesn't exist, it will be created automatically
+    path="/path/to/document.pdf",
 )
 ```
 

README.md

@@ -112,7 +112,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 | Concept | Description |
 |---------|-------------|
 | **DataverseClient** | Main entry point; provides `records`, `query`, and `tables` namespaces |
-| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), and `client.tables` (metadata) |
+| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), `client.tables` (metadata), and `client.files` (file uploads) |
 | **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 |
@@ -326,11 +326,11 @@ result = client.tables.create_lookup_field(
 
 ```python
 # Upload a file to a record
-client.upload_file(
-    table_schema_name="account",
-    record_id=account_id,
-    file_name_attribute="new_Document",  # If the file column doesn't exist, it will be created automatically
-    path="/path/to/document.pdf"
+client.files.upload(
+    "account",
+    account_id,
+    "new_Document",  # If the file column doesn't exist, it will be created automatically
+    "/path/to/document.pdf",
 )
 ```
 

examples/advanced/file_upload.py

@@ -248,7 +248,7 @@ def get_dataset_info(file_path: Path):
     try:
         DATASET_FILE, small_file_size, src_hash = get_dataset_info(_GENERATED_TEST_FILE)
         backoff(
-            lambda: client.upload_file(
+            lambda: client.files.upload(
                 table_schema_name,
                 record_id,
                 small_file_attr_schema,
@@ -282,7 +282,7 @@ def get_dataset_info(file_path: Path):
         print("Small single-request upload demo - REPLACE with 8MB file:")
         replacement_file, replace_size_small, replace_hash_small = get_dataset_info(_GENERATED_TEST_FILE_8MB)
         backoff(
-            lambda: client.upload_file(
+            lambda: client.files.upload(
                 table_schema_name,
                 record_id,
                 small_file_attr_schema,
@@ -320,7 +320,7 @@ def get_dataset_info(file_path: Path):
     try:
         DATASET_FILE, src_size_chunk, src_hash_chunk = get_dataset_info(_GENERATED_TEST_FILE)
         backoff(
-            lambda: client.upload_file(
+            lambda: client.files.upload(
                 table_schema_name,
                 record_id,
                 chunk_file_attr_schema,
@@ -351,7 +351,7 @@ def get_dataset_info(file_path: Path):
         print("Streaming chunk upload demo - REPLACE with 8MB file:")
         replacement_file, replace_size_chunk, replace_hash_chunk = get_dataset_info(_GENERATED_TEST_FILE_8MB)
         backoff(
-            lambda: client.upload_file(
+            lambda: client.files.upload(
                 table_schema_name,
                 record_id,
                 chunk_file_attr_schema,

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -21,6 +21,7 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - `client.records` -- CRUD and OData queries
 - `client.query` -- query and search operations
 - `client.tables` -- table metadata, columns, and relationships
+- `client.files` -- file upload operations
 
 ### Bulk Operations
 The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `update()` for automatic bulk processing, for `delete()`, set `use_bulk_delete` when passing lists to use bulk operation
@@ -267,11 +268,11 @@ client.tables.delete_relationship(result["relationship_id"])
 
 ```python
 # Upload file to a file column
-client.upload_file(
-    table_schema_name="account",
+client.files.upload(
+    table="account",
     record_id=account_id,
-    file_name_attribute="new_Document",  # If the file column doesn't exist, it will be created automatically
-    path="/path/to/document.pdf"
+    file_column="new_Document",  # If the file column doesn't exist, it will be created automatically
+    path="/path/to/document.pdf",
 )
 ```
 

src/PowerPlatform/Dataverse/client.py

@@ -14,6 +14,7 @@
 from .data._odata import _ODataClient
 from .operations.records import RecordOperations
 from .operations.query import QueryOperations
+from .operations.files import FileOperations
 from .operations.tables import TableOperations
 
 
@@ -56,6 +57,7 @@ class DataverseClient:
     - ``client.records`` -- create, update, delete, and get records (single or paginated queries)
     - ``client.query`` -- query and search operations
     - ``client.tables`` -- table and column metadata management
+    - ``client.files`` -- file upload operations
 
     Example:
         Create a client and perform basic operations::
@@ -101,6 +103,7 @@ def __init__(
         self.records = RecordOperations(self)
         self.query = QueryOperations(self)
         self.tables = TableOperations(self)
+        self.files = FileOperations(self)
 
     def _get_odata(self) -> _ODataClient:
         """
@@ -665,67 +668,41 @@ def upload_file(
         if_none_match: bool = True,
     ) -> None:
         """
+        .. note::
+            Deprecated. Use :meth:`~PowerPlatform.Dataverse.operations.files.FileOperations.upload` instead.
+
         Upload a file to a Dataverse file column.
 
-        :param table_schema_name: Schema name of the table, e.g. ``"account"`` or ``"new_MyTestTable"``.
+        :param table_schema_name: Schema name of the table.
         :type table_schema_name: :class:`str`
         :param record_id: GUID of the target record.
         :type record_id: :class:`str`
-        :param file_name_attribute: Schema name of the file column attribute (e.g., ``"new_Document"``). If the column doesn't exist, it will be created automatically.
+        :param file_name_attribute: Schema name of the file column attribute.
         :type file_name_attribute: :class:`str`
-        :param path: Local filesystem path to the file. The stored filename will be
-            the basename of this path.
+        :param path: Local filesystem path to the file.
         :type path: :class:`str`
         :param mode: Upload strategy: ``"auto"`` (default), ``"small"``, or ``"chunk"``.
-            Auto mode selects small or chunked upload based on file size.
         :type mode: :class:`str` or None
-        :param mime_type: Explicit MIME type to store with the file (e.g. ``"application/pdf"``).
-            If not provided, the MIME type may be inferred from the file extension.
+        :param mime_type: Explicit MIME type to store with the file.
         :type mime_type: :class:`str` or None
-        :param if_none_match: When True (default), sends ``If-None-Match: null`` header to only
-            succeed if the column is currently empty. Set False to always overwrite using
-            ``If-Match: *``. Used for small and chunk modes only.
+        :param if_none_match: When True (default), only succeed if the column is
+            currently empty.
         :type if_none_match: :class:`bool`
-
-        :raises ~PowerPlatform.Dataverse.core.errors.HttpError: If the upload fails or the file column is not empty
-            when ``if_none_match=True``.
-        :raises FileNotFoundError: If the specified file path does not exist.
-
-        .. note::
-            Large files are automatically chunked to avoid request size limits. The chunk mode performs multiple requests with resumable upload support.
-
-        Example:
-            Upload a PDF file::
-
-                client.upload_file(
-                    table_schema_name="account",
-                    record_id=account_id,
-                    file_name_attribute="new_Contract",
-                    path="/path/to/contract.pdf",
-                    mime_type="application/pdf"
-                )
-
-            Upload with auto mode selection::
-
-                client.upload_file(
-                    table_schema_name="email",
-                    record_id=email_id,
-                    file_name_attribute="new_Attachment",
-                    path="/path/to/large_file.zip",
-                    mode="auto"
-                )
         """
-        with self._scoped_odata() as od:
-            od._upload_file(
-                table_schema_name,
-                record_id,
-                file_name_attribute,
-                path,
-                mode=mode,
-                mime_type=mime_type,
-                if_none_match=if_none_match,
-            )
-            return None
+        warnings.warn(
+            "client.upload_file() is deprecated. Use client.files.upload() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.files.upload(
+            table_schema_name,
+            record_id,
+            file_name_attribute,
+            path,
+            mode=mode,
+            mime_type=mime_type,
+            if_none_match=if_none_match,
+        )
 
     # Cache utilities
     def flush_cache(self, kind) -> int:

src/PowerPlatform/Dataverse/operations/files.py

@@ -0,0 +1,114 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""File operations namespace for the Dataverse SDK."""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import DataverseClient
+
+
+__all__ = ["FileOperations"]
+
+
+class FileOperations:
+    """Namespace for file operations.
+
+    Accessed via ``client.files``. Provides file upload operations for
+    Dataverse file columns.
+
+    :param client: The parent :class:`~PowerPlatform.Dataverse.client.DataverseClient` instance.
+    :type client: ~PowerPlatform.Dataverse.client.DataverseClient
+
+    Example::
+
+        client = DataverseClient(base_url, credential)
+
+        client.files.upload(
+            "account", account_id, "new_Document", "/path/to/file.pdf"
+        )
+    """
+
+    def __init__(self, client: DataverseClient) -> None:
+        self._client = client
+
+    # ----------------------------------------------------------------- upload
+
+    def upload(
+        self,
+        table: str,
+        record_id: str,
+        file_column: str,
+        path: str,
+        *,
+        mode: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        if_none_match: bool = True,
+    ) -> None:
+        """Upload a file to a Dataverse file column.
+
+        :param table: Schema name of the table (e.g. ``"account"`` or
+            ``"new_MyTestTable"``).
+        :type table: :class:`str`
+        :param record_id: GUID of the target record.
+        :type record_id: :class:`str`
+        :param file_column: Schema name of the file column attribute (e.g.,
+            ``"new_Document"``). If the column doesn't exist, it will be
+            created automatically.
+        :type file_column: :class:`str`
+        :param path: Local filesystem path to the file. The stored filename
+            will be the basename of this path.
+        :type path: :class:`str`
+        :param mode: Upload strategy: ``"auto"`` (default), ``"small"``, or
+            ``"chunk"``. Auto mode selects small or chunked upload based on
+            file size.
+        :type mode: :class:`str` or None
+        :param mime_type: Explicit MIME type to store with the file (e.g.
+            ``"application/pdf"``). If not provided, the MIME type may be
+            inferred from the file extension.
+        :type mime_type: :class:`str` or None
+        :param if_none_match: When True (default), sends
+            ``If-None-Match: null`` header to only succeed if the column is
+            currently empty. Set False to always overwrite using
+            ``If-Match: *``.
+        :type if_none_match: :class:`bool`
+
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the upload fails or the file column is not empty when
+            ``if_none_match=True``.
+        :raises FileNotFoundError: If the specified file path does not exist.
+
+        Example:
+            Upload a PDF file::
+
+                client.files.upload(
+                    "account",
+                    account_id,
+                    "new_Contract",
+                    "/path/to/contract.pdf",
+                    mime_type="application/pdf",
+                )
+
+            Upload with auto mode selection::
+
+                client.files.upload(
+                    "email",
+                    email_id,
+                    "new_Attachment",
+                    "/path/to/large_file.zip",
+                )
+        """
+        with self._client._scoped_odata() as od:
+            od._upload_file(
+                table,
+                record_id,
+                file_column,
+                path,
+                mode=mode,
+                mime_type=mime_type,
+                if_none_match=if_none_match,
+            )
+        return None

tests/unit/test_client_deprecations.py

@@ -264,6 +264,25 @@ def test_delete_columns_warns(self):
         )
         self.assertEqual(result, ["new_Notes", "new_Active"])
 
+    # ----------------------------------------------------------- upload_file
+
+    def test_upload_file_warns(self):
+        """client.upload_file() emits a DeprecationWarning and delegates
+        to files.upload.
+        """
+        with self.assertWarns(DeprecationWarning):
+            self.client.upload_file("account", "guid-1", "new_Document", "/path/to/file.pdf")
+
+        self.client._odata._upload_file.assert_called_once_with(
+            "account",
+            "guid-1",
+            "new_Document",
+            "/path/to/file.pdf",
+            mode=None,
+            mime_type=None,
+            if_none_match=True,
+        )
+
 
 if __name__ == "__main__":
     unittest.main()