SDK Documentation

dropbox.oauth – OAuth

exception dropbox.oauth.BadRequestException

Thrown if the redirect URL was missing parameters or if the given parameters were not valid.

The recommended action is to show an HTTP 400 error page.

exception dropbox.oauth.BadStateException

Thrown if all the parameters are correct, but there’s no CSRF token in the session. This probably means that the session expired.

The recommended action is to redirect the user’s browser to try the approval process again.

exception dropbox.oauth.CsrfException

Thrown if the given ‘state’ parameter doesn’t contain the CSRF token from the user’s session. This is blocked to prevent CSRF attacks.

The recommended action is to respond with an HTTP 403 error page.

class dropbox.oauth.DropboxOAuth2Flow(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale=None)

OAuth 2 authorization helper. Use this for web apps.

OAuth 2 has a two-step authorization process. The first step is having the user authorize your app. The second involves getting an OAuth 2 access token from Dropbox.

Example:

from dropbox import DropboxOAuth2Flow

def get_dropbox_auth_flow(web_app_session):
    redirect_uri = "https://my-web-server.org/dropbox-auth-finish"
    return DropboxOAuth2Flow(
        APP_KEY, APP_SECRET, redirect_uri, web_app_session,
        "dropbox-auth-csrf-token")

# URL handler for /dropbox-auth-start
def dropbox_auth_start(web_app_session, request):
    authorize_url = get_dropbox_auth_flow(web_app_session).start()
    redirect_to(authorize_url)

# URL handler for /dropbox-auth-finish
def dropbox_auth_finish(web_app_session, request):
    try:
        oauth_result = \
                get_dropbox_auth_flow(web_app_session).finish(
                    request.query_params)
    except BadRequestException, e:
        http_status(400)
    except BadStateException, e:
        # Start the auth flow again.
        redirect_to("/dropbox-auth-start")
    except CsrfException, e:
        http_status(403)
    except NotApprovedException, e:
        flash('Not approved?  Why not?')
        return redirect_to("/home")
    except ProviderException, e:
        logger.log("Auth error: %s" % (e,))
        http_status(403)
finish(query_params)

Call this after the user has visited the authorize URL (see start()), approved your app and was redirected to your redirect URI.

Parameters:query_params (dict) – The query parameters on the GET request to your redirect URI.
Return type:OAuth2FlowResult
Raises:BadRequestException If the redirect URL was missing parameters or if the given parameters were not valid.
Raises:BadStateException If there’s no CSRF token in the session.
Raises:CsrfException If the state query parameter doesn’t contain the CSRF token from the user’s session.
Raises:NotApprovedException If the user chose not to approve your app.
Raises:ProviderException If Dropbox redirected to your redirect URI with some unexpected error identifier and error message.
start(url_state=None)

Starts the OAuth 2 authorization process.

This function builds an “authorization URL”. You should redirect your user’s browser to this URL, which will give them an opportunity to grant your app access to their Dropbox account. When the user completes this process, they will be automatically redirected to the redirect_uri you passed in to the constructor.

This function will also save a CSRF token to session[csrf_token_session_key] (as provided to the constructor). This CSRF token will be checked on finish() to prevent request forgery.

Parameters:url_state (str) – Any data that you would like to keep in the URL through the authorization process. This exact value will be returned to you by finish().
Returns:The URL for a page on Dropbox’s website. This page will let the user “approve” your app, which gives your app permission to access the user’s Dropbox account. Tell the user to visit this URL and approve your app.
class dropbox.oauth.DropboxOAuth2FlowNoRedirect(consumer_key, consumer_secret, locale=None)

OAuth 2 authorization helper for apps that can’t provide a redirect URI (such as the command-line example apps).

Example:

from dropbox import DropboxOAuth2FlowNoRedirect

auth_flow = DropboxOAuth2FlowNoRedirect(APP_KEY, APP_SECRET)

authorize_url = auth_flow.start()
print "1. Go to: " + authorize_url
print "2. Click \"Allow\" (you might have to log in first)."
print "3. Copy the authorization code."
auth_code = raw_input("Enter the authorization code here: ").strip()

try:
    oauth_result = auth_flow.finish(auth_code)
except Exception, e:
    print('Error: %s' % (e,))
    return

dbx = Dropbox(oauth_result.access_token)
finish(code)

If the user approves your app, they will be presented with an “authorization code”. Have the user copy/paste that authorization code into your app and then call this method to get an access token.

Parameters:code (str) – The authorization code shown to the user when they approved your app.
Return type:OAuth2FlowNoRedirectResult
Raises:The same exceptions as DropboxOAuth2Flow.finish().
start()

Starts the OAuth 2 authorization process.

Returns:The URL for a page on Dropbox’s website. This page will let the user “approve” your app, which gives your app permission to access the user’s Dropbox account. Tell the user to visit this URL and approve your app.
exception dropbox.oauth.NotApprovedException

The user chose not to approve your app.

class dropbox.oauth.OAuth2FlowNoRedirectResult(access_token, account_id, user_id)

Authorization information for an OAuth2Flow performed with no redirect.

class dropbox.oauth.OAuth2FlowResult(access_token, account_id, user_id, url_state)

Authorization information for an OAuth2Flow with redirect.

classmethod from_no_redirect_result(result, url_state)
exception dropbox.oauth.ProviderException

Dropbox redirected to your redirect URI with some unexpected error identifier and error message.

The recommended action is to log the error, tell the user something went wrong, and let them try again.

dropbox.dropbox – Dropbox

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

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

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

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

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

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

dropbox.auth.TokenFromOAuth1Result

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.auth.TokenFromOAuth1Error
auth_token_revoke()

Disables the access token used to authenticate the call.

Return type:None
file_properties_properties_add(path, property_groups)

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

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.AddPropertiesError
file_properties_properties_overwrite(path, property_groups)

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

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.InvalidPropertyGroupError
file_properties_properties_remove(path, property_template_ids)

Remove the specified property group from the file. To remove specific property field key value pairs, see file_properties_properties_update(). To update a template, see file_properties_templates_update_for_user() or file_properties_templates_update_for_team(). Templates can’t be removed once created.

Parameters:
Return type:

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.RemovePropertiesError

Search across property templates for particular property field values.

Parameters:
Return type:

dropbox.file_properties.PropertiesSearchResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.PropertiesSearchError
file_properties_properties_update(path, update_property_groups)

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

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.UpdatePropertiesError
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.

Return type:dropbox.file_properties.AddTemplateResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_add_for_user(name, description, fields)

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

Return type:dropbox.file_properties.AddTemplateResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_get_for_team(template_id)

Get the schema for a specified template.

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

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

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

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

Return type:dropbox.file_properties.ListTemplateResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.file_properties.TemplateError
file_properties_templates_list_for_user()

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

Return type:dropbox.file_properties.ListTemplateResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.file_properties.TemplateError
file_properties_templates_update_for_team(template_id, name=None, description=None, add_fields=None)

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

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

dropbox.file_properties.UpdateTemplateResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_update_for_user(template_id, name=None, description=None, add_fields=None)

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

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

dropbox.file_properties.UpdateTemplateResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_properties.ModifyTemplateError
file_requests_create(title, destination, deadline=None, open=True)

Creates a file request for this user.

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

dropbox.file_requests.FileRequest

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.file_requests.CreateFileRequestError
file_requests_get(id)

Returns the specified file request.

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

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

Return type:dropbox.file_requests.ListFileRequestsResult
file_requests_update(id, title=None, destination=None, deadline=UpdateFileRequestDeadline('no_update', None), open=None)

Update a file request.

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

dropbox.file_requests.FileRequest

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

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

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

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

Parameters:
  • f (bytes) – Contents to upload.
  • property_groups (Nullable) – List of custom properties to add to file.
Return type:

