Box¶

Overview¶

Box is a commercial file sharing service similar to Dropbox and Google Drive. The current Parsons API supports listing files and folders, creating and deleting folders, and uploading/downloading Parsons tables as either CSV or JSON files.

Note

Authentication: This connector requires authentication credentials for a Box business-level account. Information on setting up those credentials can be found at the Box Custom App Quick Start page.

Quickstart¶

This class requires credentials in the form three strings to be either passed into the constructor or made available as environment variables:

# Note: these are fake keys, provided as examples.
export BOX_CLIENT_ID=dp4rqi0cz5qckz361fziavdtdwxz
export BOX_CLIENT_SECRET=4KHMDLVy89TeuUpSRa4CN5o35u9h
export BOX_ACCESS_TOKEN=7B39m3ozIGyTcazbWRbi5F2SSZ5J

NOTE: Most functions in this class exist both in ‘path’-based form and ‘folder_id’/’file_id’-based form. The path-based forms rely on the get_item_id() method, which navigates through subfolders with sequential API calls. This can be slow and computationally expensive if the path in question is long, or intermediate folders contain many items. If efficiency is paramount, consider using the “by_id” methods of each function.

Instantiate class

from parsons import Box

# First approach: Use API credentials via environmental variables
box = Box()

# Second approach: Pass API credentials as arguments
box = Box(client_id='dp4rqi0cz5qckz361fziavdtdwxz',
          client_secret='4KHMDLVy89TeuUpSRa4CN5o35u9h',
          access_token='7B39m3ozIGyTcazbWRbi5F2SSZ5J'):

Create a subfolder and upload a Parsons table to it

# Create folder inside default folder
my_folder_id = box.create_folder('My Folder')

# Create subfolder inside new folder and upload table to it
box.create_folder(path='My Folder/My Subfolder')
box_file = box.upload_table(table=my_parsons_table,
                            path='My Folder/My Subfolder/My Parsons Table')

# Create new subfolder using folder_id and upload table to it
sub_folder_id = box.create_folder_by_id(folder_name='My SubFolder',
                                        parent_folder_id=my_folder_id)
box_file = box.upload_table_to_folder_id(table=my_parsons_table,
                                         file_name='My Parsons Table',
                                         folder_id=sub_folder_id)

List folders and files

# List default folder
default_folder_list = box.list()

# Subfolder list - by path
subfolder_list = box.list('My Folder/My Subfolder')

subfolder_file_list = box.list(path='My Folder/My Subfolder',
                               item_type='file')

# Subfolder list - by id
subfolder_file_list = box.list_files_by_id(folder_id='533944')
subfolder_folder_list = box.list_folders_by_id(folder_id='533944')
all_items = box.list_items_by_id(folder_id='533944')

Retrieve folder/file ids from path names

# Download a table
downloaded_table = box.get_table(path='My Folder/My Subfolder/My Parsons Table')

# Download a table using file id
downloaded_table = box.get_table_by_file_id(file_id=box_file.id)

Get an item id from path

file_id = box.get_item_id(path='My Folder/My Subfolder/My Parsons Table')

Delete folders/files

# Delete a file
box.delete_file(path='My Folder/My Subfolder/My Parsons Table')
# Delete a file by id
box.delete_file_by_id(file_id=file_id)

box.delete_folder(path='My Folder/My Subfolder')
box.delete_folder_by_id(folder_id=subfolder_id)

API¶

class parsons.Box(auth: Authentication | None = None)[source]¶

Box is a file storage provider.

Parameters:: auth – Authentication Box Authentication – usually constructed as an access token of 32 characters, alphanumeric. Note that this is only valid for developer use only, and should not be used when creating and maintaining access for typical users. If not passed, will attempt to grab an access token from the environment variable named “BOX_ACCESS_TOKEN”.
Returns:: Box class.
Return type:: Box

NOTE: All path-based methods in this class use an intermediate method that looks up the relevant folder/file id by successive API calls. This can be slow for long paths or intermediate folders that contain many items. If performance is an issue, please use the corresponding folder_id/file_id methods for each function.

create_folder(path: str) → str[source]¶

Create a Box folder.

Parameters:: path – str Box path str to the folder to be created. If no slashes are present, path will be name of folder created in the default folder. Any back slashes will be treated as forward slashes.
Returns:: The Box id of the newly-created folder.
Return type:: str

create_folder_by_id(folder_name: str, parent_folder_id: str = '0') → str[source]¶

Create a Box folder.

Parameters:

folder_name – str The name to give to the new folder.
parent_folder_id – str Folder id of the parent folder in which to create the new folder. If omitted, the default folder will be used.

Returns:

The Box id of the newly-created folder.

Return type:

str

delete_folder(path: str) → None[source]¶

Delete a Box folder.

Parameters:: folder_id – str Box path str to the folder to delete. Any back slashes will be treated as forward slashes.

delete_folder_by_id(folder_id: str) → None[source]¶

Delete a Box folder.

Parameters:: folder_id – str The Box id of the folder to delete.

delete_file(path: str) → None[source]¶

Delete a Box file.

Parameters:: path – str Box path str to the file to delete. Any back slashes will be treated as forward slashes.

delete_file_by_id(file_id: str) → None[source]¶

Delete a Box file.

Parameters:: file_id – str The Box id of the file to delete.

