Microsoft SharePoint

SharePointClient

Client for interacting with Microsoft Graph SharePoint API routes.

Attributes:

Name	Type	Description
user_id		Unique ID for the user tethered to the client. Used to scope delegated access.
client_id		Entra client ID. Defaults to environment variable ENTRA_CLIENT_ID.
access_token	str	Three-legged OAuth token for calling Graph APIs.

access_token property writable

access_token

Returns a valid signed URL, regenerating if necessary

Returns:

Type	Description
str	Signed URL

__init__

__init__(user_id, access_token=None, client_id=os.getenv('ENTRA_CLIENT_ID'), client_secret=os.getenv('ENTRA_CLIENT_SECRET'))

Initialize the client.

Parameters:

Name	Type	Description	Default
user_id	str	Unique ID for the user tethered to the client. Used to scope delegated access.	required
access_token	str | None	Three-legged OAuth token for calling Graph APIs.	None
client_id	str | None	Entra client ID. Defaults to environment variable ENTRA_CLIENT_ID.	getenv('ENTRA_CLIENT_ID')
client_secret	str | None	Entra client secret. Defaults to environment variable ENTRA_CLIENT_SECRET.	getenv('ENTRA_CLIENT_SECRET')

batch_get_download_urls

batch_get_download_urls(file_requests, max_workers=4)

Get multiple download URLs in parallel batch requests.

Parameters:

Name	Type	Description	Default
file_requests	list[dict[str, str]]	List of batch requests. Each request is a dictionary matching the schema in get_download_url()	required
max_workers	int	Number of parallel threads to split requests across.	4

Returns:

Type	Description
dict[str, str]	Key-value pairs of file_id and download_url.

batch_get_folder_contents

batch_get_folder_contents(items, max_workers=4)

Fetch children for many folders in as few Graph round-trips as possible.

Uses Microsoft Graph's $batch endpoint to bundle up to 20 sub-requests per HTTP call and dispatches chunks in parallel. Designed to back the bulk lazy-load endpoint on the Hoppa API, replacing thousands of sequential single-folder calls during tree expansion.

Parameters:

Name	Type	Description	Default
items	list[dict[str, Any]]	List of dicts. Each dict must contain site_id and drive_id. folder_id is optional; None or missing means "drive root".	required
max_workers	int	Maximum number of parallel $batch POSTs.	4

Returns:

Type	Description
list[dict[str, Any]]	List of dicts in the same length and order as items. Each output
list[dict[str, Any]]	dict contains: site_id, drive_id, folder_id: echoed from input children: shaped folder/file entries identical to build_folder_id_content's output (empty list on failure) error: None on success, or {"status": int, "message": str} on failure

build_folder_id_content

build_folder_id_content(site_id, drive_id, folder_id=None)

Retrieves folder contents (non-recursive) from folder_id with pagination using pooled connection.

https://learn.microsoft.com/en-us/graph/api/driveitem-list-children?view=graph-rest-1.0&tabs=http

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site	required
drive_id	str	ID of the drive in the site	required
folder_id	str | None	Folder ID, child item of drive with drive_id. If not provided then method will return the children of the drive.	None

Returns:

Type

Description

list[dict[str, Any]]

List of children. Each child item has the following fields: id (str): Unique Id of the drive item name (str): Display name for the drive item type (str): 'folder' or 'file' siteId (str): ID of the site the item belongs to driveId (str): ID of the parent drive children: Placeholder list of children, ready for lazy loading in a UI table or tree component Other attributes specific to the drive item type

build_folder_tree

build_folder_tree(site_id, drive_id, folder_path=None)

Recursively build folder tree.

Parameters:

Name	Type	Description	Default
site_id	str	ID of a SharePoint site	required
drive_id	str	ID of a SharePoint drive in the site	required
folder_path	str | None	Relative folder path from the drive root. If not provided then function will recurse from the drive root	None

Returns:

Type	Description
list[dict[str, Any]]	Dictionary fields are: id (str): ID of the drive item name (str): Display name for the item type (str): 'folder' or 'file' children (List): List of children. Adopts the same schema.

