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.

1Password Integration (Recommended)

The from_1password() factory method downloads a credential JSON document from 1Password and auto-detects whether it is a service account key or an OAuth client secret:

from siege_utilities.analytics.google_workspace import GoogleWorkspaceClient

# Service account (server-to-server, no browser required)
client = GoogleWorkspaceClient.from_1password(
    item_title="Google Service Account - siege_utilities",
    vault="Employee",
    account="Siege_Analytics",
)

# OAuth (opens browser on first use, caches token afterward)
client = GoogleWorkspaceClient.from_1password(
    item_title="Google OAuth Client - siege_utilities",
    vault="Personal",
    account="Siege_Analytics",
)

One-time GCP setup for a service account:

# Create the service account
gcloud iam service-accounts create siege-utilities-workspace \
    --project=windy-art-489721-j3 \
    --display-name="siege_utilities Workspace"

# Enable Workspace APIs
gcloud services enable sheets.googleapis.com docs.googleapis.com \
    slides.googleapis.com drive.googleapis.com \
    --project=windy-art-489721-j3

# Download the JSON key
gcloud iam service-accounts keys create ~/siege-utilities-sa.json \
    --iam-account=siege-utilities-workspace@windy-art-489721-j3.iam.gserviceaccount.com \
    --project=windy-art-489721-j3

# Store in 1Password and delete the local file
op document create ~/siege-utilities-sa.json \
    --title "Google Service Account - siege_utilities" \
    --vault Employee --account Siege_Analytics
rm ~/siege-utilities-sa.json

One-time OAuth setup (for personal Drive access):

python scripts/google_workspace_auth.py

This opens a browser for Google sign-in and caches the token at ~/.siege/tokens/workspace_token.json.

Note

Service accounts have their own Drive space. To access files in a user’s personal Drive, share those files with the service account email (siege-utilities-workspace@windy-art-489721-j3.iam.gserviceaccount.com).

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()

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)

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)

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”)