The class that lets you make Dropbox API calls. You’ll need to obtain an OAuth 2 access token first. You can get an access token using either DropboxOAuth2Flow or DropboxOAuth2FlowNoRedirect.
All of the API call methods can raise a dropbox.rest.ErrorResponse exception if the server returns a non-200 or invalid HTTP response. Note that a 401 return status at any point indicates that the access token you’re using is no longer valid and the user must be put through the OAuth 2 authorization flow again.
An internal method that builds the url, headers, and params for a Dropbox API request. It is exposed if you need to make API calls not implemented in this library or if you need to debug requests.
Retrieve information about the user’s account.
A dictionary containing account information.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#account-info
Creates a ChunkedUploader to upload the given file-like object.
The expected use of this function is as follows:
bigFile = open("data.txt", 'rb')
uploader = myclient.get_chunked_uploader(bigFile, size)
print "uploading: ", size
while uploader.offset < size:
try:
upload = uploader.upload_chunked()
except rest.ErrorResponse, e:
# perform error handling and retry logic
uploader.finish('/bigFile.txt')
The SDK leaves the error handling and retry logic to the developer to implement, as the exact requirements will depend on the application involved.
Contains the logic around a chunked upload, which uploads a large file to Dropbox via the /chunked_upload endpoint
Uploads data from this ChunkedUploader’s file_obj in chunks, until an error occurs. Throws an exception when an error occurs, and can be called again to resume the upload.
Commits the bytes uploaded by this ChunkedUploader to a file in the users dropbox.
Uploads a single chunk of data from the given file like object. The majority of users should use the ChunkedUploader object, which provides a simpler interface to the chunked_upload API endpoint.
Upload a file.
A typical use case would be as follows:
f = open('working-draft.txt', 'rb')
response = client.put_file('/magnum-opus.txt', f)
print "uploaded:", response
which would return the metadata of the uploaded file, similar to:
{
'bytes': 77,
'icon': 'page_white_text',
'is_dir': False,
'mime_type': 'text/plain',
'modified': 'Wed, 20 Jul 2011 22:04:50 +0000',
'path': '/magnum-opus.txt',
'rev': '362e2029684fe',
'revision': 221922,
'root': 'dropbox',
'size': '77 bytes',
'thumb_exists': False
}
A dictionary containing the metadata of the newly uploaded file.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#files-put
Note: In Python versions below version 2.6, httplib doesn’t handle file-like objects. In that case, this code will read the entire file into memory (!).
Download a file.
Unlike most other calls, get_file returns a raw HTTPResponse with the connection open. You should call .read() and perform any processing you need, then close the HTTPResponse.
A typical usage looks like this:
out = open('magnum-opus.txt', 'w')
f = client.get_file('/magnum-opus.txt').read()
out.write(f)
which would download the file magnum-opus.txt and write the contents into the file magnum-opus.txt on the local filesystem.
Download a file alongwith its metadata.
Acts as a thin wrapper around get_file() (see get_file() comments for more details)
A typical usage looks like this:
out = open('magnum-opus.txt', 'w')
f, metadata = client.get_file_and_metadata('/magnum-opus.txt')
out.write(f)
A way of letting you keep up with changes to files and folders in a user’s Dropbox. You can periodically call delta() to get a list of “delta entries”, which are instructions on how to update your local state to match the server’s state.
Remember: Dropbox treats file names in a case-insensitive but case-preserving way. To facilitate this, the path strings above are lower-cased versions of the actual path. The metadata dicts have the original, case-preserved path.
Creates and returns a copy ref for a specific file. The copy ref can be used to instantly copy that file to the Dropbox of another account.
A dictionary that looks like the following example:
{"expires":"Fri, 31 Jan 2042 21:01:05 +0000", "copy_ref":"z1X6ATl6aWtzOGq0c3g5Ng"}
Adds the file referenced by the copy ref to the specified path
Copy a file or folder to a new location.
A dictionary containing the metadata of the new copy of the file or folder.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#fileops-copy
Create a folder.
A dictionary containing the metadata of the newly created folder.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#fileops-create-folder
Delete a file or folder.
A dictionary containing the metadata of the just deleted file.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#fileops-delete
Move a file or folder to a new location.
A dictionary containing the metadata of the new copy of the file or folder.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#fileops-move
Retrieve metadata for a file or folder.
A typical use would be:
folder_metadata = client.metadata('/')
print "metadata:", folder_metadata
which would return the metadata of the root directory. This will look something like:
{
'bytes': 0,
'contents': [
{
'bytes': 0,
'icon': 'folder',
'is_dir': True,
'modified': 'Thu, 25 Aug 2011 00:03:15 +0000',
'path': '/Sample Folder',
'rev': '803beb471',
'revision': 8,
'root': 'dropbox',
'size': '0 bytes',
'thumb_exists': False
},
{
'bytes': 77,
'icon': 'page_white_text',
'is_dir': False,
'mime_type': 'text/plain',
'modified': 'Wed, 20 Jul 2011 22:04:50 +0000',
'path': '/magnum-opus.txt',
'rev': '362e2029684fe',
'revision': 221922,
'root': 'dropbox',
'size': '77 bytes',
'thumb_exists': False
}
],
'hash': 'efdac89c4da886a9cece1927e6c22977',
'icon': 'folder',
'is_dir': True,
'path': '/',
'root': 'app_folder',
'size': '0 bytes',
'thumb_exists': False
}
In this example, the root directory contains two things: Sample Folder, which is a folder, and /magnum-opus.txt, which is a text file 77 bytes long
A dictionary containing the metadata of the file or folder (and contained files if appropriate).
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#metadata
Download a thumbnail for an image.
Unlike most other calls, thumbnail returns a raw HTTPResponse with the connection open. You should call .read() and perform any processing you need, then close the HTTPResponse.
Download a thumbnail for an image alongwith its metadata.
Acts as a thin wrapper around thumbnail() (see thumbnail() comments for more details)
from_path: The path to the file to be thumbnailed.
for details.
Search directory for filenames matching query.
Retrieve revisions of a file.
A list of the metadata of all matching files (up to rev_limit entries).
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#revisions
Restore a file to a previous revision.
A dictionary containing the metadata of the newly restored file.
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#restore
Get a temporary unauthenticated URL for a media file.
All of Dropbox’s API methods require OAuth, which may cause problems in situations where an application expects to be able to hit a URL multiple times (for example, a media player seeking around a video file). This method creates a time-limited URL that can be accessed without any authentication, and returns that to you, along with an expiration time.
A dictionary that looks like the following example:
{'url': 'https://dl.dropbox.com/0/view/wvxv1fw6on24qw7/file.mov', 'expires': 'Thu, 16 Sep 2011 01:01:25 +0000'}
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#media
Create a shareable link to a file or folder.
Shareable links created on Dropbox are time-limited, but don’t require any authentication, so they can be given out freely. The time limit should allow at least a day of shareability, though users have the ability to disable a link from their account if they like.
A dictionary that looks like the following example:
{'url': 'http://www.dropbox.com/s/m/a2mbDa2', 'expires': 'Thu, 16 Sep 2011 01:01:25 +0000'}
For a detailed description of what this call returns, visit: https://www.dropbox.com/developers/reference/api#shares
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.
from dropbox.client import DropboxOAuth2Flow, DropboxClient
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:
access_token, user_id, url_state = \
get_dropbox_auth_flow(web_app_session).finish(request.query_params)
except DropboxOAuth2Flow.BadRequestException, e:
http_status(400)
except DropboxOAuth2Flow.BadStateException, e:
# Start the auth flow again.
redirect_to("/dropbox-auth-start")
except DropboxOAuth2Flow.CsrfException, e:
http_status(403)
except DropboxOAuth2Flow.NotApprovedException, e:
flash('Not approved? Why not, bro?')
return redirect_to("/home")
except DropboxOAuth2Flow.ProviderException, e:
logger.log("Auth error: %s" % (e,))
http_status(403)
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.
Call this after the user has visited the authorize URL (see start()), approved your app and was redirected to your redirect URI.
Returns a tuple of (access_token, user_id, url_state). access_token can be used to construct a DropboxClient. user_id is the Dropbox user ID (string) of the user that just approved your app. url_state is the value you originally passed in to start().
Can throw BadRequestException, BadStateException, CsrfException, NotApprovedException, ProviderException.
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.
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.
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.
The user chose not to approve your app.
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.
OAuth 2 authorization helper for apps that can’t provide a redirect URI (such as the command-line example apps).
from dropbox.client import DropboxOAuth2FlowNoRedirect, DropboxClient
from dropbox import rest as dbrest
oauth_flow = DropboxOAuth2FlowNoRedirect(APP_KEY, APP_SECRET)
authorize_url = oauth_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:
access_token, user_id = auth_flow.finish(auth_code)
except dbrest.ErrorResponse, e:
print('Error: %s' % (e,))
return
c = DropboxClient(access_token)
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.
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.
Returns a pair of (access_token, user_id). access_token is a string that can be passed to DropboxClient. user_id is the Dropbox user ID (string) of the user that just approved your app.
A simple JSON REST request abstraction layer that is used by the dropbox.client and dropbox.session modules. You shouldn’t need to use this.
An class with all static methods to perform JSON REST requests that is used internally by the Dropbox Client API. It provides just enough gear to make requests and get responses as JSON data (when applicable). All requests happen over SSL.
Perform a REST request and parse the response.
Perform a GET request using RESTClient.request
Perform a POST request using RESTClient.request
Perform a PUT request using RESTClient.request
Raised by dropbox.rest.RESTClient.request for requests that: - Return a non-200 HTTP response, or - Have a non-JSON response body, or - Have a malformed/missing header in the response.
Most errors that Dropbox returns will have a error field that is unpacked and placed on the ErrorResponse exception. In some situations, a user_error field will also come back. Messages under user_error are worth showing to an end-user of your app, while other errors are likely only useful for you as the developer.
A light wrapper for socket.errors raised by dropbox.rest.RESTClient.request that adds more information to the socket.error.