One Drive

class O365.drive.CopyOperation(*, parent=None, con=None, target=None, **kwargs)

Bases: ApiComponent

https://github.com/OneDrive/onedrive-api-docs/issues/762

__init__(*, parent=None, con=None, target=None, **kwargs)

Parameters:

• parent (Drive) – parent for this operation i.e. the source of the copied item

• con (Connection) – connection to use if no parent specified

• target (Drive) – The target drive for the copy operation

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

• monitor_url (str)

• item_id (str)

check_status(delay=0)

Checks the api endpoint in a loop

Parameters:

delay – number of seconds to wait between api calls. Note Connection ‘requests_delay’ also apply.

Returns:

tuple of status and percentage complete

Return type:

tuple(str, float)

get_item()

Returns the item copied

Returns:

Copied Item

Return type:

DriveItem

completion_percentage

Percentage complete of the copy operation.

   Type: float

item_id

item_id of the copy operation.

   Type: str

monitor_url

Monitor url of the copy operation.

   Type: str

parent

Parent drive of the copy operation.

   Type: Drive

status

Status of the copy operation.

   Type: str

target

Target drive of the copy operation.

   Type: Drive

class O365.drive.DownloadableMixin

Bases: object

download(to_path: None | str | Path = None, name: str = None, chunk_size: str | int = 'auto', convert_to_pdf: bool = False, output: BytesIO | None = None)

Downloads this file to the local drive. Can download the file in chunks with multiple requests to the server.

Parameters:

• to_path (str or Path) – a path to store the downloaded file

• name (str) – the name you want the stored file to have.

• chunk_size (int) – number of bytes to retrieve from each api call to the server. if auto, files bigger than SIZE_THERSHOLD will be chunked (into memory, will be however only 1 request)

• convert_to_pdf (bool) – will try to download the converted pdf if file extension in ALLOWED_PDF_EXTENSIONS

• output (BytesIO) – (optional) an opened io object to write to. if set, the to_path and name will be ignored

Returns:

Success / Failure

Return type:

bool

class O365.drive.Drive(*, parent=None, con=None, **kwargs)

Bases: ApiComponent

A Drive representation. A Drive is a Container of Folders and Files and act as a root item

__init__(*, parent=None, con=None, **kwargs)

Create a drive representation

Parameters:

• parent (Drive or Storage) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

get_child_folders(limit=None, *, query=None, order_by=None, batch=None)

Returns all the folders inside this folder

Parameters:

• limit (int) – max no. of folders to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

folder items in this folder

Return type:

generator of DriveItem or Pagination

get_item(item_id)

Returns a DriveItem by it’s Id

Returns:

one item

Return type:

DriveItem

get_item_by_path(item_path)

Returns a DriveItem by it’s absolute path: /path/to/file :return: one item :rtype: DriveItem

get_items(limit=None, *, query=None, order_by=None, batch=None)

Returns a collection of drive items from the root folder

Parameters:

• limit (int) – max no. of items to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

items in this folder

Return type:

generator of DriveItem or Pagination

get_recent(limit=None, *, query=None, order_by=None, batch=None)

Returns a collection of recently used DriveItems

Parameters:

• limit (int) – max no. of items to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

items in this folder

Return type:

generator of DriveItem or Pagination

get_root_folder()

Returns the Root Folder of this drive

Returns:

Root Folder

Return type:

DriveItem

get_shared_with_me(limit=None, allow_external=False, *, query=None, order_by=None, batch=None)

Returns a collection of DriveItems shared with me

Parameters:

• limit (int) – max no. of items to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

• allow_external (bool) – includes items shared from external tenants

Returns:

items in this folder

Return type:

generator of DriveItem or Pagination

get_special_folder(name)

Returns the specified Special Folder

Returns:

a special Folder

Return type:

drive.Folder

refresh()

Updates this drive with data from the server

Returns:

Success / Failure

Return type:

bool

search(search_text, limit=None, *, query=None, order_by=None, batch=None)

Search for DriveItems under this drive. Your app can search more broadly to include items shared with the current user.

To broaden the search scope, use this search instead the Folder Search.

The search API uses a search service under the covers, which requires indexing of content.

