def share(self, path):
"""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.
Args:
path: The file or folder to share.
Returns:
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/docs#share
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
- 400: Bad request (may be due to many things; check e.error for details)
- 404: Unable to find the file at the given path.
"""
path = "/shares/%s%s" % (self.session.root, format_path(path))
url, params, headers = self.request(path, method='GET')
return RESTClient.GET(url, headers)
def media(self, path):
"""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.
Args:
path: The file to return a URL for. Folders are not supported.
Returns:
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/docs#media
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
- 400: Bad request (may be due to many things; check e.error for details)
- 404: Unable to find the file at the given path.
"""
path = "/media/%s%s" % (self.session.root, format_path(path))
url, params, headers = self.request(path, method='GET')
return RESTClient.GET(url, headers)
def revisions(self, path, rev_limit=1000):
"""Retrieve revisions of a file.
Args:
path: The file to fetch revisions for. Note that revisions
are not available for folders.
rev_limit: The maximum number of file entries to return within
a folder. The server will return at max 1,000 revisions.
Returns:
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/docs#revisions
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
- 400: Bad request (may be due to many things; check e.error for details)
- 404: No revisions were found at the given path.
"""
path = "/revisions/%s%s" % (self.session.root, format_path(path))
params = {
'rev_limit': rev_limit,
}
url, params, headers = self.request(path, params, method='GET')
return RESTClient.GET(url, headers)
def metadata(self,
path,
list=True,
file_limit=10000,
hash=None,
rev=None,
include_deleted=False):
"""Retrieve metadata for a file or folder.
Args:
path: The path to the file or folder.
list: Whether to list all contained files (only applies when
path refers to a folder).
file_limit: The maximum number of file entries to return within
a folder. If the number of files in the directory exceeds this
limit, an exception is raised. The server will return at max
10,000 files within a folder.
hash: Every directory listing has a hash parameter attached that
can then be passed back into this function later to save on\
bandwidth. Rather than returning an unchanged folder's contents,\
the server will instead return a 304.\
rev: The revision of the file to retrieve the metadata for. [optional]
This parameter only applies for files. If omitted, you'll receive
the most recent revision metadata.
Returns:
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/docs#metadata
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
- 304: Current directory hash matches hash parameters, so contents are unchanged.
- 400: Bad request (may be due to many things; check e.error for details)
- 404: No file was found at given path.
- 406: Too many file entries to return.
"""
path = "/metadata/%s%s" % (self.session.root, format_path(path))
params = {
'file_limit': file_limit,
'list': 'true',
'include_deleted': include_deleted,
}
if not list:
params['list'] = 'false'
if hash is not None:
params['hash'] = hash
if rev:
params['rev'] = rev
url, params, headers = self.request(path, params, method='GET')
return RESTClient.GET(url, headers)
def account_info(self):
"""Retrieve information about the user's account.
Returns:
A dictionary containing account information.
For a detailed description of what this call returns, visit:
https://www.dropbox.com/developers/docs#account-info
"""
url, params, headers = self.request("/account/info", method='GET')
return RESTClient.GET(url, headers)
def create_copy_ref(self, from_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.
Args:
- path: The path to the file for a copy ref to be created on.
Returns:
A dictionary that looks like the following example:
``{"expires":"Fri, 31 Jan 2042 21:01:05 +0000", "copy_ref":"z1X6ATl6aWtzOGq0c3g5Ng"}``
"""
path = "/copy_ref/%s%s" % (self.session.root, format_path(from_path))
url, params, headers = self.request(path, {})
return RESTClient.GET(url, headers)
