google_api_tools

google_api_tools.authenticate_service_account(service_account_path)

Load Google Drive service-account credentials from a JSON key file.

Parameters:

Name	Type	Description	Default
service_account_path		Path to the service-account credential JSON file.	required

Returns:

Type	Description
Credentials	Credentials authorized for Google Drive operations.

google_api_tools.check_authentication(creds)

Print the email address associated with Google Drive credentials.

Parameters:

Name	Type	Description	Default
creds		Google authentication credentials to verify.	required

google_api_tools.generate_personal_google_account_token(token_path, credentials_path)

Create or reuse an OAuth token for a local personal Google account.

Parameters:

Name	Type	Description	Default
token_path		Destination of the cached authorized-user token.	required
credentials_path		Path to the OAuth client-secret JSON file.	required

Returns:

Type	Description
Credentials	Valid Google OAuth credentials for Drive access.

google_api_tools.authenticate_user_oauth(token, scopes=SCOPES)

Authenticate using OAuth as a real Google user.

Parameters:

Name	Type	Description	Default
token		Path to token.json or the equivalent JSON object. The token must include a refresh_token.	required
scopes		OAuth scopes to request. Defaults to SCOPES.	SCOPES

Returns:

Type	Description
Credentials	Valid user credentials, refreshed in place when the access token had expired.

Raises:

Type	Description
ValueError	If scopes is None, or if token is neither a path nor a dict.
Exception	If the token cannot be loaded, or if it is invalid and carries no refresh_token. Databricks cannot run the interactive consent flow, so the token must be created locally and stored as a secret.

google_api_tools.authenticate_with_saved_token(token_path)

Authenticate using a pre-generated token.json file.

Parameters:

Name	Type	Description	Default
token_path		Local path to an authorized-user token file.	required

Returns:

Type	Description
Credentials or None	Credentials loaded from the file, or None when the file is missing. The token is not refreshed; use :func:authenticate_with_refresh_token for that.

google_api_tools.authenticate_with_refresh_token(token_path)

Load credentials and refresh the access token when it has expired.

Parameters:

Name	Type	Description	Default
token_path		Local path to an authorized-user token file. Rewritten in place when the token is refreshed.	required

Returns:

Type	Description
Credentials or None	Valid credentials, or None when the file is missing.

google_api_tools.upload_to_gdrive(creds, file_path, file_name, parent_folder_id=None)

Upload a file to Google Drive.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
file_path		Local path to the file to upload.	required
file_name		Name for the file on Google Drive.	required
parent_folder_id		(Optional) ID of the Google Drive folder to upload the file to.	None

Returns:

Type	Description
	The file ID of the uploaded file.

google_api_tools.download_from_gdrive(creds, file_id, save_path, shared_drive_id=None, return_extension=False)

Downloads a file from Google Drive, including Shared Drives. Exports Google Docs files to compatible formats.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
file_id		The Google Drive file ID.	required
save_path		Local path to save the downloaded file.	required
shared_drive_id		(Optional) The ID of the Shared Drive.	None
return_extension		(Optional) If True, return the file extension chosen for the download instead of None. Defaults to False.	False

Returns:

Type	Description
	str | None: The file extension when return_extension is True, or None otherwise. Google Docs files are exported to a compatible format, so the extension may differ from the original file name.

google_api_tools.push_s3_to_drive(creds, s3_filepath, drive_folder_id)

Copy a file from S3 into a Google Drive folder.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
s3_filepath		Source S3 path. The Drive file keeps the S3 object's file name.	required
drive_folder_id		Target Drive folder ID. The authenticated account must have write access to it.	required

Returns:

Type	Description
None	The file is uploaded rather than returned.

Notes

Stages the file through the driver's local working directory and removes the temporary copy afterwards, so it is unsuitable for files larger than local disk.

google_api_tools.list_files_in_folder(creds, folder_id, trashed=False)

Lists all files in a specified Google Drive folder.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
folder_id		The Google Drive folder ID.	required
trashed		Whether to list trashed files instead of active ones. Defaults to False.	False

Returns:

Type	Description
	A list of file names and IDs.

google_api_tools.search_file(creds)

List every file visible in the authenticated account's Drive.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required

Returns:

Type	Description
list of dict	One entry per file with its id, name, and parents. Empty if the listing fails.

Notes

Issues an unfiltered query and pages through every result, so this can be slow on a large Drive. Shared Drives are not included; use :func:list_items_in_shared_drive for those.

google_api_tools.list_items_in_shared_drive(creds, shared_drive_id, parent_id, verbose=False)

Lists all files in a specific Google Shared Drive.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
shared_drive_id		The Google Shared Drive ID.	required
parent_id		ID of the folder within the Shared Drive whose direct children are listed.	required
verbose		Whether to print the discovered files. Defaults to False.	False

Returns:

Type	Description
	A list of file names and IDs. Trashed items are excluded.

google_api_tools.get_file_details(creds, file_id, return_dict=True)

