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)
return RESTClient.POST(url, params, headers)
def restore(self, path, rev):
"""Restore a file to a previous revision.
Args:
path: The file to restore. Note that folders can't be restored.
rev: A previous rev value of the file to be restored to.
Returns:
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/docs#restore
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 revision.
"""
path = "/restore/%s%s" % (self.session.root, format_path(path))
params = {
'rev': rev,
}
url, params, headers = self.request(path, params)
return RESTClient.POST(url, params, headers)
def file_move(self, from_path, to_path):
"""Move a file or folder to a new location.
Args:
from_path: The path to the file or folder to be moved.
to_path: The destination path of the file or folder to be moved.
This parameter should include the destination filename (e.g.
from_path: '/test.txt', to_path: '/dir/test.txt'). If there's
already a file at the to_path, this file or folder will be renamed to
be unique.
Returns:
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/docs#fileops-move
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 file was found at given from_path.
- 503: User over storage quota.
"""
params = {
'root': self.session.root,
'from_path': format_path(from_path),
'to_path': format_path(to_path)
}
url, params, headers = self.request("/fileops/move", params)
return RESTClient.POST(url, params, headers)
def search(self, path, query, file_limit=10000, include_deleted=False):
"""Search directory for filenames matching query.
Args:
path: The directory to search within.
query: The query to search on (minimum 3 characters).
file_limit: The maximum number of file entries to return within a folder.
The server will return at max 10,000 files.
include_deleted: Whether to include deleted files in search results.
Returns:
A list of the metadata of all matching files (up to
file_limit entries). For a detailed description of what
this call returns, visit:
https://www.dropbox.com/developers/docs#search
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
400: Bad request (may be due to many things; check e.error
for details)
"""
path = "/search/%s%s" % (self.session.root, format_path(path))
params = {
'query': query,
'file_limit': file_limit,
'include_deleted': include_deleted,
}
url, params, headers = self.request(path, params)
return RESTClient.POST(url, params, headers)
def camera_uploads_delta(cursor):
from dropbox.rest import RESTClient
path = "/camera_uploads_delta"
params = {}
if cursor is not None:
params['cursor'] = cursor
url, params, headers = c.request(path, params)
return RESTClient.POST(url, params, headers)
def delta(self, cursor=None):
"""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.
Arguments:
- ``cursor``: On the first call, omit this argument (or pass in ``None``). On
subsequent calls, pass in the ``cursor`` string returned by the previous
call.
Returns: A dict with three fields.
- ``entries``: A list of "delta entries" (described below)
- ``reset``: If ``True``, you should your local state to be an empty folder
before processing the list of delta entries. This is only ``True`` only
in rare situations.
- ``cursor``: A string that is used to keep track of your current state.
On the next call to delta(), pass in this value to return entries
that were recorded since the cursor was returned.
- ``has_more``: If ``True``, then there are more entries available; you can
call delta() again immediately to retrieve those entries. If ``False``,
then wait at least 5 minutes (preferably longer) before checking again.
Delta Entries: Each entry is a 2-item list of one of following forms:
- [*path*, *metadata*]: Indicates that there is a file/folder at the given
path. You should add the entry to your local path. (The *metadata*
value is the same as what would be returned by the ``metadata()`` call.)
- If the new entry includes parent folders that don't yet exist in your
local state, create those parent folders in your local state. You
will eventually get entries for those parent folders.
- If the new entry is a file, replace whatever your local state has at
*path* with the new entry.
- If the new entry is a folder, check what your local state has at
*path*. If it's a file, replace it with the new entry. If it's a
folder, apply the new *metadata* to the folder, but do not modify
the folder's children.
- [*path*, ``nil``]: Indicates that there is no file/folder at the *path* on
Dropbox. To update your local state to match, delete whatever is at *path*,
including any children (you will sometimes also get "delete" delta entries
for the children, but this is not guaranteed). If your local state doesn't
have anything at *path*, ignore this entry.
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.
"""
path = "/delta"
params = {}
if cursor is not None:
params['cursor'] = cursor
url, params, headers = self.request(path, params)
return RESTClient.POST(url, params, headers)
def add_copy_ref(self, copy_ref, to_path):
"""Adds the file referenced by the copy ref to the specified path
Args:
- copy_ref: A copy ref string that was returned from a create_copy_ref call.
The copy_ref can be created from any other Dropbox account, or from the same account.
- path: The path to where the file will be created.
Returns:
A dictionary containing the metadata of the new copy of the file.
"""
path = "/fileops/copy"
params = {'from_copy_ref': copy_ref,
'to_path': format_path(to_path),
'root': self.session.root}
url, params, headers = self.request(path, params)
return RESTClient.POST(url, params, headers)
def file_create_folder(self, path):
"""Create a folder.
Args:
path: The path of the new folder.
Returns:
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/docs#fileops-create-folder
Raises:
A dropbox.rest.ErrorResponse with an HTTP status of
400: Bad request (may be due to many things; check e.error for details)
403: A folder at that path already exists.
"""
params = {'root': self.session.root, 'path': format_path(path)}
url, params, headers = self.request("/fileops/create_folder", params)
return RESTClient.POST(url, params, headers)
def file_delete(self, path):
"""Delete a file or folder.
Args:
path: The path of the file or folder.
Returns:
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/docs#fileops-delete
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 file was found at the given path.
"""
params = {'root': self.session.root, 'path': format_path(path)}
url, params, headers = self.request("/fileops/delete", params)
return RESTClient.POST(url, params, headers)
