google-suite

# Google Suite

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-gsuite--sdk-indigo.svg)](https://pabloalaniz.github.io/google-suite/)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15461/badge)](https://www.bestpractices.dev/projects/15461)

Unified Python SDK for Google Workspace APIs with Clean Architecture.

## Features

- 🔐 **Unified Auth** - Single OAuth flow for all Google APIs
- 📧 **Gmail** - Send, receive, search, labels, attachments
- 📅 **Calendar** - Events, calendars, scheduling
- 📁 **Drive** - Files, folders, sharing, upload/download
- 📊 **Sheets** - Read/write, upsert, typed rows, validation, conditional formats, charts, pivots, export (engine from [GSpreadManager](docs/MIGRATING_FROM_GSPREADMANAGER.md))
- ✅ **Tasks** - Task lists, tasks, subtasks, due dates, complete/reopen
- 👥 **Contacts** - List, search, create, update and delete contacts (People API)
- 🔎 **Search Console** (read-only) - Sites, search analytics, URL inspection, sitemaps
- 📈 **Google Analytics 4** (read-only) - Account summaries, properties, reports, realtime reports
- 🏷️ **Tag Manager** (read-only) - Accounts, containers, workspaces, tags, triggers, variables, versions
- 🚀 **REST API** - Single FastAPI gateway for all services
- 💻 **CLI** - Unified command-line interface

## Installation

```bash
pip install gsuite-sdk
```

Optional extras:
```bash
pip install gsuite-sdk[cloudrun]  # Google Cloud Secret Manager support
pip install gsuite-sdk[all]       # All optional dependencies (FastAPI, CLI)
```

## Quick Start

### Prerequisites

You need OAuth credentials from Google Cloud Console. See [Getting Credentials](docs/GETTING_CREDENTIALS.md) for a step-by-step guide.

### Authentication

```python
from gsuite_core import GoogleAuth

# OAuth (interactive, opens browser)
auth = GoogleAuth()
auth.authenticate()

# Or with service account
auth = GoogleAuth.from_service_account("service-account.json")
```

### Gmail

```python
from gsuite_gmail import Gmail, query

gmail = Gmail(auth)

# Get unread messages with fluent API
for message in gmail.get_unread():
    print(f"{message.sender}: {message.subject}")
    message.mark_as_read().archive()  # Fluent chaining!

# Send email with signature
gmail.send(
    to=["recipient@example.com"],
    subject="Hello",
    body="World",
    signature=True,  # Appends your Gmail signature
)

# Search with query builder (inspired by simplegmail)
messages = gmail.search(
    query.newer_than(days=7) & query.has_attachment() & query.from_("boss@company.com")
)

# Or use construct_query for dict-style
messages = gmail.search(query.construct_query(
    unread=True,
    newer_than=(7, "day"),
    labels=["Work"],
))
```

### Drive

```python
from gsuite_drive import Drive

drive = Drive(auth)

# List files
for file in drive.list_files():
    print(f"{file.name} ({file.mime_type})")

# Upload
uploaded = drive.upload("document.pdf")
print(f"Uploaded: {uploaded.web_view_link}")

# Download
file = drive.get("file_id")
file.download("local_copy.pdf")

# Create folder and upload into it
folder = drive.create_folder("My Folder")
drive.upload("file.txt", parent_id=folder.id)
```

### Calendar

```python
from gsuite_calendar import Calendar

calendar = Calendar(auth)

# Get upcoming events
events = calendar.get_upcoming(days=7)
for event in events:
    print(f"{event.start}: {event.summary}")

# Create event
calendar.create_event(
    summary="Meeting",
    start="2026-01-30T10:00:00",
    end="2026-01-30T11:00:00",
)
```

### Sheets

```python
from gsuite_sheets import Sheets

sheets = Sheets(auth)

# Open spreadsheet by title or URL
sheet = sheets.open("My Spreadsheet")
# Or by key
sheet = sheets.open_by_key("1A2B3C...")
# Or by URL
sheet = sheets.open_by_url("https://docs.google.com/spreadsheets/d/...")

# Read values
values = sheet.get_values("Sheet1!A1:D10")
print(values)  # [[row1], [row2], ...]

# Write values
sheet.update_values("Sheet1!A1", [["Name", "Email"], ["John", "john@example.com"]])

# Append rows
sheet.append_values("Sheet1", [["Jane", "jane@example.com"]])

# Batch operations
sheet.batch_update([
    {"range": "Sheet1!A1", "values": [["Header1", "Header2"]]},
    {"range": "Sheet1!A2", "values": [["Data1", "Data2"]]},
])

# Create new spreadsheet
new_sheet = sheets.create("Budget 2026")
print(f"Created: {new_sheet.url}")

# List all spreadsheets
for spreadsheet in sheets.list_spreadsheets():
    print(f"{spreadsheet['name']} - {spreadsheet['id']}")
```

### Tasks and Contacts

Tasks and Contacts are opt-in: their scopes are not in the default login
(contacts is a sensitive scope). Log in with them and enable the **Google Tasks
API** / **People API** in your Cloud project:

```bash
gsuite auth login --force --scopes default,tasks,contacts
```

```python
from datetime import date

from gsuite_contacts import Contacts
from gsuite_tasks import Tasks

tasks = Tasks(auth)
task = tasks.create_task("Pay rent", due=date(2026, 2, 1))
for t in tasks.list_tasks(show_completed=False):
    print(t.title, t.due, "overdue" if t.is_overdue else "")
tasks.complete_task(task.id)

contacts = Contacts(auth)
for c in contacts.search("ana"):
    print(c.display_name, c.email, c.phone)
ana = contacts.create(given_name="Ana", emails=["ana@example.com"])
contacts.update(ana.id, phones=["+54 11 5555-5555"])
```

### Search Console, Analytics (GA4) and Tag Manager (read-only)

These three are read-only and opt-in: their scopes (`webmasters.readonly`,
`analytics.readonly`, `tagmanager.readonly`) are not in `default` or `all`, so
existing logins keep working without re-consent. To use them:

1. In your Google Cloud project enable the **Google Search Console API**, the
   **Google Analytics Admin API**, the **Google Analytics Data API** and the
   **Tag Manager API**.
2. If your OAuth consent screen lists scopes explicitly, add the three above.
3. Log in again. A login replaces the stored scopes, so list every set you
   still need (here, with Tasks and Contacts too):

```bash
gsuite auth login --force --scopes default,tasks,contacts,marketing
```

`marketing` is `searchconsole,analytics,tagmanager`; each can also be asked for
alone. Restart the MCP server / redeploy the API (`gsuite auth export`) after.

```python
from gsuite_analytics import Analytics
from gsuite_searchconsole import SearchConsole
from gsuite_tagmanager import TagManager

sc = SearchConsole(auth)
sc.list_sites()
sc.query(
    "sc-domain:example.com", "2026-09-01", "2026-09-30",
    dimensions=["query", "page"],
    filters=[{"dimension": "country", "operator": "equals", "expression": "arg"}],
    row_limit=100,
)
sc.inspect_url("sc-domain:example.com", "https://example.com/blog/")

ga = Analytics(auth)
ga.account_summaries()
ga.run_report(
    "123456789", ["date", "sessionSource"], ["activeUsers", "sessions"],
    date_ranges=[("28daysAgo", "today")],
    dimension_filters=[{"field": "country", "value": "Argentina"}],
    limit=50, order_by="sessions",
)
ga.run_realtime_report("123456789", ["country"], ["activeUsers"])

gtm = TagManager(auth)
container = gtm.list_containers("accounts/123")[0]["path"]
workspace = gtm.list_workspaces(container)[0]["path"]
gtm.list_tags(workspace), gtm.list_triggers(workspace), gtm.list_versions(container)
```

### REST API

```bash
# Start unified API server
gsuite serve --port 8080

# Or with Docker
docker run -p 8080:8080 gsuite-api
```

```bash
# All services under one roof
curl http://localhost:8080/gmail/messages/unread
curl http://localhost:8080/calendar/events/upcoming
curl http://localhost:8080/drive/files
curl http://localhost:8080/sheets/list
curl http://localhost:8080/sheets/{spreadsheet_id}/values/Sheet1!A1:D10
curl http://localhost:8080/tasks/lists/@default/tasks
curl "http://localhost:8080/contacts/search?q=ana"
# Read-only, need the "marketing" scopes
curl http://localhost:8080/searchconsole/sites
curl -X POST http://localhost:8080/analytics/properties/123456789:runReport \
  -H 'Content-Type: application/json' -d '{"metrics": ["sessions"], "dimensions": ["date"]}'
curl "http://localhost:8080/tagmanager/tags?parent=accounts/1/containers/2/workspaces/3"
```

**Interactive API docs available at `/docs` when server is running.** See [API Documentation](#api-documentation) section below for details.

### CLI

```bash
# Authentication
gsuite auth login              # Opens browser for OAuth
gsuite auth status             # Check auth status
gsuite auth export             # Export token for Cloud Run

# Gmail
gsuite gmail list --unread     # List unread messages
gsuite gmail read MSG_ID       # Read specific message
gsuite gmail send --to user@example.com --subject "Hi" --body "Hello"
gsuite gmail search "from:boss has:attachment"
gsuite gmail labels            # List all labels

# Calendar  
gsuite calendar list --days 7  # Upcoming events
gsuite calendar today          # Today's events
gsuite calendar week           # Week view
gsuite calendar create "Meeting" --start "2026-01-30 10:00"
gsuite calendar calendars      # List calendars

# Sheets
gsuite sheets list             # List all spreadsheets
gsuite sheets open "Budget"    # Open by title
gsuite sheets read SHEET_ID "Sheet1!A1:D10"  # Read range
gsuite sheets write SHEET_ID "Sheet1!A1" "Name,Email"
gsuite sheets append SHEET_ID "Sheet1" "John,john@example.com"
gsuite sheets create "New Sheet"  # Create spreadsheet

# Tasks (login with --scopes default,tasks)
gsuite tasks lists             # Task lists
gsuite tasks ls --due-before 2026-02-28
gsuite tasks add "Pay rent" --due 2026-02-01
gsuite tasks done TASK_ID

# Contacts (login with --scopes default,contacts)
gsuite contacts search ana
gsuite contacts add -g Ana -e ana@example.com -p "+54 11 5555-5555"
gsuite contacts show CONTACT_ID

# Server
gsuite serve --port 8080