boxsdk.client package¶

Submodules¶

boxsdk.client.client module¶

class boxsdk.client.client.Client(oauth, session=None)[source]¶

Bases: boxsdk.object.cloneable.Cloneable

auth¶

Get the OAuth2 instance the client is using for auth to Box.

Return type:	`OAuth2`

authorized_session_class¶: alias of boxsdk.session.session.AuthorizedSession

clone(session=None)[source]¶: Base class override.

collaboration(collab_id)[source]¶

Initialize a Collaboration object, whose box id is collab_id.

Parameters:	collab_id (unicode) – The box id of the `Collaboration` object.
Returns:	A `Collaboration` object with the given group id.
Return type:	`Collaboration`

collaboration_whitelist()[source]¶

Initilializes a CollaborationWhitelist object.

Returns:	A `CollaborationWhitelist` object.
Rype:	`CollaborationWhitelist`.

collaboration_whitelist_entry(entry_id)[source]¶

Initialize a CollaborationWhitelistEntry object, whose box id is entry_id.

Parameters:	entry_id (unicode) – The box id of the `CollaborationWhitelistEntry` object.
Returns:	A `CollaborationWhitelistEntry` object with the given entry id.
Return type:	`CollaborationWhitelistEntry`

collaboration_whitelist_exempt_target(exemption_id)[source]¶

Initialize a CollaborationWhitelistExemptTarget object, whose box id is target_id.

Parameters:	exemption_id (unicode) – The box id of the `CollaborationWhitelistExemptTarget` object.
Returns:	A `CollaborationWhitelistExemptTarget` object with the given target id.
Return type:	`CollaborationWhitelistExemptTarget`

collection(collection_id)[source]¶

Initialize a Collection object, whose box ID is collection_id.

Parameters:	collection_id (unicode) – The box id of the `Collection` object.
Returns:	A `Collection` object with the given collection ID.
Return type:	`Collection`

collections[source]¶

Get a list of collections for the current user.

Parameters:	limit (int or None) – The maximum number of users to return. If not specified, the Box API will determine an appropriate limit. offset (int) – The user index at which to start the response.

comment(comment_id)[source]¶

Initialize a Comment object, whose Box ID is comment_id.

Parameters:	comment_id (unicode) – The Box ID of the `Comment` object.
Returns:	A `Comment` object with the given comment ID.
Return type:	`Comment`

create_group[source]¶

Create a group with the given name.

Parameters:	name (unicode) – The name of the group. provenance (unicode or None) – Used to track the external source where the group is coming from. external_sync_identifier (unicode or None) – Used as a group identifier for groups coming from an external source. description (unicode or None) – Description of the group. invitability_level (unicode) – Specifies who can invite this group to folders. member_viewability_level (unicode) – Specifies who can view the members of this group. fields (Iterable of unicode) – List of fields to request on the `Group` objects.
Returns:	The newly created Group.
Return type:	`Group`
Raises:	`BoxAPIException` if current user doesn’t have permissions to create a group.

create_legal_hold_policy[source]¶

Create a legal hold policy.

