feat(testing): simulate multipart file upload

docs/changes/4.0.0.rst

@@ -15,7 +15,6 @@ Changes to Supported Platforms
 - CPython 3.11 is now fully supported. (`#2072 <https://github.com/falconry/falcon/issues/2072>`__)
 - End-of-life Python 3.5 & 3.6 are no longer supported. (`#2074 <https://github.com/falconry/falcon/pull/2074>`__)
 
-
 .. towncrier release notes start
 
 Contributors to this Release

falcon/testing/client.py

@@ -22,6 +22,7 @@
 import datetime as dt
 import inspect
 import json as json_module
+import os
 import time
 from typing import Dict
 from typing import Optional
@@ -30,6 +31,10 @@
 import warnings
 import wsgiref.validate
 
+from urllib3.filepost import encode_multipart_formdata
+from urllib3.filepost import RequestField
+
+
 from falcon.asgi_spec import ScopeType
 from falcon.constants import COMBINED_METHODS
 from falcon.constants import MEDIA_JSON
@@ -437,6 +442,7 @@ def simulate_request(
     content_type=None,
     body=None,
     json=None,
+    files=None,
     file_wrapper=None,
     wsgierrors=None,
     params=None,
@@ -528,6 +534,15 @@ def simulate_request(
             overrides `body` and sets the Content-Type header to
             ``'application/json'``, overriding any value specified by either
             the `content_type` or `headers` arguments.
+        files(dict): same as the  files parameter in requests,
+             dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``)
+             for multipart encoding upload.
+            ``file-tuple``: can be a 2-tuple ``('filename', fileobj)``,
+                3-tuple ``('filename', fileobj, 'content_type')``
+                or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``,
+                where ``'content-type'`` is a string defining the content
+                type of the given file and ``custom_headers`` a dict-like
+                object containing additional headers to add for the file.
         file_wrapper (callable): Callable that returns an iterable,
             to be used as the value for *wsgi.file_wrapper* in the
             WSGI environ (default: ``None``). This can be used to test
@@ -575,6 +590,7 @@ def simulate_request(
             content_type=content_type,
             body=body,
             json=json,
+            files=files,
             params=params,
             params_csv=params_csv,
             protocol=protocol,
@@ -598,6 +614,7 @@ def simulate_request(
         headers,
         body,
         json,
+        files,
         extras,
     )
 
@@ -651,6 +668,7 @@ async def _simulate_request_asgi(
     content_type=None,
     body=None,
     json=None,
+    files=None,
     params=None,
     params_csv=True,
     protocol='http',
@@ -736,6 +754,15 @@ async def _simulate_request_asgi(
             overrides `body` and sets the Content-Type header to
             ``'application/json'``, overriding any value specified by either
             the `content_type` or `headers` arguments.
+        files(dict): same as the  files parameter in requests,
+             dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``)
+             for multipart encoding upload.
+            ``file-tuple``: can be a 2-tuple ``('filename', fileobj)``,
+                3-tuple ``('filename', fileobj, 'content_type')``
+                or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``,
+                where ``'content-type'`` is a string defining the content
+                type of the given file and ``custom_headers`` a dict-like
+                object containing additional headers to add for the file.
         host(str): A string to use for the hostname part of the fully
             qualified request URL (default: 'falconframework.org')
         remote_addr (str): A string to use as the remote IP address for the
@@ -774,6 +801,7 @@ async def _simulate_request_asgi(
         headers,
         body,
         json,
+        files,
         extras,
     )
 
@@ -2133,8 +2161,133 @@ async def __aexit__(self, exc_type, exc, tb):
         await self._task_req
 
 
+def _prepare_data_fields(data):
+    """Prepare data  fields for request body.
+
+    Args:
+        data: dict or list of tuples with json data from the request
+
+    Returns: list of 2-tuples (field-name(str), value(bytes)
+
+    """
+    fields = []
+    new_fields = []
+    if data and not isinstance(data, (list, dict)):
+        raise ValueError('Data must not be a list of tuples or dict.')
+    elif data and isinstance(data, dict):
+        fields = list(data.items())
+    elif data:
+        fields = list(data)
+    # Append data to the other multipart parts
+    for field, val in fields:
+        if isinstance(val, str) or not hasattr(val, '__iter__'):
+            val = [val]
+        for v in val:
+            if v:
+                # Don't call str() on bytestrings: in Py3 it all goes wrong.
+                if not isinstance(v, bytes):
+                    v = str(v)
+
+                new_fields.append(
+                    (
+                        field.decode('utf-8') if isinstance(field, bytes) else field,
+                        v.encode('utf-8') if isinstance(v, str) else v,
+                    )
+                )
+    return new_fields
+
+
+def _prepare_files(k, v):
+    """Prepare file attributes for body of request form.
+
+    Args:
+        k: (str), file-name
+        v: fileobj or tuple (filename, data, content_type?, headers?)
+
+    Returns: file_name, file_data, file_content_type, file_header
+
+    """
+    file_content_type = None
+    file_header = None
+    if isinstance(v, (tuple, list)):
+        if len(v) == 2:
+            file_name, file_data = v
+        elif len(v) == 3:
+            file_name, file_data, file_content_type = v
+        else:
+            file_name, file_data, file_content_type, file_header = v
+        if (
+            len(v) >= 3
+            and file_content_type
+            and file_content_type.startswith('multipart/mixed')
+        ):
+            file_data, assigned_type = _encode_files(
+                json_module.loads(file_data.decode())
+            )
+            file_content_type = 'multipart/mixed; ' + (assigned_type.split('; ')[1])
+    else:
+        # if v is not a tuple or iterable it has to be a filelike obj
+        name = getattr(v, 'name', None)
+        if name and isinstance(name, str) and name[0] != '<' and name[-1] != '>':
+            file_name = os.path.basename(name)
+        else:
+            file_name = k
+        file_data = v
+    return file_name, file_data, file_content_type, file_header
+
+
+def _encode_files(files, data=None):
+    """Build the body for a multipart/form-data request.
+
+    Will successfully encode files when passed as a dict or a list of
+    tuples. Order is retained if data is a list of tuples but arbitrary
+    if parameters are supplied as a dict.
+    The tuples may be 2-tuples (filename, fileobj),
+    3-tuples (filename, fileobj, contentype)
+    or 4-tuples (filename, fileobj, contentype, custom_headers).
+    Allows for content_type = ``multipart/mixed`` for submission of nested files"""
+
+    new_fields = _prepare_data_fields(data)
+
+    if not isinstance(files, (dict, list)):
+        raise ValueError('cannot encode objects that are not 2-tuples')
+    elif isinstance(files, dict):
+        files = list(files.items())
+
+    for (k, v) in files:
+        content_disposition = None
+        file_name, file_data, file_content_type, file_header = _prepare_files(k, v)
+
+        if not file_data:
+            continue
+        elif hasattr(file_data, 'read'):
+            fdata = file_data.read()
+        else:
+            fdata = file_data
+        if file_header and 'Content-Disposition' in file_header.keys():
+            content_disposition = file_header['Content-Disposition']
+        rf = RequestField(name=k, filename=file_name, data=fdata, headers=file_header)
+        rf.make_multipart(
+            content_type=file_content_type, content_disposition=content_disposition
+        )
+        new_fields.append(rf)
+
+    body, content_type = encode_multipart_formdata(new_fields)
+
+    return body, content_type
+
+
 def _prepare_sim_args(
-    path, query_string, params, params_csv, content_type, headers, body, json, extras
+    path,
+    query_string,
+    params,
+    params_csv,
+    content_type,
+    headers,
+    body,
+    json,
+    files,
+    extras,
 ):
     if not path.startswith('/'):
         raise ValueError("path must start with '/'")
@@ -2163,7 +2316,12 @@ def _prepare_sim_args(
         headers = headers or {}
         headers['Content-Type'] = content_type
 
-    if json is not None:
+    if files is not None:
+        body, content_type = _encode_files(files, json)
+        headers = headers or {}
+        headers['Content-Type'] = content_type
+
+    elif json is not None:
         body = json_module.dumps(json, ensure_ascii=False)
         headers = headers or {}
         headers['Content-Type'] = MEDIA_JSON

requirements/mintest

@@ -5,3 +5,4 @@ pytest
 pyyaml
 requests
 ujson
+urllib3

requirements/tests

@@ -2,6 +2,7 @@ coverage >= 4.1
 pytest
 pyyaml
 requests
+urllib3
 # TODO(vytas): Check if testtools still brings anything to the table, and
 #   re-enable if/when unittest2 is adjusted to support CPython 3.10.
 testtools; python_version < '3.10'

tests/files/loremipsum.txt

@@ -0,0 +1,11 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Dolor sed viverra ipsum nunc
+aliquet bibendum enim. In massa tempor nec feugiat. Nunc aliquet bibendum enim
+facilisis gravida. Nisl nunc mi ipsum faucibus vitae aliquet nec ullamcorper.
+Amet luctus venenatis lectus magna fringilla. Volutpat maecenas volutpat blandit
+aliquam etiam erat velit scelerisque in. Egestas egestas fringilla phasellus
+faucibus scelerisque eleifend. Sagittis orci a scelerisque purus semper eget
+duis. Nulla pharetra diam sit amet nisl suscipit. Sed adipiscing diam donec
+adipiscing tristique risus nec feugiat in. Fusce ut placerat orci nulla.
+Pharetra vel turpis nunc eget lorem dolor. Tristique senectus et netus et
+malesuada.

tests/test_media_multipart.py

@@ -98,7 +98,6 @@
     b'--boundary--\r\n'
 )
 
-
 EXAMPLES = {
     '5b11af82ab65407ba8cdccf37d2a9c4f': EXAMPLE1,
     '---------------------------1574247108204320607285918568': EXAMPLE2,