support tuples for files (#33948)

Author: iscai-msft

sdk/core/azure-core/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Support tuple input for files to `azure.core.rest.HttpRequest`  #33948
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/core/azure-core/azure/core/pipeline/transport/_base.py

@@ -76,6 +76,7 @@
 if TYPE_CHECKING:
     # We need a transport to define a pipeline, this "if" avoid a circular import
     from azure.core.pipeline import Pipeline
+    from azure.core.rest._helpers import FileContent
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -249,7 +250,7 @@ def body(self, value: Optional[DataType]) -> None:
         self.data = value
 
     @staticmethod
-    def _format_data(data: Union[str, IO]) -> Union[Tuple[None, str], Tuple[Optional[str], IO, str]]:
+    def _format_data(data: Union[str, IO]) -> Union[Tuple[Optional[str], str], Tuple[Optional[str], FileContent, str]]:
         """Format field data according to whether it is a stream or
         a string for a form-data request.
 

sdk/core/azure-core/azure/core/rest/_helpers.py

@@ -66,7 +66,15 @@
 ParamsType = Mapping[str, Union[PrimitiveData, Sequence[PrimitiveData]]]
 
 FileContent = Union[str, bytes, IO[str], IO[bytes]]
-FileType = Tuple[Optional[str], FileContent]
+
+FileType = Union[
+    # file (or bytes)
+    FileContent,
+    # (filename, file (or bytes))
+    Tuple[Optional[str], FileContent],
+    # (filename, file (or bytes), content_type)
+    Tuple[Optional[str], FileContent, Optional[str]],
+]
 
 FilesType = Union[Mapping[str, FileType], Sequence[Tuple[str, FileType]]]
 
@@ -104,8 +112,9 @@ def set_urlencoded_body(data, has_files):
     return default_headers, body
 
 
-def set_multipart_body(files):
-    formatted_files = {f: _format_data_helper(d) for f, d in files.items() if d is not None}
+def set_multipart_body(files: FilesType):
+    file_items = files.items() if isinstance(files, Mapping) else files
+    formatted_files = {f: _format_data_helper(d) for f, d in file_items if d is not None}
     return {}, formatted_files
 
 

sdk/core/azure-core/azure/core/utils/_pipeline_transport_rest_shared.py

@@ -50,6 +50,7 @@
     from azure.core.pipeline.transport._base import (
         _HttpResponseBase as PipelineTransportHttpResponseBase,
     )
+    from azure.core.rest._helpers import FileType, FileContent
 
 binary_type = str
 
@@ -333,7 +334,7 @@ def parse_responses(response):
     return responses
 
 
-def _format_data_helper(data: Union[str, IO]) -> Union[Tuple[None, str], Tuple[Optional[str], IO, str]]:
+def _format_data_helper(data: "FileType") -> Union[Tuple[Optional[str], str], Tuple[Optional[str], "FileContent", str]]:
     """Helper for _format_data.
 
     Format field data according to whether it is a stream or
@@ -344,16 +345,34 @@ def _format_data_helper(data: Union[str, IO]) -> Union[Tuple[None, str], Tuple[O
     :rtype: tuple[str, IO, str] or tuple[None, str]
     :return: A tuple of (data name, data IO, "application/octet-stream") or (None, data str)
     """
-    if hasattr(data, "read"):
-        data = cast(IO, data)
-        data_name = None
-        try:
-            if data.name[0] != "<" and data.name[-1] != ">":
-                data_name = os.path.basename(data.name)
-        except (AttributeError, TypeError):
-            pass
-        return (data_name, data, "application/octet-stream")
-    return (None, cast(str, data))
+    content_type: Optional[str] = None
+    filename: Optional[str] = None
+    if isinstance(data, tuple):
+        if len(data) == 2:
+            # Filename and file bytes are included
+            filename, file_bytes = cast(Tuple[Optional[str], "FileContent"], data)
+        elif len(data) == 3:
+            # Filename, file object, and content_type are included
+            filename, file_bytes, content_type = cast(Tuple[Optional[str], "FileContent", str], data)
+        else:
+            raise ValueError(
+                "Unexpected data format. Expected file, or tuple of (filename, file_bytes) or "
+                "(filename, file_bytes, content_type)."
+            )
+    else:
+        # here we just get the file content
+        if hasattr(data, "read"):
+            data = cast(IO, data)
+            try:
+                if data.name[0] != "<" and data.name[-1] != ">":
+                    filename = os.path.basename(data.name)
+            except (AttributeError, TypeError):
+                pass
+            content_type = "application/octet-stream"
+        file_bytes = data
+    if content_type:
+        return (filename, file_bytes, content_type)
+    return (filename, cast(str, file_bytes))
 
 
 def _aiohttp_body_helper(

sdk/core/azure-core/tests/test_rest_http_request.py

@@ -515,6 +515,66 @@ def test_stream_input():
     HttpRequest(method="PUT", url="http://www.example.com", content=data_stream)  # ensure we can make this HttpRequest
 
 
+@pytest.fixture
+def filebytes():
+    file_path = os.path.join(os.path.dirname(__file__), "./conftest.py")
+    return open(file_path, "rb")
+
+
+def test_multipart_bytes(filebytes):
+    request = HttpRequest("POST", url="http://example.org", files={"file": filebytes})
+
+    assert request.content == {"file": ("conftest.py", filebytes, "application/octet-stream")}
+
+
+def test_multipart_filename_and_bytes(filebytes):
+    files = ("specifiedFileName", filebytes)
+    request = HttpRequest("POST", url="http://example.org", files={"file": files})
+
+    assert request.content == {"file": ("specifiedFileName", filebytes)}
+
+
+def test_multipart_filename_and_bytes_and_content_type(filebytes):
+    files = ("specifiedFileName", filebytes, "application/json")
+    request = HttpRequest("POST", url="http://example.org", files={"file": files})
+
+    assert request.content == {"file": ("specifiedFileName", filebytes, "application/json")}
+
+
+def test_multipart_incorrect_tuple_entry(filebytes):
+    files = ("specifiedFileName", filebytes, "application/json", "extra")
+    with pytest.raises(ValueError):
+        HttpRequest("POST", url="http://example.org", files={"file": files})
+
+
+def test_multipart_tuple_input_single(filebytes):
+    request = HttpRequest("POST", url="http://example.org", files=[("file", filebytes)])
+
+    assert request.content == {"file": ("conftest.py", filebytes, "application/octet-stream")}
+
+
+def test_multipart_tuple_input_multiple(filebytes):
+    request = HttpRequest("POST", url="http://example.org", files=[("file", filebytes), ("file2", filebytes)])
+
+    assert request.content == {
+        "file": ("conftest.py", filebytes, "application/octet-stream"),
+        "file2": ("conftest.py", filebytes, "application/octet-stream"),
+    }
+
+
+def test_multipart_tuple_input_multiple_with_filename_and_content_type(filebytes):
+    request = HttpRequest(
+        "POST",
+        url="http://example.org",
+        files=[("file", ("first file", filebytes, "image/pdf")), ("file2", ("second file", filebytes, "image/png"))],
+    )
+
+    assert request.content == {
+        "file": ("first file", filebytes, "image/pdf"),
+        "file2": ("second file", filebytes, "image/png"),
+    }
+
+
 # NOTE: For files, we don't allow list of tuples yet, just dict. Will uncomment when we add this capability
 # def test_multipart_multiple_files_single_input_content():
 #     files = [