Parameters:	policy_name (unicode) – The legal hold policy’s display name. description (unicode or None) – The description of the legal hold policy. filter_starting_at (unicode or None) – The start time filter for legal hold policy filter_ending_at (unicode or None) – The end time filter for legal hold policy is_ongoing (bool or None) – After initialization, Assignments under this Policy will continue applying to files based on events, indefinitely.
Returns:	A legal hold policy object
Return type:	:class:`LegalHoldPolicy

create_metadata_template[source]¶

Create a new metadata template. By default, only the display name and fields are required; the template key will be automatically generated based on the display name and the template will be created in the enterprise scope.

Parameters:

display_name (unicode) – The human-readable name of the template
fields (Iterable of MetadataField) – The metadata fields for the template.
template_key (unicode) – An optional key for the template. If one is not provided, it will be derived from the display name.
hidden (bool) – Whether the template should be hidden in the UI
scope (unicode) – The scope the template should be created in

create_retention_policy[source]¶

Create a retention policy for the given enterprise.

Parameters:	policy_name (unicode) – The name of the retention policy. retention_length (int or float(‘inf’)) – The amount of time in days to apply the retention policy to the selected content. The retention_length should be set to float(‘inf’) for indefinite policies. disposition_action (unicode) – For finite policy can be set to permanently delete or remove retention. For indefinite policy this must be set to remove_retention can_owner_extend_retention (boolean or None) – The owner of a file will be allowed to extend the retention if set to true. are_owners_notified (boolean or None) – The owner or co-owner will get notified when a file is nearing expiration. custom_notification_recipients (list of `User` objects) – A custom list of user mini objects that should be notified when a file is nearing expiration.
Returns:	The newly created Retention Policy
Return type:	`RetentionPolicy`

create_terms_of_service(status, tos_type, text)[source]¶

Create a terms of service.

Parameters:	status (`TermsOfServiceStatus`) – The status of the terms of service. tos_type (`TermsOfServiceType`) – The type of the terms of service. Can be set to managed or external. text (unicode) – The message of the terms of service.
Returns:	A newly created `TermsOfService` object
Return type:	`TermsOfService`

create_user[source]¶

Create a new user. Can only be used if the current user is an enterprise admin, or the current authorization scope is a Box developer edition instance.

Parameters:	name (unicode) – The user’s display name. login (unicode or None) – The user’s email address. Required for an enterprise user, but None for an app user. user_attributes – Additional attributes for the user. See the documentation at https://box-content.readme.io/#create-an-enterprise-user for enterprise users or https://box-content.readme.io/docs/app-users for app users.

create_webhook[source]¶

Create a webhook on the given file.

Parameters:	target (`File` or :class`Folder`) – Either a `File` or `Folder` to assign a webhook to. triggers (list of unicode) – Event types that trigger notifications for the target. address (unicode) – The url to send the notification to.
Returns:	A `Webhook` object with the given entry ID.
Return type:	`Webhook`

device_pinner(device_pin_id)[source]¶

Initialize a DevicePinner object, whose box id is device_pin_id.

Parameters:	device_pin_id (unicode) – The assignment ID of the `DevicePin` object.
Returns:	A `DevicePinner` object with the given entry ID.
Return type:	`DevicePinner`

device_pinners(enterprise=None, direction=None, limit=None, marker=None, fields=None)[source]¶

Returns all of the device pins for the given enterprise.

Parameters:	enterprise (:class`Enterprise` or None) – The enterprise to retrieve device pinners for, defaulting to the current enterprise. direction (unicode or None) – The sorting direction. Set to ASC or DESC limit (int or None) – The maximum number of entries to return per page. If not specified, then will use the server-side default. marker (unicode or None) – The paging marker to start paging from. fields (Iterable of unicode) – List of fields to request.
Returns:	An iterator of the entries in the device pins.
Return type:	`BoxObjectCollection`

downscope_token[source]¶

Generate a downscoped token for the provided file or folder with the provided scopes.

Parameters:	scope – The scope(s) to apply to the resulting token. item (`Item`) – (Optional) The file or folder to get a downscoped token for. If None, the resulting token will not be scoped down to just a single item. additional_data (dict) – (Optional) Key value pairs which can be used to add/update the default data values in the request.
Returns:	The response for the downscope token request.
Return type:	`TokenResponse`

email_alias(alias_id)[source]¶

Initialize a :class: EmailAlias object, whose box id is alias_id.

Parameters:	alias_id (unicode) – The aliad id of the `EmailAlias` object.
Returns:	A `EmailAlias` object with the given entry ID.
Return type:	`EmailAlias`

enterprise(enterprise_id)[source]¶

Initialize a Enterprise object, whose box ID is enterprise_id.

Parameters:	enterprise_id (unicode) – The box id of the `Enterprise` object.
Returns:	A `Enterprise` object with the given enterprise ID.
Return type:	`Enterprise`

events()[source]¶: Get an events object that can get the latest events from Box or set up a long polling event subscription.

file(file_id)[source]¶

Initialize a File object, whose box id is file_id.

Parameters:	file_id (unicode) – The box id of the `File` object.
Returns:	A `File` object with the given file id.
Return type:	`File`

file_version(version_id)[source]¶

Initialize a FileVersion object, whose box id is version_id.

Parameters:	version_id (unicode) – The box id of the `FileVersion` object.
Returns:	A `FileVersion` object with the given file version id.
Return type:	`FileVersion`

file_version_retention(retention_id)[source]¶

Initialize a FileVersionRetention object, whose box id is retention_id.

Parameters:	retention_id (unicode) – The box ID of the `FileVersionRetention` object.
Returns:	A `FileVersionRetention` object with the given retention ID.
Return type:	`FileVersionRetention`

folder(folder_id)[source]¶

Initialize a Folder object, whose box id is folder_id.

Parameters:	folder_id (unicode) – The box id of the `Folder` object. Can use ‘0’ to get the root folder on Box.
Returns:	A `Folder` object with the given folder id.
Return type:	`Folder`

get_current_enterprise[source]¶

Get the enterprise of the current user.

Returns:	The authenticated user’s enterprise
Return type:	`Enterprise`

get_file_version_retentions[source]¶

Get the entries in the file version retention.

Parameters:	target_file (`File` or None) – The file to filter the file version. file_version (`FileVersion` or None) – A file version to filter the file version retentions by. policy (`RetentionPolicy` or None) – A policy to filter the file version retentions by. disposition_action (unicode or None) – Can be set to permanently_delete or remove_retention. disposition_before (unicode or None) – A date time filter for disposition action. disposition_after (unicode or None) – A date time filter for disposition action. limit (int or None) – The maximum number of entries to return per page. If not specified, then will use the server-side default. marker (unicode or None) – The paging marker to start paging from fields (Iterable of unicode) – List of fields to request
Returns:	An iterator of the entries in the file version retention.
Return type:	`BoxObjectCollection`

get_groups[source]¶

Get a list of all groups for the current user.

Parameters:	name (unicode or None) – Filter on the name of the groups to return. limit (int or None) – The maximum number of groups to return. If not specified, the Box API will determine an appropriate limit. offset (int or None.) – The group index at which to start the response. fields (Iterable of unicode) – List of fields to request on the `Group` objects.
Returns:	The collection of all groups.
Return type:	Iterable of `Group`

get_legal_hold_policies[source]¶

Get the entries in the legal hold policy using limit-offset paging.

Parameters:	policy_name (unicode or None) – The name of the legal hold policy case insensitive to search for limit (int or None) – The maximum number of entries to return per page. If not specified, then will use the server-side default. marker (unicode or None) – The paging marker to start paging from. fields (Iterable of unicode) – List of fields to request.
Returns:	An iterator of the entries in the legal hold policy
Return type:	`BoxObjectCollection`

get_metadata_templates[source]¶

Get all metadata templates for a given scope. By default, retrieves all metadata templates for the current enterprise.

Parameters:	scope (unicode) – The scope to retrieve templates for marker (unicode or None) – The paging marker to start paging from. fields (Iterable of unicode) – List of fields to request.
Returns:	The collection of metadata templates for the given scope
Return type:	`BoxObjectCollection`

get_pending_collaborations[source]¶

Get the entries in the pending collaborations using limit-offset paging.

Parameters:	limit (int or None) – The maximum number of entries to return per page. If not specified, then will use the server-side default. offset (int or None) – The offset of the item at which to begin the response. fields (Iterable of unicode) – List of fields to request.
Returns:	An iterator of the entries in the pending collaborations
Return type:	`BoxObjectCollection`

get_recent_items[source]¶

Get the user’s recently accessed items.

Param:	limit The maximum number of items to return. If limit is set to None, then the default limit (returned by Box in the response) is used. See https://developer.box.com/reference#get-recent-items for default.
Type:	limit int or None
Parameters:	marker (str or None) – The index at which to start returning items. fields (Iterable of unicode) – List of fields to request on the file or folder which the RecentItem references. **collection_kwargs – Keyword arguments passed to MarkerBasedObjectCollection.
Returns:	An iterator on the user’s recent items
Return type:	`MarkerBasedObjectCollection`

get_retention_policies[source]¶

Get the entries in the retention policy using marker-based paging.

Parameters:	policy_name (unicode or None) – The name of the retention policy. policy_type (unicode or None) – Set to either finite or indefinite user (`User` or None) – A user to filter the retention policies. limit (int or None) – The maximum number of entries to return per page. If not specified, then will use the server-side default. marker (unicode or None) – The paging marker to start paging from fields (Iterable of unicode) – List of fields to request
Returns:	An iterator of the entries in the retention policy
Return type:	`BoxObjectCollection`

get_shared_item[source]¶

Get information about a Box shared link. https://box-content.readme.io/reference#get-a-shared-item

Parameters:	shared_link (unicode) – The shared link. password (unicode) – The password for the shared link.
Returns:	The item referred to by the shared link.
Return type:	`Item`
Raises:	`BoxAPIException` if current user doesn’t have permissions to view the shared link.

get_storage_policies(limit=None, marker=None, fields=None)[source]¶

Get the entries in the storage policy using marker-based paging.

Parameters:	limit (int or None) – The maximum number of items to return. marker (unicode or None) – The paging marker to start returning items from when using marker-based paging. fields (Iterable of unicode) – List of fields to request.
Returns:	Returns the storage policies available for the current enterprise.
Return type:	`BoxObjectCollection`

get_terms_of_services(tos_type=None, limit=None, fields=None)[source]¶

Get the entries in the terms of service using limit-offset paging.

Parameters:	tos_type (`TermsOfServiceType`) – Can be set to managed or external for the type of terms of service. fields (Iterable of unicode) – List of fields to request
Param:	limit The maximum number of items to return. If limit is set to None, then the default limit (returned by Box in the response) is used.
Type:	limit int or None
Returns:	An iterator of the entries in the terms of service
Return type:	`BoxObjectCollection`

get_url(endpoint, *args)[source]¶

Return the URL for the given Box API endpoint.

Parameters:	endpoint (url) – The name of the endpoint. args (Iterable) – Additional parts of the endpoint URL.
Return type:	unicode

get_webhooks[source]¶

Get all webhooks in an enterprise.

Parameters:	limit (int or None) – The maximum number of entries to return. marker (unicode or None) – The position marker at which to begin the response. fields (Iterable of unicode) – List of fields to request on the file or folder which the RecentItem references.
Returns:	An iterator of the entries in the webhook
Return type:	`BoxObjectCollection`

group(group_id)[source]¶

Initialize a Group object, whose box id is group_id.

Parameters:	group_id (unicode) – The box id of the `Group` object.
Returns:	A `Group` object with the given group id.
Return type:	`Group`

group_membership(group_membership_id)[source]¶

Initialize a GroupMembership object, whose box id is group_membership_id.

Parameters:	group_membership_id (unicode) – The box id of the `GroupMembership` object.
Returns:	A `GroupMembership` object with the given membership id.
Return type:	`GroupMembership`

invite(invite_id)[source]¶

Initialize a Invite object, whose box id is invite_id.

Parameters:	invite_id (unicode) – The invite ID of the `Invite` object.
Returns:	A `Invite` object with the given entry ID.
Return type:	`Invite`

legal_hold(hold_id)[source]¶

Initialize a LegalHold object, whose box id is policy_id.

Parameters:	hold_id (unicode) – The legal hold ID of the `LegalHold` object.
Returns:	A `LegalHold` object with the given entry ID.
Return type:	`LegalHold`

legal_hold_policy(policy_id)[source]¶

Initialize a LegalHoldPolicy object, whose box id is policy_id.

Parameters:	policy_id (unicode) – The box ID of the `LegalHoldPolicy` object.
Returns:	A `LegalHoldPolicy` object with the given entry ID.
Return type:	`LegalHoldPolicy`

legal_hold_policy_assignment(policy_assignment_id)[source]¶

Initialize a LegalHoldPolicyAssignment object, whose box id is policy_assignment_id.

Parameters:	policy_assignment_id (unicode) – The assignment ID of the `LegalHoldPolicyAssignment` object.
Returns:	A `LegalHoldPolicyAssignment` object with the given entry ID.
Return type:	`LegalHoldPolicyAssignment`

make_request[source]¶

Make an authenticated request to the Box API.

Parameters:	method (unicode) – The HTTP verb to use for the request. url (unicode) – The URL for the request.
Returns:	The network response for the given request.
Return type:	`BoxResponse`
Raises:	`BoxAPIException`

metadata_cascade_policy(policy_id)[source]¶

Initializes a MetadataCascadePolicy object with the given policy ID.

Parameters:	policy_id (unicode) – The ID of the cascade policy object
Returns:	The cascade policy object
Return type:	`MetadataCascadePolicy`

metadata_template(scope, template_key)[source]¶

Initialize a MetadataTemplate object with the given scope and template key.

Parameters:	scope (unicode) – The scope of the metadata template, e.g. ‘enterprise’ or ‘global’ template_key (unicode) – The key of the metadata template
Returns:	The metadata template object
Return type:	`MetadataTemplate`

metadata_template_by_id(template_id)[source]¶

Retrieves a metadata template by ID

Parameters:	template_id (unicode) – The ID of the template object
Returns:	The metadata template with data populated from the API
Return type:	`MetadataTemplate`

retention_policy(retention_id)[source]¶

Initialize a RetentionPolicy object, whose box id is retention_id.

Parameters:	retention_id (unicode) – The box ID of the `RetentionPolicy` object.
Returns:	A `RetentionPolicy` object with the given entry ID.
Return type:	`RetentionPolicy`

retention_policy_assignment(assignment_id)[source]¶

Initialize a RetentionPolicyAssignment object, whose box id is assignment_id.

Parameters:	assignment_id (unicode) – The box ID of the `RetentionPolicyAssignment` object.
Returns:	A `RetentionPolicyAssignment` object with the given assignment ID.
Return type:	`RetentionPolicyAssignment`

root_folder()[source]¶: Returns a user’s root folder object.

search[source]¶

Get a Search object that can be used for searching Box content.

Returns:	The Search object
Return type:	`Search`

session¶

Get the BoxSession instance the client is using.

Return type:	`BoxSession`

storage_policy(policy_id)[source]¶

Initialize a StoragePolicy object, whose box id is policy_id.

Parameters:	policy_id (unicode) – The box ID of the `StoragePolicy` object.
Returns:	A `StoragePolicy` object with the given entry ID.
Return type:	`StoragePolicy`

storage_policy_assignment(assignment_id)[source]¶

Initialize a StoragePolicyAssignment object, whose box id is assignment_id.

Parameters:	assignment_id (unicode) – The box ID of the `StoragePolicyAssignment` object.
Returns:	A `StoragePolicyAssignment` object with the given entry ID.
Return type:	`StoragePolicyAssignment`

task(task_id)[source]¶

Initialize a Task object, whose box id is task_id.

Parameters:	task_id (unicode) – The box ID of the `Task` object.
Returns:	A `Task` object with the given entry ID.
Return type:	`Task`

task_assignment(assignment_id)[source]¶

Initialize a TaskAssignment object, whose box id is assignment_id.

Parameters:	assignment_id (unicode) – The box ID of the `TaskAssignment` object.
Returns:	A `TaskAssignment` object with the given entry ID.
Return type:	`TaskAssignment`

terms_of_service(tos_id)[source]¶

Initialize a TermsOfService object, whose box id is tos_id.

Parameters:	tos_id (unicode) – The box id of the `TermsOfService` object.
Returns:	A `TermsOfService` object with the given terms of service id.
Return type:	`TermsOfService`

terms_of_service_user_status(tos_user_status_id)[source]¶

Initialize a TermsOfServiceUserStatus object, whose box id is tos_user_status_id.

Parameters:	tos_user_status_id – The box id of the `TermsOfServiceUserStatus` object.
Returns:	A `TermsOfServiceUserStatus` object with the given terms of service user status id.
Return type:	`TermsOfServiceUserStatus`

translator¶

The translator used for translating Box API JSON responses into BaseAPIJSONObject smart objects.

Return type:	`Translator`

trash()[source]¶

Initialize a Trash object.

Returns:	A `Trash` object.
Return type:	`Trash`

unauthorized_session_class¶: alias of boxsdk.session.session.Session

upload_session(session_id)[source]¶

Initialize a UploadSession object, whose box id is session_id.

Parameters:	session_id (unicode) – The box id of the `UploadSession` object.
Returns:	A `UploadSession` object with the given session id.
Return type:	:class`UploadSession`

user(user_id=u'me')[source]¶

Initialize a User object, whose box id is user_id.

Parameters:	user_id (unicode) – The user id of the `User` object. Can use ‘me’ to get the User for the current/authenticated user.
Returns:	A `User` object with the given id.
Return type:	`User`

users[source]¶

Get a list of all users for the Enterprise along with their user_id, public_name, and login.

Parameters:	limit (int or None) – The maximum number of users to return. If not specified, the Box API will determine an appropriate limit. offset (int) – The user index at which to start the response. filter_term (unicode or None) – Filters the results to only users starting with the filter_term in either the name or the login. user_type (unicode or None) – Filters the results to only users of the given type: ‘managed’, ‘external’, or ‘all’. fields (Iterable of unicode) – List of fields to request on the `User` objects.
Returns:	The list of all users in the enterprise.
Return type:	list of `User`
Returns:	An iterator on the user’s recent items
Return type:	`MarkerBasedObjectCollection`

web_link(web_link_id)[source]¶

Initialize a :class: WebLink object, whose box id is web_link_id. :param web_link_id:

The box ID of the WebLink object.

Returns:	A `WebLink` object with the given entry ID.
Return type:	`WebLink`

webhook(webhook_id)[source]¶

Initialize a Webhook object, whose box id is webhook_id.

Parameters:	webhook_id (unicode) – The box ID of the :class: Webhook object.
Returns:	A `Webhook` object with the given entry ID.
Return type:	`Webhook`

boxsdk.client.developer_token_client module¶

class boxsdk.client.developer_token_client.DeveloperTokenClient(oauth=None, session=None)[source]¶

Bases: boxsdk.client.client.Client

Box client subclass which authorizes with a developer token.

boxsdk.client.development_client module¶

class boxsdk.client.development_client.DevelopmentClient(*args, **kwargs)[source]¶

Bases: boxsdk.client.logging_client.LoggingClient, boxsdk.client.developer_token_client.DeveloperTokenClient

Client subclass that uses developer token auth and logs requests and responses. Great for use in development!

boxsdk.client.logging_client module¶

class boxsdk.client.logging_client.LoggingClient(*args, **kwargs)[source]¶

Bases: boxsdk.client.client.Client

Box client subclass which logs requests and responses.

boxsdk.client package¶

Submodules¶

boxsdk.client.client module¶

boxsdk.client.developer_token_client module¶

boxsdk.client.development_client module¶

boxsdk.client.logging_client module¶

Module contents¶

Table Of Contents

Previous topic

Next topic

This Page