Clients

Classes for interacting with other services.

AutodeskClient

A class for interacting with Autodesk Platform Services APIs:

• Data Management API
• BIM 360 API
• Autodesk Construction Cloud API

Handles differences in API conventions and schema, building on top of the Autodesk API to provide specialist methods for data translation / exchange use cases.

https://aps.autodesk.com/developer/documentation

Attributes:

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

__init__

__init__(user_id, access_token=None, client_id=os.getenv('AUTODESK_CLIENT_ID'))

Initialize the client.

Parameters:

Name	Type	Description	Default
user_id	str	Unique ID for the user. Used to obtain three-legged access token. .	required
access_token	str | None	Optionally pass an OAuth access token directly to the constructor.	None
client_id	str | None	Three-legged OAuth token for calling Autodesk APIs.	getenv('AUTODESK_CLIENT_ID')

build_tree

build_tree()

Constructs a hierarchical tree structure of hubs and their associated projects.

This method fetches all accessible hubs from the Autodesk Forge API and then retrieves all projects within each hub, organizing them into a nested tree structure suitable for display in UI components like tree views or dropdowns.

The tree structure follows a hub -> project hierarchy where each hub contains multiple projects as children nodes.

Returns:

Type

Description

list[dict[str, Any]]

A list of dictionaries representing the tree structure. Each hub dictionary contains: 'id' (str): The hub's unique identifier 'label' (str): The hub's display name 'type' (str): Always 'hub' for hub entries 'children' (list): List of project dictionaries, each containing: 'id' (str): The project's unique identifier 'label' (str): The project's display name 'type' (str): Always 'project' for project entries 'children' (list): Empty list (reserved for future expansion)

build_tree_project

build_tree_project(hub_id, project_id)

Constructs a hierarchical tree structure of folders and items within a specific project.

This method fetches the top-level contents of a project and recursively builds a complete tree structure that includes all nested folders and their contents. The resulting tree is suitable for displaying the project's file/folder hierarchy in UI components.

Parameters:

Name	Type	Description	Default
hub_id	str	The unique identifier of the hub containing the project	required
project_id	str	The unique identifier of the project to build the tree for	required

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionaries representing the project's folder tree structure. Each folder dictionary contains: 'id' (str): The folder's unique identifier 'label' (str): The folder's display name 'type' (str): Always 'folder' for folder entries 'children' (list): Nested list of subfolders and items within this folder

download_file_bytes

download_file_bytes(file_href)

Downloads a file from Autodesk Forge and returns its content as bytes.

This method handles the multi-step process required to download files from Autodesk Forge: 1. Fetches file metadata using the provided file reference URL 2. Extracts the storage download URL from the metadata 3. Cleans the URL by removing query parameters that may interfere with the download 4. Requests a signed S3 download URL from Autodesk's storage service 5. Downloads the actual file content using the signed URL

Parameters:

Name	Type	Description	Default
file_href	str	The file reference URL obtained from Autodesk Forge API, typically from item or version data	required

Returns:

Name	Type	Description
bytes	bytes	The raw file content as bytes

Raises:

Type	Description
Exception	If the download fails

exchange_refresh_token

exchange_refresh_token()

Retrieve the user's refresh token and exchange for a three-legged OAuth access token.

get_document_versions

get_document_versions(project_id, item_id)

Retrieve all versions for a specific document item.

This method fetches all available versions of a document item using the Autodesk Data Management API. Versions represent different iterations or revisions of the same document.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID in Data Management API format (no "b." prefix)	required
item_id	str	The unique identifier for the document item	required

Returns:

Type	Description
list[dict[str, Any]]	List of document versions

get_folder_contents

get_folder_contents(hub_id, project_id, folder_id=None)

Retrieve the contents of a folder in an Autodesk project, or get top-level folders if no folder ID is specified.

Parameters:

Name	Type	Description	Default
hub_id	str	The hub ID where the project is located	required
project_id	str	The project ID in Data Management API format (no "b." prefix)	required
folder_id	str | None	The folder ID to get contents for. If None, returns top-level folders for the project	None

Returns:

Type	Description
list[Any]	A list containing folder contents at the folder-level only (not nested folders)

get_folder_contents_recursive

get_folder_contents_recursive(hub_id, project_id, folder_id)

Recursively retrieve all contents of a folder and its subfolders in an Autodesk project.

Parameters:

Name	Type	Description	Default
hub_id	str	The hub ID where the project is located	required
project_id	str	The project ID in Data Management API format (no "b." prefix)	required
folder_id	str	The folder ID to recursively get contents for	required

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionaries representing the folder structure, where each item contains: id: The item ID project_id: The project ID hub_id: The hub ID name: The display name of the item label: The display name of the item (duplicate of name) type: The item type ('folders' or 'items') children: List of child items (only present for folders) Additional fields from the original item data

get_folder_named_attributes