As a result, there will be some time between creation of an item and when it will appear in search results.

Parameters:

• search_text (str) – The query text used to search for items. Values may be matched across several fields including filename, metadata, and file content.

• limit (int) – max no. of items to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

items in this folder matching search

Return type:

generator of DriveItem or Pagination

parent

The parent of the Drive.

   Type: Drive

class O365.drive.DriveItem(*, parent=None, con=None, **kwargs)

Bases: ApiComponent

A DriveItem representation. Groups all functionality

__init__(*, parent=None, con=None, **kwargs)

Create a DriveItem

Parameters:

• parent (Drive or drive.Folder) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

copy(target=None, name=None)

Asynchronously creates a copy of this DriveItem and all it’s child elements.

Parameters:

• target (drive.Folder or Drive) – target location to move to. If it’s a drive the item will be moved to the root folder. If it’s None, the target is the parent of the item being copied i.e. item will be copied into the same location.

• name – a new name for the copy.

Return type:

CopyOperation

delete()

Moves this item to the Recycle Bin

Returns:

Success / Failure

Return type:

bool

get_drive()

Returns this item drive :return: Drive of this item :rtype: Drive or None

get_parent()

the parent of this DriveItem

Returns:

Parent of this item

Return type:

Drive or drive.Folder

get_permissions()

Returns a list of DriveItemPermissions with the permissions granted for this DriveItem.

Returns:

List of Permissions

Return type:

list[DriveItemPermission]

get_thumbnails(size=None)

Returns this Item Thumbnails. Thumbnails are not supported on SharePoint Server 2016.

Parameters:

size – request only the specified size: ej: “small”, Custom 300x400 px: “c300x400”, Crop: “c300x400_Crop”

Returns:

Thumbnail Data

Return type:

dict

get_version(version_id)

Returns a version for specified id

Returns:

a version object of specified id

Return type:

DriveItemVersion

get_versions()

Returns a list of available versions for this item

Returns:

list of versions

Return type:

list[DriveItemVersion]

move(target)

Moves this DriveItem to another Folder. Can’t move between different Drives.

Parameters:

target (drive.Folder or DriveItem or str) – a Folder, Drive item or Item Id string. If it’s a drive the item will be moved to the root folder.

Returns:

Success / Failure

Return type:

bool

share_with_invite(recipients, require_sign_in=True, send_email=True, message=None, share_type='view')

Sends an invitation to access or edit this DriveItem

Parameters:

• recipients (list[str] or list[Contact] or str or Contact) – a string or Contact or a list of the former representing recipients of this invitation

• require_sign_in (bool) – if True the recipients invited will need to log in to view the contents

• send_email (bool) – if True an email will be send to the recipients

• message (str) – the body text of the message emailed

• share_type (str) – ‘view’: will allow to read the contents. ‘edit’ will allow to modify the contents

Returns:

link to share

Return type:

DriveItemPermission

share_with_link(share_type='view', share_scope='anonymous', share_password=None, share_expiration_date=None)

Creates or returns a link you can share with others

Parameters:

• share_type (str) – ‘view’ to allow only view access, ‘edit’ to allow editions, and ‘embed’ to allow the DriveItem to be embedded

• share_scope (str) – ‘anonymous’: anyone with the link can access. ‘organization’ Only organization members can access

• share_password (str) – sharing link password that is set by the creator. Optional.

• share_expiration_date (str) – format of yyyy-MM-dd (e.g., 2022-02-14) that indicates the expiration date of the permission. Optional.

Returns:

link to share

Return type:

DriveItemPermission

update(**kwargs)

Updates this item

Parameters:

kwargs – all the properties to be updated. only name and description are allowed at the moment.

Returns:

Success / Failure

Return type:

bool

created

Date and time of item creation.

   Type: datetime

created_by

Identity of the user, device, and application which created the item.

   Type: Contact

description

Provides a user-visible description of the item.

   Type: str

drive

The drive

   Type: Drive

drive_id

Identifier of the drive instance that contains the item.

   Type: str

property is_file

Returns if this DriveItem is a File

property is_folder

Returns if this DriveItem is a Folder

property is_image

Returns if this DriveItem is a Image

property is_photo

