pip install boxsdkThe Box API uses OAuth2 for auth. The SDK makes it relatively painless to work with OAuth2 tokens.
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.
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')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.
me = client.user(user_id='me').get()
print 'user_login: ' + me['login']root_folder = client.folder(folder_id='0').get()
print 'folder owner: ' + root_folder.owned_by['login']
print 'folder name: ' + root_folder['name']items = client.folder(folder_id='0').get_items(limit=100, offset=0)# creates folder structure /L1/L2/L3
client.folder(folder_id='0').create_subfolder('L1').create_subfolder('L2').create_subfolder('L3')shared_link = client.folder(folder_id='SOME_FOLDER_ID').get_shared_link()client.file(file_id='SOME_FILE_ID').get()['name']client.file(file_id='SOME_FILE_ID').rename('bar-2.txt')client.file(file_id='SOME_FILE_ID').move(client.folder(folder_id='SOME_FOLDER_ID'))client.file(file_id='SOME_FILE_ID').content()client.file(file_id='SOME_FILE_ID').lock()
client.file(file_id='SOME_FILE_ID').unlock()client.search('some_query', limit=100, offset=0)# 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()# 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)The Client class and all Box objects also have an as_user method.
as-user returns a copy of the object on which it was called that will make Box API requests as though the specified user was making it.
See https://box-content.readme.io/#as-user-1 for more information about how this works via the Box API.
# Logged in as admin, but rename a file as SOME USER
user = client.user(user_id='SOME_USER_ID')
client.as_user(user).file(file_id='SOME_FILE_ID').rename('bar-2.txt')
# Same thing, but using file's as_user method
client.file(file_id='SOME_FILE_ID').as_user(user).rename('bar-2.txt')The Python SDK supports your Box Developer Edition applications.
Developer Edition support requires some extra dependencies. To get them, simply
pip install boxsdk[jwt]Instead of instantiating your Client with an instance of OAuth2, instead use an instance of JWTAuth.
from boxsdk import JWTAuth
auth = JWTAuth(
client_id='YOUR_CLIENT_ID',
client_secret='YOUR_CLIENT_SECRET',
enterprise_token='YOUR_ENTERPRISE_TOKEN',
rsa_private_key_file_sys_path='CERT.PEM',
store_tokens=your_store_tokens_callback_method,
)
access_token = auth.authenticate_instance()
from boxsdk import Client
client = Client(auth)This client is able to create application users:
ned_stark_user = client.create_user('Ned Stark')These users can then be authenticated:
ned_auth = JWTAuth(
client_id='YOUR_CLIENT_ID',
client_secret='YOUR_CLIENT_SECRET',
enterprise_token='YOUR_ENTERPRISE_TOKEN',
rsa_private_key_file_sys_path='CERT.PEM',
store_tokens=your_store_tokens_callback_method,
)
ned_auth.authenticate_app_user(ned_stark_user)
ned_client = Client(ned_auth)Requests made with ned_client (or objects returned from ned_client's methods) will be performed on behalf of the newly created app user.
See CONTRIBUTING.rst.
Create a virtual environment and install packages -
mkvirtualenv boxsdk
pip install -r requirements-dev.txtRun all tests using -
toxThe 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.
Need to contact us directly? Email [email protected] and be sure to include the name of this project in the subject. For questions, please contact us directly rather than opening an issue.
Copyright 2015 Box, Inc. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.