csa-google-workspace

A Python library for managing comments and content on Google Docs, Sheets, and Slides, via the Google APIs. Comments are handled uniformly across all three file types (a single Drive API v3 concern); content read/write and Sheets comment→cell mapping are the variant, per-API parts.

It's designed to be embedded: a clean, typed Python surface for building AI tooling on top of Google Workspace — MCP servers, agent/LLM plugins, review bots, and automation services that need to read documents, triage and reply to comments, and write edits back. The Workspace(backend=…) seam (dependency injection / run-as-a-service) and the Backend protocol exist for exactly that; an MCP wrapper is a natural (out-of-scope-for-now) layer on top.

Status: feature-complete for its scoped roadmap and live-verified end-to-end against real Google. Shipped across Docs/Sheets/Slides: comment management, content read/write, Sheets comment→cell mapping, and Docs suggestions read. See CHANGELOG.md; design + phased plans under docs/superpowers/.

Install

pip install csa-google-workspace

Python >=3.10. The package is typed (ships py.typed), so downstream mypy/pyright consume its type hints. Working on the library itself? See Development.

Usage

from csa_google_workspace import Workspace

ws = Workspace.from_credentials(my_google_creds)   # BYO credentials (or .from_oauth("client_secret.json"))
doc = ws.open("https://docs.google.com/document/d/…/edit")   # -> Doc | Sheet | Slides

# Comments — uniform across all three file types
for c in doc.comments.filter(resolved=False):      # triage open comments
    print(c.author.display_name, c.content)
    c.reply("looking into it"); c.resolve()
doc.create_comment("Please review section 3")

# Content read + write (type-specific)
doc.as_text()                                       # plain text of a Doc / Sheet grid / Slides deck
doc.replace_text("draft", "final")                  # Doc & Slides;  doc.append_text / insert_text / delete_range too
doc.suggestions                                     # Docs suggesting-mode edits (read-only)
doc.as_text(suggestions="accepted")                 # preview as if suggestions accepted / rejected

sheet = ws.open(sheet_url)
sheet.update("Sheet1!A1", [["=SUM(B:B)"]], value_input_option="USER_ENTERED")   # formulas ok
sheet.append_rows("Sheet1!A1", [["new", "row"]])    # append after the last row
sheet.as_text(tab="Data")                           # one tab; as_text() renders all tabs
sheet.comments_by_cell("B11")                       # comments mapped back to a cell (best-effort)

Entry points: Workspace.from_credentials(creds) (bring-your-own credentials — user OAuth or a service account), Workspace(backend=…) (dependency injection / run-as-a-service), Workspace.from_oauth(...) (interactive login). Writes are on by default; pass read_only=True to lock them (and narrow to read-only OAuth scopes). Public types — Comment, Author, Reply, Location, Suggestion, Slide — are importable from the package root.

Capability boundaries

The library is document-scoped and honest about what the Google APIs can't do:

  • Suggestions are read/preview only. Doc.suggestions reads suggesting-mode edits and as_text(suggestions="accepted"|"rejected") previews the outcome, but accepting/rejecting is impossible via the API (UnsupportedOperation) — Google exposes no endpoint. Reserved for a future PlaywrightBackend.
  • No document discovery. You hand the library a file id/URL (Workspace.open(id)); there is no files.list/search. A "sweep my documents" job enumerates files itself and opens each: 
    files = drive.files().list(q="mimeType='application/vnd.google-apps.document'",
                           fields="files(id)").execute()["files"]
for f in files:
    doc = ws.open(f["id"])
    ...
  • Sheets cell-anchored comments can't be created via the API — sheet.create_comment(text, cell=…) posts a file-level comment with a #gid=…&range=… deep-link instead.

Using it on a user's behalf (production)

