dropbox.dropbox – Dropbox

class dropbox.dropbox.Dropbox(oauth2_access_token, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100)

Bases: dropbox.dropbox._DropboxTransport, dropbox.base.DropboxBase

Use this class to make requests to the Dropbox API using a user’s access token. Methods of this class are meant to act on the corresponding user’s Dropbox.

__init__(oauth2_access_token, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100)
Parameters:
  • oauth2_access_token (str) – OAuth2 access token for making client requests.
  • max_retries_on_error (int) – On 5xx errors, the number of times to retry.
  • max_retries_on_rate_limit (Optional[int]) – On 429 errors, the number of times to retry. If None, always retries.
  • user_agent (str) – The user agent to use when making requests. This helps us identify requests coming from your application. We recommend you use the format “AppName/Version”. If set, we append “/OfficialDropboxPythonSDKv2/__version__” to the user_agent,
  • session (requests.sessions.Session) – If not provided, a new session (connection pool) is created. To share a session across multiple clients, use create_session().
  • headers (dict) – Additional headers to add to requests.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 30 seconds.
auth_token_from_oauth1(oauth1_token, oauth1_token_secret)

Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token.

Parameters:
  • oauth1_token (str) – The supplied OAuth 1.0 access token.
  • oauth1_token_secret (str) – The token secret associated with the supplied access token.
Return type:

dropbox.auth.TokenFromOAuth1Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.auth.TokenFromOAuth1Error
auth_token_revoke()

Disables the access token used to authenticate the call.

Return type:None
clone(oauth2_access_token=None, max_retries_on_error=None, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=None)

Creates a new copy of the Dropbox client with the same defaults unless modified by arguments to clone()

See constructor for original parameter descriptions.

Returns:New instance of Dropbox clent
Return type:Dropbox
contacts_delete_manual_contacts()

Removes all manually added contacts. You’ll still keep contacts who are on your team or who you imported. New contacts will be added when you share.

Return type:None
contacts_delete_manual_contacts_batch(email_addresses)

Removes manually added contacts from the given list.

Parameters:email_addresses (list) – List of manually added contacts to be deleted.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.contacts.DeleteManualContactsError
file_properties_properties_add(path, property_groups)

Add property groups to a Dropbox file. See file_properties_templates_add_for_user() or file_properties_templates_add_for_team() to create new templates.

Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_groups (list) – The property groups which are to be added to a Dropbox file.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.AddPropertiesError
file_properties_properties_overwrite(path, property_groups)

Overwrite property groups associated with a file. This endpoint should be used instead of file_properties_properties_update() when property groups are being updated via a “snapshot” instead of via a “delta”. In other words, this endpoint will delete all omitted fields from a property group, whereas file_properties_properties_update() will only delete fields that are explicitly marked for deletion.

Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_groups (list) – The property groups “snapshot” updates to force apply.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.InvalidPropertyGroupError
file_properties_properties_remove(path, property_template_ids)

Permanently removes the specified property group from the file. To remove specific property field key value pairs, see file_properties_properties_update(). To update a template, see file_properties_templates_update_for_user() or file_properties_templates_update_for_team(). To remove a template, see file_properties_templates_remove_for_user() or file_properties_templates_remove_for_team().

Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_template_ids (list) – A list of identifiers for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.RemovePropertiesError

Search across property templates for particular property field values.

Parameters:
Return type:

dropbox.file_properties.PropertiesSearchResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.PropertiesSearchError
file_properties_properties_search_continue(cursor)

Once a cursor has been retrieved from file_properties_properties_search(), use this to paginate through all search results.

Parameters:cursor (str) – The cursor returned by your last call to file_properties_properties_search() or file_properties_properties_search_continue().
Return type:dropbox.file_properties.PropertiesSearchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.PropertiesSearchContinueError
file_properties_properties_update(path, update_property_groups)

Add, update or remove properties associated with the supplied file and templates. This endpoint should be used instead of file_properties_properties_overwrite() when property groups are being updated via a “delta” instead of via a “snapshot” . In other words, this endpoint will not delete any omitted fields from a property group, whereas file_properties_properties_overwrite() will delete any fields that are omitted from a property group.

Parameters:
  • path (str) – A unique identifier for the file or folder.
  • update_property_groups (list) – The property groups “delta” updates to apply.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.UpdatePropertiesError
file_properties_templates_add_for_user(name, description, fields)

Add a template associated with a user. See file_properties_properties_add() to add properties to a file. This endpoint can’t be called on a team member or admin’s behalf.

Return type:dropbox.file_properties.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_get_for_user(template_id)

Get the schema for a specified template. This endpoint can’t be called on a team member or admin’s behalf.

Parameters:template_id (str) – An identifier for template added by route See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:dropbox.file_properties.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_list_for_user()

Get the template identifiers for a team. To get the schema of each template use file_properties_templates_get_for_user(). This endpoint can’t be called on a team member or admin’s behalf.

Return type:dropbox.file_properties.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_remove_for_user(template_id)

Permanently removes the specified template created from file_properties_templates_add_for_user(). All properties associated with the template will also be removed. This action cannot be undone.

Parameters:template_id (str) – An identifier for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_update_for_user(template_id, name=None, description=None, add_fields=None)

Update a template associated with a user. This route can update the template name, the template description and add optional properties to templates. This endpoint can’t be called on a team member or admin’s behalf.

Parameters:
  • template_id (str) – An identifier for template added by See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
  • name (Nullable) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable) – Description for the new template. Template descriptions can be up to 1024 bytes.
  • add_fields (Nullable) – Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:

dropbox.file_properties.UpdateTemplateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_requests_count()

Returns the total number of file requests owned by this user. Includes both open and closed file requests.

Return type:dropbox.file_requests.CountFileRequestsResult
file_requests_create(title, destination, deadline=None, open=True)

Creates a file request for this user.

Parameters:
  • title (str) – The title of the file request. Must not be empty.
  • destination (str) – The path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.
  • deadline (Nullable) – The deadline for the file request. Deadlines can only be set by Professional and Business accounts.
  • open (bool) – Whether or not the file request should be open. If the file request is closed, it will not accept any file submissions, but it can be opened later.
Return type:

dropbox.file_requests.FileRequest

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_requests.CreateFileRequestError
file_requests_delete(ids)

Delete a batch of closed file requests.

Parameters:ids (list) – List IDs of the file requests to delete.
Return type:dropbox.file_requests.DeleteFileRequestsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_requests.DeleteFileRequestError
file_requests_delete_all_closed()

Delete all closed file requests owned by this user.

Return type:dropbox.file_requests.DeleteAllClosedFileRequestsResult
file_requests_get(id)

Returns the specified file request.

Parameters:id (str) – The ID of the file request to retrieve.
Return type:dropbox.file_requests.FileRequest
file_requests_list()

Returns a list of file requests owned by this user. For apps with the app folder permission, this will only return file requests with destinations in the app folder.

Return type:dropbox.file_requests.ListFileRequestsResult
file_requests_list_continue(cursor)

Once a cursor has been retrieved from file_requests_list_v2(), use this to paginate through all file requests. The cursor must come from a previous call to file_requests_list_v2() or file_requests_list_continue().

Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.file_requests.ListFileRequestsV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_requests.ListFileRequestsContinueError
file_requests_list_v2(limit=1000)

Returns a list of file requests owned by this user. For apps with the app folder permission, this will only return file requests with destinations in the app folder.

Parameters:limit (int) – The maximum number of file requests that should be returned per request.
Return type:dropbox.file_requests.ListFileRequestsV2Result
file_requests_update(id, title=None, destination=None, deadline=UpdateFileRequestDeadline('no_update', None), open=None)

Update a file request.

Parameters:
  • id (str) – The ID of the file request to update.
  • title (Nullable) – The new title of the file request. Must not be empty.
  • destination (Nullable) – The new path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.
  • deadline (dropbox.file_requests.UpdateFileRequestDeadline) – The new deadline for the file request. Deadlines can only be set by Professional and Business accounts.
  • open (Nullable) – Whether to set this file request as open or closed.
Return type:

dropbox.file_requests.FileRequest

files_alpha_get_metadata(path, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_property_groups=None, include_property_templates=None)

Returns the metadata for a file or folder. This is an alpha endpoint compatible with the properties API. Note: Metadata for the root folder is unsupported.