get_folder_named_attributes(project_id, folder_id=None, hub_id=None)

Retrieves all custom attribute definitions for a folder within a specified project.

Custom attributes are user-defined metadata fields that can be attached to folders and items in BIM 360 / ACC.

Parameters:

Name	Type	Description	Default
project_id	str	The project identifier from the Data Management API (with "b." prefix, which will be automatically removed)	required
folder_id	str | None	The folder identifier from the Data Management API. If not provided function will retrieve the naming standard for the root project folder.	None
hub_id	str | None	The unique identifier of the hub containing the project. Must be provided if folder_id is not provided	None

Returns:

Type	Description
list[dict[str, Any]]	A list of dictionaries containing custom attribute definitions from the folders in the project. Each dictionary represents an attribute definition with properties like name, type, validation rules, etc.

get_folder_naming_standard

get_folder_naming_standard(hub_id, project_id, folder_id=None)

Retrieves the naming standard configuration from a BIM 360 / ACC project for the specified folder. Returns None if no naming standard is applied to the folder

Naming standards define rules and patterns for how files and folders should be named within a project to maintain consistency and organization.

Parameters:

Name	Type	Description	Default
hub_id	str	The unique identifier of the hub containing the project	required
project_id	str	The project identifier from the Data Management API (no "b." prefix).	required
folder_id	str | None	The folder identifier from the Data Management API. If not provided function will retrieve the naming standard for the root project folder	None

Returns:

Type	Description
dict[str, Any]	A dictionary containing the naming standard configuration data, including rules, patterns, and validation criteria defined for the standard

get_hubs

get_hubs()

Retrieves all hubs accessible to the authenticated user from the Autodesk Forge API.

Makes a GET request to the Autodesk Project API to fetch hub information. Hubs represent the highest level in the Autodesk data hierarchy and typically correspond to accounts or organizations that contain projects and folders.

Returns:

Type	Description
list[dict[str, Any]]	JSON response containing hub data from the API, including hub IDs, names, and other metadata. The exact structure depends on the Autodesk API response format.

get_naming_standard

get_naming_standard(project_id, naming_standard_id)

Retrieves a specific naming standard configuration from a BIM 360 / ACC project.

This method fetches the details of a naming standard by its ID from the specified project using the BIM 360 Docs API. Naming standards define rules and patterns for how files and folders should be named within a project to maintain consistency and organization.

Parameters:

Name	Type	Description	Default
project_id	str	The project identifier from the Data Management API (with "b." prefix, which will be automatically removed)	required
naming_standard_id	str	The unique identifier of the naming standard to retrieve	required

Returns:

Type	Description
dict[str, Any]	A dictionary containing the naming standard configuration data, including rules, patterns, and validation criteria defined for the standard

get_projects

get_projects(hub_id)

Retrieves all projects within a specified hub from the Autodesk Forge API.

Makes a GET request to the Autodesk Project API to fetch project information for a given hub. Projects are containers within hubs that hold folders, items, and other project-related data.

Parameters:

Name	Type	Description	Default
hub_id	str	The unique identifier of the hub to retrieve projects from. This should be obtained from a previous call to get_hubs().	required

Returns:

Type	Description
list[dict[str, Any]]	JSON response containing project data from the API, including project IDs, names, and other metadata. The exact structure depends on the Autodesk API response format.

get_signed_url

get_signed_url(file_href, minutes=60)

Fetches a signed URL for downloading a file from an AWS S3 bucket.

This function retrieves file details using the provided file reference URL (file_href) and an access token for authorization. It then constructs a signed URL for the file by stripping unnecessary query parameters, appending a specific download endpoint, and extracting the signed URL from the download response.

Parameters:

Name	Type	Description	Default
file_href	str	The URL pointing to the file reference details in the storage system	required
minutes	int	Time duration for validity of URL. Maximum 60 minutes.	60

Returns:

Type	Description
str	The signed URL for downloading the file.

patch_version_attributes

patch_version_attributes(project_id, version_id, attributes)

Update attributes for a document version using the Data Management API.

This method updates version-level attributes for a specific document version using the Autodesk Data Management API's PATCH endpoint.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID in Data Management API format (no "b." prefix)	required
version_id	str	The unique identifier for the document version.	required
attributes	dict[str, Any]	Dict of attribute objects to update.	required

Returns:

Type	Description
dict[str, Any]	A dictionary containing the updated document version

post_version_custom_attributes

post_version_custom_attributes(project_id, version_id, attributes)

Update custom attributes for a document version in BIM 360.

This method performs a batch update of custom attributes for a specific document version using the BIM 360 Docs API. It converts the Data Management API project ID format to the BIM 360 API format by removing the "b." prefix.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID from either Data Management API or BIM 360 API. "b." prefix will be removed	required
version_id	str	The unique identifier for the document version	required
attributes	list[dict[str, Any]]	List of custom attribute objects to update. Each dictionary should contain attribute data	required

