Google Workspace Write APIs

The Google Workspace integration provides write access to Google Sheets, Docs, Slides, and Drive via the Google API v4/v1. All operations are authenticated through GoogleWorkspaceClient, which supports OAuth2, service accounts, and multi-account registry lookup.

Installation

pip install siege-utilities[analytics]

This installs google-api-python-client, google-auth-oauthlib, and google-auth-httplib2.

Authentication

All write operations require an authenticated GoogleWorkspaceClient.

Direct Authentication

You can also authenticate without 1Password:

Service account from a file:

client = GoogleWorkspaceClient.from_service_account(
    service_account_file="/path/to/service-account.json",
)

OAuth2 with explicit credentials:

client = GoogleWorkspaceClient.from_oauth(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    token_file="workspace_token.json",
)

From a GoogleAccount registry (see Multi-Account Management):

from siege_utilities.config import GoogleAccountRegistry

registry = GoogleAccountRegistry(config_path=Path("google_accounts.json"))
client = GoogleWorkspaceClient.from_registry(registry)

Google Sheets

Create spreadsheets, write and read data, manage tabs, and round-trip DataFrames.

from siege_utilities.analytics.google_sheets import (
    create_spreadsheet, write_values, read_values, append_rows,
    write_dataframe, read_dataframe, add_sheet,
    get_spreadsheet_metadata, copy_spreadsheet,
)

# Create a spreadsheet with named tabs
spreadsheet_id = create_spreadsheet(client, "Q1 Report", sheet_names=["Data", "Summary"])

# Write raw values
write_values(client, spreadsheet_id, "Data!A1", [
    ["Name", "Revenue", "Region"],
    ["Acme", 150000, "Northeast"],
    ["Beta", 230000, "Southeast"],
])

# Append rows after existing data
append_rows(client, spreadsheet_id, "Data", [["Gamma", 90000, "West"]])

# Write a pandas DataFrame
write_dataframe(client, spreadsheet_id, df, sheet_name="Summary")

# Read it back
df_round_trip = read_dataframe(client, spreadsheet_id, "Summary")

# Add a tab
add_sheet(client, spreadsheet_id, "Notes")

# Metadata and copy
meta = get_spreadsheet_metadata(client, spreadsheet_id)
copy_id = copy_spreadsheet(client, spreadsheet_id, "Q1 Report (Copy)")

Google Slides

Create presentations, add slides, and populate them with text boxes and images.

from siege_utilities.analytics.google_slides import (
    create_presentation, get_presentation, copy_presentation,
    add_blank_slide, create_textbox, insert_text, insert_image,
)

pres_id = create_presentation(client, "Quarterly Review")

# Get the default first slide
pres = get_presentation(client, pres_id)
title_slide = pres["slides"][0]["objectId"]

# Add content to it
create_textbox(client, pres_id, title_slide, "Q1 2026 Review",
               left=50, top=80, width=600, height=60)

# Add a new blank slide with content
slide_id = add_blank_slide(client, pres_id)
create_textbox(client, pres_id, slide_id, "Revenue grew 23% YoY",
               left=50, top=100, width=600, height=40)

# Copy the presentation
copy_id = copy_presentation(client, pres_id, "Quarterly Review (Draft)")

Google Docs

Create documents, insert structured content (paragraphs, tables, images), and perform find/replace operations.

from siege_utilities.analytics.google_docs import (
    create_document, get_document, copy_document,
    read_document_text, insert_paragraph, insert_text,
    insert_table, insert_image, replace_text,
)

doc_id = create_document(client, "Meeting Notes")

# Insert a heading
insert_paragraph(client, doc_id, "Action Items", index=1, heading="HEADING_1")

# Insert body text
doc = get_document(client, doc_id)
end = doc["body"]["content"][-1]["endIndex"] - 1
insert_paragraph(client, doc_id, "Review budget allocations by Friday.", index=end)

# Insert a table
doc = get_document(client, doc_id)
end = doc["body"]["content"][-1]["endIndex"] - 1
insert_table(client, doc_id, rows=3, cols=2, index=end)

# Template substitution
replace_text(client, doc_id, "{{DATE}}", "2026-03-09")

# Read full text back
text = read_document_text(client, doc_id)

