boxsdk.object package

Submodules

boxsdk.object.api_json_object module

class boxsdk.object.api_json_object.APIJSONObject(response_object=None, **kwargs)[source]

Bases: boxsdk.object.base_api_json_object.BaseAPIJSONObject, _abcoll.Mapping

Class representing objects that are not part of the REST API.

class boxsdk.object.api_json_object.APIJSONObjectMeta(name, bases, attrs)[source]

Bases: boxsdk.object.base_api_json_object.BaseAPIJSONObjectMeta, abc.ABCMeta

Avoid conflicting metaclass definitions for APIJSONObject. http://code.activestate.com/recipes/204197-solving-the-metaclass-conflict/

boxsdk.object.base_api_json_object module

class boxsdk.object.base_api_json_object.BaseAPIJSONObject(response_object=None, **kwargs)[source]

Bases: object

Base class containing basic logic shared between true REST objects and other objects (such as an Event)

object_type

Return the Box type for the object.

Return type:unicode
response_object

Return the JSON object representing the object returned from a Box API request.

Return type:dict
classmethod untranslated_fields()[source]

The fields that should not be translated on this object.

Return type:tuple
class boxsdk.object.base_api_json_object.BaseAPIJSONObjectMeta(name, bases, attrs)[source]

Bases: type

Metaclass for Box API objects.

Registers classes with the default translator, so that API responses can be translated to the correct type. This relies on the _item_type field, which must be defined in the class’s namespace dict (and must be re-defined, in order to register a custom subclass), to match the ‘type’ field of the response json. But the type-class mapping will only be registered if the module of the class is imported.

For example, events returned from the API look like

{'type': 'event', ...}

so a class for that type could be created and registered with the default translator like this:

class Event(BaseAPIJSONObject):
    _item_type = 'event'
    ...

NOTE: The default translator registration functionality is a private implementation detail of the SDK, to make it easy to register the default API object classes with the default translator. For convenience and backwards-compatability, developers are allowed to re-define the _item_type field in their own custom subclasses in order to take advantage of this functionality, but are encouraged not to. Since this is a private implementation detail, it may change or be removed in any major or minor release. Additionally, it has the usual hazards of mutable global state. The supported and recommended ways for registering custom subclasses are:

  • Constructing a new Translator, calling Translator.register() as necessary, and passing it to the BoxSession constructor.
  • Calling session.translator.register() on an existing BoxSession.
  • Calling client.translator.register() on an existing Client.

boxsdk.object.base_endpoint module

class boxsdk.object.base_endpoint.BaseEndpoint(session, **kwargs)[source]

Bases: boxsdk.object.cloneable.Cloneable

A Box API endpoint.

clone(session=None)[source]

Returns a copy of this cloneable object using the specified session.

Parameters:session (BoxSession) – The Box session used to make requests.
get_url(endpoint, *args)[source]

Return the URL used to access the endpoint.

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

unicode

session

Get the BoxSession instance the object is using.

Return type:BoxSession
translator

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

Return type:Translator

boxsdk.object.base_object module