dropbox.files.FileMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UploadErrorWithProperties
files_copy(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

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

dropbox.files.Metadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.RelocationError
files_copy_batch(entries, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

Parameters:
  • entries (list) – List of entries to be moved or copied. Each entry is dropbox.files.RelocationPath.
  • allow_shared_folder (bool) – If true, files_copy_batch() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for files_move_batch().
  • autorename (bool) – If there’s a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_copy_batch_check(async_job_id)

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

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

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

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

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

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

dropbox.files.SaveCopyReferenceResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.SaveCopyReferenceError
files_copy_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

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

dropbox.files.RelocationResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.RelocationError
files_create_folder(path, autorename=False)

Create a folder at a given path.

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

dropbox.files.FolderMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.CreateFolderError
files_create_folder_v2(path, autorename=False)

Create a folder at a given path.

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

dropbox.files.CreateFolderResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.CreateFolderError
files_delete(path)

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

Parameters:path (str) – Path in the user’s Dropbox to delete.
Return type:dropbox.files.Metadata
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.files.DeleteError
files_delete_batch(entries)

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

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

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

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

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

Parameters:path (str) – Path in the user’s Dropbox to delete.
Return type:dropbox.files.DeleteResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.files.DeleteError
files_download(path, rev=None)

Download a file from a user’s Dropbox.

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.DownloadError

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

files_download_to_file(download_path, path, rev=None)

Download a file from a user’s Dropbox.

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.DownloadError
files_get_metadata(path, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False)

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

Parameters:
  • path (str) – The path of a file or folder on Dropbox.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted (bool) – If true, dropbox.files.DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
Return type:

dropbox.files.Metadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.GetMetadataError
files_get_preview(path, rev=None)

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.PreviewError

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

files_get_preview_to_file(download_path, path, rev=None)

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.PreviewError

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. Content-Type of the link is determined automatically by the file’s mime type.

Parameters:path (str) – The path to the file you want a temporary link to.
Return type:dropbox.files.GetTemporaryLinkResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.files.GetTemporaryLinkError
files_get_thumbnail(path, format=ThumbnailFormat('jpeg', None), size=ThumbnailSize('w64h64', None))

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ThumbnailError

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

files_get_thumbnail_batch(entries)

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

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

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ThumbnailError
files_list_folder(path, recursive=False, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_mounted_folders=True, limit=None, shared_link=None)

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

Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
  • shared_link (Nullable) – A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
Return type:

dropbox.files.ListFolderResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ListFolderError
files_list_folder_continue(cursor)

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

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

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

Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
  • shared_link (Nullable) – A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
Return type:

dropbox.files.ListFolderGetLatestCursorResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ListFolderError
files_list_folder_longpoll(cursor, timeout=30)

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

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

dropbox.files.ListFolderLongpollResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ListFolderLongpollError
files_list_revisions(path, mode=ListRevisionsMode('path', None), limit=10)

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

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

dropbox.files.ListRevisionsResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.ListRevisionsError
files_move(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

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

dropbox.files.Metadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.RelocationError
files_move_batch(entries, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

Parameters:
  • entries (list) – List of entries to be moved or copied. Each entry is dropbox.files.RelocationPath.
  • allow_shared_folder (bool) – If true, files_copy_batch() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for files_move_batch().
  • autorename (bool) – If there’s a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_move_batch_check(async_job_id)

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

Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchJobStatus
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.files.PollError
files_move_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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

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

dropbox.files.RelocationResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.RelocationError
files_permanently_delete(path)

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

Parameters:path (str) – Path in the user’s Dropbox to delete.
Return type:None
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.files.DeleteError
files_properties_add(path, property_groups)
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_groups (list) – The property groups which are to be added to a Dropbox file.
Return type:

None

Raises:

dropbox.exceptions.ApiError

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

None

Raises:

dropbox.exceptions.ApiError

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

None

Raises:

dropbox.exceptions.ApiError

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UpdatePropertiesError
files_restore(path, rev)

Restore a file to a specific revision.

Parameters:
  • path (str) – The path to the file you want to restore.
  • rev (str) – The revision to restore for the file.
Return type:

dropbox.files.FileMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.RestoreError
files_save_url(path, url)

Save a specified URL into a file in user’s Dropbox. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

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

dropbox.files.SaveUrlResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.SaveUrlError
files_save_url_check_job_status(async_job_id)

Check the status of a files_save_url() job.

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

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

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

dropbox.files.SearchResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.SearchError
files_upload(f, path, mode=WriteMode('add', None), autorename=False, client_modified=None, mute=False)

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with files_upload_session_start().

Parameters:
  • f (bytes) – Contents to upload.
  • path (str) – Path in the user’s Dropbox to save the file.
  • mode (dropbox.files.WriteMode) – Selects what to do if the file already exists.
  • autorename (bool) – If there’s a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict.
  • client_modified (Nullable) – The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.
  • mute (bool) – Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If True, this tells the clients that this modification shouldn’t result in a user notification.
Return type:

dropbox.files.FileMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UploadError
files_upload_session_append(f, session_id, offset)

Append more data to an upload session. A single request should not upload more than 150 MB.

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UploadSessionLookupError
files_upload_session_append_v2(f, cursor, close=False)

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MB.

Parameters:
Return type:

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UploadSessionLookupError
files_upload_session_finish(f, cursor, commit)

Finish an upload session and save the uploaded data to the given file path. A single request should not upload more than 150 MB.

Parameters:
Return type:

dropbox.files.FileMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.files.UploadSessionFinishError
files_upload_session_finish_batch(entries)

This route helps you commit many files at once into a user’s Dropbox. Use files_upload_session_start() and files_upload_session_append_v2() to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling files_upload_session_finish(), use this route to finish all your upload sessions in a single request. UploadSessionStartArg.close or UploadSessionAppendArg.close needs to be true for the last files_upload_session_start() or files_upload_session_append_v2() call. This route will return a job_id immediately and do the async commit job in background. Use files_upload_session_finish_batch_check() to check the job status. For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request.

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

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

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

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB. This call starts a new upload session with the given data. You can then use files_upload_session_append_v2() to add more data and files_upload_session_finish() to save all the data to a file in Dropbox. A single request should not upload more than 150 MB. An upload session can be used for a maximum of 48 hours. Attempting to use an UploadSessionStartResult.session_id with files_upload_session_append_v2() or files_upload_session_finish() more than 48 hours after its creation will return a UploadSessionLookupError.not_found.

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

dropbox.files.UploadSessionStartResult

paper_docs_archive(doc_id)

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

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

Creates a new Paper doc with the provided content.

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

dropbox.paper.PaperDocCreateUpdateResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.paper.PaperDocCreateError
paper_docs_download(doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown.

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

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

paper_docs_download_to_file(download_path, doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown.

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

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

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

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

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

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

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

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

Parameters:
Return type:

dropbox.paper.ListPaperDocsResponse

paper_docs_list_continue(cursor)

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

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

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

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

Gets the default sharing policy for the given Paper doc.

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

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

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

Updates an existing Paper doc with the provided content.

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

dropbox.paper.PaperDocCreateUpdateResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.paper.PaperDocUpdateError
paper_docs_users_add(doc_id, members, custom_message=None, quiet=False)

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

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

list

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.paper.DocLookupError
paper_docs_users_list(doc_id, limit=1000, filter_by=UserOnPaperDocFilter('shared', None))

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

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

dropbox.paper.ListUsersOnPaperDocResponse

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.paper.DocLookupError
paper_docs_users_list_continue(doc_id, cursor)

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

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

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

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

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

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

The route’s result.

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

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

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

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

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

See request_json_string_with_retry() for description of parameters.

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

See request_json_object() for description of parameters.

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

Adds specified members to a file.

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

list

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.AddFileMemberError
sharing_add_folder_member(shared_folder_id, members, quiet=False, custom_message=None)

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

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.AddFolderMemberError
sharing_change_file_member_access(file, member, access_level)

Identical to update_file_member but with less information returned.

Parameters:
Return type:

dropbox.sharing.FileMemberActionResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.FileMemberActionError
sharing_check_job_status(async_job_id)

Returns the status of an asynchronous job. Apps must have full Dropbox access to use this endpoint.

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

Returns the status of an asynchronous job for sharing a folder. Apps must have full Dropbox access to use this endpoint.

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

Returns the status of an asynchronous job for sharing a folder. Apps must have full Dropbox access to use this endpoint.

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

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

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

dropbox.sharing.PathLinkMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.CreateSharedLinkError

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

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

dropbox.sharing.SharedLinkMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.CreateSharedLinkWithSettingsError
sharing_get_file_metadata(file, actions=None)

Returns shared file metadata.

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

dropbox.sharing.SharedFileMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.GetFileMetadataError
sharing_get_file_metadata_batch(files, actions=None)

Returns shared file metadata.

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

list

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.SharingUserError
sharing_get_folder_metadata(shared_folder_id, actions=None)

Returns shared folder metadata by its folder ID. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.SharedFolderMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.SharedFolderAccessError

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.GetSharedLinkFileError

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

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

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

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

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.GetSharedLinkFileError

Get the shared link’s metadata.

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

dropbox.sharing.SharedLinkMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.SharedLinkError

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

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

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

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

dropbox.sharing.SharedFileMembers

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.ListFileMembersError
sharing_list_file_members_batch(files, limit=10)

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

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

list

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.SharingUserError
sharing_list_file_members_continue(cursor)

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

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

Returns shared folder membership by its folder ID. Apps must have full Dropbox access to use this endpoint.

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

Once a cursor has been retrieved from sharing_list_folder_members(), use this to paginate through all shared folder members. Apps must have full Dropbox access to use this endpoint.

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

Return the list of all shared folders the current user has access to. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.ListFoldersResult

sharing_list_folders_continue(cursor)

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

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

Return the list of all shared folders the current user can mount or unmount. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.ListFoldersResult

sharing_list_mountable_folders_continue(cursor)

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

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

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

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

dropbox.sharing.ListFilesResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.SharingUserError
sharing_list_received_files_continue(cursor)

Get more results with a cursor from sharing_list_received_files().

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

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

Parameters:
Return type:

dropbox.sharing.ListSharedLinksResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.ListSharedLinksError

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

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

dropbox.sharing.SharedLinkMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.ModifySharedLinkSettingsError
sharing_mount_folder(shared_folder_id)

The current user mounts the designated folder. Mount a shared folder for a user after they have been added as a member. Once mounted, the shared folder will appear in their Dropbox. Apps must have full Dropbox access to use this endpoint.

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

The current user relinquishes their membership in the designated file. Note that the current user may still have inherited access to this file through the parent folder. Apps must have full Dropbox access to use this endpoint.

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

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

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

dropbox.sharing.LaunchEmptyResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.RelinquishFolderMembershipError
sharing_remove_file_member(file, member)

Identical to remove_file_member_2 but with less information returned.

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

dropbox.sharing.FileMemberActionIndividualResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.RemoveFileMemberError
sharing_remove_file_member_2(file, member)

Removes a specified member from the file.

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

dropbox.sharing.FileMemberRemoveActionResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.RemoveFileMemberError
sharing_remove_folder_member(shared_folder_id, member, leave_a_copy)

Allows an owner or editor (if the ACL update policy allows) of a shared folder to remove another member. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.LaunchResultBase

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.RemoveFolderMemberError

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

Parameters:url (str) – URL of the shared link.
Return type:None
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.sharing.RevokeSharedLinkError
sharing_share_folder(path, acl_update_policy=None, force_async=False, member_policy=None, shared_link_policy=None, viewer_info_policy=None, actions=None, link_settings=None)

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

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

dropbox.sharing.ShareFolderLaunch

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.ShareFolderError
sharing_transfer_folder(shared_folder_id, to_dropbox_id)

Transfer ownership of a shared folder to a member of the shared folder. User must have AccessLevel.owner access to the shared folder to perform a transfer. Apps must have full Dropbox access to use this endpoint.

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:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.TransferFolderError
sharing_unmount_folder(shared_folder_id)

The current user unmounts the designated folder. They can re-mount the folder at a later time using sharing_mount_folder(). Apps must have full Dropbox access to use this endpoint.

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

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

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

Allows a shared folder owner to unshare the folder. You’ll need to call sharing_check_job_status() to determine if the action has completed successfully. Apps must have full Dropbox access to use this endpoint.

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:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.UnshareFolderError
sharing_update_file_member(file, member, access_level)

Changes a member’s access on a shared file.

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

Allows an owner or editor of a shared folder to update another member’s permissions. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.MemberAccessLevelResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.UpdateFolderMemberError
sharing_update_folder_policy(shared_folder_id, member_policy=None, acl_update_policy=None, viewer_info_policy=None, shared_link_policy=None, link_settings=None, actions=None)

Update the sharing policies for a shared folder. User must have AccessLevel.owner access to the shared folder to update its policies. Apps must have full Dropbox access to use this endpoint.

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

dropbox.sharing.SharedFolderMetadata

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.sharing.UpdateFolderPolicyError
team_log_get_events(limit=1000, account_id=None, time=None, category=None)

Retrieves team events. Permission : Team Auditing.

Parameters:
  • limit (long) – Number of results to return per call.
  • account_id (Nullable) – Filter the events by account ID. Return ony events with this account_id as either Actor, Context, or Participants.
  • time (Nullable) – Filter by time range.
  • category (Nullable) – Filter the returned events to a single category.
Return type:

dropbox.team_log.GetTeamEventsResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team_log.GetTeamEventsError
team_log_get_events_continue(cursor)

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

Parameters:cursor (str) – Indicates from what point to get the next set of events.
Return type:dropbox.team_log.GetTeamEventsResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team_log.GetTeamEventsContinueError
users_get_account(account_id)

Get information about a user’s account.

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

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

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

Get information about the current user’s account.

Return type:dropbox.users.FullAccount
users_get_space_usage()

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

Return type:dropbox.users.SpaceUsage
class dropbox.dropbox.DropboxTeam(oauth2_access_token, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=30)

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

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

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

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

Returns:A Dropbox object that can be used to query on behalf of this member of the team.
Return type:Dropbox
request(route, namespace, request_arg, request_binary, timeout=None)

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

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

The route’s result.

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

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

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

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

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

See request_json_string_with_retry() for description of parameters.

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

See request_json_object() for description of parameters.

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

List all device sessions of a team’s member.

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

dropbox.team.ListMemberDevicesResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.ListMemberDevicesError
team_devices_list_members_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team.

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

dropbox.team.ListMembersDevicesResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.ListMembersDevicesError
team_devices_list_team_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team.

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

dropbox.team.ListTeamDevicesResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.ListTeamDevicesError
team_devices_revoke_device_session(arg)

Revoke a device session of a team’s member.

Return type:None
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.RevokeDeviceSessionError
team_devices_revoke_device_session_batch(revoke_devices)

Revoke a list of device sessions of team members.

Return type:dropbox.team.RevokeDeviceSessionBatchResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.RevokeDeviceSessionBatchError
team_features_get_values(features)

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

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

Retrieves information about a team.

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

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

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

dropbox.team.GroupFullInfo

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupCreateError
team_groups_delete(arg)

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

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

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

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

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

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

Lists groups on a team. Permission : Team Information.

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

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

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

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

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

dropbox.team.GroupMembersChangeResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupMembersAddError
team_groups_members_list(group, limit=1000)

Lists members of a group. Permission : Team Information.

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

dropbox.team.GroupsMembersListResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupSelectorError
team_groups_members_list_continue(cursor)

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

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

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

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

dropbox.team.GroupMembersChangeResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupMembersRemoveError
team_groups_members_set_access_type(group, user, access_type, return_members=True)

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

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

list

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupMemberSetAccessTypeError
team_groups_update(group, return_members=True, new_group_name=None, new_group_external_id=None, new_group_management_type=None)

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

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

dropbox.team.GroupFullInfo

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.GroupUpdateError
team_linked_apps_list_member_linked_apps(team_member_id)

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

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

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

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

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

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

Revoke a linked application of the team member.

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

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.RevokeLinkedAppError
team_linked_apps_revoke_linked_app_batch(revoke_linked_app)

Revoke a list of linked applications of the team members.

Return type:dropbox.team.RevokeLinkedAppBatchResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.RevokeLinkedAppBatchError
team_member_space_limits_get_custom_quota(users)

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

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

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

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

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

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

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

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

dropbox.team.MembersAddLaunch

team_members_add_job_status_get(async_job_id)

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

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

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

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

Lists members of a team. Permission : Team information.

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

dropbox.team.MembersListResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.MembersListError
team_members_list_continue(cursor)

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

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

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

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

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

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

dropbox.team.LaunchEmptyResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.MembersRemoveError
team_members_remove_job_status_get(async_job_id)

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

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

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

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

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

Parameters:
Return type:

dropbox.team.MembersSetPermissionsResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.MembersSetPermissionsError
team_members_set_profile(user, new_email=None, new_external_id=None, new_given_name=None, new_surname=None, new_persistent_id=None)

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

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

dropbox.team.TeamMemberInfo

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.MembersSetProfileError
team_members_suspend(user, wipe_data=True)

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

Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of user to remove/suspend.
  • wipe_data (bool) – If provided, controls if the user’s data will be deleted on their linked devices.
Return type:

None

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.MembersSuspendError
team_members_unsuspend(user)

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

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

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

Parameters:limit (long) – Specifying a value here has no effect.
Return type:dropbox.team.TeamNamespacesListResult
team_namespaces_list_continue(cursor)

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

Parameters:cursor (str) – Indicates from what point to get the next set of team-accessible namespaces.
Return type:dropbox.team.TeamNamespacesListResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.TeamNamespacesListContinueError
team_properties_template_add(name, description, fields)
team_properties_template_get(template_id)
Parameters:template_id (str) – An identifier for template added by route See team_templates_add_for_user() or team_templates_add_for_team().
Return type:dropbox.team.GetTemplateResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.TemplateError
team_properties_template_list()
team_properties_template_update(template_id, name=None, description=None, add_fields=None)
Parameters:
  • template_id (str) – An identifier for template added by See team_templates_add_for_user() or team_templates_add_for_team().
  • name (Nullable) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable) – Description for the new template. Template descriptions can be up to 1024 bytes.
  • add_fields (Nullable) – Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:

dropbox.team.UpdateTemplateResult

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.ModifyTemplateError
team_reports_get_activity(start_date=None, end_date=None)

Retrieves reporting data about a team’s user activity.

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

dropbox.team.GetActivityReport

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.DateRangeError
team_reports_get_devices(start_date=None, end_date=None)

Retrieves reporting data about a team’s linked devices.

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

dropbox.team.GetDevicesReport

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.DateRangeError
team_reports_get_membership(start_date=None, end_date=None)

Retrieves reporting data about a team’s membership.

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

dropbox.team.GetMembershipReport

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.DateRangeError
team_reports_get_storage(start_date=None, end_date=None)

Retrieves reporting data about a team’s storage usage.

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

dropbox.team.GetStorageReport

Raises:

dropbox.exceptions.ApiError

If this raises, ApiError.reason is of type:
dropbox.team.DateRangeError
team_team_folder_activate(team_folder_id)

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

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

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

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

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

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

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

Parameters:name (str) – Name for the new team folder.
Return type:dropbox.team.TeamFolderMetadata
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.TeamFolderCreateError
team_team_folder_get_info(team_folder_ids)

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

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

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

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

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

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

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

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

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

Parameters:name (str) – New team folder name.
Return type:dropbox.team.TeamFolderMetadata
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.TeamFolderRenameError
team_token_get_authenticated_admin()

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

Return type:dropbox.team.TokenGetAuthenticatedAdminResult
Raises:dropbox.exceptions.ApiError
If this raises, ApiError.reason is of type:
dropbox.team.TokenGetAuthenticatedAdminError
dropbox.dropbox.create_session(max_connections=8, proxies=None)

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

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

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

dropbox.async – Async

class dropbox.async.LaunchEmptyResult(tag, value=None)

Bases: dropbox.async.LaunchResultBase

Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:complete – The job finished synchronously and successfully.
complete = LaunchEmptyResult('complete', None)
is_complete()

Check if the union tag is complete.

Return type:bool
class dropbox.async.LaunchResultBase(tag, value=None)

Bases: dropbox.stone_base.Union

Result returned by methods that launch an asynchronous job. A method who may either launch an asynchronous job, or complete the request synchronously, can use this union by extending it, and adding a ‘complete’ field with the type of the synchronous response. See LaunchEmptyResult for an example.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:async_job_id (str) – This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
classmethod async_job_id(val)

Create an instance of this class set to the async_job_id tag with value val.

Parameters:val (str) –
Return type:LaunchResultBase
get_async_job_id()

This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.

Only call this if is_async_job_id() is true.

Return type:str
is_async_job_id()

Check if the union tag is async_job_id.

Return type:bool
class dropbox.async.PollArg(async_job_id=None)

Bases: object

Arguments for methods that poll the status of an asynchronous job.

Variables:async_job_id – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
__init__(async_job_id=None)
async_job_id

Id of the asynchronous job. This is the value of a response returned from the method that launched the job.

Return type:str
class dropbox.async.PollEmptyResult(tag, value=None)

Bases: dropbox.async.PollResultBase

Result returned by methods that poll for the status of an asynchronous job. Upon completion of the job, no additional information is returned.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:complete – The asynchronous job has completed successfully.
complete = PollEmptyResult('complete', None)
is_complete()

Check if the union tag is complete.

Return type:bool
class dropbox.async.PollError(tag, value=None)

Bases: dropbox.stone_base.Union

Error returned by methods for polling the status of asynchronous job.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • invalid_async_job_id – The job ID is invalid.
  • internal_error – Something went wrong with the job on Dropbox’s end. You’ll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
internal_error = PollError('internal_error', None)
invalid_async_job_id = PollError('invalid_async_job_id', None)
is_internal_error()

Check if the union tag is internal_error.

Return type:bool
is_invalid_async_job_id()

Check if the union tag is invalid_async_job_id.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = PollError('other', None)
class dropbox.async.PollResultBase(tag, value=None)

Bases: dropbox.stone_base.Union

Result returned by methods that poll for the status of an asynchronous job. Unions that extend this union should add a ‘complete’ field with a type of the information returned upon job completion. See PollEmptyResult for an example.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:in_progress – The asynchronous job is still in progress.
in_progress = PollResultBase('in_progress', None)
is_in_progress()

Check if the union tag is in_progress.

Return type:bool

dropbox.auth – Auth

class dropbox.auth.AccessError(tag, value=None)

Bases: dropbox.stone_base.Union

Error occurred because the account doesn’t have permission to access the resource.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
get_invalid_account_type()

Current account type cannot access the resource.

Only call this if is_invalid_account_type() is true.

Return type:InvalidAccountTypeError
get_paper_access_denied()

Current account cannot access Paper.

Only call this if is_paper_access_denied() is true.

Return type:PaperAccessError
classmethod invalid_account_type(val)

Create an instance of this class set to the invalid_account_type tag with value val.

Parameters:val (InvalidAccountTypeError) –
Return type:AccessError
is_invalid_account_type()

Check if the union tag is invalid_account_type.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_paper_access_denied()

Check if the union tag is paper_access_denied.

Return type:bool
other = AccessError('other', None)
classmethod paper_access_denied(val)

Create an instance of this class set to the paper_access_denied tag with value val.

Parameters:val (PaperAccessError) –
Return type:AccessError
class dropbox.auth.AuthError(tag, value=None)

Bases: dropbox.stone_base.Union

Errors occurred during authentication.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
invalid_access_token = AuthError('invalid_access_token', None)
invalid_select_admin = AuthError('invalid_select_admin', None)
invalid_select_user = AuthError('invalid_select_user', None)
is_invalid_access_token()

Check if the union tag is invalid_access_token.

Return type:bool
is_invalid_select_admin()

Check if the union tag is invalid_select_admin.

Return type:bool
is_invalid_select_user()

Check if the union tag is invalid_select_user.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_user_suspended()

Check if the union tag is user_suspended.

Return type:bool
other = AuthError('other', None)
user_suspended = AuthError('user_suspended', None)
class dropbox.auth.InvalidAccountTypeError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • endpoint – Current account type doesn’t have permission to access this route endpoint.
  • feature – Current account type doesn’t have permission to access this feature.
endpoint = InvalidAccountTypeError('endpoint', None)
feature = InvalidAccountTypeError('feature', None)
is_endpoint()

Check if the union tag is endpoint.

Return type:bool
is_feature()

Check if the union tag is feature.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = InvalidAccountTypeError('other', None)
class dropbox.auth.PaperAccessError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
is_not_paper_user()

Check if the union tag is not_paper_user.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_paper_disabled()

Check if the union tag is paper_disabled.

Return type:bool
not_paper_user = PaperAccessError('not_paper_user', None)
other = PaperAccessError('other', None)
paper_disabled = PaperAccessError('paper_disabled', None)
class dropbox.auth.RateLimitError(reason=None, retry_after=None)

Bases: object

Error occurred because the app is being rate limited.

Variables:
  • reason – The reason why the app is being rate limited.
  • retry_after – The number of seconds that the app should wait before making another request.
__init__(reason=None, retry_after=None)
reason

The reason why the app is being rate limited.

Return type:RateLimitReason
retry_after

The number of seconds that the app should wait before making another request.

Return type:long
class dropbox.auth.RateLimitReason(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
is_other()

Check if the union tag is other.

Return type:bool
is_too_many_requests()

Check if the union tag is too_many_requests.

Return type:bool
is_too_many_write_operations()

Check if the union tag is too_many_write_operations.

Return type:bool
other = RateLimitReason('other', None)
too_many_requests = RateLimitReason('too_many_requests', None)
too_many_write_operations = RateLimitReason('too_many_write_operations', None)
class dropbox.auth.TokenFromOAuth1Arg(oauth1_token=None, oauth1_token_secret=None)

Bases: object

Variables:
__init__(oauth1_token=None, oauth1_token_secret=None)
oauth1_token

The supplied OAuth 1.0 access token.

Return type:str
oauth1_token_secret

The token secret associated with the supplied access token.

Return type:str
class dropbox.auth.TokenFromOAuth1Error(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
app_id_mismatch = TokenFromOAuth1Error('app_id_mismatch', None)
invalid_oauth1_token_info = TokenFromOAuth1Error('invalid_oauth1_token_info', None)
is_app_id_mismatch()

Check if the union tag is app_id_mismatch.

Return type:bool
is_invalid_oauth1_token_info()

Check if the union tag is invalid_oauth1_token_info.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = TokenFromOAuth1Error('other', None)
class dropbox.auth.TokenFromOAuth1Result(oauth2_token=None)

Bases: object

Variables:oauth2_token – The OAuth 2.0 token generated from the supplied OAuth 1.0 token.
__init__(oauth2_token=None)
oauth2_token

The OAuth 2.0 token generated from the supplied OAuth 1.0 token.

Return type:str

dropbox.files – Files

This namespace contains endpoints and data types for basic file operations.

class dropbox.files.AlphaGetMetadataArg(path=None, include_media_info=None, include_deleted=None, include_has_explicit_shared_members=None, include_property_templates=None)

Bases: dropbox.files.GetMetadataArg

Variables:include_property_templates – If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties.
include_property_templates

If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties.

Return type:list of [str]
class dropbox.files.AlphaGetMetadataError(tag, value=None)

Bases: dropbox.files.GetMetadataError

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_properties_error()

Only call this if is_properties_error() is true.

Return type:file_properties.LookUpPropertiesError_validator
is_properties_error()

Check if the union tag is properties_error.

Return type:bool
classmethod properties_error(val)

Create an instance of this class set to the properties_error tag with value val.

Parameters:val (file_properties.LookUpPropertiesError_validator) –
Return type:AlphaGetMetadataError
class dropbox.files.CommitInfo(path=None, mode=None, autorename=None, client_modified=None, mute=None)

Bases: object

Variables:
  • path – Path in the user’s Dropbox to save the file.
  • mode – Selects what to do if the file already exists.
  • autorename – If there’s a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict.
  • client_modified – The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.
  • mute – Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If True, this tells the clients that this modification shouldn’t result in a user notification.
autorename

If there’s a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict.

Return type:bool
client_modified

The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.

Return type:datetime.datetime
mode

Selects what to do if the file already exists.

Return type:WriteMode
mute

Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If True, this tells the clients that this modification shouldn’t result in a user notification.

Return type:bool
path

Path in the user’s Dropbox to save the file.

Return type:str
class dropbox.files.CommitInfoWithProperties(path=None, mode=None, autorename=None, client_modified=None, mute=None, property_groups=None)

Bases: dropbox.files.CommitInfo

Variables:property_groups – List of custom properties to add to file.
property_groups

List of custom properties to add to file.

Return type:list of [file_properties.PropertyGroup_validator]
class dropbox.files.CreateFolderArg(path=None, autorename=None)

Bases: object

Variables:
  • path – Path in the user’s Dropbox to create.
  • autorename – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
autorename

If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.

Return type:bool
path

Path in the user’s Dropbox to create.

Return type:str
class dropbox.files.CreateFolderError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:WriteError
is_path()

Check if the union tag is path.

Return type:bool
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (WriteError) –
Return type:CreateFolderError
class dropbox.files.CreateFolderResult(metadata=None)

Bases: dropbox.files.FileOpsResult

Variables:metadata – Metadata of the created folder.
metadata

Metadata of the created folder.

Return type:FolderMetadata
class dropbox.files.DeleteArg(path=None)

Bases: object

Variables:path – Path in the user’s Dropbox to delete.
path

Path in the user’s Dropbox to delete.

Return type:str
class dropbox.files.DeleteBatchArg(entries=None)

Bases: object

entries
Return type:list of [DeleteArg]
class dropbox.files.DeleteBatchError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:too_many_write_operations – Use DeleteError.too_many_write_operations. dropbox.dropbox.Dropbox.files_delete_batch() now provides smaller granularity about which entry has failed because of this.
is_other()

Check if the union tag is other.

Return type:bool
is_too_many_write_operations()

Check if the union tag is too_many_write_operations.

Return type:bool
other = DeleteBatchError('other', None)
too_many_write_operations = DeleteBatchError('too_many_write_operations', None)
class dropbox.files.DeleteBatchJobStatus(tag, value=None)

Bases: dropbox.async.PollResultBase

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (DeleteBatchResult) –
Return type:DeleteBatchJobStatus
classmethod failed(val)

Create an instance of this class set to the failed tag with value val.

Parameters:val (DeleteBatchError) –
Return type:DeleteBatchJobStatus
get_complete()

The batch delete has finished.

Only call this if is_complete() is true.

Return type:DeleteBatchResult
get_failed()

The batch delete has failed.

Only call this if is_failed() is true.

Return type:DeleteBatchError
is_complete()

Check if the union tag is complete.

Return type:bool
is_failed()

Check if the union tag is failed.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = DeleteBatchJobStatus('other', None)
class dropbox.files.DeleteBatchLaunch(tag, value=None)

Bases: dropbox.async.LaunchResultBase

Result returned by dropbox.dropbox.Dropbox.files_delete_batch() that may either launch an asynchronous job or complete synchronously.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (DeleteBatchResult) –
Return type:DeleteBatchLaunch
get_complete()

Only call this if is_complete() is true.

Return type:DeleteBatchResult
is_complete()

Check if the union tag is complete.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = DeleteBatchLaunch('other', None)
class dropbox.files.DeleteBatchResult(entries=None)

Bases: dropbox.files.FileOpsResult

entries
Return type:list of [DeleteBatchResultEntry]
class dropbox.files.DeleteBatchResultData(metadata=None)

Bases: object

Variables:metadata – Metadata of the deleted object.
metadata

Metadata of the deleted object.

Return type:Metadata
class dropbox.files.DeleteBatchResultEntry(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

classmethod failure(val)

Create an instance of this class set to the failure tag with value val.

Parameters:val (DeleteError) –
Return type:DeleteBatchResultEntry
get_failure()

Only call this if is_failure() is true.

Return type:DeleteError
get_success()

Only call this if is_success() is true.

Return type:DeleteBatchResultData
is_failure()

Check if the union tag is failure.

Return type:bool
is_success()

Check if the union tag is success.

Return type:bool
classmethod success(val)

Create an instance of this class set to the success tag with value val.

Parameters:val (DeleteBatchResultData) –
Return type:DeleteBatchResultEntry
class dropbox.files.DeleteError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • too_many_write_operations – There are too many write operations in user’s Dropbox. Please retry this request.
  • too_many_files – There are too many files in one request. Please retry with fewer files.
get_path_lookup()

Only call this if is_path_lookup() is true.

Return type:LookupError
get_path_write()

Only call this if is_path_write() is true.

Return type:WriteError
is_other()

Check if the union tag is other.

Return type:bool
is_path_lookup()

Check if the union tag is path_lookup.

Return type:bool
is_path_write()

Check if the union tag is path_write.

Return type:bool
is_too_many_files()

Check if the union tag is too_many_files.

Return type:bool
is_too_many_write_operations()

Check if the union tag is too_many_write_operations.

Return type:bool
other = DeleteError('other', None)
classmethod path_lookup(val)

Create an instance of this class set to the path_lookup tag with value val.

Parameters:val (LookupError) –
Return type:DeleteError
classmethod path_write(val)

Create an instance of this class set to the path_write tag with value val.

Parameters:val (WriteError) –
Return type:DeleteError
too_many_files = DeleteError('too_many_files', None)
too_many_write_operations = DeleteError('too_many_write_operations', None)
class dropbox.files.DeleteResult(metadata=None)

Bases: dropbox.files.FileOpsResult

Variables:metadata – Metadata of the deleted object.
metadata

Metadata of the deleted object.

Return type:Metadata
class dropbox.files.DeletedMetadata(name=None, path_lower=None, path_display=None, parent_shared_folder_id=None)

Bases: dropbox.files.Metadata

Indicates that there used to be a file or folder at this path, but it no longer exists.

class dropbox.files.Dimensions(height=None, width=None)

Bases: object

Dimensions for a photo or video.

Variables:
  • height – Height of the photo/video.
  • width – Width of the photo/video.
height

Height of the photo/video.

Return type:long
width

Width of the photo/video.

Return type:long
class dropbox.files.DownloadArg(path=None, rev=None)

Bases: object

Variables:
  • path – The path of the file to download.
  • rev – Please specify revision in path instead.
path

The path of the file to download.

Return type:str
rev

Please specify revision in path instead.

Return type:str
class dropbox.files.DownloadError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = DownloadError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:DownloadError
class dropbox.files.FileMetadata(name=None, id=None, client_modified=None, server_modified=None, rev=None, size=None, path_lower=None, path_display=None, parent_shared_folder_id=None, media_info=None, sharing_info=None, property_groups=None, has_explicit_shared_members=None, content_hash=None)

Bases: dropbox.files.Metadata

Variables:
  • id – A unique identifier for the file.
  • client_modified – For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
  • server_modified – The last time the file was modified on Dropbox.
  • rev – A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
  • size – The file size in bytes.
  • media_info – Additional information if the file is a photo or video.
  • sharing_info – Set if this file is contained in a shared folder.
  • property_groups – Additional information if the file has custom properties with the property template specified.
  • has_explicit_shared_members – This flag will only be present if include_has_explicit_shared_members is true in dropbox.dropbox.Dropbox.files_list_folder() or dropbox.dropbox.Dropbox.files_get_metadata(). If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder.
  • content_hash – A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page.
client_modified

For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.

Return type:datetime.datetime
content_hash

A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page.

Return type:str
has_explicit_shared_members

This flag will only be present if include_has_explicit_shared_members is true in dropbox.dropbox.Dropbox.files_list_folder() or dropbox.dropbox.Dropbox.files_get_metadata(). If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder.

Return type:bool
id

A unique identifier for the file.

Return type:str
media_info

Additional information if the file is a photo or video.

Return type:MediaInfo
property_groups

Additional information if the file has custom properties with the property template specified.

Return type:list of [file_properties.PropertyGroup_validator]
rev

A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.

Return type:str
server_modified

The last time the file was modified on Dropbox.

Return type:datetime.datetime
sharing_info

Set if this file is contained in a shared folder.

Return type:FileSharingInfo
size

The file size in bytes.

Return type:long
class dropbox.files.FileOpsResult

Bases: object

class dropbox.files.FileSharingInfo(read_only=None, parent_shared_folder_id=None, modified_by=None)

Bases: dropbox.files.SharingInfo

Sharing info for a file which is contained by a shared folder.

Variables:
  • parent_shared_folder_id – ID of shared folder that holds this file.
  • modified_by – The last user who modified the file. This field will be null if the user’s account has been deleted.
modified_by

The last user who modified the file. This field will be null if the user’s account has been deleted.

Return type:str
parent_shared_folder_id

ID of shared folder that holds this file.

Return type:str
class dropbox.files.FolderMetadata(name=None, id=None, path_lower=None, path_display=None, parent_shared_folder_id=None, shared_folder_id=None, sharing_info=None, property_groups=None)

Bases: dropbox.files.Metadata

Variables:
  • id – A unique identifier for the folder.
  • shared_folder_id – Please use sharing_info instead.
  • sharing_info – Set if the folder is contained in a shared folder or is a shared folder mount point.
  • property_groups – Additional information if the file has custom properties with the property template specified.
id

A unique identifier for the folder.

Return type:str
property_groups

Additional information if the file has custom properties with the property template specified.

Return type:list of [file_properties.PropertyGroup_validator]
shared_folder_id

Please use sharing_info instead.

Return type:str
sharing_info

Set if the folder is contained in a shared folder or is a shared folder mount point.

Return type:FolderSharingInfo
class dropbox.files.FolderSharingInfo(read_only=None, parent_shared_folder_id=None, shared_folder_id=None, traverse_only=None, no_access=None)

Bases: dropbox.files.SharingInfo

Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.

Variables:
  • parent_shared_folder_id – Set if the folder is contained by a shared folder.
  • shared_folder_id – If this folder is a shared folder mount point, the ID of the shared folder mounted at this location.
  • traverse_only – Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don’t have read access to this folder. They do, however, have access to some sub folder.
  • no_access – Specifies that the folder cannot be accessed by the user.
no_access

Specifies that the folder cannot be accessed by the user.

Return type:bool
parent_shared_folder_id

Set if the folder is contained by a shared folder.

Return type:str
shared_folder_id

If this folder is a shared folder mount point, the ID of the shared folder mounted at this location.

Return type:str
traverse_only

Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don’t have read access to this folder. They do, however, have access to some sub folder.

Return type:bool
class dropbox.files.GetCopyReferenceArg(path=None)

Bases: object

Variables:path – The path to the file or folder you want to get a copy reference to.
path

The path to the file or folder you want to get a copy reference to.

Return type:str
class dropbox.files.GetCopyReferenceError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = GetCopyReferenceError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:GetCopyReferenceError
class dropbox.files.GetCopyReferenceResult(metadata=None, copy_reference=None, expires=None)

Bases: object

Variables:
  • metadata – Metadata of the file or folder.
  • copy_reference – A copy reference to the file or folder.
  • expires – The expiration date of the copy reference. This value is currently set to be far enough in the future so that expiration is effectively not an issue.
copy_reference

A copy reference to the file or folder.

Return type:str
expires

The expiration date of the copy reference. This value is currently set to be far enough in the future so that expiration is effectively not an issue.

Return type:datetime.datetime
metadata

Metadata of the file or folder.

Return type:Metadata
class dropbox.files.GetMetadataArg(path=None, include_media_info=None, include_deleted=None, include_has_explicit_shared_members=None)

Bases: object

Variables:
include_deleted

If true, DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned.

Return type:bool
include_has_explicit_shared_members

If true, the results will include a flag for each file indicating whether or not that file has any explicit members.

Return type:bool
include_media_info

If true, FileMetadata.media_info is set for photo and video.

Return type:bool
path

The path of a file or folder on Dropbox.

Return type:str
class dropbox.files.GetMetadataError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_path()

Check if the union tag is path.

Return type:bool
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:GetMetadataError
class dropbox.files.GetTemporaryLinkArg(path=None)

Bases: object

Variables:path – The path to the file you want a temporary link to.
path

The path to the file you want a temporary link to.

Return type:str
class dropbox.files.GetTemporaryLinkError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = GetTemporaryLinkError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:GetTemporaryLinkError
class dropbox.files.GetTemporaryLinkResult(metadata=None, link=None)

Bases: object

Variables:
  • metadata – Metadata of the file.
  • link – The temporary link which can be used to stream content the file.

The temporary link which can be used to stream content the file.

Return type:str
metadata

Metadata of the file.

Return type:FileMetadata
class dropbox.files.GetThumbnailBatchArg(entries=None)

Bases: object

Arguments for dropbox.dropbox.Dropbox.files_get_thumbnail_batch().

Variables:entries – List of files to get thumbnails.
entries

List of files to get thumbnails.

Return type:list of [ThumbnailArg]
class dropbox.files.GetThumbnailBatchError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:too_many_files – The operation involves more than 25 files.
is_other()

Check if the union tag is other.

Return type:bool
is_too_many_files()

Check if the union tag is too_many_files.

Return type:bool
other = GetThumbnailBatchError('other', None)
too_many_files = GetThumbnailBatchError('too_many_files', None)
class dropbox.files.GetThumbnailBatchResult(entries=None)

Bases: object

Variables:entries – List of files and their thumbnails.
entries

List of files and their thumbnails.

Return type:list of [GetThumbnailBatchResultEntry]
class dropbox.files.GetThumbnailBatchResultData(metadata=None, thumbnail=None)

Bases: object

metadata
Return type:FileMetadata
thumbnail
Return type:str
class dropbox.files.GetThumbnailBatchResultEntry(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:failure (ThumbnailError) – The result for this file if it was an error.
classmethod failure(val)

Create an instance of this class set to the failure tag with value val.

Parameters:val (ThumbnailError) –
Return type:GetThumbnailBatchResultEntry
get_failure()

The result for this file if it was an error.

Only call this if is_failure() is true.

Return type:ThumbnailError
get_success()

Only call this if is_success() is true.

Return type:GetThumbnailBatchResultData
is_failure()

Check if the union tag is failure.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_success()

Check if the union tag is success.

Return type:bool
other = GetThumbnailBatchResultEntry('other', None)
classmethod success(val)

Create an instance of this class set to the success tag with value val.

Parameters:val (GetThumbnailBatchResultData) –
Return type:GetThumbnailBatchResultEntry
class dropbox.files.GpsCoordinates(latitude=None, longitude=None)

Bases: object

GPS coordinates for a photo or video.

Variables:
  • latitude – Latitude of the GPS coordinates.
  • longitude – Longitude of the GPS coordinates.
latitude

Latitude of the GPS coordinates.

Return type:float
longitude

Longitude of the GPS coordinates.

Return type:float
class dropbox.files.ListFolderArg(path=None, recursive=None, include_media_info=None, include_deleted=None, include_has_explicit_shared_members=None, include_mounted_folders=None, limit=None, shared_link=None)

Bases: object

Variables:
  • path – A unique identifier for the file.
  • recursive – 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 – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
  • shared_link – A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
include_deleted

If true, the results will include entries for files and folders that used to exist but were deleted.

Return type:bool
include_has_explicit_shared_members

If true, the results will include a flag for each file indicating whether or not that file has any explicit members.

Return type:bool
include_media_info

If true, FileMetadata.media_info is set for photo and video.

Return type:bool
include_mounted_folders

If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.

Return type:bool
limit

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.

Return type:long
path

A unique identifier for the file.

Return type:str
recursive

If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.

Return type:bool

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.

Return type:SharedLink
class dropbox.files.ListFolderContinueArg(cursor=None)

Bases: object

Variables:cursor – The cursor returned by your last call to dropbox.dropbox.Dropbox.files_list_folder() or dropbox.dropbox.Dropbox.files_list_folder_continue().
cursor

The cursor returned by your last call to dropbox.dropbox.Dropbox.files_list_folder() or dropbox.dropbox.Dropbox.files_list_folder_continue().

Return type:str
class dropbox.files.ListFolderContinueError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:reset – Indicates that the cursor has been invalidated. Call dropbox.dropbox.Dropbox.files_list_folder() to obtain a new cursor.
get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
is_reset()

Check if the union tag is reset.

Return type:bool
other = ListFolderContinueError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:ListFolderContinueError
reset = ListFolderContinueError('reset', None)
class dropbox.files.ListFolderError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = ListFolderError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:ListFolderError
class dropbox.files.ListFolderGetLatestCursorResult(cursor=None)

Bases: object

Variables:cursor – Pass the cursor into dropbox.dropbox.Dropbox.files_list_folder_continue() to see what’s changed in the folder since your previous query.
cursor

Pass the cursor into dropbox.dropbox.Dropbox.files_list_folder_continue() to see what’s changed in the folder since your previous query.

Return type:str
class dropbox.files.ListFolderLongpollArg(cursor=None, timeout=None)

Bases: object

Variables:
cursor

A cursor as returned by dropbox.dropbox.Dropbox.files_list_folder() or dropbox.dropbox.Dropbox.files_list_folder_continue(). Cursors retrieved by setting ListFolderArg.include_media_info to True are not supported.

Return type:str
timeout

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:long
class dropbox.files.ListFolderLongpollError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:reset – Indicates that the cursor has been invalidated. Call dropbox.dropbox.Dropbox.files_list_folder() to obtain a new cursor.
is_other()

Check if the union tag is other.

Return type:bool
is_reset()

Check if the union tag is reset.

Return type:bool
other = ListFolderLongpollError('other', None)
reset = ListFolderLongpollError('reset', None)
class dropbox.files.ListFolderLongpollResult(changes=None, backoff=None)

Bases: object

Variables:
backoff

If present, backoff for at least this many seconds before calling dropbox.dropbox.Dropbox.files_list_folder_longpoll() again.

Return type:long
changes

Indicates whether new changes are available. If true, call dropbox.dropbox.Dropbox.files_list_folder_continue() to retrieve the changes.

Return type:bool
class dropbox.files.ListFolderResult(entries=None, cursor=None, has_more=None)

Bases: object

Variables:
cursor

Pass the cursor into dropbox.dropbox.Dropbox.files_list_folder_continue() to see what’s changed in the folder since your previous query.

Return type:str
entries

The files and (direct) subfolders in the folder.

Return type:list of [Metadata]
has_more

If true, then there are more entries available. Pass the cursor to dropbox.dropbox.Dropbox.files_list_folder_continue() to retrieve the rest.

Return type:bool
class dropbox.files.ListRevisionsArg(path=None, mode=None, limit=None)

Bases: object

Variables:
  • path – The path to the file you want to see the revisions of.
  • mode – Determines the behavior of the API in listing the revisions for a given file path or id.
  • limit – The maximum number of revision entries returned.
limit

The maximum number of revision entries returned.

Return type:long
mode

Determines the behavior of the API in listing the revisions for a given file path or id.

Return type:ListRevisionsMode
path

The path to the file you want to see the revisions of.

Return type:str
class dropbox.files.ListRevisionsError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = ListRevisionsError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:ListRevisionsError
class dropbox.files.ListRevisionsMode(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • path – Returns revisions with the same file path as identified by the latest file entry at the given file path or id.
  • id – Returns revisions with the same file id as identified by the latest file entry at the given file path or id.
id = ListRevisionsMode('id', None)
is_id()

Check if the union tag is id.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = ListRevisionsMode('other', None)
path = ListRevisionsMode('path', None)
class dropbox.files.ListRevisionsResult(is_deleted=None, entries=None, server_deleted=None)

Bases: object

Variables:
  • is_deleted – If the file identified by the latest revision in the response is either deleted or moved.
  • server_deleted – The time of deletion if the file was deleted.
  • entries – The revisions for the file. Only revisions that are not deleted will show up here.
entries

The revisions for the file. Only revisions that are not deleted will show up here.

Return type:list of [FileMetadata]
is_deleted

If the file identified by the latest revision in the response is either deleted or moved.

Return type:bool
server_deleted

The time of deletion if the file was deleted.

Return type:datetime.datetime
class dropbox.files.LookupError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • not_found – There is nothing at the given path.
  • not_file – We were expecting a file, but the given path refers to something that isn’t a file.
  • not_folder – We were expecting a folder, but the given path refers to something that isn’t a folder.
  • restricted_content – The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
get_malformed_path()

Only call this if is_malformed_path() is true.

Return type:Optional[str]
is_malformed_path()

Check if the union tag is malformed_path.

Return type:bool
is_not_file()

Check if the union tag is not_file.

Return type:bool
is_not_folder()

Check if the union tag is not_folder.

Return type:bool
is_not_found()

Check if the union tag is not_found.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_restricted_content()

Check if the union tag is restricted_content.

Return type:bool
classmethod malformed_path(val)

Create an instance of this class set to the malformed_path tag with value val.

Parameters:val (Optional[str]) –
Return type:LookupError
not_file = LookupError('not_file', None)
not_folder = LookupError('not_folder', None)
not_found = LookupError('not_found', None)
other = LookupError('other', None)
restricted_content = LookupError('restricted_content', None)
class dropbox.files.MediaInfo(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • pending – Indicate the photo/video is still under processing and metadata is not available yet.
  • metadata (MediaMetadata) – The metadata for the photo/video.
get_metadata()

The metadata for the photo/video.

Only call this if is_metadata() is true.

Return type:MediaMetadata
is_metadata()

Check if the union tag is metadata.

Return type:bool
is_pending()

Check if the union tag is pending.

Return type:bool
classmethod metadata(val)

Create an instance of this class set to the metadata tag with value val.

Parameters:val (MediaMetadata) –
Return type:MediaInfo
pending = MediaInfo('pending', None)
class dropbox.files.MediaMetadata(dimensions=None, location=None, time_taken=None)

Bases: object

Metadata for a photo or video.

Variables:
  • dimensions – Dimension of the photo/video.
  • location – The GPS coordinate of the photo/video.
  • time_taken – The timestamp when the photo/video is taken.
dimensions

Dimension of the photo/video.

Return type:Dimensions
location

The GPS coordinate of the photo/video.

Return type:GpsCoordinates
time_taken

The timestamp when the photo/video is taken.

Return type:datetime.datetime
class dropbox.files.Metadata(name=None, path_lower=None, path_display=None, parent_shared_folder_id=None)

Bases: object

Metadata for a file or folder.

Variables:
  • name – The last component of the path (including extension). This never contains a slash.
  • path_lower – The lowercased full path in the user’s Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted.
  • path_display – The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user’s filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won’t be returned by dropbox.dropbox.Dropbox.files_list_folder_continue(). This field will be null if the file or folder is not mounted.
  • parent_shared_folder_id – Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead.
name

The last component of the path (including extension). This never contains a slash.

Return type:str
parent_shared_folder_id

Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead.

Return type:str
path_display

The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user’s filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won’t be returned by dropbox.dropbox.Dropbox.files_list_folder_continue(). This field will be null if the file or folder is not mounted.

Return type:str
path_lower

The lowercased full path in the user’s Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted.

Return type:str
class dropbox.files.PhotoMetadata(dimensions=None, location=None, time_taken=None)

Bases: dropbox.files.MediaMetadata

Metadata for a photo.

class dropbox.files.PreviewArg(path=None, rev=None)

Bases: object

Variables:
  • path – The path of the file to preview.
  • rev – Please specify revision in path instead.
path

The path of the file to preview.

Return type:str
rev

Please specify revision in path instead.

Return type:str
class dropbox.files.PreviewError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • path (LookupError) – An error occurs when downloading metadata for the file.
  • in_progress – This preview generation is still in progress and the file is not ready for preview yet.
  • unsupported_extension – The file extension is not supported preview generation.
  • unsupported_content – The file content is not supported for preview generation.
get_path()

An error occurs when downloading metadata for the file.

Only call this if is_path() is true.

Return type:LookupError
in_progress = PreviewError('in_progress', None)
is_in_progress()

Check if the union tag is in_progress.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
is_unsupported_content()

Check if the union tag is unsupported_content.

Return type:bool
is_unsupported_extension()

Check if the union tag is unsupported_extension.

Return type:bool
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:PreviewError
unsupported_content = PreviewError('unsupported_content', None)
unsupported_extension = PreviewError('unsupported_extension', None)
class dropbox.files.RelocationArg(from_path=None, to_path=None, allow_shared_folder=None, autorename=None, allow_ownership_transfer=None)

Bases: dropbox.files.RelocationPath

Variables:
allow_ownership_transfer

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:bool
allow_shared_folder

If true, dropbox.dropbox.Dropbox.files_copy() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for dropbox.dropbox.Dropbox.files_move().

Return type:bool
autorename

If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.

Return type:bool
class dropbox.files.RelocationBatchArg(entries=None, allow_shared_folder=None, autorename=None, allow_ownership_transfer=None)

Bases: object

Variables:
allow_ownership_transfer

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:bool
allow_shared_folder

If true, dropbox.dropbox.Dropbox.files_copy_batch() will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for dropbox.dropbox.Dropbox.files_move_batch().

Return type:bool
autorename

If there’s a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict.

Return type:bool
entries

List of entries to be moved or copied. Each entry is RelocationPath.

Return type:list of [RelocationPath]
class dropbox.files.RelocationBatchError(tag, value=None)

Bases: dropbox.files.RelocationError

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:too_many_write_operations – There are too many write operations in user’s Dropbox. Please retry this request.
is_too_many_write_operations()

Check if the union tag is too_many_write_operations.

Return type:bool
too_many_write_operations = RelocationBatchError('too_many_write_operations', None)
class dropbox.files.RelocationBatchJobStatus(tag, value=None)

Bases: dropbox.async.PollResultBase

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (RelocationBatchResult) –
Return type:RelocationBatchJobStatus
classmethod failed(val)

Create an instance of this class set to the failed tag with value val.

Parameters:val (RelocationBatchError) –
Return type:RelocationBatchJobStatus
get_complete()

The copy or move batch job has finished.

Only call this if is_complete() is true.

Return type:RelocationBatchResult
get_failed()

The copy or move batch job has failed with exception.

Only call this if is_failed() is true.

Return type:RelocationBatchError
is_complete()

Check if the union tag is complete.

Return type:bool
is_failed()

Check if the union tag is failed.

Return type:bool
class dropbox.files.RelocationBatchLaunch(tag, value=None)

Bases: dropbox.async.LaunchResultBase

Result returned by dropbox.dropbox.Dropbox.files_copy_batch() or dropbox.dropbox.Dropbox.files_move_batch() that may either launch an asynchronous job or complete synchronously.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (RelocationBatchResult) –
Return type:RelocationBatchLaunch
get_complete()

Only call this if is_complete() is true.

Return type:RelocationBatchResult
is_complete()

Check if the union tag is complete.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = RelocationBatchLaunch('other', None)
class dropbox.files.RelocationBatchResult(entries=None)

Bases: dropbox.files.FileOpsResult

entries
Return type:list of [RelocationBatchResultData]
class dropbox.files.RelocationBatchResultData(metadata=None)

Bases: object

Variables:metadata – Metadata of the relocated object.
metadata

Metadata of the relocated object.

Return type:Metadata
class dropbox.files.RelocationError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
cant_copy_shared_folder = RelocationError('cant_copy_shared_folder', None)
cant_move_folder_into_itself = RelocationError('cant_move_folder_into_itself', None)
cant_nest_shared_folder = RelocationError('cant_nest_shared_folder', None)
cant_transfer_ownership = RelocationError('cant_transfer_ownership', None)
duplicated_or_nested_paths = RelocationError('duplicated_or_nested_paths', None)
classmethod from_lookup(val)

Create an instance of this class set to the from_lookup tag with value val.

Parameters:val (LookupError) –
Return type:RelocationError
classmethod from_write(val)

Create an instance of this class set to the from_write tag with value val.

Parameters:val (WriteError) –
Return type:RelocationError
get_from_lookup()

Only call this if is_from_lookup() is true.

Return type:LookupError
get_from_write()

Only call this if is_from_write() is true.

Return type:WriteError
get_to()

Only call this if is_to() is true.

Return type:WriteError
is_cant_copy_shared_folder()

Check if the union tag is cant_copy_shared_folder.

Return type:bool
is_cant_move_folder_into_itself()

Check if the union tag is cant_move_folder_into_itself.

Return type:bool
is_cant_nest_shared_folder()

Check if the union tag is cant_nest_shared_folder.

Return type:bool
is_cant_transfer_ownership()

Check if the union tag is cant_transfer_ownership.

Return type:bool
is_duplicated_or_nested_paths()

Check if the union tag is duplicated_or_nested_paths.

Return type:bool
is_from_lookup()

Check if the union tag is from_lookup.

Return type:bool
is_from_write()

Check if the union tag is from_write.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_to()

Check if the union tag is to.

Return type:bool
is_too_many_files()

Check if the union tag is too_many_files.

Return type:bool
other = RelocationError('other', None)
classmethod to(val)

Create an instance of this class set to the to tag with value val.

Parameters:val (WriteError) –
Return type:RelocationError
too_many_files = RelocationError('too_many_files', None)
class dropbox.files.RelocationPath(from_path=None, to_path=None)

Bases: object

Variables:
  • from_path – Path in the user’s Dropbox to be copied or moved.
  • to_path – Path in the user’s Dropbox that is the destination.
from_path

Path in the user’s Dropbox to be copied or moved.

Return type:str
to_path

Path in the user’s Dropbox that is the destination.

Return type:str
class dropbox.files.RelocationResult(metadata=None)

Bases: dropbox.files.FileOpsResult

Variables:metadata – Metadata of the relocated object.
metadata

Metadata of the relocated object.

Return type:Metadata
class dropbox.files.RestoreArg(path=None, rev=None)

Bases: object

Variables:
  • path – The path to the file you want to restore.
  • rev – The revision to restore for the file.
path

The path to the file you want to restore.

Return type:str
rev

The revision to restore for the file.

Return type:str
class dropbox.files.RestoreError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
get_path_lookup()

An error occurs when downloading metadata for the file.

Only call this if is_path_lookup() is true.

Return type:LookupError
get_path_write()

An error occurs when trying to restore the file to that path.

Only call this if is_path_write() is true.

Return type:WriteError
invalid_revision = RestoreError('invalid_revision', None)
is_invalid_revision()

Check if the union tag is invalid_revision.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_path_lookup()

Check if the union tag is path_lookup.

Return type:bool
is_path_write()

Check if the union tag is path_write.

Return type:bool
other = RestoreError('other', None)
classmethod path_lookup(val)

Create an instance of this class set to the path_lookup tag with value val.

Parameters:val (LookupError) –
Return type:RestoreError
classmethod path_write(val)

Create an instance of this class set to the path_write tag with value val.

Parameters:val (WriteError) –
Return type:RestoreError
class dropbox.files.SaveCopyReferenceArg(copy_reference=None, path=None)

Bases: object

Variables:
copy_reference

A copy reference returned by dropbox.dropbox.Dropbox.files_copy_reference_get().

Return type:str
path

Path in the user’s Dropbox that is the destination.

Return type:str
class dropbox.files.SaveCopyReferenceError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • invalid_copy_reference – The copy reference is invalid.
  • no_permission – You don’t have permission to save the given copy reference. Please make sure this app is same app which created the copy reference and the source user is still linked to the app.
  • not_found – The file referenced by the copy reference cannot be found.
  • too_many_files – The operation would involve more than 10,000 files and folders.
get_path()

Only call this if is_path() is true.

Return type:WriteError
invalid_copy_reference = SaveCopyReferenceError('invalid_copy_reference', None)
is_invalid_copy_reference()

Check if the union tag is invalid_copy_reference.

Return type:bool
is_no_permission()

Check if the union tag is no_permission.

Return type:bool
is_not_found()

Check if the union tag is not_found.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
is_too_many_files()

Check if the union tag is too_many_files.

Return type:bool
no_permission = SaveCopyReferenceError('no_permission', None)
not_found = SaveCopyReferenceError('not_found', None)
other = SaveCopyReferenceError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (WriteError) –
Return type:SaveCopyReferenceError
too_many_files = SaveCopyReferenceError('too_many_files', None)
class dropbox.files.SaveCopyReferenceResult(metadata=None)

Bases: object

Variables:metadata – The metadata of the saved file or folder in the user’s Dropbox.
metadata

The metadata of the saved file or folder in the user’s Dropbox.

Return type:Metadata
class dropbox.files.SaveUrlArg(path=None, url=None)

Bases: object

Variables:
  • path – The path in Dropbox where the URL will be saved to.
  • url – The URL to be saved.
path

The path in Dropbox where the URL will be saved to.

Return type:str
url

The URL to be saved.

Return type:str
class dropbox.files.SaveUrlError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
download_failed = SaveUrlError('download_failed', None)
get_path()

Only call this if is_path() is true.

Return type:WriteError
invalid_url = SaveUrlError('invalid_url', None)
is_download_failed()

Check if the union tag is download_failed.

Return type:bool
is_invalid_url()

Check if the union tag is invalid_url.

Return type:bool
is_not_found()

Check if the union tag is not_found.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
not_found = SaveUrlError('not_found', None)
other = SaveUrlError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (WriteError) –
Return type:SaveUrlError
class dropbox.files.SaveUrlJobStatus(tag, value=None)

Bases: dropbox.async.PollResultBase

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:complete (FileMetadata) – Metadata of the file where the URL is saved to.
classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (FileMetadata) –
Return type:SaveUrlJobStatus
classmethod failed(val)

Create an instance of this class set to the failed tag with value val.

Parameters:val (SaveUrlError) –
Return type:SaveUrlJobStatus
get_complete()

Metadata of the file where the URL is saved to.

Only call this if is_complete() is true.

Return type:FileMetadata
get_failed()

Only call this if is_failed() is true.

Return type:SaveUrlError
is_complete()

Check if the union tag is complete.

Return type:bool
is_failed()

Check if the union tag is failed.

Return type:bool
class dropbox.files.SaveUrlResult(tag, value=None)

Bases: dropbox.async.LaunchResultBase

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:complete (FileMetadata) – Metadata of the file where the URL is saved to.
classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (FileMetadata) –
Return type:SaveUrlResult
get_complete()

Metadata of the file where the URL is saved to.

Only call this if is_complete() is true.

Return type:FileMetadata
is_complete()

Check if the union tag is complete.

Return type:bool
class dropbox.files.SearchArg(path=None, query=None, start=None, max_results=None, mode=None)

Bases: object

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

The maximum number of search results to return.

Return type:long
mode

The search mode (filename, filename_and_content, or deleted_filename). Note that searching file content is only available for Dropbox Business accounts.

Return type:SearchMode
path

The path in the user’s Dropbox to search. Should probably be a folder.

Return type:str
query

The string to search for. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. “bat c” matches “bat cave” but not “batman car”).

Return type:str
start

The starting index within the search results (used for paging).

Return type:long
class dropbox.files.SearchError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_path()

Only call this if is_path() is true.

Return type:LookupError
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = SearchError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:SearchError
class dropbox.files.SearchMatch(match_type=None, metadata=None)

Bases: object

Variables:
  • match_type – The type of the match.
  • metadata – The metadata for the matched file or folder.
match_type

The type of the match.

Return type:SearchMatchType
metadata

The metadata for the matched file or folder.

Return type:Metadata
class dropbox.files.SearchMatchType(tag, value=None)

Bases: dropbox.stone_base.Union

Indicates what type of match was found for a given item.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • filename – This item was matched on its file or folder name.
  • content – This item was matched based on its file contents.
  • both – This item was matched based on both its contents and its file name.
both = SearchMatchType('both', None)
content = SearchMatchType('content', None)
filename = SearchMatchType('filename', None)
is_both()

Check if the union tag is both.

Return type:bool
is_content()

Check if the union tag is content.

Return type:bool
is_filename()

Check if the union tag is filename.

Return type:bool
class dropbox.files.SearchMode(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
deleted_filename = SearchMode('deleted_filename', None)
filename = SearchMode('filename', None)
filename_and_content = SearchMode('filename_and_content', None)
is_deleted_filename()

Check if the union tag is deleted_filename.

Return type:bool
is_filename()

Check if the union tag is filename.

Return type:bool
is_filename_and_content()

Check if the union tag is filename_and_content.

Return type:bool
class dropbox.files.SearchResult(matches=None, more=None, start=None)

Bases: object

Variables:
matches

A list (possibly empty) of matches for the query.

Return type:list of [SearchMatch]
more

Used for paging. If true, indicates there is another page of results available that can be fetched by calling dropbox.dropbox.Dropbox.files_search() again.

Return type:bool
start

Used for paging. Value to set the start argument to when calling dropbox.dropbox.Dropbox.files_search() to fetch the next page of results.

Return type:long

Bases: object

Variables:
  • url – Shared link url.
  • password – Password for the shared link.
password

Password for the shared link.

Return type:str
url

Shared link url.

Return type:str
class dropbox.files.SharingInfo(read_only=None)

Bases: object

Sharing info for a file or folder.

Variables:read_only – True if the file or folder is inside a read-only shared folder.
read_only

True if the file or folder is inside a read-only shared folder.

Return type:bool
class dropbox.files.ThumbnailArg(path=None, format=None, size=None)

Bases: object

Variables:
  • path – The path to the image file you want to thumbnail.
  • format – 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 – The size for the thumbnail image.
format

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.

Return type:ThumbnailFormat
path

The path to the image file you want to thumbnail.

Return type:str
size

The size for the thumbnail image.

Return type:ThumbnailSize
class dropbox.files.ThumbnailError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
conversion_error = ThumbnailError('conversion_error', None)
get_path()

An error occurs when downloading metadata for the image.

Only call this if is_path() is true.

Return type:LookupError
is_conversion_error()

Check if the union tag is conversion_error.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
is_unsupported_extension()

Check if the union tag is unsupported_extension.

Return type:bool
is_unsupported_image()

Check if the union tag is unsupported_image.

Return type:bool
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (LookupError) –
Return type:ThumbnailError
unsupported_extension = ThumbnailError('unsupported_extension', None)
unsupported_image = ThumbnailError('unsupported_image', None)
class dropbox.files.ThumbnailFormat(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

is_jpeg()

Check if the union tag is jpeg.

Return type:bool
is_png()

Check if the union tag is png.

Return type:bool
jpeg = ThumbnailFormat('jpeg', None)
png = ThumbnailFormat('png', None)
class dropbox.files.ThumbnailSize(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
is_w1024h768()

Check if the union tag is w1024h768.

Return type:bool
is_w128h128()

Check if the union tag is w128h128.

Return type:bool
is_w32h32()

Check if the union tag is w32h32.

Return type:bool
is_w640h480()

Check if the union tag is w640h480.

Return type:bool
is_w64h64()

Check if the union tag is w64h64.

Return type:bool
w1024h768 = ThumbnailSize('w1024h768', None)
w128h128 = ThumbnailSize('w128h128', None)
w32h32 = ThumbnailSize('w32h32', None)
w640h480 = ThumbnailSize('w640h480', None)
w64h64 = ThumbnailSize('w64h64', None)
class dropbox.files.UploadError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:path (UploadWriteFailed) – Unable to save the uploaded contents to a file.
get_path()

Unable to save the uploaded contents to a file.

Only call this if is_path() is true.

Return type:UploadWriteFailed
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
other = UploadError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (UploadWriteFailed) –
Return type:UploadError
class dropbox.files.UploadErrorWithProperties(tag, value=None)

Bases: dropbox.files.UploadError

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

get_properties_error()

Only call this if is_properties_error() is true.

Return type:file_properties.InvalidPropertyGroupError_validator
is_properties_error()

Check if the union tag is properties_error.

Return type:bool
classmethod properties_error(val)

Create an instance of this class set to the properties_error tag with value val.

Parameters:val (file_properties.InvalidPropertyGroupError_validator) –
Return type:UploadErrorWithProperties
class dropbox.files.UploadSessionAppendArg(cursor=None, close=None)

Bases: object

Variables:
close

If true, the current session will be closed, at which point you won’t be able to call dropbox.dropbox.Dropbox.files_upload_session_append_v2() anymore with the current session.

Return type:bool
cursor

Contains the upload session ID and the offset.

Return type:UploadSessionCursor
class dropbox.files.UploadSessionCursor(session_id=None, offset=None)

Bases: object

Variables:
offset

The amount of data that has been uploaded so far. We use this to make sure upload data isn’t lost or duplicated in the event of a network error.

Return type:long
session_id

The upload session ID (returned by dropbox.dropbox.Dropbox.files_upload_session_start()).

Return type:str
class dropbox.files.UploadSessionFinishArg(cursor=None, commit=None)

Bases: object

Variables:
  • cursor – Contains the upload session ID and the offset.
  • commit – Contains the path and other optional modifiers for the commit.
commit

Contains the path and other optional modifiers for the commit.

Return type:CommitInfo
cursor

Contains the upload session ID and the offset.

Return type:UploadSessionCursor
class dropbox.files.UploadSessionFinishBatchArg(entries=None)

Bases: object

Variables:entries – Commit information for each file in the batch.
entries

Commit information for each file in the batch.

Return type:list of [UploadSessionFinishArg]
class dropbox.files.UploadSessionFinishBatchJobStatus(tag, value=None)

Bases: dropbox.async.PollResultBase

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:complete (UploadSessionFinishBatchResult) – The dropbox.dropbox.Dropbox.files_upload_session_finish_batch() has finished.
classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (UploadSessionFinishBatchResult) –
Return type:UploadSessionFinishBatchJobStatus
get_complete()

The dropbox.dropbox.Dropbox.files_upload_session_finish_batch() has finished.

Only call this if is_complete() is true.

Return type:UploadSessionFinishBatchResult
is_complete()

Check if the union tag is complete.

Return type:bool
class dropbox.files.UploadSessionFinishBatchLaunch(tag, value=None)

Bases: dropbox.async.LaunchResultBase

Result returned by dropbox.dropbox.Dropbox.files_upload_session_finish_batch() that may either launch an asynchronous job or complete synchronously.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

classmethod complete(val)

Create an instance of this class set to the complete tag with value val.

Parameters:val (UploadSessionFinishBatchResult) –
Return type:UploadSessionFinishBatchLaunch
get_complete()

Only call this if is_complete() is true.

Return type:UploadSessionFinishBatchResult
is_complete()

Check if the union tag is complete.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = UploadSessionFinishBatchLaunch('other', None)
class dropbox.files.UploadSessionFinishBatchResult(entries=None)

Bases: object

Variables:entries – Commit result for each file in the batch.
entries

Commit result for each file in the batch.

Return type:list of [UploadSessionFinishBatchResultEntry]
class dropbox.files.UploadSessionFinishBatchResultEntry(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

classmethod failure(val)

Create an instance of this class set to the failure tag with value val.

Parameters:val (UploadSessionFinishError) –
Return type:UploadSessionFinishBatchResultEntry
get_failure()

Only call this if is_failure() is true.

Return type:UploadSessionFinishError
get_success()

Only call this if is_success() is true.

Return type:FileMetadata
is_failure()

Check if the union tag is failure.

Return type:bool
is_success()

Check if the union tag is success.

Return type:bool
classmethod success(val)

Create an instance of this class set to the success tag with value val.

Parameters:val (FileMetadata) –
Return type:UploadSessionFinishBatchResultEntry
class dropbox.files.UploadSessionFinishError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
get_lookup_failed()

The session arguments are incorrect; the value explains the reason.

Only call this if is_lookup_failed() is true.

Return type:UploadSessionLookupError
get_path()

Unable to save the uploaded contents to a file.

Only call this if is_path() is true.

Return type:WriteError
is_lookup_failed()

Check if the union tag is lookup_failed.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_path()

Check if the union tag is path.

Return type:bool
is_too_many_shared_folder_targets()

Check if the union tag is too_many_shared_folder_targets.

Return type:bool
is_too_many_write_operations()

Check if the union tag is too_many_write_operations.

Return type:bool
classmethod lookup_failed(val)

Create an instance of this class set to the lookup_failed tag with value val.

Parameters:val (UploadSessionLookupError) –
Return type:UploadSessionFinishError
other = UploadSessionFinishError('other', None)
classmethod path(val)

Create an instance of this class set to the path tag with value val.

Parameters:val (WriteError) –
Return type:UploadSessionFinishError
too_many_shared_folder_targets = UploadSessionFinishError('too_many_shared_folder_targets', None)
too_many_write_operations = UploadSessionFinishError('too_many_write_operations', None)
class dropbox.files.UploadSessionLookupError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • not_found – The upload session ID was not found or has expired. Upload sessions are valid for 48 hours.
  • incorrect_offset (UploadSessionOffsetError) – The specified offset was incorrect. See the value for the correct offset. This error may occur when a previous request was received and processed successfully but the client did not receive the response, e.g. due to a network error.
  • closed – You are attempting to append data to an upload session that has alread been closed (i.e. committed).
  • not_closed – The session must be closed before calling upload_session/finish_batch.
closed = UploadSessionLookupError('closed', None)
get_incorrect_offset()

The specified offset was incorrect. See the value for the correct offset. This error may occur when a previous request was received and processed successfully but the client did not receive the response, e.g. due to a network error.

Only call this if is_incorrect_offset() is true.

Return type:UploadSessionOffsetError
classmethod incorrect_offset(val)

Create an instance of this class set to the incorrect_offset tag with value val.

Parameters:val (UploadSessionOffsetError) –
Return type:UploadSessionLookupError
is_closed()

Check if the union tag is closed.

Return type:bool
is_incorrect_offset()

Check if the union tag is incorrect_offset.

Return type:bool
is_not_closed()

Check if the union tag is not_closed.

Return type:bool
is_not_found()

Check if the union tag is not_found.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
not_closed = UploadSessionLookupError('not_closed', None)
not_found = UploadSessionLookupError('not_found', None)
other = UploadSessionLookupError('other', None)
class dropbox.files.UploadSessionOffsetError(correct_offset=None)

Bases: object

Variables:correct_offset – The offset up to which data has been collected.
correct_offset

The offset up to which data has been collected.

Return type:long
class dropbox.files.UploadSessionStartArg(close=None)

Bases: object

Variables:close – If true, the current session will be closed, at which point you won’t be able to call dropbox.dropbox.Dropbox.files_upload_session_append_v2() anymore with the current session.
close

If true, the current session will be closed, at which point you won’t be able to call dropbox.dropbox.Dropbox.files_upload_session_append_v2() anymore with the current session.

Return type:bool
class dropbox.files.UploadSessionStartResult(session_id=None)

Bases: object

Variables:session_id – A unique identifier for the upload session. Pass this to dropbox.dropbox.Dropbox.files_upload_session_append_v2() and dropbox.dropbox.Dropbox.files_upload_session_finish().
session_id

A unique identifier for the upload session. Pass this to dropbox.dropbox.Dropbox.files_upload_session_append_v2() and dropbox.dropbox.Dropbox.files_upload_session_finish().

Return type:str
class dropbox.files.UploadWriteFailed(reason=None, upload_session_id=None)

Bases: object

Variables:
  • reason – The reason why the file couldn’t be saved.
  • upload_session_id – The upload session ID; this may be used to retry the commit.
reason

The reason why the file couldn’t be saved.

Return type:WriteError
upload_session_id

The upload session ID; this may be used to retry the commit.

Return type:str
class dropbox.files.VideoMetadata(dimensions=None, location=None, time_taken=None, duration=None)

Bases: dropbox.files.MediaMetadata

Metadata for a video.

Variables:duration – The duration of the video in milliseconds.
duration

The duration of the video in milliseconds.

Return type:long
class dropbox.files.WriteConflictError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • file – There’s a file in the way.
  • folder – There’s a folder in the way.
  • file_ancestor – There’s a file at an ancestor path, so we couldn’t create the required parent folders.
file = WriteConflictError('file', None)
file_ancestor = WriteConflictError('file_ancestor', None)
folder = WriteConflictError('folder', None)
is_file()

Check if the union tag is file.

Return type:bool
is_file_ancestor()

Check if the union tag is file_ancestor.

Return type:bool
is_folder()

Check if the union tag is folder.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
other = WriteConflictError('other', None)
class dropbox.files.WriteError(tag, value=None)

Bases: dropbox.stone_base.Union

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • conflict (WriteConflictError) – Couldn’t write to the target path because there was something in the way.
  • no_write_permission – The user doesn’t have permissions to write to the target location.
  • insufficient_space – The user doesn’t have enough available space (bytes) to write more data.
  • disallowed_name – Dropbox will not save the file or folder because of its name.
  • team_folder – This endpoint cannot move or delete team folders.
classmethod conflict(val)

Create an instance of this class set to the conflict tag with value val.

Parameters:val (WriteConflictError) –
Return type:WriteError
disallowed_name = WriteError('disallowed_name', None)
get_conflict()

Couldn’t write to the target path because there was something in the way.

Only call this if is_conflict() is true.

Return type:WriteConflictError
get_malformed_path()

Only call this if is_malformed_path() is true.

Return type:Optional[str]
insufficient_space = WriteError('insufficient_space', None)
is_conflict()

Check if the union tag is conflict.

Return type:bool
is_disallowed_name()

Check if the union tag is disallowed_name.

Return type:bool
is_insufficient_space()

Check if the union tag is insufficient_space.

Return type:bool
is_malformed_path()

Check if the union tag is malformed_path.

Return type:bool
is_no_write_permission()

Check if the union tag is no_write_permission.

Return type:bool
is_other()

Check if the union tag is other.

Return type:bool
is_team_folder()

Check if the union tag is team_folder.

Return type:bool
classmethod malformed_path(val)

Create an instance of this class set to the malformed_path tag with value val.

Parameters:val (Optional[str]) –
Return type:WriteError
no_write_permission = WriteError('no_write_permission', None)
other = WriteError('other', None)
team_folder = WriteError('team_folder', None)
class dropbox.files.WriteMode(tag, value=None)

Bases: dropbox.stone_base.Union

Your intent when writing a file to some path. This is used to determine what constitutes a conflict and what the autorename strategy is. In some situations, the conflict behavior is identical: (a) If the target path doesn’t refer to anything, the file is always written; no conflict. (b) If the target path refers to a folder, it’s always a conflict. (c) If the target path refers to a file with identical contents, nothing gets written; no conflict. The conflict checking differs in the case where there’s a file at the target path with contents different from the contents you’re trying to write.

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:
  • add – Do not overwrite an existing file if there is a conflict. The autorename strategy is to append a number to the file name. For example, “document.txt” might become “document (2).txt”.
  • overwrite – Always overwrite the existing file. The autorename strategy is the same as it is for add.
  • update (str) – Overwrite if the given “rev” matches the existing file’s “rev”. The autorename strategy is to append the string “conflicted copy” to the file name. For example, “document.txt” might become “document (conflicted copy).txt” or “document (Panda’s conflicted copy).txt”.
add = WriteMode('add', None)
get_update()

Overwrite if the given “rev” matches the existing file’s “rev”. The autorename strategy is to append the string “conflicted copy” to the file name. For example, “document.txt” might become “document (conflicted copy).txt” or “document (Panda’s conflicted copy).txt”.

Only call this if is_update() is true.

Return type:str
is_add()

Check if the union tag is add.

Return type:bool
is_overwrite()

Check if the union tag is overwrite.

Return type:bool
is_update()

Check if the union tag is update.

Return type:bool
overwrite = WriteMode('overwrite', None)
classmethod update(val)

Create an instance of this class set to the update tag with value val.

Parameters:val (str) –
Return type:WriteMode

dropbox.file_properties – File Properties

This namespace contains helpers for property and template metadata endpoints.

These endpoints enable you to tag arbitrary key/value data to Dropbox files.

The most basic unit in this namespace is the :type:`PropertyField`. These fields encapsulate the actual key/value data.

Fields are added to a Dropbox file using a :type:`PropertyGroup`. Property groups contain a reference to a Dropbox file and a :type:`PropertyGroupTemplate`. Property groups are uniquely identified by the combination of their associated Dropbox file and template.

The :type:`PropertyGroupTemplate` is a way of restricting the possible key names and value types of the data within a property group. The possible key names and value types are explicitly enumerated using :type:`PropertyFieldTemplate` objects.

You can think of a property group template as a class definition for a particular key/value metadata object, and the property groups themselves as the instantiations of these objects.

class dropbox.file_properties.AddPropertiesArg(path=None, property_groups=None)

Bases: object

Variables:
  • path – A unique identifier for the file or folder.
  • property_groups – The property groups which are to be added to a Dropbox file.
path

A unique identifier for the file or folder.

Return type:str
property_groups

The property groups which are to be added to a Dropbox file.

Return type:list of [PropertyGroup]
class dropbox.file_properties.AddPropertiesError(tag, value=None)

Bases: dropbox.file_properties.InvalidPropertyGroupError

This class acts as a tagged union. Only one of the is_* methods will return true. To get the associated value of a tag (if one exists), use the corresponding get_* method.

Variables:property_group_a