# Copy
copy_id = copy_document(client, doc_id, "Meeting Notes (Archive)")

Drive Utilities

The GoogleWorkspaceClient includes Drive operations for files it creates:

# Copy any file (spreadsheet, doc, presentation)
new_id = client.copy_file(file_id, "New Title")

# Share with a user
client.share_file(file_id, "colleague@example.com", role="writer")

# Move to a folder
client.move_to_folder(file_id, folder_id)

Multi-Account Management

The GoogleAccount model and GoogleAccountRegistry support managing multiple Google accounts (OAuth and service account) per user.

from siege_utilities.config.models.google_account import (
    GoogleAccount, GoogleAccountType, GoogleAccountStatus,
)
from siege_utilities.config import GoogleAccountRegistry
from siege_utilities.config.models.person import Person

# Create accounts
oauth_acct = GoogleAccount(
    google_account_id="personal",
    email="user@example.com",
    display_name="Personal",
    account_type=GoogleAccountType.OAUTH,
    is_default=True,
    oauth_integration_name="google-workspace",
    token_file="~/.siege/tokens/token.json",
)

svc_acct = GoogleAccount(
    google_account_id="pipeline",
    email="svc@project.iam.gserviceaccount.com",
    display_name="Pipeline SA",
    account_type=GoogleAccountType.SERVICE_ACCOUNT,
    service_account_ref="op://Infra/google-sa/credential",
)

# Registry: register, persist, load
registry = GoogleAccountRegistry()
registry.register(oauth_acct)
registry.register(svc_acct)
registry.save(Path("google_accounts.json"))

# Build client from registry
client = GoogleWorkspaceClient.from_registry(registry)

# Person integration
person = Person(person_id="dheeraj", name="Dheeraj Chand")
person.add_google_account(oauth_acct)
default = person.get_default_google_account()

# Migrate from legacy OAuthIntegration
from siege_utilities.config.google_account_registry import migrate_single_account
migrated = migrate_single_account(legacy_oauth, email="user@example.com")

Notebook

See notebooks/18_Google_Workspace.ipynb for a full walkthrough using elect.info onboarding content written to live Google Drive files.

API Reference

Google Workspace base client for Docs, Sheets, and Slides write APIs.

Provides shared authentication and service-building logic reused by the Sheets, Slides, and Docs service modules.

Authentication follows the same patterns as GoogleAnalyticsConnector: - OAuth2 (interactive flow with token file) - Service Account (from 1Password or file) - Explicit Credentials object

Usage:

from siege_utilities.analytics.google_workspace import GoogleWorkspaceClient

# OAuth2 with token file client = GoogleWorkspaceClient.from_oauth(

client_id=”…”, client_secret=”…”, token_file=”token.json”,

)

# Service Account from 1Password client = GoogleWorkspaceClient.from_service_account()

# Get a specific API service sheets = client.sheets_service() docs = client.docs_service() slides = client.slides_service()

class siege_utilities.analytics.google_workspace.GoogleWorkspaceClient[source]

Bases: object

Authenticated client that builds Google API service objects.

Do not instantiate directly — use the from_oauth() or from_service_account() class methods.

__init__(credentials)[source]
classmethod from_oauth(client_id, client_secret, token_file=None, redirect_uri='urn:ietf:wg:oauth:2.0:oob', scopes=None)[source]

Authenticate via OAuth2 interactive flow.

If token_file exists and contains a valid/refreshable token, no browser interaction is needed.

Parameters:
Return type:

GoogleWorkspaceClient

classmethod from_1password(item_title='Google OAuth Client - siege_utilities', vault=None, account='TLTQ3ANAABGCNEK7KIAOTDNK2Q', token_file=None, scopes=None)[source]

Authenticate using credentials stored in a 1Password Document item.

Auto-detects whether the JSON document is an OAuth client secret (has "installed" or "web" key) or a service account key (has "type": "service_account"), and routes to the appropriate auth flow.

For OAuth: runs the installed-app flow (browser required on first use; cached token reused afterward).

For service account: authenticates server-to-server with no browser interaction.