Returns if this DriveItem is a Photo

modified

Date and time the item was last modified.

   Type: datetime

modified_by

Identity of the user, device, and application which last modified the item

   Type: Contact

name

The name of the item (filename and extension).

   Type: str

object_id

The unique identifier of the item within the Drive.

   Type: str

parent_id

The id of the parent.

   Type: str

parent_path

Path that can be used to navigate to the item.

   Type: str

remote_item

Remote item data, if the item is shared from a drive other than the one being accessed.

   Type: remoteItem

shared

Indicates that the item has been shared with others and provides information about the shared state of the item.

   Type: str

size

Size of the item in bytes.

   Type: int

thumbnails

The thumbnails.

   Type: any

web_url

URL that displays the resource in the browser.

   Type: str

class O365.drive.DriveItemPermission(*, parent=None, con=None, **kwargs)

Bases: ApiComponent

A Permission representation for a DriveItem

__init__(*, parent=None, con=None, **kwargs)

Permissions for DriveItem

Parameters:

• parent (DriveItem) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

delete()

Deletes this permission. Only permissions that are not inherited can be deleted.

Returns:

Success / Failure

Return type:

bool

update_roles(roles='view')

Updates the roles of this permission

Returns:

Success / Failure

Return type:

bool

driveitem_id

The unique identifier of the item within the Drive.

   Type: str

granted_to

For user type permissions, the details of the users and applications for this permission.

   Type: IdentitySet

inherited_from

Provides a reference to the ancestor of the current permission, if it’s inherited from an ancestor.

   Type: ItemReference

invited_by

The invited by user.

   Type: str

object_id

The unique identifier of the permission among all permissions on the item.

   Type: str

permission_type

The permission type.

   Type: str

require_sign_in

Is sign in required.

   Type: bool

roles

The type of permission, for example, read.

   Type: list[str]

share_email

The share email.

   Type: str

share_id

A unique token that can be used to access this shared item via the shares API

   Type: str

share_link

The share link.

   Type: str

share_scope

The share scope.

   Type: str

share_type

The share type.

   Type: str

class O365.drive.DriveItemVersion(*, parent=None, con=None, **kwargs)

Bases: ApiComponent, DownloadableMixin

A version of a DriveItem

__init__(*, parent=None, con=None, **kwargs)

Version of DriveItem

Parameters:

• parent (DriveItem) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

download(to_path: None | str | Path = None, name: str = None, chunk_size: str | int = 'auto', convert_to_pdf: bool = False, output: BytesIO | None = None)

Downloads this version. You can not download the current version (last one).

Returns:

Success / Failure

Return type:

bool

restore()

Restores this DriveItem Version. You can not restore the current version (last one).

Returns:

Success / Failure

Return type:

bool

driveitem_id

The unique identifier of the item within the Drive.

   Type: str

modified

Date and time the version was last modified.

   Type: datetime

modified_by

Identity of the user which last modified the version.

   Type: Contact

name

The name (ID) of the version.

   Type: str

object_id

The ID of the version.

   Type: str

size

Indicates the size of the content stream for this version of the item.

   Type: int

class O365.drive.File(**kwargs)

Bases: DriveItem, DownloadableMixin

A File

__init__(**kwargs)

Create a DriveItem

Parameters:

• parent (Drive or drive.Folder) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

property extension

The suffix of the file name.

Getter:

get the suffix

Type:

str

hashes

Hashes of the file’s binary content, if available.

   Type: Hashes

mime_type

The MIME type for the file.

   Type: str

class O365.drive.Folder(*args, **kwargs)

Bases: DriveItem

A Folder inside a Drive

__init__(*args, **kwargs)

Create a DriveItem

Parameters:

• parent (Drive or drive.Folder) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

create_child_folder(name, description=None)

Creates a Child Folder

Parameters:

• name (str) – the name of the new child folder

• description (str) – the description of the new child folder

Returns:

newly created folder

Return type:

drive.Folder

download_contents(to_folder=None)

This will download each file and folder sequentially. Caution when downloading big folder structures :param drive.Folder to_folder: folder where to store the contents

get_child_folders(limit=None, *, query=None, order_by=None, batch=None)

Returns all the folders inside this folder