Parameters:include_property_templates (Nullable) – If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties.
Return type:dropbox.files.Metadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.AlphaGetMetadataError
files_alpha_upload(f, path, mode=WriteMode('add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False)

Create a new file with the contents provided in the request. Note that this endpoint is part of the properties API alpha and is slightly different from files_upload(). Do not use this to upload a file larger than 150 MB. Instead, create an upload session with files_upload_session_start().

Parameters:f (bytes) – Contents to upload.
Return type:dropbox.files.FileMetadata
files_copy(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

Copy a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be copied.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for files_move().
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_copy_batch(entries, autorename=False, allow_shared_folder=False, allow_ownership_transfer=False)

Copy multiple files or folders to different locations at once in the user’s Dropbox. If RelocationBatchArg.allow_shared_folder is false, this route is atomic. If one entry fails, the whole transaction will abort. If RelocationBatchArg.allow_shared_folder is true, atomicity is not guaranteed, but it allows you to copy the contents of shared folders to new locations. This route will return job ID immediately and do the async copy job in background. Please use files_copy_batch_check() to check the job status.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy_batch() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for files_move_batch().
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_copy_batch_check(async_job_id)

Returns the status of an asynchronous job for files_copy_batch(). If success, it returns list of results for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_copy_batch_check_v2(async_job_id)

Returns the status of an asynchronous job for files_copy_batch_v2(). It returns list of results for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchV2JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_copy_batch_v2(entries, autorename=False)

Copy multiple files or folders to different locations at once in the user’s Dropbox. This route will replace files_copy_batch(). The main difference is this route will return status for each entry, while files_copy_batch() raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async copy job in background. Please use files_copy_batch_check_v2() to check the job status.

Parameters:
  • entries (list) – List of entries to be moved or copied. Each entry is dropbox.files.RelocationPath.
  • autorename (bool) – If there’s a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict.
Return type:

dropbox.files.RelocationBatchV2Launch

files_copy_reference_get(path)

Get a copy reference to a file or folder. This reference string can be used to save that file or folder to another user’s Dropbox by passing it to files_copy_reference_save().

Parameters:path (str) – The path to the file or folder you want to get a copy reference to.
Return type:dropbox.files.GetCopyReferenceResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetCopyReferenceError
files_copy_reference_save(copy_reference, path)

Save a copy reference returned by files_copy_reference_get() to the user’s Dropbox.

Parameters:
  • copy_reference (str) – A copy reference returned by files_copy_reference_get().
  • path (str) – Path in the user’s Dropbox that is the destination.
Return type:

dropbox.files.SaveCopyReferenceResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SaveCopyReferenceError
files_copy_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

Copy a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be copied.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for files_move().
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_create_folder(path, autorename=False)

Create a folder at a given path.

Parameters:
  • path (str) – Path in the user’s Dropbox to create.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
Return type:

dropbox.files.FolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.CreateFolderError
files_create_folder_batch(paths, autorename=False, force_async=False)

Create multiple folders at once. This route is asynchronous for large batches, which returns a job ID immediately and runs the create folder batch asynchronously. Otherwise, creates the folders and returns the result synchronously for smaller inputs. You can force asynchronous behaviour by using the CreateFolderBatchArg.force_async flag. Use files_create_folder_batch_check() to check the job status.

Parameters:
  • paths (list) – List of paths to be created in the user’s Dropbox. Duplicate path arguments in the batch are considered only once.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
  • force_async (bool) – Whether to force the create to happen asynchronously.
Return type:

dropbox.files.CreateFolderBatchLaunch

files_create_folder_batch_check(async_job_id)

Returns the status of an asynchronous job for files_create_folder_batch(). If success, it returns list of result for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.CreateFolderBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_create_folder_v2(path, autorename=False)

Create a folder at a given path.

Parameters:
  • path (str) – Path in the user’s Dropbox to create.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
Return type:

dropbox.files.CreateFolderResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.CreateFolderError
files_delete(path, parent_rev=None)

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding dropbox.files.FileMetadata or dropbox.files.FolderMetadata for the item at time of deletion, and not a dropbox.files.DeletedMetadata object.

Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_delete_batch(entries)

Delete multiple files/folders at once. This route is asynchronous, which returns a job ID immediately and runs the delete batch asynchronously. Use files_delete_batch_check() to check the job status.

Return type:dropbox.files.DeleteBatchLaunch
files_delete_batch_check(async_job_id)

Returns the status of an asynchronous job for files_delete_batch(). If success, it returns list of result for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.DeleteBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_delete_v2(path, parent_rev=None)

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding dropbox.files.FileMetadata or dropbox.files.FolderMetadata for the item at time of deletion, and not a dropbox.files.DeletedMetadata object.

Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

dropbox.files.DeleteResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_download(path, rev=None)

Download a file from a user’s Dropbox.

Parameters:
  • path (str) – The path of the file to download.
  • rev (Nullable) – Please specify revision in path instead.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_download_to_file(download_path, path, rev=None)

Download a file from a user’s Dropbox.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to download.
  • rev (Nullable) – Please specify revision in path instead.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadError
files_download_zip(path)

Download a folder from the user’s Dropbox, as a zip file. The folder must be less than 20 GB in size and have fewer than 10,000 total files. The input cannot be a single file. Any single file must be less than 4GB in size.

Parameters:path (str) – The path of the folder to download.
Return type:(dropbox.files.DownloadZipResult, requests.models.Response)
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.DownloadZipError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_download_zip_to_file(download_path, path)

Download a folder from the user’s Dropbox, as a zip file. The folder must be less than 20 GB in size and have fewer than 10,000 total files. The input cannot be a single file. Any single file must be less than 4GB in size.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the folder to download.
Return type:

dropbox.files.DownloadZipResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadZipError
files_export(path)

Export a file from a user’s Dropbox. This route only supports exporting files that cannot be downloaded directly and whose ExportResult.file_metadata has ExportInfo.export_as populated.

Parameters:path (str) – The path of the file to be exported.
Return type:(dropbox.files.ExportResult, requests.models.Response)
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.ExportError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_export_to_file(download_path, path)

Export a file from a user’s Dropbox. This route only supports exporting files that cannot be downloaded directly and whose ExportResult.file_metadata has ExportInfo.export_as populated.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to be exported.
Return type:

dropbox.files.ExportResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ExportError
files_get_metadata(path, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_property_groups=None)

Returns the metadata for a file or folder. Note: Metadata for the root folder is unsupported.

Parameters:
  • path (str) – The path of a file or folder on Dropbox.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted (bool) – If true, dropbox.files.DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_property_groups (Nullable) – If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.GetMetadataError
files_get_preview(path, rev=None)

Get a preview for a file. Currently, PDF previews are generated for files with the following extensions: .ai, .doc, .docm, .docx, .eps, .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf. HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will return an unsupported extension error.

Parameters:
  • path (str) – The path of the file to preview.
  • rev (Nullable) – Please specify revision in path instead.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PreviewError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_get_preview_to_file(download_path, path, rev=None)

Get a preview for a file. Currently, PDF previews are generated for files with the following extensions: .ai, .doc, .docm, .docx, .eps, .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf. HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will return an unsupported extension error.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to preview.
  • rev (Nullable) – Please specify revision in path instead.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PreviewError

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. This URL should not be used to display content directly in the browser. The Content-Type of the link is determined automatically by the file’s mime type.

Parameters:path (str) – The path to the file you want a temporary link to.
Return type:dropbox.files.GetTemporaryLinkResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetTemporaryLinkError

Get a one-time use temporary upload link to upload a file to a Dropbox location. This endpoint acts as a delayed files_upload(). The returned temporary upload link may be used to make a POST request with the data to be uploaded. The upload will then be perfomed with the dropbox.files.CommitInfo previously provided to files_get_temporary_upload_link() but evaluated only upon consumption. Hence, errors stemming from invalid dropbox.files.CommitInfo with respect to the state of the user’s Dropbox will only be communicated at consumption time. Additionally, these errors are surfaced as generic HTTP 409 Conflict responses, potentially hiding issue details. The maximum temporary upload link duration is 4 hours. Upon consumption or expiration, a new link will have to be generated. Multiple links may exist for a specific upload path at any given time. The POST request on the temporary upload link must have its Content-Type set to “application/octet-stream”. Example temporary upload link consumption request: curl -X POST https://dl.dropboxusercontent.com/apitul/1/bNi2uIYF51cVBND –header “Content-Type: application/octet-stream” –data-binary @local_file.txt A successful temporary upload link consumption request returns the content hash of the uploaded data in JSON format. Example succesful temporary upload link consumption response: {“content-hash”: “599d71033d700ac892a0e48fa61b125d2f5994”} An unsuccessful temporary upload link consumption request returns any of the following status codes: HTTP 400 Bad Request: Content-Type is not one of application/octet-stream and text/plain or request is invalid. HTTP 409 Conflict: The temporary upload link does not exist or is currently unavailable, the upload failed, or another error happened. HTTP 410 Gone: The temporary upload link is expired or consumed. Example unsuccessful temporary upload link consumption response: Temporary upload link has been recently consumed.

Parameters:
  • commit_info (dropbox.files.CommitInfo) – Contains the path and other optional modifiers for the future upload commit. Equivalent to the parameters provided to files_upload().
  • duration (float) – How long before this link expires, in seconds. Attempting to start an upload with this link longer than this period of time after link creation will result in an error.
Return type:

dropbox.files.GetTemporaryUploadLinkResult

files_get_thumbnail(path, format=ThumbnailFormat('jpeg', None), size=ThumbnailSize('w64h64', None), mode=ThumbnailMode('strict', None))

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

Parameters:
  • path (str) – The path to the image file you want to thumbnail.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_get_thumbnail_batch(entries)

Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

Parameters:entries (list) – List of files to get thumbnails.
Return type:dropbox.files.GetThumbnailBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetThumbnailBatchError
files_get_thumbnail_to_file(download_path, path, format=ThumbnailFormat('jpeg', None), size=ThumbnailSize('w64h64', None), mode=ThumbnailMode('strict', None))

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path to the image file you want to thumbnail.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailError
files_list_folder(path, recursive=False, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_mounted_folders=True, limit=None, shared_link=None, include_property_groups=None, include_non_downloadable_files=True)

Starts returning the contents of a folder. If the result’s ListFolderResult.has_more field is True, call files_list_folder_continue() with the returned ListFolderResult.cursor to retrieve more entries. If you’re using ListFolderArg.recursive set to True to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each dropbox.files.FileMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it and remove all its children. For each dropbox.files.FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it but leave the children as they are. Check the new entry’s FolderSharingInfo.read_only and set all its children’s read-only statuses to match. For each dropbox.files.DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there’s nothing at the given path, ignore this entry. Note: dropbox.auth.RateLimitError may be returned if multiple files_list_folder() or files_list_folder_continue() calls with same parameters are made simultaneously by same API app for same user. If your app implements retry logic, please hold off the retry until the previous request finishes.

Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
  • shared_link (Nullable) – A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
  • include_property_groups (Nullable) – If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
  • include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
Return type:

dropbox.files.ListFolderResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListFolderError
files_list_folder_continue(cursor)

Once a cursor has been retrieved from files_list_folder(), use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for files_list_folder().

Parameters:cursor (str) – The cursor returned by your last call to files_list_folder() or files_list_folder_continue().
Return type:dropbox.files.ListFolderResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.ListFolderContinueError
files_list_folder_get_latest_cursor(path, recursive=False, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_mounted_folders=True, limit=None, shared_link=None, include_property_groups=None, include_non_downloadable_files=True)

A way to quickly get a cursor for the folder’s state. Unlike files_list_folder(), files_list_folder_get_latest_cursor() doesn’t return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn’t need to know about files that already exist in Dropbox.

Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
  • shared_link (Nullable) – A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
  • include_property_groups (Nullable) – If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
  • include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
Return type:

dropbox.files.ListFolderGetLatestCursorResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListFolderError
files_list_folder_longpoll(cursor, timeout=30)

A longpoll endpoint to wait for changes on an account. In conjunction with files_list_folder_continue(), this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you’re looking for server-side notifications, check out our webhooks documentation.

Parameters:
  • cursor (str) – A cursor as returned by files_list_folder() or files_list_folder_continue(). Cursors retrieved by setting ListFolderArg.include_media_info to True are not supported.
  • timeout (int) – A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts.
Return type:

dropbox.files.ListFolderLongpollResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListFolderLongpollError
files_list_revisions(path, mode=ListRevisionsMode('path', None), limit=10)

Returns revisions for files based on a file path or a file id. The file path or file id is identified from the latest file entry at the given file path or id. This end point allows your app to query either by file path or file id by setting the mode parameter appropriately. In the ListRevisionsMode.path (default) mode, all revisions at the same file path as the latest file entry are returned. If revisions with the same file id are desired, then mode must be set to ListRevisionsMode.id. The ListRevisionsMode.id mode is useful to retrieve revisions for a given file across moves or renames.

Parameters:
  • path (str) – The path to the file you want to see the revisions of.
  • mode (dropbox.files.ListRevisionsMode) – Determines the behavior of the API in listing the revisions for a given file path or id.
  • limit (int) – The maximum number of revision entries returned.
Return type:

dropbox.files.ListRevisionsResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListRevisionsError
files_move(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

Move a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be moved.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for files_move().
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_move_batch(entries, autorename=False, allow_shared_folder=False, allow_ownership_transfer=False)

Move multiple files or folders to different locations at once in the user’s Dropbox. This route is ‘all or nothing’, which means if one entry fails, the whole transaction will abort. This route will return job ID immediately and do the async moving job in background. Please use files_move_batch_check() to check the job status.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy_batch() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for files_move_batch().
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_move_batch_check(async_job_id)

Returns the status of an asynchronous job for files_move_batch(). If success, it returns list of results for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_move_batch_check_v2(async_job_id)

Returns the status of an asynchronous job for files_move_batch_v2(). It returns list of results for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchV2JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_move_batch_v2(entries, autorename=False, allow_ownership_transfer=False)

Move multiple files or folders to different locations at once in the user’s Dropbox. This route will replace files_move_batch(). The main difference is this route will return status for each entry, while files_move_batch() raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async move job in background. Please use files_move_batch_check_v2() to check the job status.

Parameters:allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:dropbox.files.RelocationBatchV2Launch
files_move_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

Move a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be moved.

Parameters:
  • allow_shared_folder (bool) – If true, files_copy() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for files_move().
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_permanently_delete(path, parent_rev=None)

Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40). Note: This endpoint is only available for Dropbox Business apps.

Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_properties_add(path, property_groups)
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_groups (list) – The property groups which are to be added to a Dropbox file.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.AddPropertiesError
files_properties_overwrite(path, property_groups)
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_groups (list) – The property groups “snapshot” updates to force apply.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.InvalidPropertyGroupError
files_properties_remove(path, property_template_ids)
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_template_ids (list) – A list of identifiers for a template created by files_templates_add_for_user() or files_templates_add_for_team().
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RemovePropertiesError
files_properties_template_get(template_id)
Parameters:template_id (str) – An identifier for template added by route See files_templates_add_for_user() or files_templates_add_for_team().
Return type:dropbox.files.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.TemplateError
files_properties_template_list()
files_properties_update(path, update_property_groups)
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • update_property_groups (list) – The property groups “delta” updates to apply.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UpdatePropertiesError
files_restore(path, rev)

Restore a specific revision of a file to the given path.

Parameters:
  • path (str) – The path to save the restored file.
  • rev (str) – The revision to restore.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RestoreError
files_save_url(path, url)

Save the data from a specified URL into a file in user’s Dropbox. Note that the transfer from the URL must complete within 5 minutes, or the operation will time out and the job will fail. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

Parameters:
  • path (str) – The path in Dropbox where the URL will be saved to.
  • url (str) – The URL to be saved.
Return type:

dropbox.files.SaveUrlResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SaveUrlError
files_save_url_check_job_status(async_job_id)

Check the status of a files_save_url() job.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.SaveUrlJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError

Searches for files and folders. Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing.

Parameters:
  • path (str) – The path in the user’s Dropbox to search. Should probably be a folder.
  • query (str) – The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. “bat c” matches “bat cave” but not “batman car”).
  • start (int) – The starting index within the search results (used for paging).
  • max_results (int) – The maximum number of search results to return.
  • mode (dropbox.files.SearchMode) – The search mode (filename, filename_and_content, or deleted_filename). Note that searching file content is only available for Dropbox Business accounts.
Return type:

dropbox.files.SearchResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SearchError
files_upload(f, path, mode=WriteMode('add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False)

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with files_upload_session_start(). Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:
  • f (bytes) – Contents to upload.
  • path (str) – Path in the user’s Dropbox to save the file.
  • mode (dropbox.files.WriteMode) – Selects what to do if the file already exists.
  • autorename (bool) – If there’s a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict.
  • client_modified (Nullable) – The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.
  • mute (bool) – Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If True, this tells the clients that this modification shouldn’t result in a user notification.
  • property_groups (Nullable) – List of custom properties to add to file.
  • strict_conflict (bool) – Be more strict about how each dropbox.files.WriteMode detects conflict. For example, always return a conflict error when mode = WriteMode.update and the given “rev” doesn’t match the existing file’s “rev”, even if the existing file has been deleted.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadError
files_upload_session_append(f, session_id, offset)

Append more data to an upload session. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:
  • f (bytes) – Contents to upload.
  • session_id (str) – The upload session ID (returned by files_upload_session_start()).
  • offset (int) – The amount of data that has been uploaded so far. We use this to make sure upload data isn’t lost or duplicated in the event of a network error.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionLookupError
files_upload_session_append_v2(f, cursor, close=False)

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionLookupError
files_upload_session_finish(f, cursor, commit)

Finish an upload session and save the uploaded data to the given file path. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionFinishError
files_upload_session_finish_batch(entries)

This route helps you commit many files at once into a user’s Dropbox. Use files_upload_session_start() and files_upload_session_append_v2() to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling files_upload_session_finish(), use this route to finish all your upload sessions in a single request. UploadSessionStartArg.close or UploadSessionAppendArg.close needs to be true for the last files_upload_session_start() or files_upload_session_append_v2() call. The maximum size of a file one can upload to an upload session is 350 GB. This route will return a job_id immediately and do the async commit job in background. Use files_upload_session_finish_batch_check() to check the job status. For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:entries (list) – Commit information for each file in the batch.
Return type:dropbox.files.UploadSessionFinishBatchLaunch
files_upload_session_finish_batch_check(async_job_id)

Returns the status of an asynchronous job for files_upload_session_finish_batch(). If success, it returns list of result for each entry.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.UploadSessionFinishBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_upload_session_start(f, close=False)

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB. This call starts a new upload session with the given data. You can then use files_upload_session_append_v2() to add more data and files_upload_session_finish() to save all the data to a file in Dropbox. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. An upload session can be used for a maximum of 48 hours. Attempting to use an UploadSessionStartResult.session_id with files_upload_session_append_v2() or files_upload_session_finish() more than 48 hours after its creation will return a UploadSessionLookupError.not_found. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

Parameters:
  • f (bytes) – Contents to upload.
  • close (bool) – If true, the current session will be closed, at which point you won’t be able to call files_upload_session_append_v2() anymore with the current session.
Return type:

dropbox.files.UploadSessionStartResult

paper_docs_archive(doc_id)

Marks the given Paper doc as archived. Note: This action can be performed or undone by anyone with edit permissions to the doc.

Parameters:doc_id (str) – The Paper doc ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_create(f, import_format, parent_folder_id=None)

Creates a new Paper doc with the provided content.

Parameters:
  • f (bytes) – Contents to upload.
  • parent_folder_id (Nullable) – The Paper folder ID where the Paper document should be created. The API user has to have write access to this folder or error is thrown.
  • import_format (dropbox.paper.ImportFormat) – The format of provided data.
Return type:

dropbox.paper.PaperDocCreateUpdateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.PaperDocCreateError
paper_docs_download(doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown.

Return type:(dropbox.paper.PaperDocExportResult, requests.models.Response)
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

paper_docs_download_to_file(download_path, doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown.

Parameters:download_path (str) – Path on local machine to save file.
Return type:dropbox.paper.PaperDocExportResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_folder_users_list(doc_id, limit=1000)

Lists the users who are explicitly invited to the Paper folder in which the Paper doc is contained. For private folders all users (including owner) shared on the folder are listed and for team folders all non-team users shared on the folder are returned.

Parameters:limit (int) – Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error.
Return type:dropbox.paper.ListUsersOnFolderResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_folder_users_list_continue(doc_id, cursor)

Once a cursor has been retrieved from paper_docs_folder_users_list(), use this to paginate through all users on the Paper folder.

Parameters:cursor (str) – The cursor obtained from paper_docs_folder_users_list() or paper_docs_folder_users_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListUsersOnFolderResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListUsersCursorError
paper_docs_get_folder_info(doc_id)

Retrieves folder information for the given Paper doc. This includes: - folder sharing policy; permissions for subfolders are set by the top-level folder. - full ‘filepath’, i.e. the list of folders (both folderId and folderName) from the root folder to the folder directly containing the Paper doc. Note: If the Paper doc is not in any folder (aka unfiled) the response will be empty.

Parameters:doc_id (str) – The Paper doc ID.
Return type:dropbox.paper.FoldersContainingPaperDoc
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_list(filter_by=ListPaperDocsFilterBy('docs_accessed', None), sort_by=ListPaperDocsSortBy('accessed', None), sort_order=ListPaperDocsSortOrder('ascending', None), limit=1000)

Return the list of all Paper docs according to the argument specifications. To iterate over through the full pagination, pass the cursor to paper_docs_list_continue().

Parameters:
Return type:

dropbox.paper.ListPaperDocsResponse

paper_docs_list_continue(cursor)

Once a cursor has been retrieved from paper_docs_list(), use this to paginate through all Paper doc.

Parameters:cursor (str) – The cursor obtained from paper_docs_list() or paper_docs_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListPaperDocsResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListDocsCursorError
paper_docs_permanently_delete(doc_id)

Permanently deletes the given Paper doc. This operation is final as the doc cannot be recovered. Note: This action can be performed only by the doc owner.

Parameters:doc_id (str) – The Paper doc ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_sharing_policy_get(doc_id)

Gets the default sharing policy for the given Paper doc.

Parameters:doc_id (str) – The Paper doc ID.
Return type:dropbox.paper.SharingPolicy
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_sharing_policy_set(doc_id, sharing_policy)

Sets the default sharing policy for the given Paper doc. The default ‘team_sharing_policy’ can be changed only by teams, omit this field for personal accounts. Note: ‘public_sharing_policy’ cannot be set to the value ‘disabled’ because this setting can be changed only via the team admin console.

Parameters:sharing_policy (dropbox.paper.SharingPolicy) – The default sharing policy to be set for the Paper doc.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_update(f, doc_id, doc_update_policy, revision, import_format)

Updates an existing Paper doc with the provided content.

Parameters:
  • f (bytes) – Contents to upload.
  • doc_update_policy (dropbox.paper.PaperDocUpdatePolicy) – The policy used for the current update call.
  • revision (int) – The latest doc revision. This value must match the head revision or an error code will be returned. This is to prevent colliding writes.
  • import_format (dropbox.paper.ImportFormat) – The format of provided data.
Return type:

dropbox.paper.PaperDocCreateUpdateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.PaperDocUpdateError
paper_docs_users_add(doc_id, members, custom_message=None, quiet=False)

Allows an owner or editor to add users to a Paper doc or change their permissions using their email address or Dropbox account ID. Note: The Doc owner’s permissions cannot be changed.

Parameters:
  • members (list) – User which should be added to the Paper doc. Specify only email address or Dropbox account ID.
  • custom_message (Nullable) – A personal message that will be emailed to each successfully added member.
  • quiet (bool) – Clients should set this to true if no email message shall be sent to added users.
Return type:

list

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_users_list(doc_id, limit=1000, filter_by=UserOnPaperDocFilter('shared', None))

Lists all users who visited the Paper doc or users with explicit access. This call excludes users who have been removed. The list is sorted by the date of the visit or the share date. The list will include both users, the explicitly shared ones as well as those who came in using the Paper url link.

Parameters:
  • limit (int) – Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error.
  • filter_by (dropbox.paper.UserOnPaperDocFilter) – Specify this attribute if you want to obtain users that have already accessed the Paper doc.
Return type:

dropbox.paper.ListUsersOnPaperDocResponse

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_users_list_continue(doc_id, cursor)

Once a cursor has been retrieved from paper_docs_users_list(), use this to paginate through all users on the Paper doc.

Parameters:cursor (str) – The cursor obtained from paper_docs_users_list() or paper_docs_users_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListUsersOnPaperDocResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListUsersCursorError
paper_docs_users_remove(doc_id, member)

Allows an owner or editor to remove users from a Paper doc using their email address or Dropbox account ID. Note: Doc owner cannot be removed.

Parameters:member (dropbox.paper.MemberSelector) – User which should be removed from the Paper doc. Specify only email address or Dropbox account ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
request(route, namespace, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API and in the process validates that the route argument and result are the expected data types. The request_arg is converted to JSON based on the arg_data_type. Likewise, the response is deserialized from JSON and converted to an object based on the {result,error}_data_type.

Parameters:
  • host – The Dropbox API host to connect to.
  • route (datatypes.stone_base.Route) – The route to make the request to.
  • request_arg – Argument for the route that conforms to the validator specified by route.arg_type.
  • request_binary – String or file pointer representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result.

request_json_object(host, route_name, route_style, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API, taking a JSON-serializable Python object as an argument, and returning one as a response.

Parameters:
  • host – The Dropbox API host to connect to.
  • route_name – The name of the route to invoke.
  • route_style – The style of the route.
  • request_arg (str) – A JSON-serializable Python object representing the argument for the route.
  • request_binary (Optional[bytes]) – Bytes representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result as a JSON-serializable Python object.

request_json_string(host, func_name, route_style, request_json_arg, request_binary, timeout=None)

See request_json_string_with_retry() for description of parameters.

request_json_string_with_retry(host, route_name, route_style, request_json_arg, request_binary, timeout=None)

See request_json_object() for description of parameters.

Parameters:request_json_arg – A string representing the serialized JSON argument to the route.
sharing_add_file_member(file, members, custom_message=None, quiet=False, access_level=AccessLevel('viewer', None), add_message_as_comment=False)

Adds specified members to a file.

Parameters:
  • file (str) – File to which to add members.
  • members (list) – Members to add. Note that even an email address is given, this may result in a user being directy added to the membership if that email is the user’s main account email.
  • custom_message (Nullable) – Message to send to added members in their invitation.
  • quiet (bool) – Whether added members should be notified via device notifications of their invitation.
  • access_level (dropbox.sharing.AccessLevel) – AccessLevel union object, describing what access level we want to give new members.
  • add_message_as_comment (bool) – If the custom message should be added as a comment on the file.
Return type:

list

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.AddFileMemberError
sharing_add_folder_member(shared_folder_id, members, quiet=False, custom_message=None)

Allows an owner or editor (if the ACL update policy allows) of a shared folder to add another member. For the new member to get access to all the functionality for this folder, you will need to call sharing_mount_folder() on their behalf.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • members (list) – The intended list of members to add. Added members will receive invites to join the shared folder.
  • quiet (bool) – Whether added members should be notified via email and device notifications of their invite.
  • custom_message (Nullable) – Optional message to display to added members in their invitation.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.AddFolderMemberError
sharing_change_file_member_access(file, member, access_level)

Identical to update_file_member but with less information returned.

Parameters:
Return type:

dropbox.sharing.FileMemberActionResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.FileMemberActionError
sharing_check_job_status(async_job_id)

Returns the status of an asynchronous job.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError
sharing_check_remove_member_job_status(async_job_id)

Returns the status of an asynchronous job for sharing a folder.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.RemoveMemberJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError
sharing_check_share_job_status(async_job_id)

Returns the status of an asynchronous job for sharing a folder.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.ShareFolderJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError

Create a shared link. If a shared link already exists for the given path, that link is returned. Note that in the returned dropbox.sharing.PathLinkMetadata, the PathLinkMetadata.url field is the shortened URL if CreateSharedLinkArg.short_url argument is set to True. Previously, it was technically possible to break a shared link by moving or renaming the corresponding file or folder. In the future, this will no longer be the case, so your app shouldn’t rely on this behavior. Instead, if your app needs to revoke a shared link, use sharing_revoke_shared_link().

Parameters:
  • path (str) – The path to share.
  • short_url (bool) – Whether to return a shortened URL.
  • pending_upload (Nullable) – If it’s okay to share a path that does not yet exist, set this to either PendingUploadMode.file or PendingUploadMode.folder to indicate whether to assume it’s a file or folder.
Return type:

dropbox.sharing.PathLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.CreateSharedLinkError

Create a shared link with custom settings. If no settings are given then the default visibility is RequestedVisibility.public (The resolved visibility, though, may depend on other aspects such as team and shared folder settings).

Parameters:
  • path (str) – The path to be shared by the shared link.
  • settings (Nullable) – The requested settings for the newly created shared link.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.CreateSharedLinkWithSettingsError
sharing_get_file_metadata(file, actions=None)

Returns shared file metadata.

Parameters:
  • file (str) – The file to query.
  • actions (Nullable) – A list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:

dropbox.sharing.SharedFileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.GetFileMetadataError
sharing_get_file_metadata_batch(files, actions=None)

Returns shared file metadata.

Parameters:
  • files (list) – The files to query.
  • actions (Nullable) – A list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:

list

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_get_folder_metadata(shared_folder_id, actions=None)

Returns shared folder metadata by its folder ID.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • actions (Nullable) – A list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:

dropbox.sharing.SharedFolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharedFolderAccessError

Download the shared link’s file from a user’s Dropbox.

Parameters:
  • url (str) – URL of the shared link.
  • path (Nullable) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable) – If the shared link has a password, this parameter can be used.
Return type:

(dropbox.sharing.SharedLinkMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinkFileError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

Download the shared link’s file from a user’s Dropbox.

Parameters:
  • download_path (str) – Path on local machine to save file.
  • url (str) – URL of the shared link.
  • path (Nullable) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable) – If the shared link has a password, this parameter can be used.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinkFileError

Get the shared link’s metadata.

Parameters:
  • url (str) – URL of the shared link.
  • path (Nullable) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable) – If the shared link has a password, this parameter can be used.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharedLinkError

Returns a list of dropbox.sharing.LinkMetadata objects for this user, including collection links. If no path is given, returns a list of all shared links for the current user, including collection links, up to a maximum of 1000 links. If a non-empty path is given, returns a list of all shared links that allow access to the given path. Collection links are never returned in this case. Note that the url field in the response is never the shortened URL.

Parameters:path (Nullable) – See sharing_get_shared_links() description.
Return type:dropbox.sharing.GetSharedLinksResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinksError
sharing_list_file_members(file, actions=None, include_inherited=True, limit=100)

Use to obtain the members who have been invited to a file, both inherited and uninherited members.

Parameters:
  • file (str) – The file for which you want to see members.
  • actions (Nullable) – The actions for which to return permissions on a member.
  • include_inherited (bool) – Whether to include members who only have access from a parent shared folder.
  • limit (int) – Number of members to return max per query. Defaults to 100 if no limit is specified.
Return type:

dropbox.sharing.SharedFileMembers

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ListFileMembersError
sharing_list_file_members_batch(files, limit=10)

Get members of multiple files at once. The arguments to this route are more limited, and the limit on query result size per file is more strict. To customize the results more, use the individual file endpoint. Inherited users and groups are not included in the result, and permissions are not returned for this endpoint.

Parameters:
  • files (list) – Files for which to return members.
  • limit (int) – Number of members to return max per query. Defaults to 10 if no limit is specified.
Return type:

list

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_list_file_members_continue(cursor)

Once a cursor has been retrieved from sharing_list_file_members() or sharing_list_file_members_batch(), use this to paginate through all shared file members.

Parameters:cursor (str) – The cursor returned by your last call to sharing_list_file_members(), sharing_list_file_members_continue(), or sharing_list_file_members_batch().
Return type:dropbox.sharing.SharedFileMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFileMembersContinueError
sharing_list_folder_members(shared_folder_id, actions=None, limit=1000)

Returns shared folder membership by its folder ID.

Parameters:shared_folder_id (str) – The ID for the shared folder.
Return type:dropbox.sharing.SharedFolderMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.SharedFolderAccessError
sharing_list_folder_members_continue(cursor)

Once a cursor has been retrieved from sharing_list_folder_members(), use this to paginate through all shared folder members.

Parameters:cursor (str) – The cursor returned by your last call to sharing_list_folder_members() or sharing_list_folder_members_continue().
Return type:dropbox.sharing.SharedFolderMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFolderMembersContinueError
sharing_list_folders(limit=1000, actions=None)

Return the list of all shared folders the current user has access to.

Parameters:
  • limit (int) – The maximum number of results to return per request.
  • actions (Nullable) – A list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:

dropbox.sharing.ListFoldersResult

sharing_list_folders_continue(cursor)

Once a cursor has been retrieved from sharing_list_folders(), use this to paginate through all shared folders. The cursor must come from a previous call to sharing_list_folders() or sharing_list_folders_continue().

Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.sharing.ListFoldersResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFoldersContinueError
sharing_list_mountable_folders(limit=1000, actions=None)

Return the list of all shared folders the current user can mount or unmount.

Parameters:
  • limit (int) – The maximum number of results to return per request.
  • actions (Nullable) – A list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:

dropbox.sharing.ListFoldersResult

sharing_list_mountable_folders_continue(cursor)

Once a cursor has been retrieved from sharing_list_mountable_folders(), use this to paginate through all mountable shared folders. The cursor must come from a previous call to sharing_list_mountable_folders() or sharing_list_mountable_folders_continue().

Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.sharing.ListFoldersResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFoldersContinueError
sharing_list_received_files(limit=100, actions=None)

Returns a list of all files shared with current user. Does not include files the user has received via shared folders, and does not include unclaimed invitations.

Parameters:
  • limit (int) – Number of files to return max per query. Defaults to 100 if no limit is specified.
  • actions (Nullable) – A list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:

dropbox.sharing.ListFilesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_list_received_files_continue(cursor)

Get more results with a cursor from sharing_list_received_files().

Parameters:cursor (str) – Cursor in ListFilesResult.cursor.
Return type:dropbox.sharing.ListFilesResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFilesContinueError

List shared links of this user. If no path is given, returns a list of all shared links for the current user. If a non-empty path is given, returns a list of all shared links that allow access to the given path - direct links to the given path and links to parent folders of the given path. Links to parent folders can be suppressed by setting direct_only to true.

Parameters:
Return type:

dropbox.sharing.ListSharedLinksResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ListSharedLinksError

Modify the shared link’s settings. If the requested visibility conflict with the shared links policy of the team or the shared folder (in case the linked file is part of a shared folder) then the LinkPermissions.resolved_visibility of the returned dropbox.sharing.SharedLinkMetadata will reflect the actual visibility of the shared link and the LinkPermissions.requested_visibility will reflect the requested visibility.

Parameters:
  • url (str) – URL of the shared link to change its settings.
  • settings (dropbox.sharing.SharedLinkSettings) – Set of settings for the shared link.
  • remove_expiration (bool) – If set to true, removes the expiration of the shared link.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ModifySharedLinkSettingsError
sharing_mount_folder(shared_folder_id)

The current user mounts the designated folder. Mount a shared folder for a user after they have been added as a member. Once mounted, the shared folder will appear in their Dropbox.

Parameters:shared_folder_id (str) – The ID of the shared folder to mount.
Return type:dropbox.sharing.SharedFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.MountFolderError
sharing_relinquish_file_membership(file)

The current user relinquishes their membership in the designated file. Note that the current user may still have inherited access to this file through the parent folder.

Parameters:file (str) – The path or id for the file.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.RelinquishFileMembershipError
sharing_relinquish_folder_membership(shared_folder_id, leave_a_copy=False)

The current user relinquishes their membership in the designated shared folder and will no longer have access to the folder. A folder owner cannot relinquish membership in their own folder. This will run synchronously if leave_a_copy is false, and asynchronously if leave_a_copy is true.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • leave_a_copy (bool) – Keep a copy of the folder’s contents upon relinquishing membership.
Return type:

dropbox.sharing.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RelinquishFolderMembershipError
sharing_remove_file_member(file, member)

Identical to remove_file_member_2 but with less information returned.

Parameters:
  • file (str) – File from which to remove members.
  • member (dropbox.sharing.MemberSelector) – Member to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user’s main account corresponds to that email address.
Return type:

dropbox.sharing.FileMemberActionIndividualResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFileMemberError
sharing_remove_file_member_2(file, member)

Removes a specified member from the file.

Parameters:
  • file (str) – File from which to remove members.
  • member (dropbox.sharing.MemberSelector) – Member to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user’s main account corresponds to that email address.
Return type:

dropbox.sharing.FileMemberRemoveActionResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFileMemberError
sharing_remove_folder_member(shared_folder_id, member, leave_a_copy)

Allows an owner or editor (if the ACL update policy allows) of a shared folder to remove another member.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • member (dropbox.sharing.MemberSelector) – The member to remove from the folder.
  • leave_a_copy (bool) – If true, the removed user will keep their copy of the folder after it’s unshared, assuming it was mounted. Otherwise, it will be removed from their Dropbox. Also, this must be set to false when kicking a group.
Return type:

dropbox.sharing.LaunchResultBase

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFolderMemberError

Revoke a shared link. Note that even after revoking a shared link to a file, the file may be accessible if there are shared links leading to any of the file parent folders. To list all shared links that enable access to a specific file, you can use the sharing_list_shared_links() with the file as the ListSharedLinksArg.path argument.

Parameters:url (str) – URL of the shared link.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.RevokeSharedLinkError
sharing_set_access_inheritance(shared_folder_id, access_inheritance=AccessInheritance('inherit', None))

Change the inheritance policy of an existing Shared Folder. Only permitted for shared folders in a shared team root. If a ShareFolderLaunch.async_job_id is returned, you’ll need to call sharing_check_share_job_status() until the action completes to get the metadata for the folder.

Parameters:
  • access_inheritance (dropbox.sharing.AccessInheritance) – The access inheritance settings for the folder.
  • shared_folder_id (str) – The ID for the shared folder.
Return type:

dropbox.sharing.ShareFolderLaunch

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SetAccessInheritanceError
sharing_share_folder(path, acl_update_policy=None, force_async=False, member_policy=None, shared_link_policy=None, viewer_info_policy=None, access_inheritance=AccessInheritance('inherit', None), actions=None, link_settings=None)

Share a folder with collaborators. Most sharing will be completed synchronously. Large folders will be completed asynchronously. To make testing the async case repeatable, set ShareFolderArg.force_async. If a ShareFolderLaunch.async_job_id is returned, you’ll need to call sharing_check_share_job_status() until the action completes to get the metadata for the folder.

Parameters:
  • actions (Nullable) – A list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
  • link_settings (Nullable) – Settings on the link for this folder.
Return type:

dropbox.sharing.ShareFolderLaunch

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ShareFolderError
sharing_transfer_folder(shared_folder_id, to_dropbox_id)

Transfer ownership of a shared folder to a member of the shared folder. User must have AccessLevel.owner access to the shared folder to perform a transfer.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • to_dropbox_id (str) – A account or team member ID to transfer ownership to.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.TransferFolderError
sharing_unmount_folder(shared_folder_id)

The current user unmounts the designated folder. They can re-mount the folder at a later time using sharing_mount_folder().

Parameters:shared_folder_id (str) – The ID for the shared folder.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.UnmountFolderError
sharing_unshare_file(file)

Remove all members from this file. Does not remove inherited members.

Parameters:file (str) – The file to unshare.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.UnshareFileError
sharing_unshare_folder(shared_folder_id, leave_a_copy=False)

Allows a shared folder owner to unshare the folder. You’ll need to call sharing_check_job_status() to determine if the action has completed successfully.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • leave_a_copy (bool) – If true, members of this shared folder will get a copy of this folder after it’s unshared. Otherwise, it will be removed from their Dropbox. The current user, who is an owner, will always retain their copy.
Return type:

dropbox.sharing.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.UnshareFolderError
sharing_update_file_member(file, member, access_level)

Changes a member’s access on a shared file.

Return type:dropbox.sharing.MemberAccessLevelResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.FileMemberActionError
sharing_update_folder_member(shared_folder_id, member, access_level)

Allows an owner or editor of a shared folder to update another member’s permissions.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • member (dropbox.sharing.MemberSelector) – The member of the shared folder to update. Only the MemberSelector.dropbox_id may be set at this time.
  • access_level (dropbox.sharing.AccessLevel) – The new access level for member. AccessLevel.owner is disallowed.
Return type:

dropbox.sharing.MemberAccessLevelResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.UpdateFolderMemberError
sharing_update_folder_policy(shared_folder_id, member_policy=None, acl_update_policy=None, viewer_info_policy=None, shared_link_policy=None, link_settings=None, actions=None)

Update the sharing policies for a shared folder. User must have AccessLevel.owner access to the shared folder to update its policies.

Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • member_policy (Nullable) – Who can be a member of this shared folder. Only applicable if the current user is on a team.
  • acl_update_policy (Nullable) – Who can add and remove members of this shared folder.
  • viewer_info_policy (Nullable) – Who can enable/disable viewer info for this shared folder.
  • shared_link_policy (Nullable) – The policy to apply to shared links created for content inside this shared folder. The current user must be on a team to set this policy to SharedLinkPolicy.members.
  • link_settings (Nullable) – Settings on the link for this folder.
  • actions (Nullable) – A list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:

dropbox.sharing.SharedFolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.UpdateFolderPolicyError
users_get_account(account_id)

Get information about a user’s account.

Parameters:account_id (str) – A user’s account identifier.
Return type:dropbox.users.BasicAccount
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.users.GetAccountError
users_get_account_batch(account_ids)

Get information about multiple user accounts. At most 300 accounts may be queried per request.

Parameters:account_ids (list) – List of user account identifiers. Should not contain any duplicate account IDs.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.users.GetAccountBatchError
users_get_current_account()

Get information about the current user’s account.

Return type:dropbox.users.FullAccount
users_get_space_usage()

Get the space usage information for the current user’s account.

Return type:dropbox.users.SpaceUsage
with_path_root(path_root)

Creates a clone of the Dropbox instance with the Dropbox-API-Path-Root header as the appropriate serialized instance of PathRoot.

For more information, see https://www.dropbox.com/developers/reference/namespace-guide#pathrootmodes

Parameters:path_root (PathRoot) – instance of PathRoot to serialize into the headers field
Returns:A :class: Dropbox
Return type:Dropbox
class dropbox.dropbox.DropboxTeam(oauth2_access_token, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100)

Bases: dropbox.dropbox._DropboxTransport, dropbox.base_team.DropboxTeamBase

Use this class to make requests to the Dropbox API using a team’s access token. Methods of this class are meant to act on the team, but there is also an as_user() method for assuming a team member’s identity.

__init__(oauth2_access_token, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100)
Parameters:
  • oauth2_access_token (str) – OAuth2 access token for making client requests.
  • max_retries_on_error (int) – On 5xx errors, the number of times to retry.
  • max_retries_on_rate_limit (Optional[int]) – On 429 errors, the number of times to retry. If None, always retries.
  • user_agent (str) – The user agent to use when making requests. This helps us identify requests coming from your application. We recommend you use the format “AppName/Version”. If set, we append “/OfficialDropboxPythonSDKv2/__version__” to the user_agent,
  • session (requests.sessions.Session) – If not provided, a new session (connection pool) is created. To share a session across multiple clients, use create_session().
  • headers (dict) – Additional headers to add to requests.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 30 seconds.
as_admin(team_member_id)

Allows a team credential to assume the identity of an administrator on the team and perform operations on any team-owned content.

Parameters:team_member_id (str) – team member id of administrator to perform actions with
Returns:A Dropbox object that can be used to query on behalf of this admin of the team.
Return type:Dropbox
as_user(team_member_id)

Allows a team credential to assume the identity of a member of the team.

Parameters:team_member_id (str) – team member id of team member to perform actions with
Returns:A Dropbox object that can be used to query on behalf of this member of the team.
Return type:Dropbox
clone(oauth2_access_token=None, max_retries_on_error=None, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=None)

Creates a new copy of the Dropbox client with the same defaults unless modified by arguments to clone()

See constructor for original parameter descriptions.

Returns:New instance of Dropbox clent
Return type:Dropbox
file_properties_templates_add_for_team(name, description, fields)

Add a template associated with a team. See file_properties_properties_add() to add properties to a file or folder. Note: this endpoint will create team-owned templates.

Return type:dropbox.file_properties.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_get_for_team(template_id)

Get the schema for a specified template.

Parameters:template_id (str) – An identifier for template added by route See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:dropbox.file_properties.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_list_for_team()

Get the template identifiers for a team. To get the schema of each template use file_properties_templates_get_for_team().

Return type:dropbox.file_properties.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_remove_for_team(template_id)

Permanently removes the specified template created from file_properties_templates_add_for_user(). All properties associated with the template will also be removed. This action cannot be undone.

Parameters:template_id (str) – An identifier for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_update_for_team(template_id, name=None, description=None, add_fields=None)

Update a template associated with a team. This route can update the template name, the template description and add optional properties to templates.

Parameters:
  • template_id (str) – An identifier for template added by See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
  • name (Nullable) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable) – Description for the new template. Template descriptions can be up to 1024 bytes.
  • add_fields (Nullable) – Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:

dropbox.file_properties.UpdateTemplateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
request(route, namespace, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API and in the process validates that the route argument and result are the expected data types. The request_arg is converted to JSON based on the arg_data_type. Likewise, the response is deserialized from JSON and converted to an object based on the {result,error}_data_type.

Parameters:
  • host – The Dropbox API host to connect to.
  • route (datatypes.stone_base.Route) – The route to make the request to.
  • request_arg – Argument for the route that conforms to the validator specified by route.arg_type.
  • request_binary – String or file pointer representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result.

request_json_object(host, route_name, route_style, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API, taking a JSON-serializable Python object as an argument, and returning one as a response.

Parameters:
  • host – The Dropbox API host to connect to.
  • route_name – The name of the route to invoke.
  • route_style – The style of the route.
  • request_arg (str) – A JSON-serializable Python object representing the argument for the route.
  • request_binary (Optional[bytes]) – Bytes representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result as a JSON-serializable Python object.

request_json_string(host, func_name, route_style, request_json_arg, request_binary, timeout=None)

See request_json_string_with_retry() for description of parameters.

request_json_string_with_retry(host, route_name, route_style, request_json_arg, request_binary, timeout=None)

See request_json_object() for description of parameters.

Parameters:request_json_arg – A string representing the serialized JSON argument to the route.
team_devices_list_member_devices(team_member_id, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team’s member.

Parameters:
  • team_member_id (str) – The team’s member id.
  • include_web_sessions (bool) – Whether to list web sessions of the team’s member.
  • include_desktop_clients (bool) – Whether to list linked desktop devices of the team’s member.
  • include_mobile_clients (bool) – Whether to list linked mobile devices of the team’s member.
Return type:

dropbox.team.ListMemberDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListMemberDevicesError
team_devices_list_members_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team. Permission : Team member file access.

Parameters:
  • cursor (Nullable) – At the first call to the team_devices_list_members_devices() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of team devices.
  • include_web_sessions (bool) – Whether to list web sessions of the team members.
  • include_desktop_clients (bool) – Whether to list desktop clients of the team members.
  • include_mobile_clients (bool) – Whether to list mobile clients of the team members.
Return type:

dropbox.team.ListMembersDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListMembersDevicesError
team_devices_list_team_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team. Permission : Team member file access.

Parameters:
  • cursor (Nullable) – At the first call to the team_devices_list_team_devices() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of team devices.
  • include_web_sessions (bool) – Whether to list web sessions of the team members.
  • include_desktop_clients (bool) – Whether to list desktop clients of the team members.
  • include_mobile_clients (bool) – Whether to list mobile clients of the team members.
Return type:

dropbox.team.ListTeamDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListTeamDevicesError
team_devices_revoke_device_session(arg)

Revoke a device session of a team’s member.

Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.RevokeDeviceSessionError
team_devices_revoke_device_session_batch(revoke_devices)

Revoke a list of device sessions of team members.

Return type:dropbox.team.RevokeDeviceSessionBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.RevokeDeviceSessionBatchError
team_features_get_values(features)

Get the values for one or more featues. This route allows you to check your account’s capability for what feature you can access or what value you have for certain features. Permission : Team information.

Parameters:features (list) – A list of features in dropbox.team.Feature. If the list is empty, this route will return dropbox.team.FeaturesGetValuesBatchError.
Return type:dropbox.team.FeaturesGetValuesBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.FeaturesGetValuesBatchError
team_get_info()

Retrieves information about a team.

Return type:dropbox.team.TeamGetInfoResult
team_groups_create(group_name, group_external_id=None, group_management_type=None)

Creates a new, empty group, with a requested name. Permission : Team member management.

Parameters:
  • group_name (str) – Group name.
  • group_external_id (Nullable) – The creator of a team can associate an arbitrary external ID to the group.
  • group_management_type (Nullable) – Whether the team can be managed by selected users, or only by team admins.
Return type:

dropbox.team.GroupFullInfo

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupCreateError
team_groups_delete(arg)

Deletes a group. The group is deleted immediately. However the revoking of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. Permission : Team member management.

Parameters:arg (dropbox.team.GroupSelector) – Argument for selecting a single group, either by group_id or by external group ID.
Return type:dropbox.team.LaunchEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupDeleteError
team_groups_get_info(arg)

Retrieves information about one or more groups. Note that the optional field GroupFullInfo.members is not returned for system-managed groups. Permission : Team Information.

Parameters:arg (dropbox.team.GroupsSelector) – Argument for selecting a list of groups, either by group_ids, or external group IDs.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsGetInfoError
team_groups_job_status_get(async_job_id)

Once an async_job_id is returned from team_groups_delete(), team_groups_members_add() , or team_groups_members_remove() use this method to poll the status of granting/revoking group members’ access to group-owned resources. Permission : Team member management.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsPollError
team_groups_list(limit=1000)

Lists groups on a team. Permission : Team Information.

Parameters:limit (int) – Number of results to return per call.
Return type:dropbox.team.GroupsListResult
team_groups_list_continue(cursor)

Once a cursor has been retrieved from team_groups_list(), use this to paginate through all groups. Permission : Team Information.

Parameters:cursor (str) – Indicates from what point to get the next set of groups.
Return type:dropbox.team.GroupsListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsListContinueError
team_groups_members_add(group, members, return_members=True)

Adds members to a group. The members are added immediately. However the granting of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. Permission : Team member management.

Parameters:
  • group (dropbox.team.GroupSelector) – Group to which users will be added.
  • members (list) – List of users to be added to the group.
Return type:

dropbox.team.GroupMembersChangeResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupMembersAddError
team_groups_members_list(group, limit=1000)

Lists members of a group. Permission : Team Information.

Parameters:
  • group (dropbox.team.GroupSelector) – The group whose members are to be listed.
  • limit (int) – Number of results to return per call.
Return type:

dropbox.team.GroupsMembersListResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupSelectorError
team_groups_members_list_continue(cursor)

Once a cursor has been retrieved from team_groups_members_list(), use this to paginate through all members of the group. Permission : Team information.

Parameters:cursor (str) – Indicates from what point to get the next set of groups.
Return type:dropbox.team.GroupsMembersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsMembersListContinueError
team_groups_members_remove(group, users, return_members=True)

Removes members from a group. The members are removed immediately. However the revoking of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. This method permits removing the only owner of a group, even in cases where this is not possible via the web client. Permission : Team member management.

Parameters:
  • group (dropbox.team.GroupSelector) – Group from which users will be removed.
  • users (list) – List of users to be removed from the group.
Return type:

dropbox.team.GroupMembersChangeResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupMembersRemoveError
team_groups_members_set_access_type(group, user, access_type, return_members=True)

Sets a member’s access type in a group. Permission : Team member management.

Parameters:
  • access_type (dropbox.team.GroupAccessType) – New group access type the user will have.
  • return_members (bool) – Whether to return the list of members in the group. Note that the default value will cause all the group members to be returned in the response. This may take a long time for large groups.
Return type:

list

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupMemberSetAccessTypeError
team_groups_update(group, return_members=True, new_group_name=None, new_group_external_id=None, new_group_management_type=None)

Updates a group’s name and/or external ID. Permission : Team member management.

Parameters:
  • group (dropbox.team.GroupSelector) – Specify a group.
  • new_group_name (Nullable) – Optional argument. Set group name to this if provided.
  • new_group_external_id (Nullable) – Optional argument. New group external ID. If the argument is None, the group’s external_id won’t be updated. If the argument is empty string, the group’s external id will be cleared.
  • new_group_management_type (Nullable) – Set new group management type, if provided.
Return type:

dropbox.team.GroupFullInfo

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupUpdateError
team_linked_apps_list_member_linked_apps(team_member_id)

List all linked applications of the team member. Note, this endpoint does not list any team-linked applications.

Parameters:team_member_id (str) – The team member id.
Return type:dropbox.team.ListMemberAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListMemberAppsError
team_linked_apps_list_members_linked_apps(cursor=None)

List all applications linked to the team members’ accounts. Note, this endpoint does not list any team-linked applications.

Parameters:cursor (Nullable) – At the first call to the team_linked_apps_list_members_linked_apps() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of the team applications.
Return type:dropbox.team.ListMembersAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListMembersAppsError
team_linked_apps_list_team_linked_apps(cursor=None)

List all applications linked to the team members’ accounts. Note, this endpoint doesn’t list any team-linked applications.

Parameters:cursor (Nullable) – At the first call to the team_linked_apps_list_team_linked_apps() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of the team applications.
Return type:dropbox.team.ListTeamAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListTeamAppsError
team_linked_apps_revoke_linked_app(app_id, team_member_id, keep_app_folder=True)

Revoke a linked application of the team member.

Parameters:
  • app_id (str) – The application’s unique id.
  • team_member_id (str) – The unique id of the member owning the device.
  • keep_app_folder (bool) – Whether to keep the application dedicated folder (in case the application uses one).
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.RevokeLinkedAppError
team_linked_apps_revoke_linked_app_batch(revoke_linked_app)

Revoke a list of linked applications of the team members.

Return type:dropbox.team.RevokeLinkedAppBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.RevokeLinkedAppBatchError
team_log_get_events(limit=1000, account_id=None, time=None, category=None)

Retrieves team events. Events have a lifespan of two years. Events older than two years will not be returned. Many attributes note ‘may be missing due to historical data gap’. Note that the file_operations category and & analogous paper events are not available on all Dropbox Business plans. Use features/get_values to check for this feature. Permission : Team Auditing.

Parameters:
  • limit (int) – The maximal number of results to return per call. Note that some calls may not return limit number of events, and may even return no events, even with has_more set to true. In this case, callers should fetch again using team_log_get_events_continue().
  • account_id (Nullable) – Filter the events by account ID. Return ony events with this account_id as either Actor, Context, or Participants.
  • time (Nullable) – Filter by time range.
  • category (Nullable) – Filter the returned events to a single category.
Return type:

dropbox.team_log.GetTeamEventsResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team_log.GetTeamEventsError
team_log_get_events_continue(cursor)

Once a cursor has been retrieved from team_log_get_events(), use this to paginate through all events. Permission : Team Auditing.

Parameters:cursor (str) – Indicates from what point to get the next set of events.
Return type:dropbox.team_log.GetTeamEventsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team_log.GetTeamEventsContinueError
team_member_space_limits_excluded_users_add(users=None)

Add users to member space limits excluded users list.

Parameters:users (Nullable) – List of users to be added/removed.
Return type:dropbox.team.ExcludedUsersUpdateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersUpdateError
team_member_space_limits_excluded_users_list(limit=1000)

List member space limits excluded users.

Parameters:limit (int) – Number of results to return per call.
Return type:dropbox.team.ExcludedUsersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersListError
team_member_space_limits_excluded_users_list_continue(cursor)

Continue listing member space limits excluded users.

Parameters:cursor (str) – Indicates from what point to get the next set of users.
Return type:dropbox.team.ExcludedUsersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersListContinueError
team_member_space_limits_excluded_users_remove(users=None)

Remove users from member space limits excluded users list.

Parameters:users (Nullable) – List of users to be added/removed.
Return type:dropbox.team.ExcludedUsersUpdateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersUpdateError
team_member_space_limits_get_custom_quota(users)

Get users custom quota. Returns none as the custom quota if none was set. A maximum of 1000 members can be specified in a single call.

Parameters:users (list) – List of users.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.CustomQuotaError
team_member_space_limits_remove_custom_quota(users)

Remove users custom quota. A maximum of 1000 members can be specified in a single call.

Parameters:users (list) – List of users.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.CustomQuotaError
team_member_space_limits_set_custom_quota(users_and_quotas)

Set users custom quota. Custom quota has to be at least 15GB. A maximum of 1000 members can be specified in a single call.

Parameters:users_and_quotas (list) – List of users and their custom quotas.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.SetCustomQuotaError
team_members_add(new_members, force_async=False)

Adds members to a team. Permission : Team member management A maximum of 20 members can be specified in a single call. If no Dropbox account exists with the email address specified, a new Dropbox account will be created with the given email address, and that account will be invited to the team. If a personal Dropbox account exists with the email address specified in the call, this call will create a placeholder Dropbox account for the user on the team and send an email inviting the user to migrate their existing personal account onto the team. Team member management apps are required to set an initial given_name and surname for a user to use in the team invitation and for ‘Perform as team member’ actions taken on the user before they become ‘active’.

Parameters:
  • new_members (list) – Details of new members to be added to the team.
  • force_async (bool) – Whether to force the add to happen asynchronously.
Return type:

dropbox.team.MembersAddLaunch

team_members_add_job_status_get(async_job_id)

Once an async_job_id is returned from team_members_add() , use this to poll the status of the asynchronous request. Permission : Team member management.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.MembersAddJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_get_info(members)

Returns information about multiple team members. Permission : Team information This endpoint will return MembersGetInfoItem.id_not_found, for IDs (or emails) that cannot be matched to a valid team member.

Parameters:members (list) – List of team members.
Return type:list
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersGetInfoError
team_members_list(limit=1000, include_removed=False)

Lists members of a team. Permission : Team information.

Parameters:
  • limit (int) – Number of results to return per call.
  • include_removed (bool) – Whether to return removed members.
Return type:

dropbox.team.MembersListResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersListError
team_members_list_continue(cursor)

Once a cursor has been retrieved from team_members_list(), use this to paginate through all team members. Permission : Team information.

Parameters:cursor (str) – Indicates from what point to get the next set of members.
Return type:dropbox.team.MembersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersListContinueError
team_members_move_former_member_files(user, transfer_dest_id, transfer_admin_id)

Moves removed member’s files to a different member. This endpoint initiates an asynchronous job. To obtain the final result of the job, the client should periodically poll team_members_move_former_member_files_job_status_check(). Permission : Team member management.

Parameters:
Return type:

dropbox.team.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersTransferFormerMembersFilesError
team_members_move_former_member_files_job_status_check(async_job_id)

Once an async_job_id is returned from team_members_move_former_member_files() , use this to poll the status of the asynchronous request. Permission : Team member management.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_recover(user)

Recover a deleted member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Parameters:user (dropbox.team.UserSelectorArg) – Identity of user to recover.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersRecoverError
team_members_remove(user, wipe_data=True, transfer_dest_id=None, transfer_admin_id=None, keep_account=False)

Removes a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. Accounts can be recovered via team_members_recover() for a 7 day period or until the account has been permanently deleted or transferred to another account (whichever comes first). Calling team_members_add() while a user is still recoverable on your team will return with MemberAddResult.user_already_on_team. Accounts can have their files transferred via the admin console for a limited time, based on the version history length associated with the team (120 days for most teams). This endpoint may initiate an asynchronous job. To obtain the final result of the job, the client should periodically poll team_members_remove_job_status_get().

Parameters:
  • transfer_dest_id (Nullable) – If provided, files from the deleted member account will be transferred to this user.
  • transfer_admin_id (Nullable) – If provided, errors during the transfer process will be sent via email to this user. If the transfer_dest_id argument was provided, then this argument must be provided as well.
  • keep_account (bool) – Downgrade the member to a Basic account. The user will retain the email address associated with their Dropbox account and data in their account that is not restricted to team members. In order to keep the account the argument wipe_data should be set to False.
Return type:

dropbox.team.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersRemoveError
team_members_remove_job_status_get(async_job_id)

Once an async_job_id is returned from team_members_remove() , use this to poll the status of the asynchronous request. Permission : Team member management.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_send_welcome_email(arg)

Sends welcome email to pending team member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. No-op if team member is not pending.

Parameters:arg (dropbox.team.UserSelectorArg) – Argument for selecting a single user, either by team_member_id, external_id or email.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersSendWelcomeError
team_members_set_admin_permissions(user, new_role)

Updates a team member’s permissions. Permission : Team member management.

Parameters:
Return type:

dropbox.team.MembersSetPermissionsResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetPermissionsError
team_members_set_profile(user, new_email=None, new_external_id=None, new_given_name=None, new_surname=None, new_persistent_id=None, new_is_directory_restricted=None)

Updates a team member’s profile. Permission : Team member management.

Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of user whose profile will be set.
  • new_email (Nullable) – New email for member.
  • new_external_id (Nullable) – New external ID for member.
  • new_given_name (Nullable) – New given name for member.
  • new_surname (Nullable) – New surname for member.
  • new_persistent_id (Nullable) – New persistent ID. This field only available to teams using persistent ID SAML configuration.
  • new_is_directory_restricted (Nullable) – New value for whether the user is a directory restricted user.
Return type:

dropbox.team.TeamMemberInfo

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetProfileError
team_members_suspend(user, wipe_data=True)

Suspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Parameters:wipe_data (bool) – If provided, controls if the user’s data will be deleted on their linked devices.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersSuspendError
team_members_unsuspend(user)

Unsuspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Parameters:user (dropbox.team.UserSelectorArg) – Identity of user to unsuspend.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersUnsuspendError
team_namespaces_list(limit=1000)

Returns a list of all team-accessible namespaces. This list includes team folders, shared folders containing team members, team members’ home namespaces, and team members’ app folders. Home namespaces and app folders are always owned by this team or members of the team, but shared folders may be owned by other users or other teams. Duplicates may occur in the list.

Parameters:limit (int) – Specifying a value here has no effect.
Return type:dropbox.team.TeamNamespacesListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamNamespacesListError
team_namespaces_list_continue(cursor)

Once a cursor has been retrieved from team_namespaces_list(), use this to paginate through all team-accessible namespaces. Duplicates may occur in the list.

Parameters:cursor (str) – Indicates from what point to get the next set of team-accessible namespaces.
Return type:dropbox.team.TeamNamespacesListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamNamespacesListContinueError
team_properties_template_add(name, description, fields)

Permission : Team member file access.

Return type:dropbox.team.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ModifyTemplateError
team_properties_template_get(template_id)

Permission : Team member file access.

Parameters:template_id (str) – An identifier for template added by route See team_templates_add_for_user() or team_templates_add_for_team().
Return type:dropbox.team.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TemplateError
team_properties_template_list()

Permission : Team member file access.

Return type:dropbox.team.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TemplateError
team_properties_template_update(template_id, name=None, description=None, add_fields=None)

Permission : Team member file access.

Parameters:
  • template_id (str) – An identifier for template added by See team_templates_add_for_user() or team_templates_add_for_team().
  • name (Nullable) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable) – Description for the new template. Template descriptions can be up to 1024 bytes.
  • add_fields (Nullable) – Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:

dropbox.team.UpdateTemplateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ModifyTemplateError
team_reports_get_activity(start_date=None, end_date=None)

Retrieves reporting data about a team’s user activity.

Parameters:
  • start_date (Nullable) – Optional starting date (inclusive).
  • end_date (Nullable) – Optional ending date (exclusive).
Return type:

dropbox.team.GetActivityReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_devices(start_date=None, end_date=None)

Retrieves reporting data about a team’s linked devices.

Parameters:
  • start_date (Nullable) – Optional starting date (inclusive).
  • end_date (Nullable) – Optional ending date (exclusive).
Return type:

dropbox.team.GetDevicesReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_membership(start_date=None, end_date=None)

Retrieves reporting data about a team’s membership.

Parameters:
  • start_date (Nullable) – Optional starting date (inclusive).
  • end_date (Nullable) – Optional ending date (exclusive).
Return type:

dropbox.team.GetMembershipReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_storage(start_date=None, end_date=None)

Retrieves reporting data about a team’s storage usage.

Parameters:
  • start_date (Nullable) – Optional starting date (inclusive).
  • end_date (Nullable) – Optional ending date (exclusive).
Return type:

dropbox.team.GetStorageReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_team_folder_activate(team_folder_id)

Sets an archived team folder’s status to active. Permission : Team member file access.

Parameters:team_folder_id (str) – The ID of the team folder.
Return type:dropbox.team.TeamFolderMetadata
team_team_folder_archive(team_folder_id, force_async_off=False)

Sets an active team folder’s status to archived and removes all folder and file members. Permission : Team member file access.

Parameters:force_async_off (bool) – Whether to force the archive to happen synchronously.
Return type:dropbox.team.TeamFolderArchiveLaunch
team_team_folder_archive_check(async_job_id)

Returns the status of an asynchronous job for archiving a team folder. Permission : Team member file access.

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.TeamFolderArchiveJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_team_folder_create(name, sync_setting=None)

Creates a new, active, team folder with no members. Permission : Team member file access.

Parameters:
  • name (str) – Name for the new team folder.
  • sync_setting (Nullable) – The sync setting to apply to this team folder. Only permitted if the team has team selective sync enabled.
Return type:

dropbox.team.TeamFolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.TeamFolderCreateError
team_team_folder_get_info(team_folder_ids)

Retrieves metadata for team folders. Permission : Team member file access.

Parameters:team_folder_ids (list) – The list of team folder IDs.
Return type:list
team_team_folder_list(limit=1000)

Lists all team folders. Permission : Team member file access.

Parameters:limit (int) – The maximum number of results to return per request.
Return type:dropbox.team.TeamFolderListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderListError
team_team_folder_list_continue(cursor)

Once a cursor has been retrieved from team_team_folder_list(), use this to paginate through all team folders. Permission : Team member file access.

Parameters:cursor (str) – Indicates from what point to get the next set of team folders.
Return type:dropbox.team.TeamFolderListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderListContinueError
team_team_folder_permanently_delete(team_folder_id)

Permanently deletes an archived team folder. Permission : Team member file access.

Parameters:team_folder_id (str) – The ID of the team folder.
Return type:None
team_team_folder_rename(team_folder_id, name)

Changes an active team folder’s name. Permission : Team member file access.

Parameters:name (str) – New team folder name.
Return type:dropbox.team.TeamFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderRenameError
team_team_folder_update_sync_settings(team_folder_id, sync_setting=None, content_sync_settings=None)

Updates the sync settings on a team folder or its contents. Use of this endpoint requires that the team has team selective sync enabled.

Parameters:
  • sync_setting (Nullable) – Sync setting to apply to the team folder itself. Only meaningful if the team folder is not a shared team root.
  • content_sync_settings (Nullable) – Sync settings to apply to contents of this team folder.
Return type:

dropbox.team.TeamFolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.TeamFolderUpdateSyncSettingsError
team_token_get_authenticated_admin()

Returns the member profile of the admin who generated the team access token used to make the call.

Return type:dropbox.team.TokenGetAuthenticatedAdminResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TokenGetAuthenticatedAdminError
with_path_root(path_root)

Creates a clone of the Dropbox instance with the Dropbox-API-Path-Root header as the appropriate serialized instance of PathRoot.

For more information, see https://www.dropbox.com/developers/reference/namespace-guide#pathrootmodes

Parameters:path_root (PathRoot) – instance of PathRoot to serialize into the headers field
Returns:A :class: Dropbox
Return type:Dropbox
dropbox.dropbox.create_session(max_connections=8, proxies=None)

Creates a session object that can be used by multiple Dropbox and DropboxTeam instances. This lets you share a connection pool amongst them, as well as proxy parameters.

Parameters:
  • max_connections (int) – Maximum connection pool size.
  • proxies (dict) – See the requests module for more details.
Return type:

requests.sessions.Session. See the requests module for more details.