Parameters:

  • item_title (str) – Title of the 1Password Document item.

  • vault (str | None) – 1Password vault name.

  • account (str | None) – 1Password account shorthand or UUID.

  • token_file (str | Path | None) – Path to cache the OAuth token (ignored for service accounts). Default: ~/.siege/tokens/workspace_token.json.

  • scopes (List[str] | None) – OAuth scopes (defaults to WORKSPACE_SCOPES).

Returns:

Authenticated GoogleWorkspaceClient.

Return type:

GoogleWorkspaceClient

classmethod from_service_account(service_account_data=None, service_account_file=None, scopes=None)[source]

Authenticate via service account credentials.

Provide service_account_data (dict) or service_account_file (path). If neither is given, attempts to fetch from 1Password via CredentialManager.get_google_service_account_from_1password().

Parameters:
Return type:

GoogleWorkspaceClient

classmethod from_credentials(credentials)[source]

Wrap an already-authenticated google.auth.credentials.Credentials.

Return type:

GoogleWorkspaceClient

classmethod from_account(account, person=None, scopes=None)[source]

Build a client from a GoogleAccount.

For OAuth accounts the method looks for a cached token_file first, then resolves oauth_integration_name from person to get client_id/client_secret for the OAuth flow.

For service accounts the method resolves service_account_ref via CredentialManager (1Password) or treats it as a file path.

Parameters:
Return type:

GoogleWorkspaceClient

classmethod from_registry(registry, google_account_id=None, person=None, scopes=None)[source]

Build a client from a registry’s default or specified account.

If google_account_id is given, looks it up directly; otherwise uses the registry’s default account.

Parameters:
Return type:

GoogleWorkspaceClient

sheets_service()[source]

Return the Google Sheets API v4 service object.

docs_service()[source]

Return the Google Docs API v1 service object.

slides_service()[source]

Return the Google Slides API v1 service object.

drive_service()[source]

Return the Google Drive API v3 service object.

property credentials
batch_update_spreadsheet(spreadsheet_id, requests)[source]

Execute a batch of Sheets API requests.

Parameters:

  • spreadsheet_id (str) – Target spreadsheet ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Sheets API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

batch_update_document(document_id, requests)[source]

Execute a batch of Docs API requests.

Parameters:

  • document_id (str) – Target document ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Docs API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

batch_update_presentation(presentation_id, requests)[source]

Execute a batch of Slides API requests.

Parameters:

  • presentation_id (str) – Target presentation ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Slides API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

static spreadsheet_url(spreadsheet_id)[source]

Return the live Google Sheets URL for a spreadsheet ID.

Parameters:

spreadsheet_id (str)

Return type:

str

static document_url(document_id)[source]

Return the live Google Docs URL for a document ID.

Parameters:

document_id (str)

Return type:

str

static presentation_url(presentation_id)[source]

Return the live Google Slides URL for a presentation ID.

Parameters:

presentation_id (str)

Return type:

str

static file_url(file_id, mime_type=None)[source]

Return the live Google Drive URL for a file ID.

If mime_type is provided, returns the appropriate editor URL. Otherwise returns the generic Drive file URL.

Parameters:

  • file_id (str)

  • mime_type (str | None)

Return type:

str

copy_file(file_id, title=None)[source]

Copy a Drive file (spreadsheet, doc, presentation) and return the new ID.

Parameters:

  • file_id (str) – The ID of the file to copy.

  • title (str | None) – Optional title for the copy. None keeps the default “Copy of …” naming.

Returns:

The new file’s ID.

Return type:

str

share_file(file_id, email, role='writer', send_notification=False)[source]

Share a Drive file with a user.

Parameters:

  • file_id (str) – The file to share.

  • email (str) – Email address of the recipient.

  • role (str) – "reader", "writer", or "commenter".

  • send_notification (bool) – Whether to send an email notification.

Returns:

The permission resource dict.

Return type:

Dict[str, Any]

move_to_folder(file_id, folder_id)[source]

Move a file into a Drive folder.

Parameters:

  • file_id (str) – The file to move.

  • folder_id (str) – Target folder ID.

Returns:

The updated file resource dict.

Return type:

Dict[str, Any]

Google Sheets write service.

Provides functions for creating spreadsheets, writing data, managing tabs (sheets), and performing batch updates via the Sheets API v4.

