Microsoft SharePoint

SharePointClient

Bases: BaseOAuthClient

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.

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.

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.