Package: boxsdk
Box Python SDKGetting Started Docs:https://developer.box.com/guides/tooling/sdks/python/InstallingGetting StartedAuthorizationServer-to-Server Auth with JWTTraditional 3-legged OAuth2Other Auth OptionsUsage DocumentationMaking API Calls ManuallyOther Client OptionsLogging ClientDeveloper Token ClientDevelopment ClientCustomizationCustom SubclassesFIPS 140-2 ComplianceVersionsSupported VersionVersion scheduleContributingDeveloper SetupTestingQuestions, Bugs, and Feature Requests?Copyright and LicenseInstallingpip install boxsdkThe current version of the SDK is v3.x --- With this release support for
Python 3.5 and earlier (including 2.x) has been dropped. if you're
looking for the code or documentation for v1.5.x, please see the1.5
branch.Getting StartedTo get started with the SDK, get a Developer Token from the
Configuration page of your app in theBox Developer
Console. You can use this token
to make test calls for your own Box account.The SDK provides an interactiveDevelopmentClientthat makes it easy
to test out the SDK in a REPL. This client will automatically prompt for
a new Developer Token when it requires one, and will log HTTP requests
and responses to aid in debugging and understanding how the SDK makes
API calls.>>>fromboxsdkimportDevelopmentClient>>>client=DevelopmentClient()Enter developer token: <ENTER DEVELOPER TOKEN HERE>>>>user=client.user().get()GET https://api.box.com/2.0/users/me {'headers': {'Authorization': '---wXyZ','User-Agent': 'box-python-sdk-2.0.0','X-Box-UA': 'agent=box-python-sdk/2.0.0; env=python/3.6.5'},'params': None}"GET https://api.box.com/2.0/users/me" 200 454{'Date': 'Thu, 01 Nov 2018 23:32:11 GMT', 'Content-Type': 'application/json', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'Strict-Transport-Security': 'max-age=31536000', 'Cache-Control': 'no-cache, no-store', 'Content-Encoding': 'gzip', 'Vary': 'Accept-Encoding', 'BOX-REQUEST-ID': '0b50luc09ahp56m2jmkla8mgmh2', 'Age': '0'}{'address': '','avatar_url': 'https://cloud.app.box.com/api/avatar/large/123456789','created_at': '2012-06-07T11:14:50-07:00','id': '123456789','job_title': '','language': 'en','login': 'user@example.com','max_upload_size': 16106127360,'modified_at': '2018-10-30T17:01:27-07:00','name': 'Example User','phone': '','space_amount': 1000000000000000.0,'space_used': 14330018065,'status': 'active','timezone': 'America/Los_Angeles','type': 'user'}>>>print(f'The current user ID is{user.id}')The current user ID is 123456789Outside of a REPL, you can initialize a newClientwith just the
Developer Token to get started.fromboxsdkimportOAuth2,Clientauth=OAuth2(client_id='YOUR_CLIENT_ID',client_secret='YOUR_CLIENT_SECRET',access_token='YOUR_DEVELOPER_TOKEN',)client=Client(auth)user=client.user().get()print(f'The current user ID is{user.id}')AuthorizationThe Box API uses OAuth2 for auth. The SDK makes it relatively painless
to work with OAuth2 tokens.Server-to-Server Auth with JWTThe Python SDK supports yourJWT
Authenticationapplications.Authenticating with a JWT requires some extra dependencies. To get them,
simplypip install "boxsdk[jwt]"Instead of instantiating yourClientwith an instance ofOAuth2,
instead use an instance ofJWTAuth.fromboxsdkimportJWTAuthfromboxsdkimportClientauth=JWTAuth(client_id='YOUR_CLIENT_ID',client_secret='YOUR_CLIENT_SECRET',enterprise_id='YOUR_ENTERPRISE_ID',jwt_key_id='YOUR_JWT_KEY_ID',rsa_private_key_file_sys_path='CERT.PEM',rsa_private_key_passphrase='PASSPHRASE',)access_token=auth.authenticate_instance()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',user=ned_stark_user,jwt_key_id='YOUR_JWT_KEY_ID',rsa_private_key_file_sys_path='CERT.PEM',rsa_private_key_passphrase='PASSPHRASE')ned_auth.authenticate_user()ned_client=Client(ned_auth)Requests made withned_client(or objects returned fromned_client's methods) will be performed on behalf of the newly
created app user.Traditional 3-legged OAuth2Get the Authorization URLfromboxsdkimportOAuth2oauth=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:defstore_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 Tokens)If you navigate the user to the auth_url, the user will eventually get
redirected tohttp://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE. After
getting the code, you will be able to use the code to exchange for an
access token and refresh 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_tokenaccess_token,refresh_token=oauth.authenticate('YOUR_AUTH_CODE')Create an Authenticated ClientfromboxsdkimportClientclient=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.Instantiate a Client Given an Access and a Refresh TokenAlternatively, you can instantiate an OAuth2 object with the access
token and refresh token. Once you have an oauth object you can pass that
into the Client object to instantiate a client and begin making calls.fromboxsdkimportClient,OAuth2oauth=OAuth2(client_id='YOUR_CLIENT_ID',client_secret='YOUR_CLIENT_SECRET',access_token='ACCESS_TOKEN',refresh_token='REFRESH_TOKEN',)client=Client(oauth)user=client.user().get()This will retrieve the current user! From here you can use the client
you created to start making calls.Other Auth OptionsFor advanced uses of the SDK, three additional auth classes are
provided:CooperativelyManagedOAuth2: Allows multiple auth instances to
share tokens.RemoteOAuth2: Allows use of the SDK on clients without access to
your application's client secret. Instead, you provide aretrieve_access_tokencallback. That callback should perform the
token refresh, perhaps on your server that does have access to the
client secret.RedisManagedOAuth2: Stores access and refresh tokens in Redis.
This allows multiple processes (possibly spanning multiple machines)
to share access tokens while synchronizing token refresh. This could
be useful for a multiprocess web server, for example.Usage DocumentationFull documentation of the available functionality with example code is
available in theSDK documentation
pages, and
there is also method-level documentation available onReadTheDocs.Making API Calls ManuallyThe Box API is continually evolving. As such, there are API endpoints
available that are not specifically supported by the SDK. You can still
use these endpoints by using themake_requestmethod of theClient.# https://developer.box.com/en/reference/get-metadata-templates-id/# Returns a Python dictionary containing the result of the API requestjson_response=client.make_request('GET',client.get_url('metadata_templates','enterprise','customer','schema'),).json()make_request()takes two parameters:method- an HTTP verb likeGETorPOSTurl- the URL of the requested API endpointTheClientclass and Box objects have aget_urlmethod. Pass it an
endpoint to get the correct URL for use with that object and endpoint.For API calls which require body or query params, you can use**kwargsto pass extra params:data- takes a jsonified dictionary of body parametersparams- takes a dictionary of query parameters# https://developer.box.com/reference/post-folders/# Creates a new folder# JSONify the bodybody=json.dumps({'name':'test-subfolder','parent':{'id':'0',}})client.make_request('POST',client.get_url('folders'),params={'fields':'name,id'},data=body)Other Client OptionsLogging ClientFor more insight into the network calls the SDK is making, you can use
theLoggingClientclass. This class logs information about network
requests and responses made to the Box API.>>>fromboxsdkimportLoggingClient>>>client=LoggingClient()>>>client.user().get()GET https://api.box.com/2.0/users/me {'headers': {u'Authorization': u'Bearer ---------------------------kBjp',u'User-Agent': u'box-python-sdk-1.5.0'},'params': None}{"type":"user","id":"..","name":"Jeffrey Meadows","login":"..",..}<boxsdk.object.user.User at 0x10615b8d0>Developer Token ClientThe Box Developer Console allows for the creation of short-lived
developer tokens. The SDK makes it easy to use these tokens. Use theget_new_token_callbackparameter to control how the client will get
new developer tokens as needed. The default is to prompt standard input
for a token.Development ClientFor exploring the Box API, or to quickly get going using the SDK, theDevelopmentClientclass combines theLoggingClientwith theDeveloperTokenClient.CustomizationCustom SubclassesCustom object subclasses can be defined:from boxsdk import Clientfrom boxsdk import Folderclass MyFolderSubclass(Folder):passclient = Client(oauth)client.translator.register('folder', MyFolderSubclass)folder = client.folder('0')>>>printfolder>>><BoxMyFolderSubclass-0>If an object subclass is registered in this way, instances of this
subclass will be returned from all SDK methods that previously returned
an instance of the parent. SeeBaseAPIJSONObjectMetaandTranslatorto see how the SDK performs dynamic lookups to determine return types.FIPS 140-2 ComplianceThe Python SDK allows the use of FIPS 140-2 validated SSL libraries, such as OpenSSL 3.0.
However, some actions are required to enable this functionality.Currently, the latest distributions of Python default to OpenSSL v1.1.1, which is not FIPS compliant.
Therefore, if you want to use OpenSSL 3.0 in your network communication,
you need to ensure that Python uses a custom SSL library.
One way to achieve this is by creating a custom Python distribution with the ssl module replaced.If you are using JWT for authentication, it is also necessary to ensure that the cryptography library,
which is one of the extra dependencies for JWT, uses OpenSSL 3.0.
To enable FIPS mode for thecryptographylibrary, you need to install a FIPS-compliant version of OpenSSL
during the installation process of cryptography using thepipcommand.VersionsWe use a modified version ofSemantic Versioningfor all changes. Seeversion strategyfor details which is effective from 30 July 2022.Supported VersionOnly the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version.A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features.  Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date.Version scheduleVersionSupported EnvironmentsStateFirst ReleaseEOL/Terminated3Python 3.6+Supported17 Jan 2022TBD2EOL01 Nov 201817 Jan 20221EOL10 Feb 201501 Nov 2018ContributingSeeCONTRIBUTING.md.Developer SetupCreate a virtual environment and install packages -mkvirtualenv boxsdkpip install -r requirements-dev.txtTestingRun all tests using -toxThe tox tests include code style checks via pep8 and pylint.The tox tests are configured to run on Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
and PyPy (our CI is configured to run PyPy tests on pypy-3.6, pypy-3.7, pypy-3.8).Questions, Bugs, and Feature Requests?Need to contact us directly?Browse the issues
tickets! Or, if that
doesn't work,file a new
oneand we will get
back to you. If you have general questions about the Box API, you can
post to theBox Developer
Forum.Copyright and LicenseCopyright 2019 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.