All functions accept a GoogleWorkspaceClient for authentication.

Usage:

from siege_utilities.analytics.google_workspace import GoogleWorkspaceClient from siege_utilities.analytics.google_sheets import (

create_spreadsheet, write_dataframe, append_rows,

)

client = GoogleWorkspaceClient.from_service_account() spreadsheet_id = create_spreadsheet(client, “Q1 Report”) write_dataframe(client, spreadsheet_id, df)

siege_utilities.analytics.google_sheets.add_sheet(client, spreadsheet_id, title)[source]

Add a new tab/sheet to an existing spreadsheet.

Returns:

The new sheet ID (integer).

Parameters:

  • spreadsheet_id (str)

  • title (str)

Return type:

int

siege_utilities.analytics.google_sheets.append_rows(client, spreadsheet_id, range_, values, value_input_option='USER_ENTERED')[source]

Append rows after existing data in a range.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Target spreadsheet ID.

  • range – A1 notation range to search for a table (e.g. "Sheet1").

  • values (List[List[Any]]) – Row-major list of lists to append.

  • value_input_option (str) – "RAW" or "USER_ENTERED" (default).

  • range_ (str)

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_sheets.batch_update(client, spreadsheet_id, requests)[source]

Execute a batch of Sheets API requests.

Delegates to GoogleWorkspaceClient.batch_update_spreadsheet().

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Target spreadsheet ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Sheets API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_sheets.copy_spreadsheet(client, spreadsheet_id, title=None)[source]

Copy an entire spreadsheet via the Drive API.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Source spreadsheet ID.

  • title (str | None) – Title for the copy (default: “Copy of …”).

Returns:

The new spreadsheet ID.

Return type:

str

siege_utilities.analytics.google_sheets.create_spreadsheet(client, title, sheet_names=None, folder_id=None)[source]

Create a new Google Spreadsheet and return its ID.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • title (str) – Title for the new spreadsheet.

  • sheet_names (List[str] | None) – Optional list of sheet/tab names to create. If omitted, a single default “Sheet1” is created.

  • folder_id (str | None) – Optional Drive folder ID to create the spreadsheet in.

Returns:

The spreadsheet ID string.

Return type:

str

siege_utilities.analytics.google_sheets.get_spreadsheet_metadata(client, spreadsheet_id)[source]

Fetch spreadsheet metadata (title, sheets, locale, etc.).

Returns:

The spreadsheet resource dict.

Parameters:

spreadsheet_id (str)

Return type:

Dict[str, Any]

siege_utilities.analytics.google_sheets.read_dataframe(client, spreadsheet_id, range_='Sheet1', has_header=True)[source]

Read a range from a spreadsheet into a pandas DataFrame.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Source spreadsheet ID.

  • range – A1 notation range (e.g. "Sheet1" or "Sheet1!A1:D100").

  • has_header (bool) – If True, first row is used as column names.

  • range_ (str)

Returns:

pandas DataFrame.

siege_utilities.analytics.google_sheets.read_values(client, spreadsheet_id, range_)[source]

Read values from a range.

Returns:

Row-major list of lists (may be ragged).

Parameters:

  • spreadsheet_id (str)

  • range_ (str)

Return type:

List[List[Any]]

siege_utilities.analytics.google_sheets.write_dataframe(client, spreadsheet_id, df, sheet_name='Sheet1', include_header=True, start_cell='A1')[source]

Write a pandas DataFrame to a sheet.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Target spreadsheet ID.

  • df – pandas DataFrame to write.

  • sheet_name (str) – Tab name (default "Sheet1").

  • include_header (bool) – Whether to include column names as first row.

  • start_cell (str) – Top-left cell (default "A1").

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_sheets.write_values(client, spreadsheet_id, range_, values, value_input_option='USER_ENTERED')[source]

Write a 2-D list of values to a range.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • spreadsheet_id (str) – Target spreadsheet ID.

  • range – A1 notation range (e.g. "Sheet1!A1:D10").

  • values (List[List[Any]]) – Row-major list of lists.

  • value_input_option (str) – "RAW" or "USER_ENTERED" (default).

  • range_ (str)

Returns:

The API response dict.

Return type:

Dict[str, Any]

Google Docs write service.

