From 466e883f987edb3745d86986513f64b169ce99f3 Mon Sep 17 00:00:00 2001 From: box-sdk-build <94016436+box-sdk-build@users.noreply.github.com> Date: Mon, 12 Aug 2024 13:10:37 +0200 Subject: [PATCH] docs: Improve docs for uploads (#254) --- .codegen.json | 2 +- README.md | 2 +- box_sdk_gen/managers/trashed_folders.py | 3 - box_sdk_gen/managers/uploads.py | 6 - box_sdk_gen/schemas/file_or_folder_scope.py | 1 + docs/authentication.md | 2 +- docs/trashed_folders.md | 2 - docs/uploads.md | 143 +++++++++++++++++--- test/ai.py | 2 +- 9 files changed, 126 insertions(+), 37 deletions(-) diff --git a/.codegen.json b/.codegen.json index 0c6f5cde..54e46fd6 100644 --- a/.codegen.json +++ b/.codegen.json @@ -1 +1 @@ -{ "engineHash": "871ac70", "specHash": "d36b9f0", "version": "1.2.0" } +{ "engineHash": "f42fdb0", "specHash": "e50af18", "version": "1.2.0" } diff --git a/README.md b/README.md index 8b5b2fc0..99ca2b49 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Supported Python versions are Python 3.8 and above. To install also extra dependencies required for JWT authentication, use command: ```console -pip install box-sdk-gen[jwt] +pip install "box-sdk-gen[jwt]" ``` # Getting Started diff --git a/box_sdk_gen/managers/trashed_folders.py b/box_sdk_gen/managers/trashed_folders.py index 4a548c06..014dfac1 100644 --- a/box_sdk_gen/managers/trashed_folders.py +++ b/box_sdk_gen/managers/trashed_folders.py @@ -79,9 +79,6 @@ def restore_folder_from_trash( original folder has been deleted. - # Folder locking - - During this operation, part of the file tree will be locked, mainly diff --git a/box_sdk_gen/managers/uploads.py b/box_sdk_gen/managers/uploads.py index bea4a556..be5af706 100644 --- a/box_sdk_gen/managers/uploads.py +++ b/box_sdk_gen/managers/uploads.py @@ -146,9 +146,6 @@ def upload_file_version( using the Chunk Upload APIs. - # Request body order - - The `attributes` part of the body must come **before** the @@ -283,9 +280,6 @@ def upload_file( using the Chunk Upload APIs. - # Request body order - - The `attributes` part of the body must come **before** the diff --git a/box_sdk_gen/schemas/file_or_folder_scope.py b/box_sdk_gen/schemas/file_or_folder_scope.py index 80b8c074..aa5b38bd 100644 --- a/box_sdk_gen/schemas/file_or_folder_scope.py +++ b/box_sdk_gen/schemas/file_or_folder_scope.py @@ -24,6 +24,7 @@ class FileOrFolderScopeScopeField(str, Enum): ITEM_PREVIEW = 'item_preview' ITEM_RENAME = 'item_rename' ITEM_SHARE = 'item_share' + ITEM_UPLOAD = 'item_upload' class FileOrFolderScope(BaseObject): diff --git a/docs/authentication.md b/docs/authentication.md index 6c94449e..006b7356 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -55,7 +55,7 @@ print(f"My user ID is {me.id}") Authenticating with a JWT requires some extra dependencies. To get them, use ``` -pip install box-sdk-gen[jwt] +pip install "box-sdk-gen[jwt]" ``` Before using JWT Auth make sure you set up correctly your Box App. diff --git a/docs/trashed_folders.md b/docs/trashed_folders.md index 93127e20..3cd507b1 100644 --- a/docs/trashed_folders.md +++ b/docs/trashed_folders.md @@ -11,8 +11,6 @@ Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. -# Folder locking - During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. diff --git a/docs/uploads.md b/docs/uploads.md index dc8b7e84..ceba7411 100644 --- a/docs/uploads.md +++ b/docs/uploads.md @@ -1,35 +1,134 @@ -# Uploads +# UploadsManager -Uploads module is used to upload files to Box. It supports uploading files from a readable stream. For now, it only supports uploading small files without chunked upload. +- [Upload file version](#upload-file-version) +- [Upload file](#upload-file) +- [Preflight check before upload](#preflight-check-before-upload) - - +## Upload file version -- [Upload a File](#upload-a-file) +Update a file's content. For file sizes over 50MB we recommend +using the Chunk Upload APIs. - +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. -## Upload a File +This operation is performed by calling function `upload_file_version`. -To upload a small file from a readable stream, call `upload_file` method. -This method returns a `Files` object which contains information about the uploaded files. +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-files-id-content/). - + ```python -from box_sdk_gen import ( - UploadFileAttributes, - UploadFileAttributesParentField, - Files, - File, +client.uploads.upload_file_version( + file.id, UploadFileVersionAttributes(name=file.name), generate_byte_stream(20) ) +``` -attrs = UploadFileAttributes( - name="filename.txt", parent=UploadFileAttributesParentField(id="0") -) -files: Files = client.uploads.upload_file( - attributes=attrs, file=open("filename.txt", "rb") +### Arguments + +- file_id `str` + - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" +- attributes `UploadFileVersionAttributes` + - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. 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. +- file `ByteStream` + - The content of the file to upload to Box. 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. +- 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. +- if_match `Optional[str]` + - Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. +- 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`. + +Returns the new file object in a list. + +## Upload file + +Uploads a small file to Box. For file sizes over 50MB we recommend +using the Chunk Upload APIs. + +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. + +This operation is performed by calling function `upload_file`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-files-content/). + + + +```python +parent_client.uploads.upload_file( + UploadFileAttributes( + name=get_uuid(), parent=UploadFileAttributesParentField(id="0") + ), + generate_byte_stream(1024 * 1024), ) -file: File = files.entries[0] -print(f"File uploaded with id {file.id}, name {file.name}") ``` + +### Arguments + +- attributes `UploadFileAttributes` + - The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. 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. +- file `ByteStream` + - The content of the file to upload to Box. 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. +- 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`. + +Returns the new file object in a list. + +## Preflight check before upload + +Performs a check to verify that a file will be accepted by Box +before you upload the entire file. + +This operation is performed by calling function `preflight_file_upload_check`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/options-files-content/). + +_Currently we don't have an example for calling `preflight_file_upload_check` in integration tests_ + +### Arguments + +- name `Optional[str]` + - The name for the file +- size `Optional[int]` + - The size of the file in bytes +- parent `Optional[PreflightFileUploadCheckParent]` + - +- 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 `UploadUrl`. + +If the check passed, the response will include a session URL that +can be used to upload the file to. diff --git a/test/ai.py b/test/ai.py index 5dc44e08..fef03f0f 100644 --- a/test/ai.py +++ b/test/ai.py @@ -122,7 +122,7 @@ def testAITextGenWithDialogueHistory(): def testGettingAIAskAgentConfig(): ai_ask_config: Union[AiAgentAsk, AiAgentTextGen] = ( client.ai.get_ai_agent_default_config( - GetAiAgentDefaultConfigMode.ASK.value, language='ja-JP' + GetAiAgentDefaultConfigMode.ASK.value, language='en-US' ) ) assert ai_ask_config.type == 'ai_agent_ask'