feat: Support upload with preflight check (box/box-codegen#676) (#515)

box-sdk-build · web-flow · commit bb4597e40d49 · 2025-03-17T17:17:09.000+01:00
diff --git a/.codegen.json b/.codegen.json
@@ -1 +1 @@
-{ "engineHash": "3d68c3f", "specHash": "c303afc", "version": "1.12.0" }
+{ "engineHash": "0f745bf", "specHash": "c303afc", "version": "1.12.0" }
diff --git a/box_sdk_gen/managers/avatars.py b/box_sdk_gen/managers/avatars.py
@@ -124,9 +124,9 @@ def create_user_avatar(
                 multipart_data=[
                     MultipartItem(
                         part_name='pic',
-                        file_stream=request_body.get('pic'),
-                        file_name=request_body.get('pic_file_name'),
-                        content_type=request_body.get('pic_content_type'),
+                        file_stream=pic,
+                        file_name=pic_file_name,
+                        content_type=pic_content_type,
                     )
                 ],
                 content_type='multipart/form-data',
diff --git a/box_sdk_gen/managers/uploads.py b/box_sdk_gen/managers/uploads.py
@@ -117,6 +117,52 @@ def __init__(
         self.content_modified_at = content_modified_at
 
 
+class UploadWithPreflightCheckAttributesParentField(BaseObject):
+    def __init__(self, id: str, **kwargs):
+        """
+                :param id: The id of the parent folder. Use
+        `0` for the user's root folder.
+                :type id: str
+        """
+        super().__init__(**kwargs)
+        self.id = id
+
+
+class UploadWithPreflightCheckAttributes(BaseObject):
+    def __init__(
+        self,
+        name: str,
+        parent: UploadWithPreflightCheckAttributesParentField,
+        size: int,
+        *,
+        content_created_at: Optional[DateTime] = None,
+        content_modified_at: Optional[DateTime] = None,
+        **kwargs
+    ):
+        """
+                :param name: The name of the file
+                :type name: str
+                :param parent: The parent folder to upload the file to
+                :type parent: UploadWithPreflightCheckAttributesParentField
+                :param size: The size of the file in bytes
+                :type size: int
+                :param content_created_at: Defines the time the file was originally created at.
+
+        If not set, the upload time will be used., defaults to None
+                :type content_created_at: Optional[DateTime], optional
+                :param content_modified_at: Defines the time the file was last modified at.
+
+        If not set, the upload time will be used., defaults to None
+                :type content_modified_at: Optional[DateTime], optional
+        """
+        super().__init__(**kwargs)
+        self.name = name
+        self.parent = parent
+        self.size = size
+        self.content_created_at = content_created_at
+        self.content_modified_at = content_modified_at
+
+
 class UploadsManager:
     def __init__(
         self,
@@ -246,15 +292,12 @@ def upload_file_version(
                 params=query_params_map,
                 headers=headers_map,
                 multipart_data=[
-                    MultipartItem(
-                        part_name='attributes',
-                        data=serialize(request_body.get('attributes')),
-                    ),
+                    MultipartItem(part_name='attributes', data=serialize(attributes)),
                     MultipartItem(
                         part_name='file',
-                        file_stream=request_body.get('file'),
-                        file_name=request_body.get('file_file_name'),
-                        content_type=request_body.get('file_content_type'),
+                        file_stream=file,
+                        file_name=file_file_name,
+                        content_type=file_content_type,
                     ),
                 ],
                 content_type='multipart/form-data',
@@ -394,15 +437,98 @@ def upload_file(
                 params=query_params_map,
                 headers=headers_map,
                 multipart_data=[
+                    MultipartItem(part_name='attributes', data=serialize(attributes)),
                     MultipartItem(
-                        part_name='attributes',
-                        data=serialize(request_body.get('attributes')),
+                        part_name='file',
+                        file_stream=file,
+                        file_name=file_file_name,
+                        content_type=file_content_type,
                     ),
+                ],
+                content_type='multipart/form-data',
+                response_format=ResponseFormat.JSON,
+                auth=self.auth,
+                network_session=self.network_session,
+            )
+        )
+        return deserialize(response.data, Files)
+
+    def upload_with_preflight_check(
+        self,
+        attributes: UploadWithPreflightCheckAttributes,
+        file: ByteStream,
+        *,
+        file_file_name: Optional[str] = None,
+        file_content_type: Optional[str] = None,
+        fields: Optional[List[str]] = None,
+        content_md_5: Optional[str] = None,
+        extra_headers: Optional[Dict[str, Optional[str]]] = None
+    ) -> Files:
+        """
+                 Upload a file with a preflight check
+                :param file: The content of the file to upload to Box.
+
+        <Message warning>
+
+          The `attributes` part of the body must come **before** the
+          `file` part. Requests that do not follow this format when
+          uploading the file will receive a HTTP `400` error with a
+          `metadata_after_file_contents` error code.
+
+        </Message>
+                :type file: ByteStream
+                :param fields: A comma-separated list of attributes to include in the
+        response. This can be used to request fields that are
+        not normally returned in a standard response.
+
+        Be aware that specifying this parameter will have the
+        effect that none of the standard fields are returned in
+        the response unless explicitly specified, instead only
+        fields for the mini representation are returned, additional
+        to the fields requested., defaults to None
+                :type fields: Optional[List[str]], optional
+                :param content_md_5: An optional header containing the SHA1 hash of the file to
+        ensure that the file was not corrupted in transit., defaults to None
+                :type content_md_5: Optional[str], optional
+                :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None
+                :type extra_headers: Optional[Dict[str, Optional[str]]], optional
+        """
+        if extra_headers is None:
+            extra_headers = {}
+        request_body: Dict = {
+            'attributes': attributes,
+            'file': file,
+            'file_file_name': file_file_name,
+            'file_content_type': file_content_type,
+        }
+        query_params_map: Dict[str, str] = prepare_params({'fields': to_string(fields)})
+        headers_map: Dict[str, str] = prepare_params(
+            {'content-md5': to_string(content_md_5), **extra_headers}
+        )
+        preflight_upload_url: UploadUrl = self.preflight_file_upload_check(
+            name=attributes.name,
+            size=attributes.size,
+            parent=PreflightFileUploadCheckParent(id=attributes.parent.id),
+            extra_headers=extra_headers,
+        )
+        if (
+            preflight_upload_url.upload_url == None
+            or not 'http' in preflight_upload_url.upload_url
+        ):
+            raise BoxSDKError(message='Unable to get preflight upload URL')
+        response: FetchResponse = self.network_session.network_client.fetch(
+            FetchOptions(
+                url=preflight_upload_url.upload_url,
+                method='POST',
+                params=query_params_map,
+                headers=headers_map,
+                multipart_data=[
+                    MultipartItem(part_name='attributes', data=serialize(attributes)),
                     MultipartItem(
                         part_name='file',
-                        file_stream=request_body.get('file'),
-                        file_name=request_body.get('file_file_name'),
-                        content_type=request_body.get('file_content_type'),
+                        file_stream=file,
+                        file_name=file_file_name,
+                        content_type=file_content_type,
                     ),
                 ],
                 content_type='multipart/form-data',
diff --git a/box_sdk_gen/managers/zip_downloads.py b/box_sdk_gen/managers/zip_downloads.py
@@ -311,9 +311,7 @@ def download_zip(
             extra_headers = {}
         request_body: Dict = {'items': items, 'download_file_name': download_file_name}
         zip_download_session: ZipDownload = self.create_zip_download(
-            request_body.get('items'),
-            download_file_name=request_body.get('download_file_name'),
-            extra_headers=extra_headers,
+            items, download_file_name=download_file_name, extra_headers=extra_headers
         )
         return self.get_zip_download_content(
             zip_download_session.download_url, extra_headers=extra_headers
diff --git a/docs/uploads.md b/docs/uploads.md
@@ -3,6 +3,7 @@
 - [Upload file version](#upload-file-version)
 - [Preflight check before upload](#preflight-check-before-upload)
 - [Upload file](#upload-file)
+- [Upload a file with a preflight check](#upload-a-file-with-a-preflight-check)
 
 ## Upload file version
 
@@ -140,3 +141,41 @@ client.uploads.upload_file(
 This function returns a value of type `Files`.
 
 Returns the new file object in a list.
+
+## Upload a file with a preflight check
+
+Upload a file with a preflight check
+
+This operation is performed by calling function `upload_with_preflight_check`.
+
+```python
+client.uploads.upload_with_preflight_check(
+    UploadWithPreflightCheckAttributes(
+        name=new_file_name,
+        size=-1,
+        parent=UploadWithPreflightCheckAttributesParentField(id="0"),
+    ),
+    file_content_stream,
+)
+```
+
+### Arguments
+
+- attributes `UploadWithPreflightCheckAttributes`
+  -
+- file `ByteStream`
+  - The content of the file to upload to Box. <Message warning> The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. </Message>
+- file_file_name `Optional[str]`
+  -
+- file_content_type `Optional[str]`
+  -
+- fields `Optional[List[str]]`
+  - A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response. Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
+- content_md_5 `Optional[str]`
+  - An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.
+- extra_headers `Optional[Dict[str, Optional[str]]]`
+  - Extra headers that will be included in the HTTP request.
+
+### Returns
+
+This function returns a value of type `Files`.
diff --git a/test/uploads.py b/test/uploads.py
@@ -1,3 +1,5 @@
+import pytest
+
 from box_sdk_gen.internal.utils import ByteStream
 
 from box_sdk_gen.schemas.files import Files
@@ -10,6 +12,10 @@
 
 from box_sdk_gen.managers.uploads import UploadFileVersionAttributes
 
+from box_sdk_gen.managers.uploads import UploadWithPreflightCheckAttributes
+
+from box_sdk_gen.managers.uploads import UploadWithPreflightCheckAttributesParentField
+
 from box_sdk_gen.schemas.upload_url import UploadUrl
 
 from box_sdk_gen.managers.uploads import PreflightFileUploadCheckParent
@@ -48,6 +54,41 @@ def testUploadFileAndFileVersion():
     client.files.delete_file_by_id(new_file_version.id)
 
 
+def testUploadFileWithPreflightCheck():
+    new_file_name: str = get_uuid()
+    file_content_stream: ByteStream = generate_byte_stream(1024 * 1024)
+    with pytest.raises(Exception):
+        client.uploads.upload_with_preflight_check(
+            UploadWithPreflightCheckAttributes(
+                name=new_file_name,
+                size=-1,
+                parent=UploadWithPreflightCheckAttributesParentField(id='0'),
+            ),
+            file_content_stream,
+        )
+    upload_files_with_preflight: Files = client.uploads.upload_with_preflight_check(
+        UploadWithPreflightCheckAttributes(
+            name=new_file_name,
+            size=1024 * 1024,
+            parent=UploadWithPreflightCheckAttributesParentField(id='0'),
+        ),
+        file_content_stream,
+    )
+    file: FileFull = upload_files_with_preflight.entries[0]
+    assert file.name == new_file_name
+    assert file.size == 1024 * 1024
+    with pytest.raises(Exception):
+        client.uploads.upload_with_preflight_check(
+            UploadWithPreflightCheckAttributes(
+                name=new_file_name,
+                size=1024 * 1024,
+                parent=UploadWithPreflightCheckAttributesParentField(id='0'),
+            ),
+            file_content_stream,
+        )
+    client.files.delete_file_by_id(file.id)
+
+
 def testPreflightCheck():
     new_file_name: str = get_uuid()
     preflight_check_result: UploadUrl = client.uploads.preflight_file_upload_check(

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-{ "engineHash": "3d68c3f", "specHash": "c303afc", "version": "1.12.0" }`
	`1`	`+{ "engineHash": "0f745bf", "specHash": "c303afc", "version": "1.12.0" }`