list(path: str | None = None, item_type: Literal['file', 'folder'] | None = None) → Table[source]¶

Return a Table of Box files and/or folders found at a path.

Parameters:

path – str If specified, Box path str of the folder to be listed. If omitted, the default folder will be used.
item_type – str Optionally which type of items should be returned, typically either file or folder. If omitted, all items will be returned. Any back slashes will be treated as forward slashes.

Returns:

A Parsons table of items in the folder and their attributes.

Return type:

Table

list_items_by_id(folder_id: str = '0', item_type: Literal['file', 'folder'] | None = None) → Table[source]¶

Return a Table of Box files and/or folders found in a folder.

Parameters:

folder_id – str The Box id of the folder to list items for.
item_type – str Optionally which type of items should be returned, typically either file or folder. If omitted, all items will be returned.

Returns:

A Parsons table of items in the folder and their attributes.

Return type:

Table

list_files_by_id(folder_id: str = '0') → Table[source]¶

List all Box files in a folder.

Parameters:: folder_id – str The Box id of the folder in which to search. If omitted, search in the default folder.
Returns:: A Parsons table of files and their attributes. The Box id of the folder in which to search. If omitted, search in the default folder.
Return type:: Table

list_folders_by_id(folder_id: str = '0') → Table[source]¶

List all Box folders.

Parameters:: folder_id – str The Box id of the folder in which to search. If omitted, search in the default folder.
Returns:: A Parsons table of folders and their attributes.
Return type:: Table

upload_table(table: Table, path: str, format: Literal['csv', 'json'] = 'csv') → str[source]¶

Save the passed table to Box.

Parameters:

table – Table The Parsons table to be saved.
path – str Box path str where table should be saved. Any back slashes will be treated as forward slashes.
format – str For now, only ‘csv’ and ‘json’; format in which to save table. Defaults to ‘csv’.

Returns:

The uploaded Box File object’s id.

Return type:

str

upload_table_to_folder_id(table: Table, file_name: str, folder_id: str = '0', format: Literal['csv', 'json'] = 'csv') → str[source]¶

Save the passed table to Box.

Parameters:

table – Table The Parsons table to be saved.
file_name – str The filename under which it should be saved in Box.
folder_id – str Optionally, the id of the subfolder in which it should be saved. If omitted, the default folder will be used.
format – str For now, only ‘csv’ and ‘json’; format in which to save table. Defaults to ‘csv’.

Returns:

The uploaded Box File object’s id.

Return type:

str

Raises:

ValueError – Value for format argument not allowed.
SystemError – Value for format argument not allowed.

upload_file(file: Path, path: str | None = None) → str[source]¶

Save the passed file to Box.

Parameters:

file – Path The local file to be saved to Box.
path – str Optionally, Box path str where table should be saved. Any back slashes will be treated as forward slashes. Defaults to default folder with a name matching the file name.

Returns:

The uploaded Box File object’s id.

Return type:

str

upload_file_to_folder_id(file: Path, file_name: str | None = None, folder_id: str = '0') → str[source]¶

Save the passed file to Box.

Parameters:

file – Path The local file to be saved to Box.
file_name – str Optionally, the filename under which it should be saved in Box. Defaults to the file name.
folder_id – str Optionally, the id of the subfolder in which it should be saved.

Returns:

The uploaded Box File object’s id.

Return type:

str

Raises:

SystemError – Invalid response from box upload.

download_file(path: str, local_path: Path | None = None) → Path[source]¶

Download a Box object to a local file.

Parameters:

path – str The Box path str. Any back slashes will be treated as forward slashes.
local_path – Path The local path where the file will be downloaded. If not specified, a temporary file will be created and returned, and that file will be removed automatically when the script is done running.

Returns:

The Path of the new file.

Return type:

Path

get_table(path: str, format: Literal['csv', 'json'] = 'csv') → Table[source]¶

Get a table that has been saved to Box in csv or JSON format.

Parameters:

path – str The slash-separated Box path str to the file containing the table. Any back slashes will be treated as forward slashes.
format – str Format in which Table has been saved; for now, only ‘csv’ or ‘json’. Defaults to ‘csv’.

Returns:

A Parsons Table.

Return type:

Table

get_table_by_file_id(file_id: str, format: Literal['csv', 'json'] = 'csv') → Table[source]¶

Get a table that has been saved to Box in csv or JSON format.

Parameters:

file_id – str The Box file_id of the table to be retrieved.
format – str Format in which Table has been saved; for now, only ‘csv’ or ‘json’. Defaults to ‘csv’.

Returns:

A Parsons Table.

Return type:

Table

Raises:

ValueError – Value for format argument not allowed.
SystemError – Value for format argument not allowed.

get_item_id(path: str, base_folder_id: str = '0') → str[source]¶

Given a Box path str, try to return the id for the file or folder at the end of the str.

NOTE: This method makes one API call for each level in path, so can be slow for long paths or intermediate folders containing very many items.

Parameters:

path – str A slash-separated Box path str from the base folder to the file or folder in question. Any back slashes will be treated as forward slashes.
base_folder_id – str What to use as the base folder for the path. If omitted, the default folder will be used.

Returns:

A Box File object’s id.

Return type:

str

Raises:

ValueError – Trailing slash or file / folder not found.