IPWorks Cloud 2020 Python Edition

Questions / Feedback?

upload_file Method

Uploads a file resource.

Syntax

def upload_file(new_file_resource: str) -> str: ...

Remarks

This method uploads a new file resource (or potentially updates or overwrites an existing one). The Id of the newly-created (or updated) file resource is returned.

NewFileResource must be a file path, an Id-based relative file path, or (only when updating/overwriting) a file resource Id.

Name Conflict Resolution

The class automatically chooses how the server should resolve name conflicts (which occur if the specified NewFileResource already exists) based on the current values of the IfRevision and RenameIfExists configuration settings and the overwrite property. The following steps describe how the choice is made:

  1. If the uploaded file data is identical to the contents of the existing file resource, the server will always ignore the upload attempt and return a successful response, regardless of what IfRevision, RenameIfExists, and overwrite are currently set to. (This is a Dropbox server-side behavior that cannot be changed.)
  2. Otherwise, if IfRevision is populated, then the existing file resource will have its contents updated as long as its latest revision Id matches the one held by IfRevision. If the revision Ids don't match, then RenameIfExists decides the outcome:
    • If RenameIfExists is True, then a new file resource is created with a unique name that contains "conflicted copy".
    • If RenameIfExists is False, then the upload fails.
  3. Otherwise, if RenameIfExists is True, then a new file resource is created with a unique name.
  4. Otherwise, if overwrite is True, then the existing file resource is overwritten with a new one.
  5. Otherwise, the upload fails.

If local_file is set the file will be uploaded from the specified path. If local_file is not set the data in resource_data will be used.

To encrypt the file before uploading it, set encryption_algorithm and encryption_password.

Upload Notes

Dropbox offers two ways to upload a file. For smaller files a simple upload option is provided to upload data in one request. This is the default option. For larger files, uploads can be fragmented into multiple pieces, allowing resuming of uploads that may be interrupted.

Simple

By default the class uses the simple upload mechanism.

dropbox.LocalFile = "../MyFile.zip";
dropbox.UploadFile("/MyFile.zip");

Resumable

To enable resumable uploads set use_resumable_upload to True. This is recommended for large files. The class will automatically fragment the specified file into smaller pieces and upload each individually. FragmentSize may be set to specify the size of the fragment if desired. The default fragment size is 10 MB.

When use_resumable_upload is set to True and upload_file is called, a resumable upload session is started by the class. upload_session_id is populated with a resumable upload session Id identifying the session (this value may be needed for additional operations if the upload does not complete normally).

During a resumable upload, the on_fragment_complete event fires after each fragment is uploaded to indicate overall progress. The class also updates start_byte as necessary to indicate the current offset in the file.

If the upload is interrupted for any reason, resuming it is easy. First, verify that upload_session_id and start_byte are populated (if the same instance of the class is used, they should already be populated, and no special action should be needed). Then call upload_file again to resume the upload at the specified start_byte offset.

Note that if the upload is not resumed after some time the upload session will expire.

dropbox.LocalFile = "../MyFile.zip";
dropbox.UploadFile("MyFile.zip");

//The transfer is interrupted and UploadFile() above fails. Later, resume the download.
//Using the same instance StartByte and ResumeURL are already populated from the previous
//upload attempt.
dropbox.UploadFile("MyFile.zip");

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Cloud 2020 Python Edition - Version 20.0 [Build 8265]