Provides functions for creating documents, inserting text, tables, images, and performing batch updates via the Docs API v1.

Usage:

from siege_utilities.analytics.google_workspace import GoogleWorkspaceClient from siege_utilities.analytics.google_docs import (

create_document, insert_text, insert_table,

)

client = GoogleWorkspaceClient.from_service_account() doc_id = create_document(client, “Meeting Notes”) insert_text(client, doc_id, “Agendan”, bold=True) insert_table(client, doc_id, rows=3, cols=2)

siege_utilities.analytics.google_docs.batch_update(client, document_id, requests)[source]

Execute a batch of Docs API requests.

Delegates to GoogleWorkspaceClient.batch_update_document().

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Docs API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.copy_document(client, document_id, title=None)[source]

Copy a document via the Drive API.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Source document ID.

  • title (str | None) – Title for the copy (default: “Copy of …”).

Returns:

The new document ID.

Return type:

str

siege_utilities.analytics.google_docs.create_document(client, title, folder_id=None)[source]

Create a new Google Doc and return its document ID.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • title (str) – Title for the new document.

  • folder_id (str | None) – Optional Drive folder ID to create the document in.

Returns:

The document ID string.

Return type:

str

siege_utilities.analytics.google_docs.get_document(client, document_id)[source]

Fetch full document metadata and content structure.

Returns:

The document resource dict.

Parameters:

document_id (str)

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.insert_image(client, document_id, image_uri, index=1, width=None, height=None)[source]

Insert an image from a URL.

The URI must be publicly accessible or a Google Drive file.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • image_uri (str) – Public URL of the image.

  • index (int) – Character index for insertion.

  • width (float | None) – Optional width in points.

  • height (float | None) – Optional height in points.

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.insert_paragraph(client, document_id, text, index=1, heading=None)[source]

Insert a paragraph with optional heading style.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • text (str) – Paragraph text (newline is appended automatically).

  • index (int) – Character index (1-based).

  • heading (str | None) – Named style ("HEADING_1" through "HEADING_6", "TITLE", "SUBTITLE", or None for normal text).

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.insert_table(client, document_id, rows, cols, index=1)[source]

Insert an empty table at the given index.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • rows (int) – Number of rows.

  • cols (int) – Number of columns.

  • index (int) – Character index where the table is inserted.

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.insert_text(client, document_id, text, index=1, bold=False, italic=False, font_size=None)[source]

Insert text at a given index in a document.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • text (str) – Text to insert.

  • index (int) – Character index (1-based; 1 = start of document body).

  • bold (bool) – Apply bold formatting.

  • italic (bool) – Apply italic formatting.

  • font_size (int | None) – Font size in points (None = default).

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_docs.read_document_text(client, document_id)[source]

Read the full plain-text content of a document.

Extracts text from all structural elements (paragraphs, tables, etc.).

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

Returns:

The document text as a single string.

Return type:

str

siege_utilities.analytics.google_docs.replace_text(client, document_id, find, replace_with, match_case=True)[source]

Find and replace text throughout a document.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • document_id (str) – Target document ID.

  • find (str) – Text to search for.

  • replace_with (str) – Replacement text.

  • match_case (bool) – Whether the search is case-sensitive.

Returns:

The API response dict.

Return type:

Dict[str, Any]

Google Slides write service.

Provides functions for creating presentations, adding slides, inserting text and images, and performing batch updates via the Slides API v1.

Usage:

from siege_utilities.analytics.google_workspace import GoogleWorkspaceClient from siege_utilities.analytics.google_slides import (

create_presentation, add_blank_slide, insert_text,

)

client = GoogleWorkspaceClient.from_service_account() pres_id = create_presentation(client, “Q1 Report”) slide_id = add_blank_slide(client, pres_id) insert_text(client, pres_id, slide_id, “Hello World”)

siege_utilities.analytics.google_slides.add_blank_slide(client, presentation_id, layout='BLANK', insertion_index=None)[source]

Add a blank slide to a presentation.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • layout (str) – Predefined layout ("BLANK", "TITLE", "TITLE_AND_BODY", etc.).

  • insertion_index (int | None) – Position (0-based). None appends at end.

Returns:

The new slide’s object ID.