Parameters:

• limit (int) – max no. of folders to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

folder items in this folder

Return type:

generator of DriveItem or Pagination

get_items(limit=None, *, query=None, order_by=None, batch=None)

Returns generator all the items inside this folder

Parameters:

• limit (int) – max no. of folders to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

items in this folder

Return type:

generator of DriveItem or Pagination

search(search_text, limit=None, *, query=None, order_by=None, batch=None)

Search for DriveItems under this folder The search API uses a search service under the covers, which requires indexing of content.

As a result, there will be some time between creation of an item and when it will appear in search results.

Parameters:

• search_text (str) – The query text used to search for items. Values may be matched across several fields including filename, metadata, and file content.

• limit (int) – max no. of folders to get. Over 999 uses batch.

• query (Query or str) – applies a OData filter to the request

• order_by (Query or str) – orders the result set based on this condition

• batch (int) – batch size, retrieves items in batches allowing to retrieve more items than the limit.

Returns:

items in this folder matching search

Return type:

generator of DriveItem or Pagination

upload_file(item, item_name=None, chunk_size=5242880, upload_in_chunks=False, stream=None, stream_size=None, conflict_handling=None, file_created_date_time: str = None, file_last_modified_date_time: str = None)

Uploads a file

Parameters:

• item (str or Path) – path to the item you want to upload

• item_name (str or Path) – name of the item on the server. None to use original name

• chunk_size – Only applies if file is bigger than 4MB or upload_in_chunks is True. Chunk size for uploads. Must be a multiple of 327.680 bytes

• upload_in_chunks – force the method to upload the file in chunks

• stream (io.BufferedIOBase) – (optional) an opened io object to read into. if set, the to_path and name will be ignored

• stream_size (int) – size of stream, required if using stream

• conflict_handling (str) – How to handle conflicts. NOTE: works for chunk upload only (>4MB or upload_in_chunks is True) None to use default (overwrite). Options: fail | replace | rename

• file_created_date_time – allow to force file created date time while uploading

• file_last_modified_date_time – allow to force file last modified date time while uploading

Returns:

uploaded file

Return type:

DriveItem

child_count

Number of children contained immediately within this container.

   Type: int

special_folder

The unique identifier for this item in the /drive/special collection.

   Type: str

class O365.drive.Image(**kwargs)

Bases: File

An Image

__init__(**kwargs)

Create a DriveItem

Parameters:

• parent (Drive or drive.Folder) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

property dimensions

Dimension of the Image

Returns:

width x height

Return type:

str

height

Height of the image, in pixels.

   Type: int

width

Width of the image, in pixels.

   Type: int

class O365.drive.Photo(**kwargs)

Bases: Image

Photo Object. Inherits from Image but has more attributes

__init__(**kwargs)

Create a DriveItem

Parameters:

• parent (Drive or drive.Folder) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

camera_make

Camera manufacturer.

   Type: str

camera_model

Camera model.

   Type: str

exposure_denominator

The denominator for the exposure time fraction from the camera.

   Type: float

exposure_numerator

The numerator for the exposure time fraction from the camera.

   Type: float

fnumber

The F-stop value from the camera

   Type: float

focal_length

The focal length from the camera.

   Type: float

iso

The ISO value from the camera.

   Type: int

taken_datetime

Represents the date and time the photo was taken.

   Type: datetime

class O365.drive.Storage(*, parent=None, con=None, **kwargs)

Bases: ApiComponent

Parent Class that holds drives

__init__(*, parent=None, con=None, **kwargs)

Create a storage representation

Parameters:

• parent (Account) – parent for this operation

• con (Connection) – connection to use if no parent specified

• protocol (Protocol) – protocol to use if no parent specified (kwargs)

• main_resource (str) – use this resource instead of parent resource (kwargs)

get_default_drive(request_drive=False)

Returns a Drive instance

Parameters:

request_drive – True will make an api call to retrieve the drive data

Returns:

default One Drive

Return type:

Drive

get_drive(drive_id)

Returns a Drive instance

Parameters:

drive_id – the drive_id to be retrieved

Returns:

Drive for the id

Return type:

Drive

get_drives()

Returns a collection of drives