This library is a building block for MCP servers / agents / automations acting on a user's behalf with a full-Drive token. Before deploying, read SECURITY.md — prompt injection through document/comment content is the primary risk. In short:

  • Credential seam: from_oauth + local token.json is PoC/CLI scaffolding (run_local_server() can't run on a server). In production the host runs its own OAuth, stores per-user tokens in a secret store, and passes ready credentials via Workspace.from_credentials(creds) — the production entry point.
  • Concurrency: one Workspace per request/user; never share a Workspace (or its backend) across threads — googleapiclient clients aren't thread-safe. The stack is synchronous; wrap calls in asyncio.to_thread(...) from async code.
  • Isolation & least authority: a Workspace binds one user's credentials — never reuse it across users. Default to read_only=True and escalate to a write-capable Workspace deliberately, per operation.

Documents

Document What it is
docs/superpowers/specs/2026-07-20-csa-google-workspace-design.md The design spec. Scope, two-axis architecture, API surface, error model, phasing.
docs/superpowers/plans/ The six phased, TDD implementation plans (foundations · comments · content read · cell-mapping · content write · suggestions read).
research/google-drive-comments-reference.md Canonical reference on how Drive/Sheets comments actually work: the 10 API methods, fields, resolution/deletion models, OAuth scopes, and the hard truth about the anchor field.
research/docs-suggestions-reference.md How Docs suggestions behave: readable (incl. accepted/rejected previews), but no accept/reject endpoint and no author exposed.
research/server-landscape.md Source-verified survey of prior-art servers that handle Google comments.
research/mcp-server-design.md · research/mcp-protocol-notes.md Earlier MCP-server design + protocol notes (kept for reference should an MCP wrapper be added).
experiments/ Runnable empirical probes (with dated RESULTS.md): anchor-probe, comment-lifecycle, docs-suggestions, sheets-cellmap. Probe beats docs.
CHANGELOG.md What changed in each refresh, and why.

Three things worth knowing

  1. Comments are a Google Drive API v3 concern — not the Sheets/Docs/Slides APIs (those handle content). One comment API serves all three file types. (Sheets notes are separate and out of scope.)
  2. You cannot anchor a comment to a specific Sheets cell via the API. Google treats API-created anchors as unanchored; the real anchor is a workbook-range with an opaque id. Mapping a comment back to a cell requires exporting the sheet as XLSX and parsing the comment XML — the central hard problem, which the library solves (best-effort) via comment.location / sheet.comments_by_cell().
  3. The space isn't greenfield, so the value is in the hard parts — reliable read-side cell mapping and clean Docs/Sheets/Slides coverage — not merely "supporting comments." See server-landscape.md.

Development

pip install -e ".[dev]"       # from a clone; src/ layout, Python >=3.10
pytest -q                      # unit suite: no network, no credentials (in-memory FakeBackend)
ruff check src tests && mypy   # lint + type-check (the CI `lint` job)

Everything above runs offline and gates CI. Two opt-in suites exercise real Google and are skipped unless their env vars are set:

# Live API suite — real Docs/Sheets/Slides/Drive. Needs OAuth client secrets; a cached token
# avoids re-consent, otherwise the first run opens a browser to log in:
CSA_GW_INTEGRATION=1 CSA_GW_CLIENT_SECRETS=path/to/client_secret.json pytest tests/integration/

# Interactive OAuth suite — the login flow itself (token caching, file permissions, read-only
# contract). Separate because it needs a human at a browser + touches the sensitive token:
CSA_GW_OAUTH=1 CSA_GW_CLIENT_SECRETS=path/to/client_secret.json pytest tests/oauth/

The client secret must be an installed/desktop-app OAuth client, and Drive, Docs, Sheets, and Slides must be enabled in its Cloud project (a scoped token still 403s until each API is enabled). client_secret.json and token*.json are gitignored — never commit them. Releasing is documented in RELEASING.md.

License

Licensed under the Apache License, Version 2.0.

Project links

Data verified by PyPI on Jul 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.52.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for 203984092384 from gravatar.com 203984092384

Credits

PyPI data
Data sourced directly from PyPI's database.

Maintainer: Kurt Seifried

Author: Cloud Security Alliance

GitHub Statistics

Data verified by PyPI on Jul 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

google google-workspace google-docs google-sheets google-slides google-drive comments suggestions mcp

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

csa_google_workspace-0.1.1.tar.gz (54.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

csa_google_workspace-0.1.1-py3-none-any.whl (32.1 kB view details)

Uploaded Python 3

File details

Details for the file csa_google_workspace-0.1.1.tar.gz.

File metadata

  • Download URL: csa_google_workspace-0.1.1.tar.gz
  • Upload date:
  • Size: 54.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for csa_google_workspace-0.1.1.tar.gz
Algorithm Hash digest
SHA256 9b156da5a4b0b3cc4fad9a14598a77cf537cd7313b533b0a621c00c5ab177cdd
MD5 4e8fa973a8b903571278c1d76ebbd373
BLAKE2b-256 f14bc8d7a5b9b5df3132ee3da5336a16a1d6fd274fc81af4f6518f82c6207104

See more details on using hashes here.

Provenance

The following attestation bundles were made for csa_google_workspace-0.1.1.tar.gz:

Publisher: release.yml on CloudSecurityAlliance/csa-google-workspace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file csa_google_workspace-0.1.1-py3-none-any.whl.

File metadata

File hashes

Hashes for csa_google_workspace-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 362545d96acacbaa343bdaf1604b36cc57712eae9843a95956b75796a6faf613
MD5 bbce27ac35ff07a1fd8fa4697f0648d4
BLAKE2b-256 714769d0221eac960fc66d187c73e1693d1e946b18399e85eff628c1d36050dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for csa_google_workspace-0.1.1-py3-none-any.whl:

Publisher: release.yml on CloudSecurityAlliance/csa-google-workspace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.52.0

2 files

0.51.1

2 files

0.51.0

2 files

0.50.0

2 files

0.49.0

2 files

0.48.0

2 files

0.47.0

2 files

0.46.0

2 files

0.45.0

2 files

0.44.0

2 files

0.43.1

2 files

0.43.0

2 files

0.42.0

2 files

0.41.0

2 files

0.40.1

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.1

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.0

2 files

0.31.1

2 files

0.31.0

2 files

0.30.14

2 files

0.30.13

2 files

0.30.12

2 files

0.30.11

2 files

0.30.10

2 files

0.30.9

2 files

0.30.8

2 files

0.30.7

2 files

0.30.6

2 files

0.30.5

2 files

0.30.4

2 files

0.30.3

2 files

0.30.2

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.0

2 files

0.25.0

2 files

Yanked

0.24.0

2 files

Yanked reason: CSV formula injection in export_comments — upgrade to 0.25.0

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.1

2 files

0.20.0

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.0

2 files

0.16.0

2 files

0.15.0

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.3.1

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

This release

0.1.1 This release

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page