class boxsdk.object.base_object.BaseObject(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint, boxsdk.object.base_api_json_object.BaseAPIJSONObject

A Box API endpoint for interacting with a Box object.

clone(session=None)[source]

Base class override.

delete[source]

Delete the object.

Parameters:
  • params (dict or None) – Additional parameters to send with the request. Can be None
  • headers (dict or None) – Any customer headers to send with the request. Can be None
Returns:

Whether or not the delete was successful.

Return type:

bool

Raises:

BoxAPIException in case of unexpected errors.

get[source]

Get information about the object, specified by fields. If fields is None, return the default fields.

Parameters:
  • fields (Iterable of unicode) – List of fields to request.
  • headers (dict) – Additional headers to send with the request.
Returns:

An object of the same type that has the requested information.

Return type:

BaseObject

get_type_url()[source]

Return the URL for type of the given resource.

Return type:unicode
get_url(*args)[source]

Base class override. Return the given object’s URL, appending any optional parts as specified by args.

object_id

Return the Box ID for the object.

Return type:unicode
update_info[source]

Update information about this object.

Send a PUT to the object’s base endpoint to modify the provided attributes.

Parameters:
  • data (dict) – The updated information about this object. Must be JSON serializable. Update the object attributes in data.keys(). The semantics of the values depends on the the type and attributes of the object being updated. For details on particular semantics, refer to the Box developer API documentation <https://box-content.readme.io/docs/>.
  • params (dict or None) – (optional) Query string parameters for the request.
  • headers (dict or None) – (optional) Extra HTTP headers for the request.
  • kwargs – Optional arguments that put takes.
Returns:

The updated object. Return a new object of the same type, without modifying the original object passed as self. Construct the new object with all the default attributes that are returned from the endpoint.

Return type:

BaseObject

boxsdk.object.cloneable module

class boxsdk.object.cloneable.Cloneable[source]

Bases: object

Cloneable interface to be implemented by endpoint objects that should have ability to be cloned, but with a different session member if desired.

as_user(user)[source]

Returns a new endpoint object with default headers set up to make requests as the specified user.

Parameters:user (User) – The user to impersonate when making API requests.
clone(session=None)[source]

Returns a copy of this cloneable object using the specified session.

Parameters:session (BoxSession) – The Box session used to make requests.
session

Return the Box session being used to make requests.

Return type:BoxSession

Returns a new endpoint object with default headers set up to make requests using the shared link for auth.

Parameters:
  • shared_link (unicode) – The shared link.
  • shared_link_password (unicode) – The password for the shared link.

boxsdk.object.collaboration module

class boxsdk.object.collaboration.Collaboration(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

An object that represents a collaboration between a folder and an individual or group

accept[source]

Accepts a pending collaboration

reject[source]

Rejects a pending collaboration

update_info[source]

Edit an existing collaboration on Box

Parameters:
  • role (CollaborationRole) – The new role for this collaboration or None to leave unchanged
  • status (CollaborationStatus) – The new status for this collaboration or None to leave unchanged. A pending collaboration can be set to accepted or rejected if permissions allow it.
Returns:

Whether or not the edit was successful.

Return type:

bool

Raises:

BoxAPIException if current user doesn’t have permissions to edit the collaboration.

class boxsdk.object.collaboration.CollaborationRole[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of possible collaboration roles

CO_OWNER = u'co-owner'
EDITOR = u'editor'
OWNER = u'owner'
PREVIEWER = u'previewer'
PREVIEWER_UPLOADER = u'previewer uploader'
UPLOADER = u'uploader'
VIEWER = u'viewer'
VIEWER_UPLOADER = u'viewer uploader'
class boxsdk.object.collaboration.CollaborationStatus[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of possible statuses of a collaboration

ACCEPTED = u'accepted'
PENDING = u'pending'
REJECTED = u'rejected'

boxsdk.object.collaboration_whitelist module

class boxsdk.object.collaboration_whitelist.CollaborationWhitelist(session, **kwargs)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint

Represents the whitelist of email domains that users in an enterprise may collaborate with.

add_domain[source]

Add a new domain to the collaboration whitelist.

Parameters:
  • domain (unicode) – The email domain to add to the whitelist.
  • direction (unicode) – The direction in which collaboration should be allowed: ‘inbound’, ‘outbound’, or ‘both’.
Returns:

The created whitelist entry for the domain.

Return type:

CollaborationWhitelistEntry

add_exemption[source]

Exempt a user from the collaboration whitelist.

Parameters:user (User) – The user to exempt from the whitelist.
Returns:The created whitelist exemption.
Return type:CollaborationWhitelistExemptTarget
get_entries[source]

Get the entries in the collaboration whitelist 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.
  • 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 whitelist.

Return type:

BoxObjectCollection

get_exemptions[source]

Get the list of exempted users who are not subject to the collaboration whitelist rules.

Parameters:
  • 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 exemptions to the whitelist.

Return type:

BoxObjectCollection

class boxsdk.object.collaboration_whitelist.WhitelistDirection[source]

Bases: boxsdk.util.text_enum.TextEnum

Used to determine the direction of the whitelist.

BOTH = u'both'
INBOUND = u'inbound'
OUTBOUNT = u'outbound'

boxsdk.object.collaboration_whitelist_entry module

class boxsdk.object.collaboration_whitelist_entry.CollaborationWhitelistEntry(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a whitelisted email domain for enterprise collaboration.

get_url(*args)[source]

Gets the collaboration whitelist entries endpoint URL.

Returns:The collaboration whitelist entries endpoint URL.
Return type:unicode

boxsdk.object.collaboration_whitelist_exempt_target module

class boxsdk.object.collaboration_whitelist_exempt_target.CollaborationWhitelistExemptTarget(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a user who is exempted from the collaboration whitelist.

boxsdk.object.collection module

class boxsdk.object.collection.Collection(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Box API endpoint for interacting with collections.

get_items[source]

Get the items in a collection using limit-offset paging.

Parameters:
  • limit (int or None) – The maximum number of items to return per page. If not specified, then will use the server-side default.
  • offset (int) – The index at which to start returning items.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

An iterator of the items in the folder.

Return type:

BoxObjectCollection

boxsdk.object.comment module

class boxsdk.object.comment.Comment(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

An object that represents a comment on an item

static construct_params_from_message(message)[source]
edit[source]

Edit the message of the comment.

Parameters:message (unicode) – The content of the reply comment.
reply[source]

Add a reply to the comment.

Parameters:message (unicode) – The content of the reply comment.

boxsdk.object.device_pinner module

class boxsdk.object.device_pinner.DevicePinner(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the device pinner

boxsdk.object.email_alias module

class boxsdk.object.email_alias.EmailAlias(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box email alias.

boxsdk.object.enterprise module

class boxsdk.object.enterprise.Enterprise(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box file version retention.

invite_user[source]

Invites an existing user to an Enterprise. The user must already have a Box account.

Parameters:user_email (unicode) – The login email address of the user that will receive the invitation.
Returns:The invitation record for the user
Return type:Invite

boxsdk.object.event module

class boxsdk.object.event.Event(response_object=None, **kwargs)[source]

Bases: boxsdk.object.api_json_object.APIJSONObject

Represents a single Box event.

boxsdk.object.events module

class boxsdk.object.events.EnterpriseEventsStreamType[source]

Bases: boxsdk.object.events.EventsStreamType

An enum of all possible values of the stream_type parameter for enterprise events.

  • ADMIN_LOGS: Retrieves up to a year’s events for all users in the enterprise.

NOTE: Requires Admin: These stream types will only work with an auth token from an enterprise admin account.

<https://box-content.readme.io/reference#enterprise-events>

ADMIN_LOGS = u'admin_logs'
class boxsdk.object.events.Events(session, **kwargs)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint

Box API endpoint for subscribing to changes in a Box account.

generate_events_with_long_polling[source]

Subscribe to events from the given stream position.

Parameters:
  • stream_position (unicode) – The location in the stream from which to start getting events. 0 is the beginning of time. ‘now’ will return no events and just current stream position.
  • stream_type (:enum:`UserEventsStreamType`) –

    (optional) Which type of events to return. Defaults to UserEventsStreamType.ALL.

    NOTE: Currently, the Box API requires this to be one of the user events stream types. The request will fail if an enterprise events stream type is passed.

Returns:

Events corresponding to changes on Box in realtime, as they come in.

Return type:

generator of Event

get_events[source]

Get Box events from a given stream position for a given stream type.

Parameters:
  • limit (int) – Maximum number of events to return.
  • stream_position (unicode) –

    The location in the stream from which to start getting events. 0 is the beginning of time. ‘now’ will return no events and just current stream position.

    NOTE: Currently, ‘now’ is only valid for user events stream types. The request will fail if an enterprise events stream type is passed.

  • stream_type (:enum:`EventsStreamType`) – (optional) Which type of events to return. Defaults to UserEventsStreamType.ALL.
Returns:

Dictionary containing the next stream position along with a list of some number of events.

Return type:

dict

get_latest_stream_position[source]

Get the latest stream position. The return value can be used with get_events() or generate_events_with_long_polling().

Parameters:stream_type (:enum:`UserEventsStreamType`) –

(optional) Which events stream to query. Defaults to UserEventsStreamType.ALL.

NOTE: Currently, the Box API requires this to be one of the user events stream types. The request will fail if an enterprise events stream type is passed.

Returns:The latest stream position.
Return type:int
get_long_poll_options[source]

Get the url and retry timeout for setting up a long polling connection.

Parameters:stream_type (:enum:`EventsStreamType`) – (optional) Which type of events to return. Defaults to UserEventsStreamType.ALL.
Returns:A dict including a long poll url, retry timeout, etc. E.g.
{
“type”: “realtime_server”, “url”: “http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all”, “ttl”: “10”, “max_retries”: “10”, “retry_timeout”: 610,

}

Return type:dict
get_url(*args)[source]

Base class override.

long_poll[source]

Set up a long poll connection at the specified url.

Parameters:
  • options (dict) – The long poll options which include a long pull url, retry timeout, etc.
  • stream_position (unicode) – The location in the stream from which to start getting events. 0 is the beginning of time. ‘now’ will return no events and just current stream position.
Returns:

{“message”: “new_change”}, which means there’re new changes on Box or {“version”: 1, “message”: “reconnect”} if nothing happens on Box during the long poll.

Return type:

dict

class boxsdk.object.events.EventsStreamType[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of all possible values of the stream_type parameter for user events.

The value of the stream_type parameter determines the type of events returned by the endpoint.

<https://box-content.readme.io/reference#events>

ADMIN_LOGS = u'admin_logs'
ALL = u'all'
CHANGES = u'changes'
SYNC = u'sync'
class boxsdk.object.events.UserEventsStreamType[source]

Bases: boxsdk.object.events.EventsStreamType

An enum of all possible values of the stream_type parameter for user events.

  • ALL: Returns all user events.
  • CHANGES: Returns tree changes.
  • SYNC: Returns tree changes only for sync folders.

<https://box-content.readme.io/reference#standard-user-events>

ALL = u'all'
CHANGES = u'changes'
SYNC = u'sync'

boxsdk.object.file module

class boxsdk.object.file.File(session, object_id, response_object=None)[source]

Bases: boxsdk.object.item.Item

Box API endpoint for interacting with files.

add_comment[source]

Add a comment to the file.

Parameters:message (unicode) – The content of the reply comment.
content[source]

Get the content of a file on Box.

Parameters:
  • file_version (FileVersion or None) – The specific version of the file to retrieve the contents of.
  • byte_range ((int, int)) – A tuple of inclusive byte offsets to download, e.g. (100, 199) to download the second 100 bytes of a file
Returns:

File content as bytes.

Return type:

bytes

copy(parent_folder, name=None, file_version=None)[source]

Copy the item to the given folder.

Parameters:
  • parent_folder (Folder) – The folder to which the item should be copied.
  • name (unicode or None) – A new name for the item, in case there is already another item in the new parent folder with the same name.
  • file_version (FileVersion) – A specific version of the file to copy
Returns:

The copy of the file

Return type:

File

create_task[source]

Create a task on the given file.

Parameters:
  • message (unicode or None) – An optional message to include in the task.
  • due_at (unicode or None) – When this task is due.
Returns:

The newly created task

Return type:

Task

create_upload_session(file_size, file_name=None)[source]

Create a new chunked upload session for uploading a new version of the file.

Parameters:
  • file_size (int) – The size of the file in bytes that will be uploaded.
  • file_name (unicode or None) – The new name of the file version that will be uploaded.
Returns:

A UploadSession object.

Return type:

UploadSession

delete_version[source]

Delete a specific version of a file.

Parameters:
  • file_version (FileVersion) – The file version to delete.
  • etag (unicode or None) – If specified, instruct the Box API to update the item only if the current version’s etag matches.
Returns:

Whether the operation succeeded.

Return type:

boolean

download_to[source]

Download the file; write it to the given stream.

Parameters:
  • writeable_stream (file) – A file-like object where bytes can be written into.
  • file_version (FileVersion or None) – The specific version of the file to retrieve the contents of.
  • byte_range ((int, int)) – A tuple of inclusive byte offsets to download, e.g. (100, 199) to download the second 100 bytes of a file
get_chunked_uploader[source]

Instantiate the chunked upload instance and create upload session with path to file.

Parameters:
  • file_path (unicode) – The local path to the file you wish to upload.
  • rename_file (bool) – Indicates whether the file should be renamed or not.
Returns:

A ChunkedUploader object.

Return type:

ChunkedUploader

get_comments[source]

Get the comments on the file.

Parameters:
  • limit (int or None) – The maximum number of items to return per page. If not specified, then will use the server-side default.
  • offset (int) – The index at which to start returning items.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

An iterator of the items in the folder.

Return type:

BoxObjectCollection

get_download_url[source]
get_embed_url[source]

Get a URL suitable for embedding the file in an iframe in a web application.

Returns:The embed URL.
Return type:unicode
get_previous_versions[source]

Get previous versions of the file.

Parameters:
  • limit (int or None) – The maximum number of items to return per page. If not specified, then will use the server-side default.
  • offset (int) – The index at which to start returning items.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

An iterator of the previous versions of the file.

Return type:

BoxObjectCollection

get_representation_info[source]

Get information about the representations available for a file.

Parameters:rep_hints (unicode or None) – A formatted string describing which representations are desired.
Returns:The representation information
Return type:list of dict

Get a shared link download url for the file with the given access permissions. This url is a direct download url for the file.

Parameters:
  • access (unicode or None) – Determines who can access the shared link. May be open, company, or collaborators. If no access is specified, the default access will be used.
  • etag (unicode or None) – If specified, instruct the Box API to create the link only if the current version’s etag matches.
  • unshared_at (unicode or None) – The date on which this link should be disabled. May only be set if the current user is not a free user and has permission to set expiration dates. Takes an RFC3339-formatted string, e.g. ‘2018-10-31T23:59:59-07:00’ for 11:59:59 PM on October 31, 2018 in the America/Los_Angeles timezone. The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
  • allow_preview (bool or None) – Whether or not the item being shared can be previewed when accessed via the shared link. If this parameter is None, the default setting will be used.
  • password (unicode or None) – The password required to view this link. If no password is specified then no password will be set. Please notice that this is a premium feature, which might not be available to your app.
Returns:

The URL of the shared link that allows direct download.

Return type:

unicode

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the item.

get_tasks[source]

Get the entries in the file tasks.

Parameters:fields (Iterable of unicode) – List of fields to request.
Returns:An iterator of the entries in the file tasks
Return type:BoxObjectCollection
get_thumbnail[source]

Retrieve a thumbnail image for the file.

Parameters:
  • extension (unicode) – The file extension for the thumbnail, e.g. ‘png’ or ‘jpg’
  • min_width (int or None) – The minimum width required for the thumbnail image
  • min_height (int or None) – The minimum height required for the thumbnail image
  • max_width (int or None) – The maximum width required for the thumbnail image
  • max_height (int or None) – The maximum height required for the thumbnail image
Returns:

The file contents of the thumbnail image

Return type:

bytes

lock[source]

Lock a file, preventing others from modifying (or possibly even downloading) it.

Parameters:
  • prevent_download (bool) – Whether or not the lock should prevent other users from downloading the file.
  • expire_time (unicode or None) – The RFC-3339 datetime when the lock should automatically expire, unlocking the file.
Returns:

A new File instance reflecting that the file has been locked.

Return type:

File

preflight_check[source]

Make an API call to check if the file can be updated with the new name and size of the file.

Parameters:
  • size (int) – The size of the file in bytes. Specify 0 for unknown file-sizes.
  • name (unicode) – The name of the file to be updated. It’s optional, if the name is not being changed.
Raises:

BoxAPIException when preflight check fails.

promote_version[source]

Promote a file version to become the current version of this file. This will create a new file version identical to the previous version as the new current version.

Parameters:file_version (FileVersion) – The file version to promote.
Returns:The new file version created as the current.
Return type:FileVersion
unlock[source]

Unlock a file, releasing any restrictions that the lock maintained.

Returns:A new File instance reflecting that the file has been unlocked.
Return type:File
update_contents[source]

Upload a new version of a file. The contents are taken from the given file path.

Parameters:
  • file_path (unicode) – The path of the file that should be uploaded.
  • etag (unicode or None) – If specified, instruct the Box API to update the item only if the current version’s etag matches.
  • preflight_check (bool) – If specified, preflight check will be performed before actually uploading the file.
  • preflight_expected_size (int) – The size of the file to be uploaded in bytes, which is used for preflight check. The default value is ‘0’, which means the file size is unknown.
  • upload_using_accelerator (bool) –

    If specified, the upload will try to use Box Accelerator to speed up the uploads for big files. It will make an extra API call before the actual upload to get the Accelerator upload url, and then make a POST request to that url instead of the default Box upload url. It falls back to normal upload endpoint, if cannot get the Accelerator upload url.

    Please notice that this is a premium feature, which might not be available to your app.

Returns:

A new file object

Return type:

File

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the file or preflight check fails.

update_contents_with_stream[source]

Upload a new version of a file, taking the contents from the given file stream.

Parameters:
  • file_stream (file) – The file-like object containing the bytes
  • etag (unicode or None) – If specified, instruct the Box API to update the item only if the current version’s etag matches.
  • preflight_check (bool) – If specified, preflight check will be performed before actually uploading the file.
  • preflight_expected_size (int) – The size of the file to be uploaded in bytes, which is used for preflight check. The default value is ‘0’, which means the file size is unknown.
  • upload_using_accelerator (bool) –

    If specified, the upload will try to use Box Accelerator to speed up the uploads for big files. It will make an extra API call before the actual upload to get the Accelerator upload url, and then make a POST request to that url instead of the default Box upload url. It falls back to normal upload endpoint, if cannot get the Accelerator upload url.

    Please notice that this is a premium feature, which might not be available to your app.

Returns:

A new file object

Return type:

File

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the file or preflight check fails.

boxsdk.object.file_version module

class boxsdk.object.file_version.FileVersion(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box file version.

boxsdk.object.file_version_retention module

class boxsdk.object.file_version_retention.FileVersionRetention(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box file version retention.

boxsdk.object.folder module

class boxsdk.object.folder.Folder(session, object_id, response_object=None)[source]

Bases: boxsdk.object.item.Item

Box API endpoint for interacting with folders.

add_collaborator[source]

Add a collaborator to the folder

Parameters:
  • collaborator (User or Group or unicode) – collaborator to add. May be a User, Group, or email address (unicode string)
  • role (CollaboratorRole) – The collaboration role
  • notify (bool) – Whether to send a notification email to the collaborator
  • can_view_path (bool) – Whether view path collaboration feature is enabled or not. Note - only folder owners can create collaborations with can_view_path.
Returns:

The new collaboration

Return type:

Collaboration

cascade_metadata[source]

Create a metadata cascade policy to apply the metadata instance values on the folder for the given metadata template to all files within the folder.

Parameters:metadata_template (MetadataTemplate) – The metadata template to cascade values for
Returns:The created metadata cascade policy
Return type:MetadataCascadePolicy
create_subfolder[source]

Create a subfolder with the given name in the folder.

Parameters:name (unicode) – The name of the new folder
create_upload_session(file_size, file_name)[source]

Creates a new chunked upload session for upload a new file.

Parameters:
  • file_size (int) – The size of the file in bytes that will be uploaded.
  • file_name (unicode) – The name of the file that will be uploaded.
Returns:

A UploadSession object.

Return type:

UploadSession

Create a WebLink with a given url.

Parameters:
  • target_url (unicode) – The url the web link points to.
  • name (unicode or None) – The name of the web link. Optional, the API will give it a default if not specified.
  • description – Description of the web link
Returns:

A WebLink object.

Return type:

WebLink

delete[source]

Base class override. Delete the folder.

Parameters:
  • recursive (bool) – Whether or not the folder should be deleted if it isn’t empty.
  • etag (unicode or None) – If specified, instruct the Box API to delete the folder only if the current version’s etag matches.
Returns:

Whether or not the update was successful.

Return type:

bool

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the folder.

get_chunked_uploader[source]

Instantiate the chunked upload instance and create upload session with path to file.

Parameters:file_path (unicode) – The local path to the file you wish to upload.
Returns:A ChunkedUploader object.
Return type:ChunkedUploader
get_items[source]

Get the items in a folder.

Parameters:
  • limit (int or None) – The maximum number of items to return.
  • offset (int) – The index at which to start returning items when using offset-based pagin.
  • use_marker (bool) – Whether to use marker-based paging instead of offset-based paging, defaults to False.
  • marker (unicode or None) – The paging marker to start returning items from when using marker-based paging.
  • sort – Item field to sort results on: ‘id’, ‘name’, or ‘date’.
  • direction (unicode or None) – Sort direction for the items returned.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

The collection of items in the folder.

Return type:

Iterable of Item

get_metadata_cascade_policies[source]

Get the metadata cascade policies current applied to the folder.

Parameters:
  • owner_enterprise (Enterprise) – Which enterprise’s metadata templates to get cascade policies for. This defauls to the current enterprise.
  • 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 cascade policies attached on the folder.

Return type:

BoxObjectCollection

preflight_check[source]

Make an API call to check if a new file with given name and size can be uploaded to this folder.

Parameters:
  • size (int) – The size of the file in bytes. Specify 0 for unknown file-sizes.
  • name (unicode) – The name of the file to be uploaded.
Raises:

BoxAPIException when preflight check fails.

update_sync_state[source]

Update the sync_state attribute of this folder.

Change whether this folder will be synced by sync clients.

Parameters:sync_state (FolderSyncState) – The desired sync state of this folder. Must be a member of the FolderSyncState enum.
Returns:A new Folder instance with updated information reflecting the new sync state.
Return type:Folder
upload[source]

Upload a file to the folder. The contents are taken from the given file path, and it will have the given name. If file_name is not specified, the uploaded file will take its name from file_path.

Parameters:
  • file_path (unicode) – The file path of the file to upload to Box.
  • file_name (unicode) – The name to give the file on Box. If None, then use the leaf name of file_path
  • preflight_check (bool) – If specified, preflight check will be performed before actually uploading the file.
  • preflight_expected_size (int) – The size of the file to be uploaded in bytes, which is used for preflight check. The default value is ‘0’, which means the file size is unknown.
  • upload_using_accelerator (bool) –

    If specified, the upload will try to use Box Accelerator to speed up the uploads for big files. It will make an extra API call before the actual upload to get the Accelerator upload url, and then make a POST request to that url instead of the default Box upload url. It falls back to normal upload endpoint, if cannot get the Accelerator upload url.

    Please notice that this is a premium feature, which might not be available to your app.

Returns:

The newly uploaded file.

Return type:

File

upload_stream[source]

Upload a file to the folder. The contents are taken from the given file stream, and it will have the given name.

Parameters:
  • file_stream (file) – The file-like object containing the bytes
  • file_name (unicode) – The name to give the file on Box.
  • preflight_check (bool) – If specified, preflight check will be performed before actually uploading the file.
  • preflight_expected_size (int) – The size of the file to be uploaded in bytes, which is used for preflight check. The default value is ‘0’, which means the file size is unknown.
  • upload_using_accelerator (bool) –

    If specified, the upload will try to use Box Accelerator to speed up the uploads for big files. It will make an extra API call before the actual upload to get the Accelerator upload url, and then make a POST request to that url instead of the default Box upload url. It falls back to normal upload endpoint, if cannot get the Accelerator upload url.

    Please notice that this is a premium feature, which might not be available to your app.

Returns:

The newly uploaded file.

Return type:

File

class boxsdk.object.folder.FolderSyncState[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of all possible values of a folder’s sync_state attribute.

The value of the sync_state attribute determines whether the folder will be synced by sync clients.

IS_SYNCED = u'synced'
NOT_SYNCED = u'not_synced'
PARTIALLY_SYNCED = u'partially_synced'

boxsdk.object.group module

class boxsdk.object.group.Group(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box group.

add_member[source]

Add the given user to this group under the given role

Parameters:
  • user (User) – The User to add to the group.
  • role (unicode) – The role for the user.
  • configurable_permissions – This is a group level permission that is configured for Group members with admin role only.
Returns:

The new GroupMembership instance.

Return type:

GroupMembership

get_collaborations[source]

Get the entries in the collaboration for the group 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 collaboration for the group.

Return type:

BoxObjectCollection

get_memberships[source]

Get the membership records for the group, which indicate which users are included in the group.

Parameters:
  • offset (int or None) – The index at which to begin.
  • limit (int or None) – The maximum number of items to return in a page.
Returns:

The collection of membership objects for the group.

Return type:

Iterable of GroupMembership

class boxsdk.object.group.GroupRole[source]

Bases: boxsdk.util.text_enum.TextEnum

The role in the group.

ADMIN = u'admin'
MEMBER = u'member'

boxsdk.object.group_membership module

class boxsdk.object.group_membership.GroupMembership(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box group_membership, which relates a user & group under a specific role.

boxsdk.object.invite module

class boxsdk.object.invite.Invite(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the invite

boxsdk.object.item module

class boxsdk.object.item.Item(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Box API endpoint for interacting with files and folders.

add_to_collection[source]

Add the item to a collection. This method is not currently safe from race conditions.

Parameters:collection (Collection) – The collection to add the item to.
Returns:This item.
Return type:Item
apply_watermark[source]

Apply watermark on a Box file

Returns:Watermark object.
Return type:Watermark
collaborate[source]

Collaborate user or group onto a Box item.

Parameters:
  • accessible_by (class:User or class:Group) – An object containing the collaborator.
  • role (unicode) – The permission level to grant the collaborator.
  • can_view_path (bool or None) – Indicates whether the user can view the path of the folder collaborated into.
  • notify (bool or None) – Determines if the collaborator should receive a notification for the collaboration.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

The new collaboration

Return type:

Collaboration

collaborate_with_login[source]

Collaborate user onto a Box item with the user login.

Parameters:
  • login (unicode) – The email address of the person to grant access to.
  • role (unicode) – The permission level to grant the collaborator.
  • can_view_path (bool or None) – Indicates whether the user can view the path of the folder collaborated into.
  • notify (bool or None) – Determines if the collaborator should receive a notification for the collaboration.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

The new collaboration with the user login

Return type:

Collaboration

copy[source]

Copy the item to the given folder.

Parameters:
  • parent_folder (Folder) – The folder to which the item should be copied.
  • name (unicode or None) – A new name for the item, in case there is already another item in the new parent folder with the same name.

Create a shared link for the item with the given access permissions.

Parameters:
  • access (unicode or None) – Determines who can access the shared link. May be open, company, or collaborators. If no access is specified, the default access will be used.
  • etag (unicode or None) – If specified, instruct the Box API to create the link only if the current version’s etag matches.
  • unshared_at (unicode or None) – The date on which this link should be disabled. May only be set if the current user is not a free user and has permission to set expiration dates. Takes an RFC3339-formatted string, e.g. ‘2018-10-31T23:59:59-07:00’ for 11:59:59 PM on October 31, 2018 in the America/Los_Angeles timezone. The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
  • allow_download (bool or None) – Whether or not the item being shared can be downloaded when accessed via the shared link. If this parameter is None, the default setting will be used.
  • allow_preview (bool or None) – Whether or not the item being shared can be previewed when accessed via the shared link. If this parameter is None, the default setting will be used.
  • password (unicode or None) – The password required to view this link. If no password is specified then no password will be set. Please notice that this is a premium feature, which might not be available to your app.
Returns:

The updated object with s shared link. Returns a new object of the same type, without modifying the original object passed as self.

Return type:

Item

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the item.

delete[source]

Delete the item.

Parameters:
  • params (dict) – Additional parameters to send with the request.
  • etag (unicode or None) – If specified, instruct the Box API to delete the item only if the current version’s etag matches.
Returns:

Whether or not the delete was successful.

Return type:

bool

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the item.

delete_watermark[source]

Deletes the watermark info for a Box file

Returns:Whether or not the delete succeeded.
Return type:bool
get[source]

Base class override.

Parameters:
  • fields (Iterable of unicode) – List of fields to request.
  • etag (unicode or None) – If specified, instruct the Box API to get the info only if the current version’s etag doesn’t match.
Returns:

Information about the file or folder.

Return type:

dict

Raises:

BoxAPIException if the specified etag matches the latest version of the item.

get_all_metadata()[source]

Get all metadata attached to the item.

get_collaborations[source]

Get the entries in the collaboration.

Parameters:
  • limit (int or None) – The maximum number of items to return per page. If not specified, then will use the server-side default.
  • 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:

An iterator of the entries in the collaboration.

Return type:

BoxObjectCollection

Get a shared link for the item with the given access permissions. This url leads to a Box.com shared link page, where the item can be previewed, downloaded, etc.

Parameters:
  • access (unicode or None) – Determines who can access the shared link. May be open, company, or collaborators. If no access is specified, the default access will be used.
  • etag (unicode or None) – If specified, instruct the Box API to create the link only if the current version’s etag matches.
  • unshared_at (datetime.date or None) – The date on which this link should be disabled. May only be set if the current user is not a free user and has permission to set expiration dates.
  • allow_download (bool or None) – Whether or not the item being shared can be downloaded when accessed via the shared link. If this parameter is None, the default setting will be used.
  • allow_preview (bool or None) – Whether or not the item being shared can be previewed when accessed via the shared link. If this parameter is None, the default setting will be used.
  • password (unicode or None) – The password required to view this link. If no password is specified then no password will be set. Please notice that this is a premium feature, which might not be available to your app.
Returns:

The URL of the shared link.

Return type:

unicode

Raises:

BoxAPIException if the specified etag doesn’t match the latest version of the item.

get_watermark[source]

Return the watermark info for a Box file

Returns:Watermark object.
Return type:Watermark
metadata(scope=u'global', template=u'properties')[source]

Instantiate a Metadata object associated with this item.

Parameters:
Returns:

A new metadata instance associated with this item.

Return type:

Metadata

move[source]

Move the item to the given folder.

Parameters:
  • parent_folder (Folder) – The parent Folder object, where the item will be moved to.
  • name (unicode or None) – A new name for the item, in case there is already another item in the new parent folder with the same name.
remove_from_collection[source]

Remove the item from a collection. This method is not currently safe from race conditions.

Parameters:collection (Collection) – The collection to remove the item from.
Returns:This item.
Return type:Item

Delete the shared link for the item.

Parameters:etag (unicode or None) – If specified, instruct the Box API to delete the link only if the current version’s etag matches.
Returns:Whether or not the update was successful.
Return type:bool
Raises:BoxAPIException if the specified etag doesn’t match the latest version of the item.
rename[source]

Rename the item to a new name.

Parameters:name (unicode) – The new name, you want the item to be renamed to.
update_info[source]

Baseclass override.

Parameters:etag (unicode or None) – If specified, instruct the Box API to perform the update only if the current version’s etag matches.
Returns:The updated object. Return a new object of the same type, without modifying the original object passed as self. Construct the new object with all the default attributes that are returned from the endpoint.
Return type:BaseObject

boxsdk.object.legal_hold module

class boxsdk.object.legal_hold.LegalHold(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the legal hold policy for a file version

get_url(*args)[source]

boxsdk.object.legal_hold_policy module

class boxsdk.object.legal_hold_policy.LegalHoldPolicy(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box legal_hold_policy

assign[source]

Assign legal hold policy

Parameters:assignee (FileVersion File or Folder or User) – The file_version, file, folder, or user to assign the legal hold policy to.
Returns:A legal hold policy assignment object
Return type:LegalHoldPolicyAssignment
get_assignments[source]

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

Parameters:
  • assign_to_type (unicode or None) – Filter assignments of this type only. Can be file_version, file, folder, or user
  • assign_to_id (unicode or None) – Filter assignments to this ID only
  • 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 assignment

Return type:

BoxObjectCollection

Get legal holds for a file version.

Parameters:
  • 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 legal holds

Return type:

BoxObjectCollection

get_url(*args)[source]

boxsdk.object.legal_hold_policy_assignment module

class boxsdk.object.legal_hold_policy_assignment.LegalHoldPolicyAssignment(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the legal hold policy assignment

boxsdk.object.metadata module

class boxsdk.object.metadata.Metadata(session, box_object, scope, template)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint

clone(session=None)[source]

Base class override.

create[source]

Create the metadata instance on Box. If the instance already exists, use update() instead.

Parameters:metadata (dict) – The key/value pairs to be stored in this metadata instance on Box.
Returns:A dictionary containing the key/value pairs for this metadata object.
Return type:Metadata
delete[source]

Delete the metadata object.

Returns:Whether or not the delete was successful.
Return type:bool
get[source]

Get the key/value pairs that make up this metadata instance.

Returns:A dictionary containing the key/value pairs for this metadata object.
Return type:Metadata
get_url(*args)[source]

Base class override.

static start_update()[source]

Get a MetadataUpdate for use with the update() method.

Returns:A metadata update object that can be used to update this metadata object.
Return type:MetadataUpdate
update[source]

Update the key/value pairs associated with this metadata object. See https://box-content.readme.io/reference#update-metadata for more details.

Parameters:metadata_update (MetadataUpdate) – A metadata update object containing the changes that should be made to the metadata.
Returns:A dictionary containing the updated key/value pairs for this metadata object.
Return type:Metadata
class boxsdk.object.metadata.MetadataUpdate[source]

Bases: object

Helper class for updating Box metadata. See https://box-content.readme.io/reference#update-metadata for more details. See http://jsonpatch.com/ for details about JSON patch.

add(path, value)[source]

Insert an add operation to this metadata update.

Parameters:
  • path (unicode) – JSON pointer specifying where to add the new value.
  • value (unicode) – The value to add to the metadata document.
ops

Get a list of json patch operations in this update.

Returns:The list of json patch operations in this update.
Return type:list of dict
remove(path, old_value=None)[source]

Insert a remove operation to this metadata update.

Parameters:
  • path (unicode) – JSON pointer specifying where to remove the value from.
  • old_value (unicode) – If specified, only remove the key/value pair if the current value is equal to oldValue.
test(path, value)[source]

Insert a test operation to this metadata update. A test operation can invalidate the following operation if the value at the specified path does not match the supplied value.

Parameters:
  • path (unicode) – JSON pointer specifying where the value is in the metadata document to test.
  • value (unicode) – The value to match against.
update(path, value, old_value=None)[source]

Insert an update operation to this metadata update.

Parameters:
  • path (unicode) – JSON pointer specifying where the value is in the metadata document that should be updated.
  • value (unicode) – The updated value.
  • old_value (unicode) – If specified, only update the key/value pair if the current value is equal to oldValue.

boxsdk.object.metadata_cascade_policy module

class boxsdk.object.metadata_cascade_policy.CascadePolicyConflictResolution[source]

Bases: boxsdk.util.text_enum.TextEnum

OVERWRITE = u'overwrite'
PRESERVE_EXISTING = u'none'
class boxsdk.object.metadata_cascade_policy.MetadataCascadePolicy(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a metadata cascade policy, which applies folder metadata to files in that folder.

force_apply[source]

Applies the metadata values on the folder to all files within the folder. The conflict resolution parameter determines how conflicts when the same metadata template is already applied to a file will be handled; either the file’s existing values or the folder values can be given precendence.

Parameters:conflict_resolution (CascadePolicyConflictResolution) – How conflicting metadata values should be reolved
Returns:Whether the force application succeeded.
Return type:bool
get_url(*args)[source]

Base class override to account for the correct pluralization.

Return type:unicode

boxsdk.object.metadata_template module

class boxsdk.object.metadata_template.MetadataField(field_type, display_name, key=None, options=None)[source]

Bases: object

Represents a metadata field when creating or updating a metadata template.

json()[source]

Returns the correct representation of the template field for the API.

Return type:dict
class boxsdk.object.metadata_template.MetadataFieldType[source]

Bases: boxsdk.util.text_enum.TextEnum

DATE = u'date'
ENUM = u'enum'
FLOAT = u'float'
MULTISELECT = u'multiSelect'
STRING = u'string'
class boxsdk.object.metadata_template.MetadataTemplate(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a metadata template, which contains the the type information for associated metadata fields.

get_url(*args)[source]

Base class override, since metadata templates have a weird compound ID and non-standard URL format

Return type:unicode
scope
static start_update()[source]

Start an update operation on the template.

Returns:An update object to collect the desired update operations.
Return type:MetadataTemplateUpdate
template_key
update_info[source]

Update a metadata template with a set of update operations.

Parameters:updates (MetadataTemplateUpdate) – The update operations to apply to the template
Returns:The updated metadata template object
Return type:MetadataTemplate
class boxsdk.object.metadata_template.MetadataTemplateUpdate[source]

Bases: object

Represents a set of update operations to a metadata template.

add_enum_option(field_key, option_key)[source]

Adds a new option to an enum field.

Parameters:
  • field_key (unicode) – The key of the template field to add the option to
  • option_key (unicode) – The option to add
add_field(field)[source]

Add a new field to the template.

Parameters:field (MetadataField) – The new field to add
add_operation(operation)[source]

Adds an update operation.

Parameters:operation (dict) – The operation to add.
edit_enum_option_key(field_key, old_option_key, new_option_key)[source]

Change the key of an enum field option.

Parameters:
  • field_key (unicode) – The key of the template field in which the option appears
  • old_option_key (unicode) – The old option key
  • new_option_key (unicode) – The new option key
edit_field(field_key, field)[source]

Edits a field in the template.

Parameters:
  • field_key (unicode) – The key of the field to update
  • field (MetadataField) – The updated field values
edit_template(data)[source]

Edit top-level template properties.

Parameters:data (dict) – The properties to modify
json()[source]
remove_enum_option(field_key, option_key)[source]

Remove an option from an enum field.

Parameters:
  • field_key (unicode) – The key of the template field in which the option appears
  • option_key (unicode) – The key of the enum option to remove
remove_field(field_key)[source]

Remove a field from the metadata template.

Parameters:field_key (unicode) – The key of the field to remove
reorder_enum_options(field_key, option_keys)[source]

Reorders the options in an enum field, which affects their display in UI.

Parameters:
  • field_key (unicode) – The key of the enum field to reorder
  • option_keys (list of unicode) – The option keys in the desired order
reorder_fields(field_keys)[source]

Reorders the fields in a metadata template, which affects their display in UI.

Parameters:field_keys (list of unicode) – The field keys in the desired order

boxsdk.object.recent_item module

class boxsdk.object.recent_item.RecentItem(response_object=None, **kwargs)[source]

Bases: boxsdk.object.base_api_json_object.BaseAPIJSONObject

Represents a single recent item accessed by a Box user.

boxsdk.object.retention_policy module

class boxsdk.object.retention_policy.RetentionPolicy(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box retention policy.

assign[source]

Assign a retention policy to a Box item

Parameters:
  • assignee (Folder, Enterprise, or MetadataTemplate) – The item to assign the retention policy on.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

A RetentionPolicyAssignment object.

Return type:

RetentionPolicyAssignment

assignments[source]

Get the assignments for the retention policy.

Parameters:
  • assignment_type (unicode or None.) – The type of retention policy assignment to retrieve. Can be set to ‘folder’, ‘enterprise’, or ‘metadata_template’.
  • limit (int or None) – The maximum number of items to return.
  • marker (unicode or None) – The position marker at which to begin the response.
  • fields (Iterable of unicode) – List of fields to request.
Returns:

An iterable of assignments in the retention policy.

Return type:

BoxObjectCollection

get_url(*args)[source]

Returns the url for this retention policy.

boxsdk.object.retention_policy_assignment module

class boxsdk.object.retention_policy_assignment.RetentionPolicyAssignment(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box retention policy assignment.

boxsdk.object.search module

class boxsdk.object.search.MetadataSearchFilter(template_key, scope)[source]

Bases: object

Helper class to encapsulate a single search filter. A search filter can only search against one template, but can filter on many fields. See MetadataSearchFilters.

add_range_filter(field_key, gt_value=None, lt_value=None)[source]

Add a range filter (used for ranged searches on numbers and dates)

Parameters:
  • field_key – The field key to filter on
  • gt_value (unicode or int or float or long or None) – The lower bound of the range filter (inclusive)
  • lt_value (unicode or int or float or long or None) – The upper bound of the range filter (inclusive)
add_value_based_filter(field_key, value)[source]

Add a value-based filter (used for token-based search on string fields, and exact match search on all other fields)

Parameters:
  • field_key – The field key to filter on
  • value (unicode) – The value to use to filter
as_dict()[source]

Returns a dict representation of this object

Returns:The dict representation
Return type:dict
class boxsdk.object.search.MetadataSearchFilters[source]

Bases: object

Helper class to encapsulate a list of metadata search filter params (mdfilters API param) See https://developers.box.com/metadata-api/#search for more details

add_filter(metadata_filter)[source]

Add a filter to this object. Note that the API only supports one filter.

Parameters:metadata_filter (MetadataSearchFilter) – The filter to add
as_list()[source]

Get a list of filters from this object to use as a parameter in the Search API

Returns:The list of filters
Return type:list of dict
class boxsdk.object.search.Search(session, **kwargs)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint

Search Box for files and folders.

get_url(*args)[source]

Gets the search endpoint URL.

Returns:The search endpoint URL.
Return type:unicode
static make_single_metadata_filter(template_key, scope)[source]

Make a single MetadataSearchFilter that represents a filter on a template. It must be added to a MetadataSearchFilters.

Returns:The new MetadataSearchFilter
Return type:MetadataSearchFilter
query[source]

Search Box for items matching the given query.

Parameters:
  • query (unicode) – The string to search for.
  • limit (int) – The maximum number of items to return.
  • offset (int) – The search result at which to start the response.
  • ancestor_folders (Iterable of Folder) – Folder ids to limit the search to.
  • file_extensions (iterable of unicode) – File extensions to limit the search to.
  • metadata_filters (MetadataSearchFilters) – Filters used for metadata search
  • result_type (unicode) – Which type of result you want. Can be file or folder.
  • content_types (Iterable of unicode) – Which content types to search. Valid types include name, description, file_content, comments, and tags.
  • scope (unicode or None) – The scope of content to search over
  • created_at_range ((unicode or None, unicode or None)) – A tuple of the form (lower_bound, upper_bound) for the creation datetime of items to search.
  • updated_at_range ((unicode or None, unicode or None)) – A tuple of the form (lower_bound, upper_bound) for the update datetime of items to search.
  • size_range ((int or None, int or None)) – A tuple of the form (lower_bound, upper_bound) for the size in bytes of items to search.
  • owner_users (iterable of User) – Owner users to filter content by; only content belonging to these users will be returned.
  • trash_content (unicode or None) – Whether to search trashed or non-trashed content.
  • fields (Iterable of unicode) – Fields to include on the returned items.
Returns:

The collection of items that match the search query.

Return type:

Iterable of Item

static start_metadata_filters()[source]

Get a MetadataSearchFilters that represents a set of metadata filters.

Returns:The new MetadataSearchFilters
Return type:MetadataSearchFilters
class boxsdk.object.search.SearchScope[source]

Bases: boxsdk.util.text_enum.TextEnum

Enum of possible serach scopes.

ENTERPRISE = u'enterprise_content'
USER = u'user_content'
class boxsdk.object.search.TrashContent[source]

Bases: boxsdk.util.text_enum.TextEnum

Enum of trash content values.

NONE = u'non_trashed_only'
ONLY = u'trashed_only'

boxsdk.object.storage_policy module

class boxsdk.object.storage_policy.StoragePolicy(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the storage policy

assign(user)[source]

Checks to see if a user is already assigned a storage policy or if the storage policy assigned to user belongs to the enterprise. If neither, then update the user storage policy to the new one.

Parameters:user (User) – The class:User to assign the storage policy to
Returns:Information about the StoragePolicyAssignment object.
Return type:StoragePolicyAssignment
create_assignment(user)[source]

Assign a storage policy to a User.

Parameters:user – The :class:’User` to assign the storage policy to.
Type:User
Returns:Information about the StoragePolicyAssignment object
Return type:StoragePolicyAssignment
get_url(*args)[source]

Get url for storage policies.

boxsdk.object.storage_policy_assignment module

class boxsdk.object.storage_policy_assignment.StoragePolicyAssignment(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents the storage policy assignment

boxsdk.object.task module

class boxsdk.object.task.Task(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box task.

assign[source]

Assign a task to a single user on a single file.

Parameters:assignee (User) – The User to assign the task to.
Returns:A task assignment object.
Return type:TaskAssignment
assign_with_login[source]

Used to assign a task to a single user with the login email address of the assignee.

Parameters:assign_to_login (unicode or None) – The login of the user to assign the task to.
Returns:A task assignment object.
Return type:TaskAssignment
get_assignments[source]

Get the entries in the file task assignment.

Parameters:fields (Iterable of unicode) – List of fields to request.
Returns:An iterator of the entries in the file task assignment.
Return type:BoxObjectCollection

boxsdk.object.task_assignment module

class boxsdk.object.task_assignment.ResolutionState[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of possible resolution states

APPROVED = u'approved'
COMPLETED = u'completed'
INCOMPLETE = u'incomplete'
REJECTED = u'rejected'
class boxsdk.object.task_assignment.TaskAssignment(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box task.

boxsdk.object.terms_of_service module

class boxsdk.object.terms_of_service.TermsOfService(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box terms of service.

accept(user=None)[source]

Accept a terms of service.

Parameters:user (User or None) – The User to assign the terms of service to.
Returns:A newly created TermsOfServiceUserStatus object
Return type:TermsOfServiceUserStatus
get_user_status(user=None)[source]

Get the terms of service user status.

Parameters:user (User or None) – This is the user to get the status of the terms of service for. This defaults to current user.
Returns:A TermsOfServiceUserStatus object
Return type:TermsOfServiceUserStatus
reject(user=None)[source]

Reject a terms of service.

Parameters:user (User or None) – The User to assign the terms of service to.
Returns:A newly created TermsOfServiceUserStatus object
Return type:TermsOfServiceUserStatus
set_user_status(is_accepted, user=None)[source]

Create a terms of service user status.

Parameters:
  • is_accepted (bool) – Indicates whether a use has accepted or rejected a terms of service.
  • user (User or None) – The User to assign the terms of service to.
Returns:

A newly created TermsOfServiceUserStatus object

Return type:

TermsOfServiceUserStatus

class boxsdk.object.terms_of_service.TermsOfServiceStatus[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of possible terms of service status

DISABLED = u'disabled'
ENABLED = u'enabled'
class boxsdk.object.terms_of_service.TermsOfServiceType[source]

Bases: boxsdk.util.text_enum.TextEnum

An enum of possible terms of service types

EXTERNAL = u'external'
MANAGED = u'managed'

boxsdk.object.terms_of_service_user_status module

class boxsdk.object.terms_of_service_user_status.TermsOfServiceUserStatus(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box terms of service user status.

accept()[source]

Accept a term of service.

get_url(*args)[source]
reject()[source]

Reject a term of service.

boxsdk.object.trash module

class boxsdk.object.trash.Trash(session, **kwargs)[source]

Bases: boxsdk.object.base_endpoint.BaseEndpoint

Box API endpoint for performing trash related actions in Box.

get_item[source]

Get item from trash.

Parameters:
  • item (Item) – The Item object to get info on.
  • fields (Iterable of unicode) – List of fields to request
Returns:

Information for a trashed Item object.

Return type:

Item

get_items[source]

Using limit-offset paging, get the files, folders and web links that are in the user’s trash.

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 trash

Return type:

BoxObjectCollection

permanently_delete_item[source]

Permanently delete an item that is in the trash. The item will no longer exist in Box.

Parameters:item (Item) – The Item to delete from trash.
Returns:Whether or not the delete was successful.
Return type:bool
restore_item[source]

Restores an item from the trash. Could be files, folders, or weblinks.

Parameters:
  • item (Item.) – The Item object to restore from trash.
  • name (unicode or None) – The new name for this item. Only used if the item can’t be restored due to name conflict.
  • parent_folder (Item or None) – The new parent folder. Only used if the previous parent folder no longer exists.
  • fields (Iterable of unicode) – List of fields to request
Returns:

A restored Item.

Return type:

Item.

boxsdk.object.upload_session module

class boxsdk.object.upload_session.UploadSession(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

abort()[source]

Abort an upload session, cancelling the upload and removing any parts that have already been uploaded.

Returns:A boolean indication success of the upload abort.
Return type:bool
commit(content_sha1, parts=None, file_attributes=None, etag=None)[source]

Commit a multiput upload.

Parameters:
  • content_sha1 (bytes) – SHA-1 hash of the file contents that was uploaded.
  • parts (Iterable of dict or None) – List of parts that were uploaded.
  • file_attributes (dict) – A dict of attributes to set on the uploaded file.
  • etag (unicode or None) – If specified, instruct the Box API to delete the folder only if the current version’s etag matches.
Returns:

The newly-uploaded file object.

Return type:

File

get_chunked_uploader(file_path)[source]

Instantiate the chunked upload instance and create upload session with path to file.

Parameters:file_path (unicode) – The local path to the file you wish to upload.
Returns:A ChunkedUploader object.
Return type:ChunkedUploader
get_chunked_uploader_for_stream(content_stream, file_size)[source]

Instantiate the chunked upload instance and create upload session.

Parameters:
  • content_stream (File) – File-like object containing the content of the part to be uploaded.
  • file_size (int) – The size of the file that this part belongs to.
Returns:

A ChunkedUploader object.

Return type:

ChunkedUploader

get_parts(limit=None, offset=None)[source]

Get a list of parts uploaded so far.

Parameters:
  • limit (int or None) – The maximum number of items to return per page. If not specified, then will use the server-side default.
  • offset (int or None) – The index at which to start returning items.
Returns:

Returns a BoxObjectCollection object containing the uploaded parts.

Return type:

BoxObjectCollection

get_url(*args)[source]

Base class override. Endpoint is a little different - it’s /files/upload_sessions.

Return type:unicode
upload_part_bytes(part_bytes, offset, total_size, part_content_sha1=None)[source]

Upload a part of a file.

Parameters:
  • part_bytes (bytes) – Part bytes
  • offset (int) – Offset, in number of bytes, of the part compared to the beginning of the file. This number should be a multiple of the part size.
  • total_size (int) – The size of the file that this part belongs to.
  • part_content_sha1 (bytes or None) – SHA-1 hash of the part’s content. If not specified, this will be calculated.
Returns:

The uploaded part record.

Return type:

dict

boxsdk.object.user module

class boxsdk.object.user.User(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box user.

add_email_alias[source]

Adds a new email alias to the given user’s account.

Parameters:email (unicode) – The email alias to add to the user.
Returns:The new email alias object
Return type:EmailAlias
delete[source]

Delete a user’s account. This user will no longer be able to access Box.

Parameters:
  • notify (bool) – Whether a notification should be sent about the deletion
  • force – Whether the user should be deleted even if they still own files
Returns:

Whether the deletion succeeded

Return type:

bool

get_email_aliases[source]

Gets an list of email aliases for a user.

Parameters:
  • limit (int or None) – The maximum number of users to return. If not specified, the Box API will determine an appropriate limit.
  • fields (Iterable of unicode) – List of fields to request
Returns:

An iterator of the user’s email aliases

Return type:

BoxObjectCollection

get_group_memberships[source]

Get the entries in the user group membership 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 groups

Return type:

BoxObjectCollection

get_storage_policy_assignment()[source]

Get the storage policy assignment assigned to the user.

Returns:The StoragePolicyAssignment object information
Return type:StoragePolicyAssignment
remove_email_alias[source]

Remove an email alias from the user.

Parameters:email_alias (EmailAlias) – The email alias to remove.
Returns:Whether the removal succeeded.
Return type:bool
transfer_content[source]

Move all of the items owned by a user into a new folder in another user’s account.

Parameters:
  • destination_user (User) – The id of the user to transfer content to.
  • notify (bool or None) – Whether the destination user should receive email notification of the transfer.
  • fields (Iterable of unicode) – Fields to return on the resulting Folder object
Returns:

A Folder object that was transferred to another user.

Return type:

Folder

boxsdk.object.watermark module

class boxsdk.object.watermark.Watermark(response_object=None, **kwargs)[source]

Bases: boxsdk.object.api_json_object.APIJSONObject

Box API endpoint for applying watermark in a Box account.

boxsdk.object.webhook module

class boxsdk.object.webhook.Webhook(session, object_id, response_object=None)[source]

Bases: boxsdk.object.base_object.BaseObject

Represents a Box Webhook.

Module contents