Retrieves file metadata including the owner and last modified user.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
file_id		The Google Drive file ID.	required
return_dict		If True, return the metadata dictionary. If False, the details are only printed. Defaults to True.	True

Returns:

Type	Description
	A dictionary containing file details, or None when return_dict is
	False or the lookup fails.

google_api_tools.__find_files_in_drive__(creds, shared_drive_id, root_folder_id, case_id_pattern='\\d{4}Q\\d_[A-Za-z0-9]+_[A-Za-z0-9]+_\\dWAY_[A-Z]{2}', file_pattern='RespomondoIds.csv')

Find survey-sent and response files for BL cases in a Shared Drive.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
shared_drive_id		Shared Drive identifier to search.	required
root_folder_id		Folder to start the breadth-first traversal from.	required
case_id_pattern		Regular expression a folder name must fully match to be treated as a case folder.	'\\d{4}Q\\d_[A-Za-z0-9]+_[A-Za-z0-9]+_\\dWAY_[A-Z]{2}'
file_pattern		Regular expression a file name must fully match to be collected.	'RespomondoIds.csv'

Returns:

Type	Description
dict	Mapping of matching case-folder name to the matched files found beneath it. Files outside any case folder are ignored.

Notes

Superseded by :func:find_files_in_drive, which also returns each file's path relative to root_folder_id. Issues one Drive listing call per visited folder.

google_api_tools.find_files_in_drive(creds, shared_drive_id, root_folder_id, case_id_pattern='\\d{4}Q\\d_[A-Za-z0-9]+_[A-Za-z0-9]+_\\dWAY_[A-Z]{2}', file_pattern='')

Find files below matching case folders in a shared Google Drive.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
shared_drive_id		Shared Drive identifier to search.	required
root_folder_id		Folder to start the depth-first traversal from.	required
case_id_pattern		Regular expression a folder name must fully match to be treated as a case folder.	'\\d{4}Q\\d_[A-Za-z0-9]+_[A-Za-z0-9]+_\\dWAY_[A-Z]{2}'
file_pattern		Regular expression a file name must fully match to be collected. The default empty pattern matches only empty names, so callers normally pass an explicit pattern.	''

Returns:

Type	Description
dict	Mapping of matching case-folder name to a list of (file_id, file_name, path_parts) tuples, where path_parts is the path relative to root_folder_id. Files outside any case folder are ignored.

Notes

Issues one Drive listing call per visited folder, so traversal cost grows with the folder count rather than the file count.

google_api_tools.find_folder_id(creds, shared_drive_id, root_folder_id, folder_name)

Return the identifier of a direct child folder, if it exists.

Parameters:

Name	Type	Description	Default
creds		Google authentication credentials.	required
shared_drive_id		Shared Drive identifier.	required
root_folder_id		Identifier of the folder to search.	required
folder_name		Exact child-folder name to locate.	required

Returns:

Type	Description
str or None	Matching folder identifier, or None when absent.

google_api_tools.move_file(creds, file_id, old_parent_id, new_parent_id)

Move a Google Drive file by updating its parents.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object. Requires a Drive scope that allows modification, such as drive or drive.file.	required
file_id	str	Google Drive ID of the file to move.	required
old_parent_id	str	Parent folder ID to detach the file from.	required
new_parent_id	str	Parent folder ID to attach the file to.	required

Returns:

Type	Description
dict	Drive API response containing the file's id, name, and updated parents.

google_api_tools.rename_item(creds, item_id, new_name, supports_all_drives=False)

Rename a Google Drive file or folder via files.update.

Parameters:

Name	Type	Description	Default
creds		Authenticated credentials object.	required
item_id	str	Google Drive ID of the file or folder to rename.	required
new_name	str	Replacement name.	required
supports_all_drives	bool	Set to True for items in a Shared Drive; the Drive API rejects the update otherwise.	False

Returns:

Type	Description
dict	Drive API response containing the item's id and new name.

google_api_tools.create_folder(creds, folder_name, parent_id)

Create a Google Drive folder within a parent folder.

Parameters:

Name	Type	Description	Default
creds		Authenticated Google credentials.	required
folder_name	str	Name of the folder to create.	required
parent_id	str	Google Drive ID of the parent folder.	required

Returns:

Type	Description
dict	Metadata containing the created folder's ID, name, and parents.

google_api_tools.delete_item(creds, item_id, permanent=False)

Permanently delete a Google Drive file or folder.

Parameters:

Name	Type	Description	Default
creds		Authenticated Google credentials.	required
item_id	str	Google Drive ID of the file or folder to delete.	required
permanent	bool	Boolean for permanent deletion or trashing.	False

Returns:

Type	Description
dict	Empty response returned by the Google Drive API.

Raises:

Type	Description
PermissionError	If the authenticated user lacks the capability for the requested action. Permanent deletion of Shared Drive content typically requires Manager-level permission on the parent folder.