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