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
-
-
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 theBoxSession
constructor. - Calling session.translator.register() on an existing
BoxSession
. - Calling client.translator.register() on an existing
Client
.
- Constructing a new
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.
-
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:
-
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:
-
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
-
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.- role (
-
-
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'¶
-
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
-
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.
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
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.
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()
orgenerate_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
-
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
- file_version (
-
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: - parent_folder (
-
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
- file_version (
-
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_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_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:
-
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: 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: 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
orGroup
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
- collaborator (
-
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 forReturns: 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_web_link
[source]¶ 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_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
- owner_enterprise (
-
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
- user (
-
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.
- parent_folder (
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: 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_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: - scope (unicode) – Scope of the metadata. Must be either ‘global’ or ‘enterprise’.
- template (unicode) – The name of the metadata template. See https://docs.box.com/reference#metadata-object for more details.
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.
- parent_folder (
-
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
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
orFolder
orUser
) – 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_file_version_legal_holds
[source]¶ 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
-
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
-
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
-
static
start_update
()[source]¶ Get a
MetadataUpdate
for use with theupdate()
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 reolvedReturns: Whether the force application succeeded. Return type: bool
-
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.
-
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 templateReturns: 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
-
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
-
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
, orMetadataTemplate
) – The item to assign the retention policy on. - fields (Iterable of unicode) – List of fields to request.
Returns: A
RetentionPolicyAssignment
object.Return type: RetentionPolicyAssignment
- assignee (
-
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
-
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)
-
-
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
-
-
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 aMetadataSearchFilters
.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 toReturns: Information about the StoragePolicyAssignment
object.Return type: StoragePolicyAssignment
-
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
) – TheUser
to assign the task to.Returns: A task assignment object. Return type: TaskAssignment
-
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) – TheUser
to assign the terms of service to.Returns: A newly created TermsOfServiceUserStatus
objectReturn 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
objectReturn type: TermsOfServiceUserStatus
-
reject
(user=None)[source]¶ Reject a terms of service.
Parameters: user ( User
or None) – TheUser
to assign the terms of service to.Returns: A newly created TermsOfServiceUserStatus
objectReturn 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) – TheUser
to assign the terms of service to.
Returns: A newly created
TermsOfServiceUserStatus
objectReturn 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.
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
) – TheItem
object to get info on. - fields (Iterable of unicode) – List of fields to request
Returns: Information for a trashed
Item
object.Return type: Item
- 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
) – TheItem
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
.) – TheItem
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
.- 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_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 informationReturn 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
- destination_user (
-
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.web_link module¶
-
class
boxsdk.object.web_link.
WebLink
(session, object_id, response_object=None)[source]¶ Bases:
boxsdk.object.base_object.BaseObject
Box API endpoint for interacting with WebLinks.
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.