build_tree

build_tree()

Build tree of all sites

Returns:

Type	Description
list[dict[str, Any]]	Dictionary fields are: id (str): ID of the SharePoint site name (str): Display name type (str): Always 'site' children (List): An empty list, ready for lazy-loading when used in conjunction with `build_tree_site()

build_tree_site

build_tree_site(site_id)

Build tree for a specific site. Recurses through all drives and sub-folders to gather the full folder tree.

Parameters:

Name	Type	Description	Default
site_id	str	The ID of a SharePoint site	required

Returns:

Type	Description
list[dict[str, Any]]	Dictionary fields are: id (str): ID of the SharePoint drive name (str): Display name type (str): Always 'drive' children (List): A list of child items. See build_folder_tree()

create_list_column

create_list_column(site_id, list_id, column_definition)

Create a new column on a SharePoint list.

https://learn.microsoft.com/en-us/graph/api/list-post-columns?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required
column_definition	dict[str, Any]	Column body as returned by metadata_property_to_column_definition.	required

Returns:

Type	Description
dict[str, Any]	The created column resource (includes id).

create_url_generator

create_url_generator(site_id, drive_id, file_id)

Create a URL generator function that uses caching and connection pooling.

Returns:

Type	Description
Callable	Calling this function will regenerate the download URL for a file. Passing it to a DocumentVersion constructor will ensure the file content remains accessible if the initial download_url expires.

delete_list_column

delete_list_column(site_id, list_id, column_id)

Delete a column from a SharePoint list.

https://learn.microsoft.com/en-us/graph/api/columndefinition-delete?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required
column_id	str	ID of the column to delete.	required

Returns:

Type	Description
dict[str, Any]	Empty dict on success.

download_file

download_file(download_url, local_path, file_name)

Download file using pooled connection.

Parameters:

Name	Type	Description	Default
download_url	str	The direct download URL for the SharePoint file	required
local_path	str	The local directory path where the file should be saved	required
file_name	str	The name to use for the downloaded file	required

download_file_bytes

download_file_bytes(download_url)

Downloads a file and returns content as bytes using pooled connection.

Parameters:

Name	Type	Description	Default
download_url	str	The direct download URL for the file	required

Returns:

Type	Description
bytes	The file content as bytes

Raises:

Type	Description
RequestException	If the download fails

download_folder_content

download_folder_content(site_id, drive_id, folder_id, local_folder_path)

Recursively download folder contents to a local folder using pooled connection.

Parameters:

Name	Type	Description	Default
site_id	str	The ID of the SharePoint site containing the folder to download	required
drive_id	str	The ID of the SharePoint drive containing the folder to download	required
folder_id	str	The ID of the SharePoint folder to download	required
local_folder_path	str	The local path to download files to	required

get_download_url

get_download_url(site_id, drive_id, file_id)

Get the download URL for a file.

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site where the file is held	required
drive_id	str	ID of the drivr where the file is held	required
file_id	str	ID of the file	required

Returns:

Type	Description
str | None	Download URL if file is found, else None.

get_drive_item_fields

get_drive_item_fields(site_id, drive_id, item_id)

Get the field values for a drive item's list item.

https://learn.microsoft.com/en-us/graph/api/listitem-get?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
drive_id	str	ID of the drive.	required
item_id	str	ID of the drive item.	required

Returns:

Type	Description
dict[str, Any]	Field values dictionary.

get_drive_item_list_item

get_drive_item_list_item(site_id, drive_id, item_id)

Resolve a drive item to its underlying list item.

https://learn.microsoft.com/en-us/graph/api/listitem-get?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
drive_id	str	ID of the drive.	required
item_id	str	ID of the drive item.	required

Returns:

Type	Description
dict[str, Any]	List item resource (includes id and fields).

get_drive_list

get_drive_list(site_id, drive_id)

Get the list backing a document library drive.

Bridges from drive_id to list_id, which is needed for column and list-item operations.

https://learn.microsoft.com/en-us/graph/api/drive-get?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
drive_id	str	ID of the drive.	required

Returns:

Type	Description
dict[str, Any]	List resource associated with the drive.

get_drives

get_drives(site_id)

Get drives for a site using pooled connection.

https://learn.microsoft.com/en-us/graph/api/drive-list?view=graph-rest-1.0&tabs=http

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site	required

Returns:

Type	Description
dict[str, Any]	List of drives can be accessed at the dictionary's value key.

get_folder_content

get_folder_content(site_id, drive_id, folder_path=None)

Get folder contents (non-recursive) from folder_path using pooled connection.

https://learn.microsoft.com/en-us/graph/api/driveitem-list-children?view=graph-rest-1.0&tabs=http

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site	required
drive_id	str	ID of the drive in the site	required
folder_path	str | None	Folder path, relative to the drive root. If not provided then method will return the children of the drive.	None

Returns:

Type	Description
list[dict[str, Any]]	List of children. Each child item has the following fields: id (str): ID of the drive item name (str): Name of the drive item type (str): 'folder' or 'file' mimeType (str): Content type of the item. Set as 'None' for folder drive items.

get_folder_id

get_folder_id(folder_contents, folder_name)

Extract folder ID from folder contents

get_list

get_list(site_id, list_id)

Get a specific list in a SharePoint site.

https://learn.microsoft.com/en-us/graph/api/list-get?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required

Returns:

Type	Description
dict[str, Any]	List resource.

get_list_columns

get_list_columns(site_id, list_id)

Get all columns defined on a SharePoint list.

https://learn.microsoft.com/en-us/graph/api/list-list-columns?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required

Returns:

Type	Description
dict[str, Any]	Column definitions can be accessed at the dictionary's value key.

get_lists

get_lists(site_id)

Get all lists in a SharePoint site.

https://learn.microsoft.com/en-us/graph/api/list-list?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required

Returns:

Type	Description
dict[str, Any]	List of lists can be accessed at the dictionary's value key.

get_raw_response

get_raw_response(item_url, json=None, headers=None, method='GET')

General-purpose method for calling Microsoft Graph API using pooled connection.

Parameters:

Name	Type	Description	Default
item_url	str	URL to call	required
json	dict | None	Body content	None
headers	dict | None	HTTP request headers	None
method	str	HTTP method.	'GET'

Returns:

Type	Description
dict[str, Any]	JSON body, if present on the response

get_sites

get_sites()

Get all SharePoint sites using pooled connection.

https://learn.microsoft.com/en-us/graph/api/site-search?view=graph-rest-1.0&tabs=http

Returns:

Type	Description
dict[str, Any]	List of sites can be accessed at the dictionary's value key.

revoke

revoke()

Revoke the user's Microsoft/SharePoint connection.

Microsoft does not support programmatic token revocation for confidential clients. Removing the refresh token from KeyVault (done by the caller) effectively disconnects the user since the app can no longer obtain new access tokens.

Returns:

Type	Description
bool	True if a refresh token was found (caller should proceed
bool	with deletion), False if no token exists.

update_list_column

update_list_column(site_id, list_id, column_id, column_update)

Update an existing column on a SharePoint list.

https://learn.microsoft.com/en-us/graph/api/columndefinition-update?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required
column_id	str	ID of the column to update.	required
column_update	dict[str, Any]	Partial column body with fields to update.	required

Returns:

Type	Description
dict[str, Any]	The updated column resource.

update_list_item_fields

update_list_item_fields(site_id, list_id, item_id, fields)

Update field values on a list item.

https://learn.microsoft.com/en-us/graph/api/listitem-update?view=graph-rest-1.0

Parameters:

Name	Type	Description	Default
site_id	str	ID of the site.	required
list_id	str	ID of the list.	required
item_id	str	ID of the list item (not the drive item).	required
fields	dict[str, Any]	Dictionary of field internal names → values.	required

Returns:

Type	Description
dict[str, Any]	Updated fields dictionary.