docs: Improve docs for uploads (#254)

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "871ac70", "specHash": "d36b9f0", "version": "1.2.0" }
+{ "engineHash": "f42fdb0", "specHash": "e50af18", "version": "1.2.0" }

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

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
 
 

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
 
 

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):

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.

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.

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)
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## 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.
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+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/).
 
-<!-- sample post_files_content -->
+<!-- sample 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. <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 `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.
+- 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/).
+
+<!-- sample 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. <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 `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`.
+
+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.

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'