Skip to main content

Official Box Python SDK

Project description

http://opensource.box.com/badges/active.svg https://travis-ci.org/box/box-python-sdk.png?branch=master Documentation Status https://pypip.in/v/boxsdk/badge.png https://pypip.in/d/boxsdk/badge.png

Installing

pip install boxsdk

Authorization

The Box API uses OAuth2 for auth. The SDK makes it relatively painless to work with OAuth2 tokens.

Get the authorization url

from boxsdk import OAuth2

oauth = OAuth2(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    store_tokens=your_store_tokens_callback_method,
)

auth_url, csrf_token = oauth.get_authorization_url('http://YOUR_REDIRECT_URL')

store_tokens is a callback used to store the access token and refresh token. You might want to define something like this:

def store_tokens(access_token, refresh_token):
    # store the tokens at secure storage (e.g. Keychain)

The SDK will keep the tokens in memory for the duration of the Python script run, so you don’t always need to pass store_tokens.

Authenticate (get access/refresh token)

If you navigate the user to the auth_url, the user will eventually get redirected to http://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE. After getting the code, you will be able to use the code to exchange for access token and fresh token.

The SDK handles all the work for you; all you need to do is run:

# Make sure that the csrf token you get from the `state` parameter
# in the final redirect URI is the same token you get from the
# get_authorization_url method.
assert 'THE_CSRF_TOKEN_YOU_GOT' == csrf_token
access_token, refresh_token = oauth.authenticate('YOUR_AUTH_CODE')

Create an authenticated client

from boxsdk import Client

client = Client(oauth)

And that’s it! You can start using the client to do all kinds of cool stuff and the SDK will handle the token refresh for you automatically.

Usage

Get user info

me = client.user(user_id='me').get()
print 'user_login: ' + me['login']

Get folder info

root_folder = client.folder(folder_id='0').get()
print 'folder owner: ' + root_folder.owned_by['login']
print 'folder name: ' + root_folder['name']

Get items in a folder

items = client.folder(folder_id='0').get_items(limit=100, offset=0)

Create subfolder

# creates folder structure /L1/L2/L3
client.folder(folder_id='0').create_subfolder('L1').create_subfolder('L2').create_subfolder('L3')

Get file name

client.file(file_id='SOME_FILE_ID').get()['name']

Rename an item

client.file(file_id='SOME_FILE_ID').rename('bar-2.txt')

Move an item

client.file(file_id='SOME_FILE_ID').move(client.folder(folder_id='SOME_FOLDER_ID'))

Get content of a file

client.file(file_id='SOME_FILE_ID').content()

Lock/unlock a file

client.file(file_id='SOME_FILE_ID').lock()
client.file(file_id='SOME_FILE_ID').unlock()

Events

# Get events
client.events().get_events(limit=100, stream_position='now')

# Generate events using long polling
for event in client.events().generate_events_with_long_polling():
    pass  # Do something with the event

# Get latest stream position
client.events().get_latest_stream_position()

Metadata

# Get metadata
client.file(file_id='SOME_FILE_ID').metadata().get()

# Create metadata
client.file(file_id='SOME_FILE_ID').metadata().create({'key': 'value'})

# Update metadata
metadata = client.file(file_id='SOME_FILE_ID').metadata()
update = metadata.start_update()
update.add('/key', 'new_value')
metadata.update(update)

Contributing

See CONTRIBUTING.rst.

Developer Setup

Create a virtual environment and install packages -

mkvirtualenv boxsdk
pip install -r requirements-dev.txt

Testing

Run all tests using -

tox

The tox tests include code style checks via pep8 and pylint.

The tox tests are configured to run on Python 2.6, 2.7, 3.3, 3.4, and PyPy.

Support

Need to contact us directly? Email oss@box.com and be sure to include the name of this project in the subject. For questions, please contact us directly rather than opening an issue.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for boxsdk, version 1.1.5
Filename, size File type Python version Upload date Hashes
Filename, size boxsdk-1.1.5.tar.gz (65.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page