Return type:

str

siege_utilities.analytics.google_slides.batch_update(client, presentation_id, requests)[source]

Execute a batch of Slides API requests.

Delegates to GoogleWorkspaceClient.batch_update_presentation().

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • requests (List[Dict[str, Any]]) – List of request dicts per the Slides API batchUpdate spec.

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_slides.copy_presentation(client, presentation_id, title=None)[source]

Copy an entire presentation via the Drive API.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Source presentation ID.

  • title (str | None) – Title for the copy (default: “Copy of …”).

Returns:

The new presentation ID.

Return type:

str

siege_utilities.analytics.google_slides.create_argument_slide(client, presentation_id, argument, slide_index=None)[source]

Add one slide for an Argument.

Layout is derived from argument.layout:

“full_width” → title / narrative / figure stacked vertically “side_by_side” → title top; narrative left, figure right

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • argument – Argument dataclass instance.

  • slide_index (int | None) – Insertion position. None → append at end.

Returns:

Slide object ID.

Return type:

str

siege_utilities.analytics.google_slides.create_presentation(client, title, folder_id=None)[source]

Create a new Google Slides presentation and return its ID.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • title (str) – Title for the new presentation.

  • folder_id (str | None) – Optional Drive folder ID to create the presentation in.

Returns:

The presentation ID string.

Return type:

str

siege_utilities.analytics.google_slides.create_report_from_arguments(client, title, arguments, folder_id=None, theme_presentation_id=None)[source]

Create a complete presentation from a list of Arguments.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • title (str) – Presentation title.

  • arguments (List) – List of Argument dataclass instances (one slide each).

  • folder_id (str | None) – Optional Drive folder to place the presentation in.

  • theme_presentation_id (str | None) – If given, copies this presentation first (preserves master slides / theme).

Returns:

Presentation ID of the newly created report.

Return type:

str

siege_utilities.analytics.google_slides.create_textbox(client, presentation_id, slide_id, text, left=100, top=100, width=400, height=50)[source]

Create a text box on a slide and populate it with text.

Dimensions are in EMU (English Metric Units). 1 inch = 914400 EMU. For convenience, this function accepts points (1 pt = 12700 EMU) but the values are treated as points internally.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • slide_id (str) – Slide object ID.

  • text (str) – Text to put in the box.

  • left (float) – Position in points from top-left.

  • top (float) – Position in points from top-left.

  • width (float) – Dimensions in points.

  • height (float) – Dimensions in points.

Returns:

The textbox object ID.

Return type:

str

siege_utilities.analytics.google_slides.get_presentation(client, presentation_id)[source]

Fetch full presentation metadata.

Returns:

The presentation resource dict.

Parameters:

presentation_id (str)

Return type:

Dict[str, Any]

siege_utilities.analytics.google_slides.insert_image(client, presentation_id, slide_id, image_url, left=100, top=100, width=400, height=300)[source]

Insert an image onto a slide from a URL.

The URL must be publicly accessible or a Google Drive file URL.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • slide_id (str) – Slide object ID.

  • image_url (str) – Public URL of the image.

  • left (float) – Position in points.

  • top (float) – Position in points.

  • width (float) – Size in points.

  • height (float) – Size in points.

Returns:

The image object ID.

Return type:

str

siege_utilities.analytics.google_slides.insert_text(client, presentation_id, object_id, text, insertion_index=0)[source]

Insert text into an existing shape or text box.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • presentation_id (str) – Target presentation ID.

  • object_id (str) – The shape/text-box object ID to insert into.

  • text (str) – Text string to insert.

  • insertion_index (int) – Character index within the shape’s text (default 0).

Returns:

The API response dict.

Return type:

Dict[str, Any]

siege_utilities.analytics.google_slides.upload_figure_to_drive(client, figure, filename, folder_id=None)[source]

Save a matplotlib Figure to a temp PNG, upload to Google Drive, return URL.

Parameters:

  • client – Authenticated GoogleWorkspaceClient.

  • figure – matplotlib Figure object.

  • filename (str) – Name for the uploaded file (without extension).

  • folder_id (str | None) – Optional Drive folder ID.

Returns:

Public URL string for the uploaded image (suitable for insert_image).

Return type:

str