Classes Reference

BoxAuthenticateFlow

class boxpython.BoxAuthenticateFlow(client_id, client_secret)

From the Client ID and Client Secret from Box, get the Access Token and the Refresh Token.

Usage:

>>> flow = BoxAuthenticateFlow('my_id', 'my_secret')
>>> url = flow.get_authorization_url()
...
...
>>> access_token, refresh_token = flow.get_access_tokens('generated_auth_code')

get_access_tokens(authorization_code)

From the authorization code, get the “access token” and the “refresh token” from Box.

Args:

authorization_code (str). Authorisation code emitted by Box at the url provided by the function get_authorization_url().

Returns:

tuple. (access_token, refresh_token)

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

get_authorization_url(redirect_uri=None)

Get the url used to get an authorization code.

Args:

redirect_uri (str): Https url where Box will redirect the user with the authorization code in the querystring. If None the value stored in the Box application settings will be used.

Returns:

str. Url used to get an authorization code.

BoxSession

class boxpython.BoxSession(client_id, client_secret, last_refresh_token, last_access_token=None, tokens_changed=None, timeout=None)

Manage files and folder from Box.

When you instanciate this class you have to provide at least the Refresh Token (found with BoxAuthenticateFlow). If the Access Token is not provided a request will be made to Box to get a new one (and a new Refresh Token will be generated).

The Access Token expires every hour. When you use this class with an Access Token expired, a new one will be requested automatically.

Use the “tokens_changed” callback to backup the Access Token and the Refresh Token each time they change. If you do not backup them, you will have to follow the authenticate flow again (with BoxAuthenticateFlow).

Usage:

>>> def tokens_changed(refresh_token, access_token):
...    save_to_file(refresh_token, access_token)
...
>>> box = BoxSession('my_id', 'my_secret', refresh_token, access_token, tokens_changed)
>>> print box.get_folder_info(0)

chunk_upload_file(name, folder_id, file_path, progress_callback=None, chunk_size=1048576)

Upload a file chunk by chunk.

The whole file is never loaded in memory. Use this function for big file.

The callback(transferred, total) to let you know the upload progress. Upload can be cancelled if the callback raise an Exception.

>>> def progress_callback(transferred, total):
...    print 'Uploaded %i bytes of %i' % (transferred, total, )
...    if user_request_cancel:
...       raise MyCustomCancelException()

Args:

name (str): Name of the file on your Box storage.

folder_id (int): ID of the folder where to upload the file.

file_path (str): Local path of the file to upload.

progress_callback (func): Function called each time a chunk is uploaded.

chunk_size (int): Size of chunks.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

copy_file(file_id, dest_folder_id)

Copy file to new destination

Args:

file_id (int): ID of the folder.

dest_folder_id (int): ID of parent folder you are copying to.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxError: 409 - Item with the same name already exists. In this case you will need download the file and upload a new version to your destination. (Box currently doesn’t have a method to copy a new verison.)

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

create_folder(name, parent_folder_id=0)

Create a folder

If the folder exists, a BoxError will be raised.

Args:

folder_id (int): Name of the folder.

parent_folder_id (int): ID of the folder where to create the new one.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

delete_file(file_id)

Delete an existing file

Args:

file_id (int): ID of the file to delete.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

delete_folder(folder_id, recursive=True)

Delete an existing folder

Args:

folder_id (int): ID of the folder to delete. recursive (bool): Delete all subfolder if True.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

download_file(file_id, dest_file_path, progress_callback=None, chunk_size=1048576)

Download a file.

The whole file is never loaded in memory.

The callback(transferred, total) to let you know the download progress. Download can be cancelled if the callback raise an Exception.

>>> def progress_callback(transferred, total):
...    print 'Downloaded %i bytes of %i' % (transferred, total, )
...    if user_request_cancel:
...       raise MyCustomCancelException()

Args:

file_id (int): ID of the file to download.

dest_file_path (str): Local path where to store the downloaded filed.

progress_callback (func): Function called each time a chunk is downloaded.

chunk_size (int): Size of chunks.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

find_id_in_folder(name, parent_folder_id=0)

Find a folder or a file ID from its name, inside a given folder.

Args:

name (str): Name of the folder or the file to find.

parent_folder_id (int): ID of the folder where to search.

Returns:

int. ID of the file or folder found. None if not found.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

get_file_info(file_id)

Get info on a file

Args:

file_id (int): ID of the folder.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

get_folder_info(folder_id)

Get info on a folder

Args:

folder_id (int): ID of the folder.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

get_folder_items(folder_id, limit=100, offset=0, fields_list=None)

Get files and folders inside a given folder

Args:

folder_id (int): Where to get files and folders info.

limit (int): The number of items to return.

offset (int): The item at which to begin the response.

fields_list (list): List of attributes to get. All attributes if None.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

get_user_info()

Returns a single complete user object about the user who is currently

logged in.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

search(**kwargs)

Searches for files/folders

Args:

**kwargs (dict): A dictionary containing necessary parameters

(check https://developers.box.com/docs/#search for list of parameters)

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

upload_file(name, folder_id, file_path)

Upload a file into a folder.

Use function for small file otherwise there is the chunk_upload_file() function

Args::

name (str): Name of the file on your Box storage.

folder_id (int): ID of the folder where to upload the file.

file_path (str): Local path of the file to upload.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

upload_new_file_version(name, folder_id, file_id, file_path)

Upload a new version of a file into a folder.

Use function for small file otherwise there is the chunk_upload_file() function.

Args::

name (str): Name of the file on your Box storage.

folder_id (int): ID of the folder where to upload the file.

file_id (int): ID of the file to update.

file_path (str): Local path of the file to upload.

Returns:

dict. Response from Box.

Raises:

BoxError: An error response is returned from Box (status_code >= 400).

BoxHttpResponseError: Response from Box is malformed.

requests.exceptions.*: Any connection related problem.

Exceptions

class boxpython.BoxError(status, attributes)

Bases: exceptions.Exception

class boxpython.BoxHttpResponseError

Bases: exceptions.Exception