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
-
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
objectReturn type: TermsOfService
- status (
-
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 aFile
orFolder
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
- target (
-
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
- target_file (
-
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 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
- tos_type (
-
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
-
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
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
-
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.