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 account. The simplest form of authentication is a through a BoxDeveloperTokenAuth, and this document will cover how to use it. Information on setting up credentials for a developer access token can be found at the Create a Platform App page. On the Configuration tab, check enable “Write all files and folders stored in Box” under Application Scopes, and save, prior to generating a token. If you fail to do so, the token will not have the correct scope. Developer access tokens are not recommended for production environments. However, Box supports a variety of authentication methods.

Quickstart¶

This class requires credentials in the form of Box Authentication passed to the constructor, or made available as an environment variable in the form of an access token:

# Note: these are fake keys, provided as examples.
export BOX_ACCESS_TOKEN=7B39m3ozIGyTcazbWRbi5F2SSZ5J

Note

Performance: 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 Box path string in question is long, or intermediate folders contain many items. If efficiency and memory management is paramount, consider using the “by_id” methods of each function. In most cases, the id will be more accessible from returns on upload methods despite this documentation describing both methods.

Instantiate class

from parsons import Box

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

# Second approach: Pass API authentication as an argument.
from box_sdk_gen import BoxDeveloperTokenAuth
access_token = "7B39m3ozIGyTcazbWRbi5F2SSZ5J"
oauth = BoxDeveloperTokenAuth(token=access_token)
box = Box(auth=oauth):

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 Box path str.
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")

Upload tables to Box

# Upload a table as a csv file.
uploaded_table = box.upload_table(my_data_table, path="My Folder/My Subfolder/My Parsons Table", format="csv")

# Upload a table as a json file.
uploaded_table = box.upload_table(my_data_table, path="My Folder/My Subfolder/My Parsons Table", format="json")

Retrieve tables from Box

# Download a table (csv).
downloaded_table = box.get_table(path="My Folder/My Subfolder/My Parsons Table", format="csv")

# Download a table (csv) using file id.
downloaded_table = box.get_table_by_file_id(file_id=box_file_id, format="csv")

Upload files to Box

# Upload a file to a specified location.
uploaded_file = box.upload_file(my_file, path="My Folder/My Subfolder/My File")

Retrieve files from Box

# Download a file to a temporary file.
downloaded_file = box.download_file("My Folder/My Subfolder/My File")

# Download a file to a persistent, specified location.
downloaded_file = box.download_file("My Folder/My Subfolder/My File", local_path="my_file.dat")

Get an item id from a Box path str

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.box.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.