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(client_id=None, client_secret=None, access_token=None)[source]

Box is a file storage provider.

Args:

client_id: str: Box client (account) id – probably a 16-char alphanumeric. Not required if BOX_CLIENT_ID env variable is set.
client_secret: str: Box private key – probably a 32-char alphanumeric. Not required if BOX_CLIENT_SECRET env variable is set.
access_token: str: Box developer access token – probably a 32-char alphanumeric. Note that this is only valid for developer use only, and should not be used when creating and maintaining access for typical users. Not required if ‘’BOX_ACCESS_TOKEN’’ env variable is set.

Returns:

Box class

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[source]

Create a Box folder.

Args:

path: str: Path to the folder to be created. If no slashes are present, path will be name of folder created in the default folder.

Returns:

str: The Box id of the newly-created folder.

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

Create a Box folder.

Args:

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:

str: The Box id of the newly-created folder.

delete_folder(path) → None[source]

Delete a Box folder.

Args:

folder_id: str: Path to the folder to delete.

delete_folder_by_id(folder_id) → None[source]

Delete a Box folder.

Args:

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

delete_file(path) → None[source]

Delete a Box file.

Args:

path: str: Path to the file to delete.

delete_file_by_id(file_id) → None[source]

Delete a Box file.

Args:

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

list(path='', item_type=None) → Table[source]

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

Args:

path:str: If specified, the slash-separated path 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.

Returns: Table

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

list_files_by_id(folder_id='0') → Table[source]

List all Box files in a folder.

Args:

folder_id: str: The Box id of the folder in which to search. If omitted, search in the default folder.

Returns: Table

A Parsons table of files and their attributes.

list_folders_by_id(folder_id='0') → Table[source]

List all Box folders.

Args:

folder_id: str: The Box id of the folder in which to search. If omitted, search in the default folder.

Returns: Table

A Parsons table of folders and their attributes.

upload_table(table, path='', format='csv') → File[source]

Save the passed table to Box.

Args:

table:Table: The Parsons table to be saved.
path: str: Optionally, file path to filename where table should be saved.
format: str: For now, only ‘csv’ and ‘json’; format in which to save table.

Returns: BoxFile

A Box File object

upload_table_to_folder_id(table, file_name, folder_id='0', format='csv') → File[source]

Save the passed table to Box.

Args:

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.
format: str: For now, only ‘csv’ and ‘json’; format in which to save table.

Returns: BoxFile

A Box File object

download_file(path: str, local_path: str = None) → str[source]

Download a Box object to a local file.

Args:

path: str: The slash-separated path to the file in Box.
local_path: str: 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:

str: The path of the new file

get_table(path, format='csv') → Table[source]

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

Args:

path: str: The slash-separated path to the file containing the table.
format: str: Format in which Table has been saved; for now, only ‘csv’ or ‘json’.

Returns: Table

A Parsons Table.

get_table_by_file_id(file_id, format='csv') → Table[source]

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

Args:

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

Returns: Table

A Parsons Table.

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

Given a path-like object, try to return the id for the file or folder at the end of the path.

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.

Args:

path: str: A slash-separated path from the base folder to the file or folder in question.
base_folder_id: str: What to use as the base folder for the path. By default, use the default folder.

Returns: Table

A Parsons Table.