Returns:

Type	Description
dict[str, Any]	A dictionary containing the updated custom attributes for the document

upload_file_bytes

upload_file_bytes(project_id, folder_id, file_name, file_bytes)

Upload file byte content to an Autodesk project folder. If a file with file_name already exists then will append file_bytes as a new item version.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID in Data Management API format (no "b." prefix)	required
folder_id	str	The folder ID	required
file_name	str	The name of the file	required
file_bytes	bytes	Contents of the file	required

Returns:

Type

Description

dict[str, Any]

A dictionary containing upload information with the following keys: object_id: The storage object ID bucket: The bucket key object_key: The object key upload_status: Status of the upload (should be 'success') action: Type of action performed ('new file' or 'new version') version_id: The ID of the created version version_number: The version number assigned existing_item_id: The item ID if file already existed, None otherwise

Raises:

Type	Description
Exception	If folder information cannot be retrieved
Exception	If storage location creation fails
Exception	If signed URL generation fails
Exception	If file upload to signed URL fails
Exception	If upload validation fails
Exception	If version/item creation fails

AzureBlobStorageClient

Wrapper around the Azure BlobServiceClient that implements additional specialist methods.

https://learn.microsoft.com/en-us/python/api/overview/azure/storage-blob-readme?view=azure-python

Attributes:

Name	Type	Description
organization	str	Organization containing the workspace session to connect to. Must match an Azure Blob Storage container name.
workspace	str	The workspace containing the session.
session_id	str	The id of the session.
directory	str	Default directory where new blobs will be created. Concatenation of workspace and session_id.
connection_string	str	Credential for connecting to the Azure Blob Storage resource.
url_prefix	str	The root URL to the Azure Blob Storage resource.
client	BlobServiceClient	Blob service client. Use to access all sub methods.

__init__

__init__(organization, workspace, session_id, connection_string=os.environ['BLOB_CONNECTION_STRING'], url_prefix=os.environ['BLOB_URL_PREFIX'])

Initialize client.

Parameters:

Name	Type	Description	Default
organization	str	Organization containing the workspace session to connect to. Must match an Azure Blob Storage container name.	required
workspace	str	The workspace containing the session. Must match a folder in the parent container.	required
session_id	str	The id of the session. Must match a folder in the parent workspace folder in the organization container.	required
connection_string	str	Credential for connecting to the Azure Blob Storage resource. Defaults to environment variable BLOB_CONNECTION_STRING.	environ['BLOB_CONNECTION_STRING']
url_prefix	str	The root URL to the Azure Blob Storage resource. Defaults to environment variable BLOB_URL_PREFIX.	environ['BLOB_URL_PREFIX']

download_blob_json

download_blob_json(blob_name)

Used to download and access JSON files.

Parameters:

Name	Type	Description	Default
blob_name	str	The path to the blob in the container.	required

Returns:

Type	Description
Any	The JSON content of the blob, likely a list or dictionary.

get_blob_client

get_blob_client(blob_name)

Return a client for interacting with blob objects.

Parameters:

Name	Type	Description	Default
blob_name	str	Name of the blob.	required

Returns:

Type	Description
BlobClient	Blob client.

get_signed_url

get_signed_url(blob_name, minutes=720)

Generate a signed URL for an Azure Blob Storage object, valid for specified duration.

Parameters:

Name	Type	Description	Default
blob_name	str	Name of the blob.	required
minutes	int	Time duration for validity of URL.	720

Returns:

Type	Description
str	The signed URL.

list_blobs_in_directory

list_blobs_in_directory(ignore_files=None)

Lists all blobs in the client directory within an Azure Blob container.

Parameters:

Name	Type	Description	Default
ignore_files	list[str] | None	Blob names containing any string in this list will not be included in the outputted list.	None

Returns:

Type	Description
list[BlobProperties]	A list of blobs in the client directory.

list_blobs_with_prefix

list_blobs_with_prefix(prefix, ignore_files=None)

Lists all blobs in the Azure Blob container with the supplied prefix.

Parameters:

Name	Type	Description	Default
prefix	str	The prefix to search for	required
ignore_files	list[str] | None	Blob names containing any string in this list will not be included in the outputted list	None

Returns:

Type	Description
list[BlobProperties]	A list of blobs with the matching prefix.

upload_blob_json

upload_blob_json(blob_name, blob_content)

Used to upload JSON files to a blob in the container.

Parameters:

Name	Type	Description	Default
blob_name	str	The path to the blob in the container.	required
blob_content	str	The JSON-formatted content to be uploaded.	required

Returns:

Type	Description
dict[str, Any]	Blob updated property dictionary.

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.

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 label (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 label (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 label (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 label (str): Display name type (str): Always 'drive' children (List): A list of child items. See build_folder_tree()

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.

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_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_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.