The main client API you’ll be working with most often. You’ll need to configure a dropbox.session.DropboxSession for this to work, but otherwise it’s fairly self-explanatory.
Before you can begin making requests to the dropbox API, you have to authenticate your application with Dropbox and get the user to authorize your application to use dropbox on his behalf. A typical progam, from the initial imports to making a simple request (account_info), looks like this:
# Include the Dropbox SDK libraries
from dropbox import client, rest, session
# Get your app key and secret from the Dropbox developer website
APP_KEY = 'INSERT_APP_KEY_HERE'
APP_SECRET = 'INSERT_SECRET_HERE'
# ACCESS_TYPE should be 'dropbox' or 'app_folder' as configured for your app
ACCESS_TYPE = 'INSERT_ACCESS_TYPE_HERE'
sess = session.DropboxSession(APP_KEY, APP_SECRET, ACCESS_TYPE)
request_token = sess.obtain_request_token()
url = sess.build_authorize_url(request_token)
# Make the user sign in and authorize this token
print "url:", url
print "Please visit this website and press the 'Allow' button, then hit 'Enter' here."
raw_input()
# This will fail if the user didn't visit the above URL and hit 'Allow'
access_token = sess.obtain_access_token(request_token)
client = client.DropboxClient(sess)
print "linked account:", client.account_info()
The main access point of doing REST calls on Dropbox. You should first create and configure a dropbox.session.DropboxSession object, and then pass it into DropboxClient’s constructor. DropboxClient then does all the work of properly calling each API method with the correct OAuth authentication.
You should be aware that any of these methods can raise a 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 user needs to be reauthenticated.
Contains the logic around a chunked upload, which uploads a large file to Dropbox via the /chunked_upload endpoint
Commits the bytes uploaded by this ChunkedUploader to a file in the users dropbox.
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.
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
Adds the file referenced by the copy ref to the specified 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"}
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.
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
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
The SDK leaves the error handling and retry logic to the developer to implement, as the exact requirements will depend on the application involved.
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, metadata = client.get_file_and_metadata('/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)
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
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
Upload a file.
A typical use case would be as follows:
f = open('working-draft.txt')
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 (!).
Make an HTTP request to a target API method.
This is an internal method used to properly craft the url, headers, and params for a Dropbox API request. It is exposed for you in case you need craft other API calls not in this library or if you want to debug it.
target: The target URL with leading slash (e.g. ‘/files’)
params: A dictionary of parameters to add to the request
method: An HTTP method (e.g. ‘GET’ or ‘POST’)
API content server, for example to fetch the contents of a file rather than its metadata.
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
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
Search directory for filenames matching query.
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
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.
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.
dropbox.session.DropboxSession is responsible for holding OAuth authentication info (app key/secret, request key/secret, access key/secret) as well as configuration information for your app (‘app_folder’ or ‘dropbox’ access type, optional locale preference). It knows how to use all of this information to craft properly constructed requests to Dropbox.
A DropboxSession object must be passed to a dropbox.client.DropboxClient object upon initialization.
Build OAuth access headers for a future request.
Build a request token authorization URL.
After obtaining a request token, you’ll need to send the user to the URL returned from this function so that they can confirm that they want to connect their account to your app.
Build the path component for an API URL.
This method urlencodes the parameters, adds them to the end of the target url, and puts a marker for the API version in front.
Build an API URL.
This method adds scheme and hostname to the path returned from build_path.
Return whether the DropboxSession has an access token attached.
Obtain an access token for a user.
After you get a request token, and then send the user to the authorize URL, you can use the authorized request token with this method to get the access token to use for future operations. The access token is stored on the session object.
Obtain a request token from the Dropbox API.
This is your first step in the OAuth process. You call this to get a request_token from the Dropbox server that you can then use with DropboxSession.build_authorize_url() to get the user to authorize it. After it’s authorized you use this token with DropboxSession.obtain_access_token() to get an access token.
NOTE: You should only need to do this once for each user, and then you can store the access token for that user for later operations.
Attach an request token to the DropboxSession.
Note that the request ‘token’ is made up of both a token string and a secret string.
Attach an access token to the DropboxSession.
Note that the access ‘token’ is made up of both a token string and a secret string.
Remove any attached access token from the DropboxSession.
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.
Perform a GET request using RESTClient.request
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 POST request using RESTClient.request
Perform a PUT request using RESTClient.request
Perform a REST request and parse the response.
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.