dropbox.dropbox
– Dropbox
- class dropbox.dropbox_client.Dropbox(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
Bases:
_DropboxTransport
,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=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
- 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, usecreate_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 100 seconds.
oauth2_refresh_token (str) – OAuth2 refresh token for refreshing access token
oauth2_access_token_expiration (datetime) – Expiration for oauth2_access_token
app_key (str) – application key of requesting application; used for token refresh
app_secret (str) – application secret of requesting application; used for token refresh Not required if PKCE was used to authorize the token
scope (list) – list of scopes to request on refresh. If left blank, refresh will request all available scopes for application
ca_certs (str) – a path to a file of concatenated CA certificates in PEM format. Has the same meaning as when using
ssl.wrap_socket()
.
- account_set_profile_photo(photo)
Sets a user’s profile photo.
- Route attributes:
scope: account_info.write
- Parameters:
photo (
dropbox.account.PhotoSourceArg
) – Image to set as the user’s new profile photo.- Return type:
dropbox.account.SetProfilePhotoResult
- Raises:
- If this raises, ApiError will contain:
dropbox.account.SetProfilePhotoError
- 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:
- Raises:
- If this raises, ApiError will contain:
- auth_token_revoke()
Disables the access token used to authenticate the call. If there is a corresponding refresh token for the access token, this disables that refresh token, as well as any other access tokens for that refresh token.
- Return type:
None
- check_and_refresh_access_token()
Checks if access token needs to be refreshed and refreshes if possible :return:
- check_app(query='')
This endpoint performs App Authentication, validating the supplied app key and secret, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the app key and secret valid.
- Parameters:
query (str) – The string that you’d like to be echoed back to you.
- Return type:
dropbox.check.EchoResult
- check_user(query='')
This endpoint performs User Authentication, validating the supplied access token, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the access token is valid.
- Route attributes:
scope: account_info.read
- Parameters:
query (str) – The string that you’d like to be echoed back to you.
- Return type:
dropbox.check.EchoResult
- 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, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=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 client
- Return type:
- close()
Cleans up all resources like the request session/network connection.
- 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.
- Route attributes:
scope: contacts.write
- Return type:
None
- contacts_delete_manual_contacts_batch(email_addresses)
Removes manually added contacts from the given list.
- Route attributes:
scope: contacts.write
- Parameters:
email_addresses (List[str]) – List of manually added contacts to be deleted.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- file_properties_properties_add(path, property_groups)
Add property groups to a Dropbox file. See
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
to create new templates.- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.file_properties.PropertyGroup
] property_groups: The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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, whereasfile_properties_properties_update()
will only delete fields that are explicitly marked for deletion.- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.file_properties.PropertyGroup
] property_groups: The property groups “snapshot” updates to force apply. No two groups in the input should refer to the same template.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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, seefile_properties_templates_update_for_user()
orfile_properties_templates_update_for_team()
. To remove a template, seefile_properties_templates_remove_for_user()
orfile_properties_templates_remove_for_team()
.- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
property_template_ids (List[str]) – A list of identifiers for a template created by
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- file_properties_properties_search(queries, template_filter=TemplateFilter('filter_none', None))
Search across property templates for particular property field values.
- Route attributes:
scope: files.metadata.read
- :param List[
dropbox.file_properties.PropertiesSearchQuery
] queries: Queries to search.
- Parameters:
template_filter (
dropbox.file_properties.TemplateFilter
) – Filter results to contain only properties associated with these template IDs.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.read
- Parameters:
cursor (str) – The cursor returned by your last call to
file_properties_properties_search()
orfile_properties_properties_search_continue()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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, whereasfile_properties_properties_overwrite()
will delete any fields that are omitted from a property group.- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.file_properties.PropertyGroupUpdate
] update_property_groups: The property groups “delta” updates to apply.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.write
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.metadata.read
- Parameters:
template_id (str) – An identifier for template added by route See
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.read
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.write
- Parameters:
template_id (str) – An identifier for a template created by
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.metadata.write
- Parameters:
template_id (str) – An identifier for template added by See
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
- :param
Nullable[List[
dropbox.file_properties.PropertyFieldTemplate
]] add_fields: Property field templates to be added to the group template. There can be up to 32 properties in a single template.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- file_requests_count()
Returns the total number of file requests owned by this user. Includes both open and closed file requests.
- Route attributes:
scope: file_requests.read
- Return type:
- file_requests_create(title, destination, deadline=None, open=True, description=None)
Creates a file request for this user.
- Route attributes:
scope: file_requests.write
- 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.
- :param Nullable[
dropbox.file_requests.FileRequestDeadline
] deadline: The deadline for the file request. Deadlines can only be set by Professional and Business accounts.
- Parameters:
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.
description (Nullable[str]) – A description of the file request.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- file_requests_delete(ids)
Delete a batch of closed file requests.
- Route attributes:
scope: file_requests.write
- Parameters:
ids (List[str]) – List IDs of the file requests to delete.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- file_requests_delete_all_closed()
Delete all closed file requests owned by this user.
- Route attributes:
scope: file_requests.write
- file_requests_get(id)
Returns the specified file request.
- Route attributes:
scope: file_requests.read
- Parameters:
id (str) – The ID of the file request to retrieve.
- Return type:
- 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.
- Route attributes:
scope: file_requests.read
- Return type:
- 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 tofile_requests_list_v2()
orfile_requests_list_continue()
.- Route attributes:
scope: file_requests.read
- Parameters:
cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: file_requests.read
- Parameters:
limit (int) – The maximum number of file requests that should be returned per request.
- Return type:
- file_requests_update(id, title=None, destination=None, deadline=UpdateFileRequestDeadline('no_update', None), open=None, description=None)
Update a file request.
- Route attributes:
scope: file_requests.write
- Parameters:
id (str) – The ID of the file request to update.
title (Nullable[str]) – The new title of the file request. Must not be empty.
destination (Nullable[str]) – 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[bool]) – Whether to set this file request as open or closed.
description (Nullable[str]) – The description of the file request.
- Return type:
- 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.
- Route attributes:
scope: files.metadata.read
- Parameters:
include_property_templates (Nullable[List[str]]) – If set to a valid list of template IDs,
FileMetadata.property_groups
is set for files with custom properties.- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_alpha_upload(f, path, mode=WriteMode('add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False, content_hash=None)
Create a new file with the contents provided in the request. Note that the behavior of this alpha endpoint is unstable and subject to change. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with
files_upload_session_start()
.- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
content_hash (Nullable[str]) – A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- Raises:
- If this raises, ApiError will contain:
- 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. 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.- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- 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, whilefiles_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 usefiles_copy_batch_check_v2()
to check the job status.- Route attributes:
scope: files.content.write
- :param List[
dropbox.files.RelocationPath
] entries: List of entries to be moved or copied. Each entry is
dropbox.files.RelocationPath
.
- Parameters:
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:
- 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()
.- Route attributes:
scope: files.content.write
- Parameters:
path (str) – The path to the file or folder you want to get a copy reference to.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_copy_reference_save(copy_reference, path)
Save a copy reference returned by
files_copy_reference_get()
to the user’s Dropbox.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- Raises:
- If this raises, ApiError will contain:
- files_create_folder(path, autorename=False)
Create a folder at a given path.
- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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. Usefiles_create_folder_batch_check()
to check the job status.- Route attributes:
scope: files.content.write
- Parameters:
paths (List[str]) – 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:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.files.PollError
- files_create_folder_v2(path, autorename=False)
Create a folder at a given path.
- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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
ordropbox.files.FolderMetadata
for the item at time of deletion, and not adropbox.files.DeletedMetadata
object.- Route attributes:
scope: files.content.write
- Parameters:
path (str) – Path in the user’s Dropbox to delete.
parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.content.write
- Return type:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- 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
ordropbox.files.FolderMetadata
for the item at time of deletion, and not adropbox.files.DeletedMetadata
object.- Route attributes:
scope: files.content.write
- Parameters:
path (str) – Path in the user’s Dropbox to delete.
parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_download(path, rev=None)
Download a file from a user’s Dropbox.
- Route attributes:
scope: files.content.read
- Parameters:
path (str) – The path of the file to download.
rev (Nullable[str]) – Please specify revision in
path
instead.
- Return type:
(
dropbox.files.FileMetadata
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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.
- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
path (str) – The path of the file to download.
rev (Nullable[str]) – Please specify revision in
path
instead.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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 any single file within must be less than 4 GB in size. The resulting zip must have fewer than 10,000 total file and folder entries, including the top level folder. The input cannot be a single file. Note: this endpoint does not support HTTP range requests.
- Route attributes:
scope: files.content.read
- Parameters:
path (str) – The path of the folder to download.
- Return type:
(
dropbox.files.DownloadZipResult
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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 any single file within must be less than 4 GB in size. The resulting zip must have fewer than 10,000 total file and folder entries, including the top level folder. The input cannot be a single file. Note: this endpoint does not support HTTP range requests.
- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
path (str) – The path of the folder to download.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_export(path, export_format=None)
Export a file from a user’s Dropbox. This route only supports exporting files that cannot be downloaded directly and whose
ExportResult.file_metadata
hasExportInfo.export_as
populated.- Route attributes:
scope: files.content.read
- Parameters:
path (str) – The path of the file to be exported.
export_format (Nullable[str]) – The file format to which the file should be exported. This must be one of the formats listed in the file’s export_options returned by
files_get_metadata()
. If none is specified, the default format (specified in export_as in file metadata) will be used.
- Return type:
(
dropbox.files.ExportResult
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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_format=None)
Export a file from a user’s Dropbox. This route only supports exporting files that cannot be downloaded directly and whose
ExportResult.file_metadata
hasExportInfo.export_as
populated.- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
path (str) – The path of the file to be exported.
export_format (Nullable[str]) – The file format to which the file should be exported. This must be one of the formats listed in the file’s export_options returned by
files_get_metadata()
. If none is specified, the default format (specified in export_as in file metadata) will be used.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_get_file_lock_batch(entries)
Return the lock metadata for the given list of paths.
- Route attributes:
scope: files.content.read
- :param List[
dropbox.files.LockFileArg
] entries: List of ‘entries’. Each ‘entry’ contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.metadata.read
- 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, otherwiseLookupError.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.
- :param Nullable[
dropbox.files.TemplateFilterBase
] include_property_groups: 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.content.read
- Parameters:
path (str) – The path of the file to preview.
rev (Nullable[str]) – Please specify revision in
path
instead.
- Return type:
(
dropbox.files.FileMetadata
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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.
- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
path (str) – The path of the file to preview.
rev (Nullable[str]) – Please specify revision in
path
instead.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_get_temporary_link(path)
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.
- Route attributes:
scope: files.content.read
- Parameters:
path (str) – The path to the file you want a temporary link to.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_get_temporary_upload_link(commit_info, duration=14400.0)
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 thedropbox.files.CommitInfo
previously provided tofiles_get_temporary_upload_link()
but evaluated only upon consumption. Hence, errors stemming from invaliddropbox.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://content.dropboxapi.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 successful 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.- Route attributes:
scope: files.content.write
- Parameters:
commit_info (
dropbox.files.CommitInfo
) – Contains the path and other optional modifiers for the future upload commit. Equivalent to the parameters provided tofiles_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:
- 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, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.
- Route attributes:
scope: files.content.read
- 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:
- If this raises, ApiError will contain:
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, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.
- Route attributes:
scope: files.content.read
- :param List[
dropbox.files.ThumbnailArg
] entries: List of files to get thumbnails.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.
- Route attributes:
scope: files.content.read
- 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:
- Raises:
- If this raises, ApiError will contain:
- files_get_thumbnail_to_file_v2(download_path, resource, 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, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.
- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
resource (
dropbox.files.PathOrLink
) – Information specifying which file to preview. This could be a path to a file, a shared link pointing to a file, or a shared link pointing to a folder, with a relative path.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:
- Raises:
- If this raises, ApiError will contain:
- files_get_thumbnail_v2(resource, 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, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.
- Route attributes:
scope: files.content.read
- Parameters:
resource (
dropbox.files.PathOrLink
) – Information specifying which file to preview. This could be a path to a file, a shared link pointing to a file, or a shared link pointing to a folder, with a relative path.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.PreviewResult
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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_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 isTrue
, callfiles_list_folder_continue()
with the returnedListFolderResult.cursor
to retrieve more entries. If you’re usingListFolderArg.recursive
set toTrue
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 eachdropbox.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 eachdropbox.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’sFolderSharingInfo.read_only
and set all its children’s read-only statuses to match. For eachdropbox.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 multiplefiles_list_folder()
orfiles_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.- Route attributes:
scope: files.metadata.read
- 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[int]) – 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.
- :param Nullable[
dropbox.files.SharedLink
] shared_link: 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.- :param Nullable[
dropbox.files.TemplateFilterBase
] include_property_groups: 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.
- Parameters:
include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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 forfiles_list_folder()
.- Route attributes:
scope: files.metadata.read
- Parameters:
cursor (str) – The cursor returned by your last call to
files_list_folder()
orfiles_list_folder_continue()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.read
- 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[int]) – 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.
- :param Nullable[
dropbox.files.SharedLink
] shared_link: 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.- :param Nullable[
dropbox.files.TemplateFilterBase
] include_property_groups: 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.
- Parameters:
include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.metadata.read
- Parameters:
cursor (str) – A cursor as returned by
files_list_folder()
orfiles_list_folder_continue()
. Cursors retrieved by settingListFolderArg.include_media_info
toTrue
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:
- Raises:
- If this raises, ApiError will contain:
- 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 toListRevisionsMode.id
. TheListRevisionsMode.id
mode is useful to retrieve revisions for a given file across moves or renames.- Route attributes:
scope: files.metadata.read
- 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:
- Raises:
- If this raises, ApiError will contain:
- files_lock_file_batch(entries)
Lock the files at the given paths. A locked file will be writable only by the lock holder. A successful response indicates that the file has been locked. Returns a list of the locked file paths and their metadata after this operation.
- Route attributes:
scope: files.content.write
- :param List[
dropbox.files.LockFileArg
] entries: List of ‘entries’. Each ‘entry’ contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- Raises:
- If this raises, ApiError will contain:
- 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 will return job ID immediately and do the async moving job in background. Please use
files_move_batch_check()
to check the job status.- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- 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. Note that we do not currently support case-only renaming. This route will replace
files_move_batch()
. The main difference is this route will return status for each entry, whilefiles_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 usefiles_move_batch_check_v2()
to check the job status.- Route attributes:
scope: files.content.write
- 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:
- 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. Note that we do not currently support case-only renaming.
- Route attributes:
scope: files.content.write
- Parameters:
allow_shared_folder (bool) – This flag has no effect.
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:
- Raises:
- If this raises, ApiError will contain:
- files_paper_create(f, path, import_format)
Creates a new Paper doc with the provided content.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
path (str) – The fully qualified path to the location in the user’s Dropbox where the Paper Doc should be created. This should include the document’s title and end with .paper.
import_format (
dropbox.files.ImportFormat
) – The format of the provided data.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_paper_update(f, path, import_format, doc_update_policy, paper_revision=None)
Updates an existing Paper doc with the provided content.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
path (str) – Path in the user’s Dropbox to update. The path must correspond to a Paper doc or an error will be returned.
import_format (
dropbox.files.ImportFormat
) – The format of the provided data.doc_update_policy (
dropbox.files.PaperDocUpdatePolicy
) – How the provided content should be applied to the doc.paper_revision (Nullable[int]) – The latest doc revision. Required when doc_update_policy is update. This value must match the current revision of the doc or error revision_mismatch will be returned.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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). If the given file or folder is not yet deleted, this route will first delete it. It is possible for this route to successfully delete, then fail to permanently delete. Note: This endpoint is only available for Dropbox Business apps.
- Route attributes:
scope: files.permanent_delete
- Parameters:
path (str) – Path in the user’s Dropbox to delete.
parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- files_properties_add(path, property_groups)
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.files.PropertyGroup
] property_groups: The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
dropbox.files.AddPropertiesError
- files_properties_overwrite(path, property_groups)
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.files.PropertyGroup
] property_groups: The property groups “snapshot” updates to force apply. No two groups in the input should refer to the same template.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
dropbox.files.InvalidPropertyGroupError
- files_properties_remove(path, property_template_ids)
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
property_template_ids (List[str]) – A list of identifiers for a template created by
files_templates_add_for_user()
orfiles_templates_add_for_team()
.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
dropbox.files.RemovePropertiesError
- files_properties_template_get(template_id)
- Route attributes:
scope: files.metadata.read
- Parameters:
template_id (str) – An identifier for template added by route See
files_templates_add_for_user()
orfiles_templates_add_for_team()
.- Return type:
dropbox.files.GetTemplateResult
- Raises:
- If this raises, ApiError will contain:
dropbox.files.TemplateError
- files_properties_template_list()
- Route attributes:
scope: files.metadata.read
- Return type:
dropbox.files.ListTemplateResult
- Raises:
- If this raises, ApiError will contain:
dropbox.files.TemplateError
- files_properties_update(path, update_property_groups)
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – A unique identifier for the file or folder.
- :param List[
dropbox.files.PropertyGroupUpdate
] update_property_groups: The property groups “delta” updates to apply.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
dropbox.files.UpdatePropertiesError
- files_restore(path, rev)
Restore a specific revision of a file to the given path.
- Route attributes:
scope: files.content.write
- Parameters:
path (str) – The path to save the restored file.
rev (str) – The revision to restore.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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 15 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).
- Route attributes:
scope: files.content.write
- Parameters:
path (str) – The path in Dropbox where the URL will be saved to.
url (str) – The URL to be saved.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_save_url_check_job_status(async_job_id)
Check the status of a
files_save_url()
job.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.files.PollError
- files_search(path, query, start=0, max_results=100, mode=SearchMode('filename', None))
Searches for files and folders. Note: Recent changes will be reflected in search results within a few seconds and older revisions of existing files may still match your query for up to a few days.
- Route attributes:
scope: files.metadata.read
- Parameters:
path (str) – The path in the user’s Dropbox to search. Should probably be a folder.
query (str) – The string to search for. Query string may be rewritten to improve relevance of results. The 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:
- Raises:
- If this raises, ApiError will contain:
- files_search_continue_v2(cursor)
Fetches the next page of search results returned from
files_search_v2()
. Note:files_search_v2()
along withfiles_search_continue_v2()
can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.- Route attributes:
scope: files.metadata.read
- Parameters:
cursor (str) – The cursor returned by your last call to
files_search_v2()
. Used to fetch the next page of results.- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_search_v2(query, options=None, match_field_options=None, include_highlights=None)
Searches for files and folders. Note:
files_search_v2()
along withfiles_search_continue_v2()
can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.- Route attributes:
scope: files.metadata.read
- Parameters:
query (str) – The string to search for. May match across multiple fields based on the request arguments.
- :param Nullable[
dropbox.files.SearchOptions
] options: Options for more targeted search results.
- :param Nullable[
dropbox.files.SearchMatchFieldOptions
] match_field_options: Options for search results match fields.
- Parameters:
include_highlights (Nullable[bool]) – Deprecated and moved this option to SearchMatchFieldOptions.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_tags_add(path, tag_text)
Add a tag to an item. A tag is a string. The strings are automatically converted to lowercase letters. No more than 20 tags can be added to a given item.
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – Path to the item to be tagged.
tag_text (str) – The value of the tag to add. Will be automatically converted to lowercase letters.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- files_tags_get(paths)
Get list of tags assigned to items.
- Route attributes:
scope: files.metadata.read
- Parameters:
paths (List[str]) – Path to the items.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_tags_remove(path, tag_text)
Remove a tag from an item.
- Route attributes:
scope: files.metadata.write
- Parameters:
path (str) – Path to the item to tag.
tag_text (str) – The tag to remove. Will be automatically converted to lowercase letters.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- files_unlock_file_batch(entries)
Unlock the files at the given paths. A locked file can only be unlocked by the lock holder or, if a business account, a team admin. A successful response indicates that the file has been unlocked. Returns a list of the unlocked file paths and their metadata after this operation.
- Route attributes:
scope: files.content.write
- :param List[
dropbox.files.UnlockFileArg
] entries: List of ‘entries’. Each ‘entry’ contains a path of the file which will be unlocked. Duplicate path arguments in the batch are considered only once.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_upload(f, path, mode=WriteMode('add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False, content_hash=None)
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.- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
content_hash (Nullable[str]) –
A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
session_id (str) – The upload session ID (returned by
files_upload_session_start()
).offset (int) – Offset in bytes at which data should be appended. We use this to make sure upload data isn’t lost or duplicated in the event of a network error.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- files_upload_session_append_v2(f, cursor, close=False, content_hash=None)
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.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
cursor (
dropbox.files.UploadSessionCursor
) – Contains the upload session ID and the offset.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.content_hash (Nullable[str]) –
A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- files_upload_session_finish(f, cursor, commit, content_hash=None)
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.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
cursor (
dropbox.files.UploadSessionCursor
) – Contains the upload session ID and the offset.commit (
dropbox.files.CommitInfo
) – Contains the path and other optional modifiers for the commit.content_hash (Nullable[str]) –
A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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()
andfiles_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 callingfiles_upload_session_finish()
, use this route to finish all your upload sessions in a single request.UploadSessionStartArg.close
orUploadSessionAppendArg.close
needs to be true for the lastfiles_upload_session_start()
orfiles_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. Usefiles_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.- Route attributes:
scope: files.content.write
- :param List[
dropbox.files.UploadSessionFinishArg
] entries: Commit information for each file in the batch.
- Return type:
- 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.- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.files.PollError
- files_upload_session_finish_batch_v2(entries)
This route helps you commit many files at once into a user’s Dropbox. Use
files_upload_session_start()
andfiles_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 callingfiles_upload_session_finish()
, use this route to finish all your upload sessions in a single request.UploadSessionStartArg.close
orUploadSessionAppendArg.close
needs to be true for the lastfiles_upload_session_start()
orfiles_upload_session_append_v2()
call of each upload session. The maximum size of a file one can upload to an upload session is 350 GB. 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.- Route attributes:
scope: files.content.write
- :param List[
dropbox.files.UploadSessionFinishArg
] entries: Commit information for each file in the batch.
- Return type:
- files_upload_session_start(f, close=False, session_type=None, content_hash=None)
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 andfiles_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 7 days. Attempting to use anUploadSessionStartResult.session_id
withfiles_upload_session_append_v2()
orfiles_upload_session_finish()
more than 7 days after its creation will return aUploadSessionLookupError.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. By default, upload sessions require you to send content of the file in sequential order via consecutivefiles_upload_session_start()
,files_upload_session_append_v2()
,files_upload_session_finish()
calls. For better performance, you can instead optionally use aUploadSessionType.concurrent
upload session. To start a new concurrent session, setUploadSessionStartArg.session_type
toUploadSessionType.concurrent
. After that, you can send file data in concurrentfiles_upload_session_append_v2()
requests. Finally finish the session withfiles_upload_session_finish()
. There are couple of constraints with concurrent sessions to make them work. You can not send data withfiles_upload_session_start()
orfiles_upload_session_finish()
call, only withfiles_upload_session_append_v2()
call. Also data uploaded infiles_upload_session_append_v2()
call must be multiple of 4194304 bytes (except for lastfiles_upload_session_append_v2()
withUploadSessionStartArg.close
toTrue
, that may contain any remaining data).- Route attributes:
scope: files.content.write
- 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.
- :param Nullable[
dropbox.files.UploadSessionType
] session_type: Type of upload session you want to start. If not specified, default is
UploadSessionType.sequential
.
- Parameters:
content_hash (Nullable[str]) –
A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- files_upload_session_start_batch(num_sessions, session_type=None)
This route starts batch of upload_sessions. Please refer to upload_session/start usage. 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.
- Route attributes:
scope: files.content.write
- :param Nullable[
dropbox.files.UploadSessionType
] session_type: Type of upload session you want to start. If not specified, default is
UploadSessionType.sequential
.
- Parameters:
num_sessions (int) – The number of upload sessions to start.
- Return type:
- openid_userinfo()
This route is used for refreshing the info that is found in the id_token during the OIDC flow. This route doesn’t require any arguments and will use the scopes approved for the given access token.
- Route attributes:
scope: openid
- Return type:
dropbox.openid.UserInfoResult
- Raises:
- If this raises, ApiError will contain:
dropbox.openid.UserInfoError
- paper_docs_archive(doc_id)
Marks the given Paper doc as archived. This action can be performed or undone by anyone with edit permissions to the doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.
- Route attributes:
scope: files.content.write
- Parameters:
doc_id (str) – The Paper doc ID.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- paper_docs_create(f, import_format, parent_folder_id=None)
Creates a new Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.
- Route attributes:
scope: files.content.write
- Parameters:
f (bytes) – Contents to upload.
parent_folder_id (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- paper_docs_download(doc_id, export_format)
Exports and downloads Paper doc either as HTML or markdown. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: files.content.read
- Return type:
(
dropbox.paper.PaperDocExportResult
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: files.content.read
- Parameters:
download_path (str) – Path on local machine to save file.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.read
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor obtained from
paper_docs_folder_users_list()
orpaper_docs_folder_users_list_continue()
. Allows for pagination.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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. If the Paper doc is not in any folder (aka unfiled) the response will be empty. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.read
- Parameters:
doc_id (str) – The Paper doc ID.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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()
. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.- Route attributes:
scope: files.metadata.read
- Parameters:
filter_by (
dropbox.paper.ListPaperDocsFilterBy
) – Allows user to specify how the Paper docs should be filtered.sort_by (
dropbox.paper.ListPaperDocsSortBy
) – Allows user to specify how the Paper docs should be sorted.sort_order (
dropbox.paper.ListPaperDocsSortOrder
) – Allows user to specify the sort order of the result.limit (int) – Size limit per batch. The maximum number of docs that can be retrieved per batch is 1000. Higher value results in invalid arguments error.
- Return type:
- paper_docs_list_continue(cursor)
Once a cursor has been retrieved from
paper_docs_list()
, use this to paginate through all Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.- Route attributes:
scope: files.metadata.read
- Parameters:
cursor (str) – The cursor obtained from
paper_docs_list()
orpaper_docs_list_continue()
. Allows for pagination.- Return type:
- Raises:
- If this raises, ApiError will contain:
- paper_docs_permanently_delete(doc_id)
Permanently deletes the given Paper doc. This operation is final as the doc cannot be recovered. This action can be performed only by the doc owner. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: files.permanent_delete
- Parameters:
doc_id (str) – The Paper doc ID.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- paper_docs_sharing_policy_get(doc_id)
Gets the default sharing policy for the given Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.read
- Parameters:
doc_id (str) – The Paper doc ID.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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. The ‘public_sharing_policy’ policy can’t be set to the value ‘disabled’ because this setting can be changed only via the team admin console. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.write
- Parameters:
sharing_policy (
dropbox.paper.SharingPolicy
) – The default sharing policy to be set for the Paper doc.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- paper_docs_update(f, doc_id, doc_update_policy, revision, import_format)
Updates an existing Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.
- Route attributes:
scope: files.content.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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. The doc owner’s permissions cannot be changed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.write
- :param List[
dropbox.paper.AddMember
] members: User which should be added to the Paper doc. Specify only email address or Dropbox account ID.
- Parameters:
custom_message (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- 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. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.read
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor obtained from
paper_docs_users_list()
orpaper_docs_users_list_continue()
. Allows for pagination.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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. The doc owner cannot be removed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: sharing.write
- 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:
- If this raises, ApiError will contain:
- paper_folders_create(name, parent_folder_id=None, is_team_folder=None)
Create a new Paper folder with the provided info. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.
- Route attributes:
scope: files.content.write
- Parameters:
name (str) – The name of the new Paper folder.
parent_folder_id (Nullable[str]) – The encrypted Paper folder Id where the new Paper folder should be created. The API user has to have write access to this folder or error is thrown. If not supplied, the new folder will be created at top level.
is_team_folder (Nullable[bool]) – Whether the folder to be created should be a team folder. This value will be ignored if parent_folder_id is supplied, as the new folder will inherit the type (private or team folder) from its parent. We will by default create a top-level private folder if both parent_folder_id and is_team_folder are not supplied.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- raise_dropbox_error_for_resp(res)
Checks for errors from a res and handles appropiately.
- Parameters:
res – Response of an api request.
- refresh_access_token(host='api.dropboxapi.com', scope=None)
Refreshes an access token via refresh token if available
- Parameters:
host – host to hit token endpoint with
scope – list of permission scopes for access token
- Returns:
- 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 (
stone.backends.python_rsrc.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, auth_type, 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.
:param auth_type str :param Optional[bytes] request_binary: Bytes representing the binary
payload. Use None if there is no binary payload.
- Parameters:
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, auth_type, 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, auth_type, 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.
- Route attributes:
scope: sharing.write
- Parameters:
file (str) – File to which to add members.
- :param List[
dropbox.sharing.MemberSelector
] members: Members to add. Note that even an email address is given, this may result in a user being directly added to the membership if that email is the user’s main account email.
- Parameters:
custom_message (Nullable[str]) – Message to send to added members in their invitation.
quiet (bool) – Whether added members should be notified via email and 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:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: sharing.write
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
- :param List[
dropbox.sharing.AddMember
] members: The intended list of members to add. Added members will receive invites to join the shared folder.
- Parameters:
quiet (bool) – Whether added members should be notified via email and device notifications of their invite.
custom_message (Nullable[str]) – Optional message to display to added members in their invitation.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- sharing_check_job_status(async_job_id)
Returns the status of an asynchronous job.
- Route attributes:
scope: sharing.write
- 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:
- Raises:
- 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.
- Route attributes:
scope: sharing.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.sharing.PollError
Returns the status of an asynchronous job for sharing a folder.
- Route attributes:
scope: sharing.write
- 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:
- Raises:
- 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. 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()
.- Route attributes:
scope: sharing.write
- Parameters:
path (str) – The path to share.
- :param Nullable[
dropbox.sharing.PendingUploadMode
] pending_upload: If it’s okay to share a path that does not yet exist, set this to either
PendingUploadMode.file
orPendingUploadMode.folder
to indicate whether to assume it’s a file or folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
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).- Route attributes:
scope: sharing.write
- Parameters:
path (str) – The path to be shared by the shared link.
- :param Nullable[
dropbox.sharing.SharedLinkSettings
] settings: The requested settings for the newly created shared link.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- sharing_get_file_metadata(file, actions=None)
Returns shared file metadata.
- Route attributes:
scope: sharing.read
- Parameters:
file (str) – The file to query.
- :param Nullable[List[
dropbox.sharing.FileAction
]] actions: 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:
- Raises:
- If this raises, ApiError will contain:
- sharing_get_file_metadata_batch(files, actions=None)
Returns shared file metadata.
- Route attributes:
scope: sharing.read
- Parameters:
files (List[str]) – The files to query.
- :param Nullable[List[
dropbox.sharing.FileAction
]] actions: 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:
- Raises:
- If this raises, ApiError will contain:
- sharing_get_folder_metadata(shared_folder_id, actions=None)
Returns shared folder metadata by its folder ID.
- Route attributes:
scope: sharing.read
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
- :param Nullable[List[
dropbox.sharing.FolderAction
]] actions: 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:
- Raises:
- If this raises, ApiError will contain:
Download the shared link’s file from a user’s Dropbox.
- Route attributes:
scope: sharing.read
- Parameters:
url (str) – URL of the shared link.
path (Nullable[str]) – 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[str]) – If the shared link has a password, this parameter can be used.
- Return type:
(
dropbox.sharing.SharedLinkMetadata
,requests.models.Response
)- Raises:
- If this raises, ApiError will contain:
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.
- Route attributes:
scope: sharing.read
- Parameters:
download_path (str) – Path on local machine to save file.
url (str) – URL of the shared link.
path (Nullable[str]) – 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[str]) – If the shared link has a password, this parameter can be used.
- Return type:
- Raises:
- If this raises, ApiError will contain:
Get the shared link’s metadata.
- Route attributes:
scope: sharing.read
- Parameters:
url (str) – URL of the shared link.
path (Nullable[str]) – 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[str]) – If the shared link has a password, this parameter can be used.
- Return type:
- Raises:
- If this raises, ApiError will contain:
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.- Route attributes:
scope: sharing.read
- Parameters:
path (Nullable[str]) – See
sharing_get_shared_links()
description.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.read
- Parameters:
file (str) – The file for which you want to see members.
- :param Nullable[List[
dropbox.sharing.MemberAction
]] actions: The actions for which to return permissions on a member.
- Parameters:
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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.read
- Parameters:
files (List[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- sharing_list_file_members_continue(cursor)
Once a cursor has been retrieved from
sharing_list_file_members()
orsharing_list_file_members_batch()
, use this to paginate through all shared file members.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor returned by your last call to
sharing_list_file_members()
,sharing_list_file_members_continue()
, orsharing_list_file_members_batch()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- sharing_list_folder_members(shared_folder_id, actions=None, limit=1000)
Returns shared folder membership by its folder ID.
- Route attributes:
scope: sharing.read
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor returned by your last call to
sharing_list_folder_members()
orsharing_list_folder_members_continue()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- sharing_list_folders(limit=1000, actions=None)
Return the list of all shared folders the current user has access to.
- Route attributes:
scope: sharing.read
- Parameters:
limit (int) – The maximum number of results to return per request.
- :param Nullable[List[
dropbox.sharing.FolderAction
]] actions: 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:
- 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 tosharing_list_folders()
orsharing_list_folders_continue()
.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- sharing_list_mountable_folders(limit=1000, actions=None)
Return the list of all shared folders the current user can mount or unmount.
- Route attributes:
scope: sharing.read
- Parameters:
limit (int) – The maximum number of results to return per request.
- :param Nullable[List[
dropbox.sharing.FolderAction
]] actions: 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:
- 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 tosharing_list_mountable_folders()
orsharing_list_mountable_folders_continue()
.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.read
- Parameters:
limit (int) – Number of files to return max per query. Defaults to 100 if no limit is specified.
- :param Nullable[List[
dropbox.sharing.FileAction
]] actions: 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:
- Raises:
- If this raises, ApiError will contain:
- sharing_list_received_files_continue(cursor)
Get more results with a cursor from
sharing_list_received_files()
.- Route attributes:
scope: sharing.read
- Parameters:
cursor (str) – Cursor in
ListFilesResult.cursor
.- Return type:
- Raises:
- If this raises, ApiError will contain:
List shared links of this user. If no path is given, returns a list of all shared links for the current user. For members of business teams using team space and member folders, returns all shared links in the team member’s home folder unless the team space ID is specified in the request header. For more information, refer to the Namespace Guide. 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.
- Route attributes:
scope: sharing.read
- Parameters:
path (Nullable[str]) – See
sharing_list_shared_links()
description.cursor (Nullable[str]) – The cursor returned by your last call to
sharing_list_shared_links()
.direct_only (Nullable[bool]) – See
sharing_list_shared_links()
description.
- Return type:
- Raises:
- If this raises, ApiError will contain:
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 returneddropbox.sharing.SharedLinkMetadata
will reflect the actual visibility of the shared link and theLinkPermissions.requested_visibility
will reflect the requested visibility.- Route attributes:
scope: sharing.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.write
- Parameters:
shared_folder_id (str) – The ID of the shared folder to mount.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.write
- Parameters:
file (str) – The path or id for the file.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.write
- 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. This must be set to false when the folder is within a team folder or another shared folder.
- Return type:
dropbox.sharing.LaunchEmptyResult
- Raises:
- If this raises, ApiError will contain:
- sharing_remove_file_member(file, member)
Identical to remove_file_member_2 but with less information returned.
- Route attributes:
scope: sharing.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- sharing_remove_file_member_2(file, member)
Removes a specified member from the file.
- Route attributes:
scope: sharing.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.write
- 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. This must be set to false when removing a group, or when the folder is within a team folder or another shared folder.
- Return type:
dropbox.sharing.LaunchResultBase
- Raises:
- If this raises, ApiError will contain:
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 theListSharedLinksArg.path
argument.- Route attributes:
scope: sharing.write
- Parameters:
url (str) – URL of the shared link.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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 callsharing_check_share_job_status()
until the action completes to get the metadata for the folder.- Route attributes:
scope: sharing.write
- 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:
- Raises:
- If this raises, ApiError will contain:
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 callsharing_check_share_job_status()
until the action completes to get the metadata for the folder.- Route attributes:
scope: sharing.write
- :param Nullable[List[
dropbox.sharing.FolderAction
]] actions: 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.
- :param Nullable[
dropbox.sharing.LinkSettings
] link_settings: Settings on the link for this folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: sharing.write
- 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:
- If this raises, ApiError will contain:
- 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()
.- Route attributes:
scope: sharing.write
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
Remove all members from this file. Does not remove inherited members.
- Route attributes:
scope: sharing.write
- Parameters:
file (str) – The file to unshare.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
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.- Route attributes:
scope: sharing.write
- 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:
- If this raises, ApiError will contain:
- sharing_update_file_member(file, member, access_level)
Changes a member’s access on a shared file.
- Route attributes:
scope: sharing.write
- Parameters:
file (str) – File for which we are changing a member’s access.
member (
dropbox.sharing.MemberSelector
) – The member whose access we are changing.access_level (
dropbox.sharing.AccessLevel
) – The new access level for the member.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sharing.write
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
member (
dropbox.sharing.MemberSelector
) – The member of the shared folder to update. Only theMemberSelector.dropbox_id
may be set at this time.access_level (
dropbox.sharing.AccessLevel
) – The new access level formember
.AccessLevel.owner
is disallowed.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: sharing.write
- Parameters:
shared_folder_id (str) – The ID for the shared folder.
- :param Nullable[
dropbox.sharing.MemberPolicy
] member_policy: Who can be a member of this shared folder. Only applicable if the current user is on a team.
- :param Nullable[
dropbox.sharing.AclUpdatePolicy
] acl_update_policy: Who can add and remove members of this shared folder.
- :param Nullable[
dropbox.sharing.ViewerInfoPolicy
] viewer_info_policy: Who can enable/disable viewer info for this shared folder.
- :param Nullable[
dropbox.sharing.SharedLinkPolicy
] shared_link_policy: 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
.- :param Nullable[
dropbox.sharing.LinkSettings
] link_settings: Settings on the link for this folder.
- :param Nullable[List[
dropbox.sharing.FolderAction
]] actions: 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:
- Raises:
- If this raises, ApiError will contain:
- users_features_get_values(features)
Get a list of feature values that may be configured for the current account.
- Route attributes:
scope: account_info.read
- :param List[
dropbox.users.UserFeature
] features: A list of features in
dropbox.users.UserFeature
. If the list is empty, this route will returndropbox.users.UserFeaturesGetValuesBatchError
.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- users_get_account(account_id)
Get information about a user’s account.
- Route attributes:
scope: sharing.read
- Parameters:
account_id (str) – A user’s account identifier.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- users_get_account_batch(account_ids)
Get information about multiple user accounts. At most 300 accounts may be queried per request.
- Route attributes:
scope: sharing.read
- Parameters:
account_ids (List[str]) – List of user account identifiers. Should not contain any duplicate account IDs.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- users_get_current_account()
Get information about the current user’s account.
- Route attributes:
scope: account_info.read
- Return type:
- users_get_space_usage()
Get the space usage information for the current user’s account.
- Route attributes:
scope: account_info.read
- Return type:
- 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
- class dropbox.dropbox_client.DropboxTeam(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
Bases:
_DropboxTransport
,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=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
- 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, usecreate_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 100 seconds.
oauth2_refresh_token (str) – OAuth2 refresh token for refreshing access token
oauth2_access_token_expiration (datetime) – Expiration for oauth2_access_token
app_key (str) – application key of requesting application; used for token refresh
app_secret (str) – application secret of requesting application; used for token refresh Not required if PKCE was used to authorize the token
scope (list) – list of scopes to request on refresh. If left blank, refresh will request all available scopes for application
ca_certs (str) – a path to a file of concatenated CA certificates in PEM format. Has the same meaning as when using
ssl.wrap_socket()
.
- 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.
- as_user(team_member_id)
Allows a team credential to assume the identity of a member of the team.
- check_and_refresh_access_token()
Checks if access token needs to be refreshed and refreshes if possible :return:
- 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, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=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 client
- Return type:
- close()
Cleans up all resources like the request session/network connection.
- 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.- Route attributes:
scope: files.team_metadata.write
- Return type:
- Raises:
- If this raises, ApiError will contain:
- file_properties_templates_get_for_team(template_id)
Get the schema for a specified template.
- Route attributes:
scope: files.team_metadata.write
- Parameters:
template_id (str) – An identifier for template added by route See
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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()
.- Route attributes:
scope: files.team_metadata.write
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: files.team_metadata.write
- Parameters:
template_id (str) – An identifier for a template created by
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: files.team_metadata.write
- Parameters:
template_id (str) – An identifier for template added by See
file_properties_templates_add_for_user()
orfile_properties_templates_add_for_team()
.name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
- :param
Nullable[List[
dropbox.file_properties.PropertyFieldTemplate
]] add_fields: Property field templates to be added to the group template. There can be up to 32 properties in a single template.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- raise_dropbox_error_for_resp(res)
Checks for errors from a res and handles appropiately.
- Parameters:
res – Response of an api request.
- refresh_access_token(host='api.dropboxapi.com', scope=None)
Refreshes an access token via refresh token if available
- Parameters:
host – host to hit token endpoint with
scope – list of permission scopes for access token
- Returns:
- 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 (
stone.backends.python_rsrc.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, auth_type, 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.
:param auth_type str :param Optional[bytes] request_binary: Bytes representing the binary
payload. Use None if there is no binary payload.
- Parameters:
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, auth_type, 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, auth_type, 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.
- Route attributes:
scope: sessions.list
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sessions.list
- Parameters:
cursor (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sessions.list
- Parameters:
cursor (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- team_devices_revoke_device_session(arg)
Revoke a device session of a team’s member.
- Route attributes:
scope: sessions.modify
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- team_devices_revoke_device_session_batch(revoke_devices)
Revoke a list of device sessions of team members.
- Route attributes:
scope: sessions.modify
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: team_info.read
- :param List[
dropbox.team.Feature
] features: A list of features in
dropbox.team.Feature
. If the list is empty, this route will returndropbox.team.FeaturesGetValuesBatchError
.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_get_info()
Retrieves information about a team.
- Route attributes:
scope: team_info.read
- Return type:
- team_groups_create(group_name, add_creator_as_owner=False, group_external_id=None, group_management_type=None)
Creates a new, empty group, with a requested name. Permission : Team member management.
- Route attributes:
scope: groups.write
- Parameters:
group_name (str) – Group name.
add_creator_as_owner (bool) – Automatically add the creator of the group.
group_external_id (Nullable[str]) – The creator of a team can associate an arbitrary external ID to the group.
- :param Nullable[
dropbox.team.GroupManagementType
] group_management_type: Whether the team can be managed by selected users, or only by team admins.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: groups.write
- 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:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: groups.read
- Parameters:
arg (
dropbox.team.GroupsSelector
) – Argument for selecting a list of groups, either by group_ids, or external group IDs.- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_groups_job_status_get(async_job_id)
Once an async_job_id is returned from
team_groups_delete()
,team_groups_members_add()
, orteam_groups_members_remove()
use this method to poll the status of granting/revoking group members’ access to group-owned resources. Permission : Team member management.- Route attributes:
scope: groups.write
- 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:
- If this raises, ApiError will contain:
- team_groups_list(limit=1000)
Lists groups on a team. Permission : Team Information.
- Route attributes:
scope: groups.read
- Parameters:
limit (int) – Number of results to return per call.
- Return type:
- 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.- Route attributes:
scope: groups.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of groups.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: groups.write
- Parameters:
group (
dropbox.team.GroupSelector
) – Group to which users will be added.
- :param List[
dropbox.team.MemberAccess
] members: List of users to be added to the group.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_groups_members_list(group, limit=1000)
Lists members of a group. Permission : Team Information.
- Route attributes:
scope: groups.read
- Parameters:
group (
dropbox.team.GroupSelector
) – The group whose members are to be listed.limit (int) – Number of results to return per call.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: groups.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of groups.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: groups.write
- Parameters:
group (
dropbox.team.GroupSelector
) – Group from which users will be removed.
- :param List[
dropbox.team.UserSelectorArg
] users: List of users to be removed from the group.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: groups.write
- 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: groups.write
- Parameters:
group (
dropbox.team.GroupSelector
) – Specify a group.new_group_name (Nullable[str]) – Optional argument. Set group name to this if provided.
new_group_external_id (Nullable[str]) – 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.
- :param Nullable[
dropbox.team.GroupManagementType
] new_group_management_type: Set new group management type, if provided.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_create_policy(name, members, description=None, start_date=None, end_date=None)
Creates new legal hold policy. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
name (str) – Policy name.
description (Nullable[str]) – A description of the legal hold policy.
members (List[str]) – List of team member IDs added to the hold.
start_date (Nullable[datetime]) – start date of the legal hold policy.
end_date (Nullable[datetime]) – end date of the legal hold policy.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_get_policy(id)
Gets a legal hold by Id. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
id (str) – The legal hold Id.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_list_held_revisions(id)
List the file metadata that’s under the hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
id (str) – The legal hold Id.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_list_held_revisions_continue(id, cursor=None)
Continue listing the file metadata that’s under the hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
id (str) – The legal hold Id.
cursor (Nullable[str]) – The cursor idicates where to continue reading file metadata entries for the next API call. When there are no more entries, the cursor will return none.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_list_policies(include_released=False)
Lists legal holds on a team. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
include_released (bool) – Whether to return holds that were released.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_release_policy(id)
Releases a legal hold by Id. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
id (str) – The legal hold Id.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- team_legal_holds_update_policy(id, name=None, description=None, members=None)
Updates a legal hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.
- Route attributes:
scope: team_data.governance.write
- Parameters:
id (str) – The legal hold Id.
name (Nullable[str]) – Policy new name.
description (Nullable[str]) – Policy new description.
members (Nullable[List[str]]) – List of team member IDs to apply the policy on.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sessions.list
- Parameters:
team_member_id (str) – The team member id.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sessions.list
- Parameters:
cursor (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: sessions.list
- Parameters:
cursor (Nullable[str]) – 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:
- Raises:
- If this raises, ApiError will contain:
- team_linked_apps_revoke_linked_app(app_id, team_member_id, keep_app_folder=True)
Revoke a linked application of the team member.
- Route attributes:
scope: sessions.modify
- 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) – This flag is not longer supported, the application dedicated folder (in case the application uses one) will be kept.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- team_linked_apps_revoke_linked_app_batch(revoke_linked_app)
Revoke a list of linked applications of the team members.
- Route attributes:
scope: sessions.modify
List[
dropbox.team.RevokeLinkedApiAppArg
] :rtype:dropbox.team.RevokeLinkedAppBatchResult
:raises:exceptions.ApiError
- If this raises, ApiError will contain:
- team_log_get_events(limit=1000, account_id=None, time=None, category=None, event_type=None)
Retrieves team events. If the result’s
GetTeamEventsResult.has_more
field isTrue
, callteam_log_get_events_continue()
with the returned cursor to retrieve more entries. If end_time is not specified in your request, you may use the returned cursor to pollteam_log_get_events_continue()
for new events. 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.- Route attributes:
scope: events.read
- 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 usingteam_log_get_events_continue()
.account_id (Nullable[str]) – Filter the events by account ID. Return only events with this account_id as either Actor, Context, or Participants.
- :param Nullable[
dropbox.team_log.TimeRange
] time: Filter by time range.
- :param Nullable[
dropbox.team_log.EventCategory
] category: Filter the returned events to a single category. Note that category shouldn’t be provided together with event_type.
- :param Nullable[
dropbox.team_log.EventTypeArg
] event_type: Filter the returned events to a single event type. Note that event_type shouldn’t be provided together with category.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: events.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of events.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_member_space_limits_excluded_users_add(users=None)
Add users to member space limits excluded users list.
- Route attributes:
scope: members.write
- :param Nullable[List[
dropbox.team.UserSelectorArg
]] users: List of users to be added/removed.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_member_space_limits_excluded_users_list(limit=1000)
List member space limits excluded users.
- Route attributes:
scope: members.read
- Parameters:
limit (int) – Number of results to return per call.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_member_space_limits_excluded_users_list_continue(cursor)
Continue listing member space limits excluded users.
- Route attributes:
scope: members.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of users.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_member_space_limits_excluded_users_remove(users=None)
Remove users from member space limits excluded users list.
- Route attributes:
scope: members.write
- :param Nullable[List[
dropbox.team.UserSelectorArg
]] users: List of users to be added/removed.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_member_space_limits_get_custom_quota(users)
Get users custom quota. A maximum of 1000 members can be specified in a single call. Note: to apply a custom space limit, a team admin needs to set a member space limit for the team first. (the team admin can check the settings here: https://www.dropbox.com/team/admin/settings/space).
- Route attributes:
scope: members.read
:param List[
dropbox.team.UserSelectorArg
] users: List of users. :rtype: List[dropbox.team.CustomQuotaResult
] :raises:exceptions.ApiError
- If this raises, ApiError will contain:
- team_member_space_limits_remove_custom_quota(users)
Remove users custom quota. A maximum of 1000 members can be specified in a single call. Note: to apply a custom space limit, a team admin needs to set a member space limit for the team first. (the team admin can check the settings here: https://www.dropbox.com/team/admin/settings/space).
- Route attributes:
scope: members.write
:param List[
dropbox.team.UserSelectorArg
] users: List of users. :rtype: List[dropbox.team.RemoveCustomQuotaResult
] :raises:exceptions.ApiError
- If this raises, ApiError will contain:
- 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. Note: to apply a custom space limit, a team admin needs to set a member space limit for the team first. (the team admin can check the settings here: https://www.dropbox.com/team/admin/settings/space).
- Route attributes:
scope: members.read
- :param List[
dropbox.team.UserCustomQuotaArg
] users_and_quotas: List of users and their custom quotas.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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’.
- Route attributes:
scope: members.write
- :param List[
dropbox.team.MemberAddArg
] new_members: Details of new members to be added to the team.
- Return type:
- 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.- Route attributes:
scope: members.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.team.PollError
- team_members_add_job_status_get_v2(async_job_id)
Once an async_job_id is returned from
team_members_add_v2()
, use this to poll the status of the asynchronous request. Permission : Team member management.- Route attributes:
scope: members.write
- 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:
- Raises:
- If this raises, ApiError will contain:
dropbox.team.PollError
- team_members_add_v2(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’.
- Route attributes:
scope: members.write
- :param List[
dropbox.team.MemberAddV2Arg
] new_members: Details of new members to be added to the team.
- Return type:
- team_members_delete_profile_photo(user)
Deletes a team member’s profile photo. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of the user whose profile photo will be deleted.- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_delete_profile_photo_v2(user)
Deletes a team member’s profile photo. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of the user whose profile photo will be deleted.- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_get_available_team_member_roles()
Get available TeamMemberRoles for the connected team. To be used with
team_members_set_admin_permissions_v2()
. Permission : Team member management.- Route attributes:
scope: members.read
- 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.- Route attributes:
scope: members.read
- :param List[
dropbox.team.UserSelectorArg
] members: List of team members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_get_info_v2(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.- Route attributes:
scope: members.read
- :param List[
dropbox.team.UserSelectorArg
] members: List of team members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_list(limit=1000, include_removed=False)
Lists members of a team. Permission : Team information.
- Route attributes:
scope: members.read
- Parameters:
limit (int) – Number of results to return per call.
include_removed (bool) – Whether to return removed members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: members.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_list_continue_v2(cursor)
Once a cursor has been retrieved from
team_members_list_v2()
, use this to paginate through all team members. Permission : Team information.- Route attributes:
scope: members.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_list_v2(limit=1000, include_removed=False)
Lists members of a team. Permission : Team information.
- Route attributes:
scope: members.read
- Parameters:
limit (int) – Number of results to return per call.
include_removed (bool) – Whether to return removed members.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: members.write
- Parameters:
transfer_dest_id (
dropbox.team.UserSelectorArg
) – Files from the deleted member account will be transferred to this user.transfer_admin_id (
dropbox.team.UserSelectorArg
) – Errors during the transfer process will be sent via email to this user.
- Return type:
dropbox.team.LaunchEmptyResult
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: members.write
- 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:
- 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.
- Route attributes:
scope: members.delete
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user to recover.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- team_members_remove(user, wipe_data=True, transfer_dest_id=None, transfer_admin_id=None, keep_account=False, retain_team_shares=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). Callingteam_members_add()
while a user is still recoverable on your team will return withMemberAddResult.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 (180 days for most teams). This endpoint may initiate an asynchronous job. To obtain the final result of the job, the client should periodically pollteam_members_remove_job_status_get()
.- Route attributes:
scope: members.delete
- :param Nullable[
dropbox.team.UserSelectorArg
] transfer_dest_id: If provided, files from the deleted member account will be transferred to this user.
- :param Nullable[
dropbox.team.UserSelectorArg
] transfer_admin_id: 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.
- Parameters:
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 toFalse
.retain_team_shares (bool) – If provided, allows removed users to keep access to Dropbox folders (not Dropbox Paper folders) already explicitly shared with them (not via a group) when they are downgraded to a Basic account. Users will not retain access to folders that do not allow external sharing. In order to keep the sharing relationships, the arguments
wipe_data
should be set toFalse
andkeep_account
should be set toTrue
.
- Return type:
dropbox.team.LaunchEmptyResult
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: members.delete
- 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:
- If this raises, ApiError will contain:
dropbox.team.PollError
- team_members_secondary_emails_add(new_secondary_emails)
Add secondary emails to users. Permission : Team member management. Emails that are on verified domains will be verified automatically. For each email address not on a verified domain a verification email will be sent.
- Route attributes:
scope: members.write
- :param List[
dropbox.team.UserSecondaryEmailsArg
] new_secondary_emails: List of users and secondary emails to add.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_secondary_emails_delete(emails_to_delete)
Delete secondary emails from users Permission : Team member management. Users will be notified of deletions of verified secondary emails at both the secondary email and their primary email.
- Route attributes:
scope: members.write
- :param List[
dropbox.team.UserSecondaryEmailsArg
] emails_to_delete: List of users and their secondary emails to delete.
- Return type:
- team_members_secondary_emails_resend_verification_emails(emails_to_resend)
Resend secondary email verification emails. Permission : Team member management.
- Route attributes:
scope: members.write
- :param List[
dropbox.team.UserSecondaryEmailsArg
] emails_to_resend: List of users and secondary emails to resend verification emails to.
- Return type:
- 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.
- Route attributes:
scope: members.write
- Parameters:
arg (
dropbox.team.UserSelectorArg
) – Argument for selecting a single user, either by team_member_id, external_id or email.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- team_members_set_admin_permissions(user, new_role)
Updates a team member’s permissions. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user whose role will be set.new_role (
dropbox.team.AdminTier
) – The new role of the member.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_set_admin_permissions_v2(user, new_roles=None)
Updates a team member’s permissions. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user whose role will be set.new_roles (Nullable[List[str]]) – The new roles for the member. Send empty list to make user member only. For now, only up to one role is allowed.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user whose profile will be set.new_email (Nullable[str]) – New email for member.
new_external_id (Nullable[str]) – New external ID for member.
new_given_name (Nullable[str]) – New given name for member.
new_surname (Nullable[str]) – New surname for member.
new_persistent_id (Nullable[str]) – New persistent ID. This field only available to teams using persistent ID SAML configuration.
new_is_directory_restricted (Nullable[bool]) – New value for whether the user is a directory restricted user.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_set_profile_photo(user, photo)
Updates a team member’s profile photo. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of the user whose profile photo will be set.photo (
dropbox.team.PhotoSourceArg
) – Image to set as the member’s new profile photo.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_set_profile_photo_v2(user, photo)
Updates a team member’s profile photo. Permission : Team member management.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of the user whose profile photo will be set.photo (
dropbox.team.PhotoSourceArg
) – Image to set as the member’s new profile photo.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_members_set_profile_v2(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.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user whose profile will be set.new_email (Nullable[str]) – New email for member.
new_external_id (Nullable[str]) – New external ID for member.
new_given_name (Nullable[str]) – New given name for member.
new_surname (Nullable[str]) – New surname for member.
new_persistent_id (Nullable[str]) – New persistent ID. This field only available to teams using persistent ID SAML configuration.
new_is_directory_restricted (Nullable[bool]) – New value for whether the user is a directory restricted user.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: members.write
- Parameters:
wipe_data (bool) – If provided, controls if the user’s data will be deleted on their linked devices.
- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: members.write
- Parameters:
user (
dropbox.team.UserSelectorArg
) – Identity of user to unsuspend.- Return type:
None
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: team_data.member
- Parameters:
limit (int) – Specifying a value here has no effect.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: team_data.member
- Parameters:
cursor (str) – Indicates from what point to get the next set of team-accessible namespaces.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_properties_template_add(name, description, fields)
Permission : Team member file access.
- Route attributes:
scope: files.team_metadata.write
- Return type:
dropbox.team.AddTemplateResult
- Raises:
- If this raises, ApiError will contain:
dropbox.team.ModifyTemplateError
- team_properties_template_get(template_id)
Permission : Team member file access. The scope for the route is files.team_metadata.write.
- Route attributes:
scope: files.team_metadata.write
- Parameters:
template_id (str) – An identifier for template added by route See
team_templates_add_for_user()
orteam_templates_add_for_team()
.- Return type:
dropbox.team.GetTemplateResult
- Raises:
- If this raises, ApiError will contain:
dropbox.team.TemplateError
- team_properties_template_list()
Permission : Team member file access. The scope for the route is files.team_metadata.write.
- Route attributes:
scope: files.team_metadata.write
- Return type:
dropbox.team.ListTemplateResult
- Raises:
- 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.
- Route attributes:
scope: files.team_metadata.write
- Parameters:
template_id (str) – An identifier for template added by See
team_templates_add_for_user()
orteam_templates_add_for_team()
.name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
- :param Nullable[List[
dropbox.team.PropertyFieldTemplate
]] add_fields: 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:
- 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. Deprecated: Will be removed on July 1st 2021.
- Route attributes:
scope: team_info.read
- Parameters:
start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
end_date (Nullable[datetime]) – Optional ending date (exclusive).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_reports_get_devices(start_date=None, end_date=None)
Retrieves reporting data about a team’s linked devices. Deprecated: Will be removed on July 1st 2021.
- Route attributes:
scope: team_info.read
- Parameters:
start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
end_date (Nullable[datetime]) – Optional ending date (exclusive).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_reports_get_membership(start_date=None, end_date=None)
Retrieves reporting data about a team’s membership. Deprecated: Will be removed on July 1st 2021.
- Route attributes:
scope: team_info.read
- Parameters:
start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
end_date (Nullable[datetime]) – Optional ending date (exclusive).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_reports_get_storage(start_date=None, end_date=None)
Retrieves reporting data about a team’s storage usage. Deprecated: Will be removed on July 1st 2021.
- Route attributes:
scope: team_info.read
- Parameters:
start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
end_date (Nullable[datetime]) – Optional ending date (exclusive).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_sharing_allowlist_add(domains=None, emails=None)
Endpoint adds Approve List entries. Changes are effective immediately. Changes are committed in transaction. In case of single validation error - all entries are rejected. Valid domains (RFC-1034/5) and emails (RFC-5322/822) are accepted. Added entries cannot overflow limit of 10000 entries per team. Maximum 100 entries per call is allowed.
- Route attributes:
scope: team_info.write
- Parameters:
domains (Nullable[List[str]]) – List of domains represented by valid string representation (RFC-1034/5).
emails (Nullable[List[str]]) – List of emails represented by valid string representation (RFC-5322/822).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_sharing_allowlist_list(limit=1000)
Lists Approve List entries for given team, from newest to oldest, returning up to limit entries at a time. If there are more than limit entries associated with the current team, more can be fetched by passing the returned cursor to
team_sharing_allowlist_list_continue()
.- Route attributes:
scope: team_info.read
- Parameters:
limit (int) – The number of entries to fetch at one time.
- Return type:
- team_sharing_allowlist_list_continue(cursor)
Lists entries associated with given team, starting from a the cursor. See
team_sharing_allowlist_list()
.- Route attributes:
scope: team_info.read
- Parameters:
cursor (str) – The cursor returned from a previous call to
team_sharing_allowlist_list()
orteam_sharing_allowlist_list_continue()
.- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_sharing_allowlist_remove(domains=None, emails=None)
Endpoint removes Approve List entries. Changes are effective immediately. Changes are committed in transaction. In case of single validation error - all entries are rejected. Valid domains (RFC-1034/5) and emails (RFC-5322/822) are accepted. Entries being removed have to be present on the list. Maximum 1000 entries per call is allowed.
- Route attributes:
scope: team_info.write
- Parameters:
domains (Nullable[List[str]]) – List of domains represented by valid string representation (RFC-1034/5).
emails (Nullable[List[str]]) – List of emails represented by valid string representation (RFC-5322/822).
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_team_folder_activate(team_folder_id)
Sets an archived team folder’s status to active. Permission : Team member file access.
- Route attributes:
scope: team_data.content.write
- Parameters:
team_folder_id (str) – The ID of the team folder.
- Return type:
- 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. This endpoint cannot be used for teams that have a shared team space. Permission : Team member file access.
- Route attributes:
scope: team_data.content.write
- Parameters:
force_async_off (bool) – Whether to force the archive to happen synchronously.
- Return type:
- 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.
- Route attributes:
scope: team_data.content.write
- 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:
- Raises:
- 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. This endpoint can only be used for teams that do not already have a shared team space. Permission : Team member file access.
- Route attributes:
scope: team_data.content.write
- Parameters:
name (str) – Name for the new team folder.
- :param Nullable[
dropbox.team.SyncSettingArg
] sync_setting: The sync setting to apply to this team folder. Only permitted if the team has team selective sync enabled.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_team_folder_get_info(team_folder_ids)
Retrieves metadata for team folders. Permission : Team member file access.
- Route attributes:
scope: team_data.content.read
- Parameters:
team_folder_ids (List[str]) – The list of team folder IDs.
- Return type:
- team_team_folder_list(limit=1000)
Lists all team folders. Permission : Team member file access.
- Route attributes:
scope: team_data.content.read
- Parameters:
limit (int) – The maximum number of results to return per request.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.- Route attributes:
scope: team_data.content.read
- Parameters:
cursor (str) – Indicates from what point to get the next set of team folders.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_team_folder_permanently_delete(team_folder_id)
Permanently deletes an archived team folder. This endpoint cannot be used for teams that have a shared team space. Permission : Team member file access.
- Route attributes:
scope: team_data.content.write
- 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.
- Route attributes:
scope: team_data.content.write
- Parameters:
name (str) – New team folder name.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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.
- Route attributes:
scope: team_data.content.write
- :param Nullable[
dropbox.team.SyncSettingArg
] sync_setting: Sync setting to apply to the team folder itself. Only meaningful if the team folder is not a shared team root.
- :param Nullable[List[
dropbox.team.ContentSyncSettingArg
]] content_sync_settings: Sync settings to apply to contents of this team folder.
- Return type:
- Raises:
- If this raises, ApiError will contain:
- team_token_get_authenticated_admin()
Returns the member profile of the admin who generated the team access token used to make the call.
- Route attributes:
scope: team_info.read
- Return type:
- Raises:
- If this raises, ApiError will contain:
- 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
- dropbox.dropbox_client.create_session(max_connections=8, proxies=None, ca_certs=None)
Creates a session object that can be used by multiple
Dropbox
andDropboxTeam
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.