googlekit 0.0.4

Unofficial Python SDK for Google Drive API, Google Sheets API, Google Calendar API, Google Docs API, and Google Slides API (Google Workspace)

GitHub • PyPI • Documentation • Issues

GoogleKit

GoogleKit is an unofficial Python SDK for the Google Drive API, Google Sheets API, Google Calendar API, Google Docs API, and Google Slides API.

GoogleKit is not affiliated with, endorsed by, or sponsored by Google LLC.

Use GoogleKit to upload and download Google Drive files, read and write Google Sheets spreadsheets, manage Google Calendar events, create Google Docs documents, and build Google Slides presentations — from one Python package. It wraps google-api-python-client with OAuth 2.0, service account, and Application Default Credentials (ADC) auth, least-privilege scopes, retries, and a clean typed API for Google Workspace automation, bots, scripts, and backend services.

Whether you need a Python Google Drive client, a Google Sheets Python library, a Google Calendar SDK, a Google Docs API wrapper, or a Google Slides API client, GoogleKit gives you one consistent Google Workspace Python SDK instead of wiring each Google API by hand.

Table of Contents

• Features
• Supported Services
• Documentation
• Installation
• Quick Start
• Authentication Methods
  • Method 1: Application Default Credentials
  • Method 2: Service Account
  • Method 3: OAuth2 Client
  • Method 4: Auto-detect
  • Environment Variable
• API Overview
• Usage Examples
• OAuth Scopes
• Error Handling
• CLI
• Requirements
• Development
• License
• Disclaimer

Features

• Google Drive API v3 (Python) — upload, download, search, copy, move, trash, export Docs/Sheets/Slides, shared drives
• Google Sheets API v4 — read, write, append, and clear cell values with A1 notation; formatting and worksheets
• Google Calendar API v3 — create and list events, Google Meet conference links, free/busy, calendars
• Google Docs API v1 — create documents, insert text, tables, batch updates, UTF-16-safe indexes
• Google Slides API v1 — create presentations, pages, shapes, images, tables, template text replace
• Google OAuth 2.0 & service accounts — desktop OAuth, ADC (gcloud auth application-default login), JSON keys
• Four auth factories — from_adc(), from_service_account(), from_oauth(), and dedicated auto() discovery
• Least-privilege OAuth scopes — readonly, readwrite, full presets per Google API
• Unified Google Workspace client — one GoogleKit entry point or per-service clients (DriveClient, SheetsClient, …)
• Production-ready transport — retries, rate-limit handling, lazy pagination, typed exceptions
• MIT open source — install with pip install googlekit or uv add googlekit

Supported Services

Google API	Python module	Client class	Common tasks
Google Drive API	googlekit.gdrive	DriveClient	File upload/download, folders, sharing, export
Google Sheets API	googlekit.gsheets	SheetsClient	Spreadsheet values, worksheets, formatting
Google Calendar API	googlekit.gcalendar	CalendarClient	Events, Meet links, free/busy
Google Docs API	googlekit.gdocs	DocsClient	Documents, text, tables, export
Google Slides API	googlekit.gslides	SlidesClient	Presentations, slides, images, templates

Enable each API in Google Cloud Console → APIs & Services → Library.

Documentation

Full docs: https://ssujitx.github.io/GoogleKit/

Topic	Link
Installation	Docs → Installation
Authentication (OAuth, ADC, service account)	Docs → Authentication
OAuth scopes	Docs → Scopes
Errors	Docs → Errors
Google Drive API — files, folders, sharing, changes, export	Docs → Drive
Google Sheets API — values, worksheets, formatting	Docs → Sheets
Google Calendar API — events, Meet, free/busy, sync	Docs → Calendar
Google Docs API — text, tables, UTF-16 indexes	Docs → Docs
Google Slides API — pages, shapes, images, templates	Docs → Slides

The README covers install, auth, and quick examples. Method-level reference, recipes, and pitfalls live on the docs site.

Official Google API documentation

Product	Guides	Reference
Google Workspace	Workspace APIs	—
Drive	Guides	REST v3
Sheets	Guides	REST
Calendar	Guides	REST v3
Docs	Guides	REST
Slides	Guides	REST
OAuth / scopes	OAuth 2.0	Scopes

Installation

pip install googlekit

Or with UV (recommended):

uv add googlekit

Google API client libraries are included by default — no extras required.

---

Quick Start

GoogleKit exposes managers (full API) and optional shortcuts (flat helpers). Both are suggested after client.drive. / client.sheets. / … with hover docs.

Unified client

from googlekit import GoogleKit
from googlekit.auth.scopes import ScopeProfile

client = GoogleKit.auto(
    services=["gdrive", "gsheets"],
    profile=ScopeProfile.FULL,  # list all My Drive (not only drive.file)
)

# Managers (full control)
page = client.drive.files.list(folder_id="root")
client.sheets.values.write("spreadsheet_id", "Sheet1!A1", [["Ada", 98]])

# Optional shortcuts (same behavior, flatter)
page = client.drive.list_files(folder_id="root")
client.sheets.write_values("spreadsheet_id", "Sheet1!A1", [["Ada", 98]])

Shortcuts at a glance (all services)

Service	Shortcut examples	Equivalent managers
Drive	list_files, upload_file, share, …	files.list, files.upload_path, permissions.share_user, …
Sheets	read_values, write_values, create_spreadsheet	values.read / write, spreadsheets.create
Calendar	list_events, create_event, delete_event	events.list / create / delete
Docs	create_document, append_text, insert_text	documents.create, content.append_text / insert_text
Slides	create_presentation, get_presentation, add_slide	presentations.create / get, pages.add

Drive shortcuts (PyDrive4-style)

from googlekit.gdrive import DriveClient
from googlekit.auth.scopes import ScopeProfile

drive = DriveClient.from_oauth(
    "client_secrets.json",
    profile=ScopeProfile.FULL,
)

# Shortcut                          # Manager equivalent
page = drive.list_files()           # drive.files.list(folder_id="root")
folders = drive.list_folders()      # drive.files.list(..., query=folder mime)
hits = drive.search_files("report") # drive.files.search("name contains 'report'")
folder = drive.create_folder("Reports")  # drive.folders.create(...)
result = drive.upload_file("report.pdf", folder_id=folder.id)
#                                     drive.files.upload_path(..., parents=[...])
drive.download_file(result.file.id, "report.pdf")
drive.share(result.file.id, email="[e-mail]", role="reader")
# public link (explicit): drive.get_share_link(file_id, public=True)

Other services — shortcut vs manager

from datetime import UTC, datetime, timedelta
from googlekit import GoogleKit

client = GoogleKit.auto(services=["gsheets", "gcalendar", "gdocs", "gslides"])

# Sheets
client.sheets.write_values("sid", "Sheet1!A1", [["A", 1]])
client.sheets.values.write("sid", "Sheet1!A1", [["A", 1]])

# Calendar
start, end = datetime.now(UTC), datetime.now(UTC) + timedelta(hours=1)
client.calendar.create_event("primary", summary="Standup", start=start, end=end)
client.calendar.events.create("primary", summary="Standup", start=start, end=end)

# Docs
doc = client.docs.create_document("Proposal")
doc = client.docs.documents.create("Proposal")
client.docs.append_text(doc.id, "Hello\n")
client.docs.content.append_text(doc.id, "Hello\n")

# Slides
deck = client.slides.create_presentation("Pitch")
deck = client.slides.presentations.create("Pitch")
client.slides.add_slide(deck.id)
client.slides.pages.add(deck.id)

Drive-only client (managers)

from googlekit.gdrive import DriveClient

drive = DriveClient.from_oauth("client_secrets.json")
drive.files.upload_path("report.pdf")

---

Authentication Methods

GoogleKit supports four authentication methods, ordered by recommendation for most workflows:

Method	Factory	Best For	Setup Required
1. Application Default Credentials	from_adc()	Local dev, Google Cloud	gcloud CLI
2. Service Account	from_service_account()	Servers, automation, bots	JSON key file
3. OAuth2 Client	from_oauth()	Personal scripts, desktop apps	JSON + browser auth
4. Auto-detect	auto()	Quick start / scripts that accept any local creds	ADC or a JSON file in CWD

Security: never commit client_secrets.json, service-account keys, or token files. OAuth tokens default to ./token.json in the current working directory when token_path is omitted (keep it gitignored).

---

Method 1: Application Default Credentials (Recommended)

The easiest method for local development. No JSON files to manage!

Step-by-Step Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Project dropdown → New Project → create and select it

Step 2: Enable APIs

Enable the APIs you need in APIs & Services → Library:

API	Enable
Google Drive	Enable Drive API
Google Sheets	Enable Sheets API
Google Calendar	Enable Calendar API
Google Docs	Enable Docs API
Google Slides	Enable Slides API

Step 3: Install Google Cloud SDK and sign in

1. Install Google Cloud SDK
2. Login with your Google account:

gcloud auth application-default login

Step 4: Use GoogleKit

from googlekit import GoogleKit

client = GoogleKit.from_adc(services=["gdrive"])

How it Works

ADC checks these locations in order:

1. GOOGLE_APPLICATION_CREDENTIALS environment variable
2. gcloud auth application-default login credentials
3. Google Cloud metadata service (on GCE, Cloud Run, etc.)

---

Method 2: Service Account (For Automation)

Best for servers, bots, and CI/CD. No browser interaction.

Step-by-Step Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Project dropdown → New Project → create and select it

Step 2: Enable APIs

Enable the APIs you need in APIs & Services → Library:

API	Enable
Google Drive	Enable Drive API
Google Sheets	Enable Sheets API
Google Calendar	Enable Calendar API
Google Docs	Enable Docs API
Google Slides	Enable Slides API

Step 3: Create Service Account + JSON Key

1. IAM & Admin → Service Accounts → Create
2. Keys → Add Key → Create new key → JSON
3. Rename the download to service_account.json and keep it out of git

Organization Policy Error

If key creation is blocked (iam.disableServiceAccountKeyCreation):

1. Use OAuth2 (Method 3) or ADC (Method 1)
2. Or ask your admin for an exception

Usage

from googlekit import GoogleKit

client = GoogleKit.from_service_account(
    "service_account.json",
    services=["gdrive", "gsheets"],
)

Aspect	OAuth2	Service Account
Browser needed	Yes (first time)	No
Whose data?	Your Google account	The service account identity
Best for	Personal scripts	Servers, automation
Access	Files you own / can open	Only resources shared with the SA email

Important: Service accounts start with an empty Drive. Share folders/files with the SA email (e.g. [e-mail]), or use domain-wide delegation with a subject.

---

Method 3: OAuth2 Client Credentials (Recommended for Personal Use)

For desktop apps that access your Google account. Opens a browser once.

Step-by-Step Setup

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Project dropdown → New Project → create and select it

Step 2: Enable APIs

Enable the APIs you need in APIs & Services → Library:

API	Enable
Google Drive	Enable Drive API
Google Sheets	Enable Sheets API
Google Calendar	Enable Calendar API
Google Docs	Enable Docs API
Google Slides	Enable Slides API

Step 3: Configure Google Auth Platform (OAuth app)

Google now uses Google Auth Platform (not only the old “OAuth consent screen” page). Complete these before creating a client:

1. Branding — app name, support email, developer contact
2. Audience — External (or Internal for Workspace); while testing, add yourself as a test user
3. Data Access — add the Google Workspace scopes you need (or GoogleKit will request them at runtime; listing them here helps consent / verification)

If the console still shows the older UI: APIs & Services → OAuth consent screen does the same job.

Step 4: Create OAuth client (Desktop)

You’re on the right page when you see Clients and + Create client (empty until you create one):

1. Open Google Auth Platform → Clients
2. + Create client
3. Application type: Desktop app
4. Name it (e.g. GoogleKit desktop) → Create
5. Download the JSON → rename to client_secrets.json (keep it out of git)

Older path (still works on some projects): APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app.

Usage

from googlekit import GoogleKit

client = GoogleKit.from_oauth(
    "client_secrets.json",
    token_path="token.json",  # optional; defaults to ./token.json
    services=["gdrive", "gsheets", "gcalendar"],
)

First run: a browser window opens for consent. Tokens are cached for later runs.

Per-service clients:

from googlekit.gdrive import DriveClient

drive = DriveClient.from_oauth("client_secrets.json")

---

Method 4: Auto-detect (auto())

Convenience factory that picks credentials for you — use when you want one call that works with ADC or a local JSON file.

from googlekit import GoogleKit

client = GoogleKit.auto(services=["gdrive"])
# Optional: token_path=... when discovery lands on OAuth

Discovery order:

1. Application Default Credentials (gcloud login or GOOGLE_APPLICATION_CREDENTIALS)
2. Service account files in the working directory:
   • service_account.json
   • service_account_key.json
   • sa_credentials.json
3. OAuth client files in the working directory:
   • client_secrets.json
   • client_secret.json
   • credentials.json
   • oauth_credentials.json
4. Raise AuthenticationError with setup guidance

Prefer explicit from_adc() / from_service_account() / from_oauth() in production when you know which credential type you need.

---

Environment Variable

# Linux/macOS
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"

# Windows PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\credentials.json"

client = GoogleKit.from_adc(services=["gdrive"])
# or Method 4: GoogleKit.auto(services=["gdrive"])

---

API Overview

GoogleKit

GoogleKit.from_oauth(client_secrets, token_path=None, *, services=[...], profile=...)
GoogleKit.from_service_account(credentials_file, subject=None, *, services=[...], profile=...)
GoogleKit.from_adc(*, services=[...], profile=..., quota_project_id=None)
GoogleKit.auto(*, services=[...], profile=...)

services (or explicit scopes=) is required on unified constructors so GoogleKit never requests every Workspace write scope by default.

Lazy accessors: client.drive, client.sheets, client.calendar, client.docs, client.slides.

Config and retries

from googlekit import ClientConfig, RetryPolicy

ClientConfig(retry=5)  # shorthand → RetryPolicy(max_attempts=5)
ClientConfig(retry=RetryPolicy(max_attempts=8, initial_delay=1.0))
ClientConfig(timeout=60, default_timezone="UTC")

Pass config= into GoogleKit.from_oauth / .auto or any service from_* factory.

Drive (client.drive)

Manager	Highlights
files	list, iterate, search, get, upload_path, download_path, export, copy, move, rename, trash, restore, delete, empty_trash
folders	create, create_path, list_children, upload_directory, download_directory
permissions	share_user, share_group, share_domain, share_anyone (needs public=True), create_shareable_link, list, remove
changes	get_start_page_token, list, iterate

Shortcuts: list_files, list_folders, search_files, search_folders, create_folder, upload_file, download_file, upload_folder, delete_file / delete_folder, share, unshare, list_permissions, get_share_link

Sheets (client.sheets)

Manager	Highlights
values	read, read_multiple, write, write_multiple, append, clear
spreadsheets / worksheets	create, get, add/delete/duplicate sheets
formatting	text, number formats, borders, merge

Shortcuts: create_spreadsheet, get_spreadsheet, read_values, write_values, append_values

Calendar (client.calendar)

Manager	Highlights
events	list, create, update, patch, delete (Meet via conference=True)
calendars	calendar list / CRUD
freebusy	availability queries

Shortcuts: list_events, create_event, get_event, delete_event

Docs / Slides

Client	Highlights
client.docs	documents.create / get, content helpers, tables, export / share via Drive
client.slides	presentations.create / get, pages, elements, tables, images, text replace

Docs shortcuts: create_document, get_document, append_text, insert_text
Slides shortcuts: create_presentation, get_presentation, add_slide

---

Usage Examples

Drive — list, upload, download

from googlekit import GoogleKit
from googlekit.auth.scopes import ScopeProfile

client = GoogleKit.auto(services=["gdrive"], profile=ScopeProfile.FULL)
drive = client.drive

# Manager
page = drive.files.list(folder_id="root")
# Shortcut (equivalent)
page = drive.list_files(folder_id="root")

for f in page.items:
    print(f"{f.name} ({f.id})")

uploaded = drive.files.upload_path("document.pdf", parents=["folder_id"])
# or: drive.upload_file("document.pdf", folder_id="folder_id")
drive.files.download_path(uploaded.file.id, "local-copy.pdf")
# or: drive.download_file(uploaded.file.id, "local-copy.pdf")

Drive — folders and sharing

folder = drive.folders.create_path("Projects/2026")
# or: drive.create_folder("Projects") then nest as needed
drive.folders.upload_directory("./my_project", parent_id=folder.id)
# or: drive.upload_folder("./my_project", parent_id=folder.id)

drive.permissions.share_user(folder.id, "[e-mail]", role="writer")
# or: drive.share(folder.id, email="[e-mail]", role="writer")
link = drive.permissions.create_shareable_link(folder.id, public=True)
# or: drive.get_share_link(folder.id, public=True)
print(link)

Sheets

client = GoogleKit.auto(services=["gsheets"])

# Manager
client.sheets.values.write(
    "spreadsheet_id",
    "Sheet1!A1:B2",
    [["Name", "Score"], ["Ada", 98]],
)
rows = client.sheets.values.read("spreadsheet_id", "Sheet1!A1:B10")

# Shortcut (equivalent)
client.sheets.write_values(
    "spreadsheet_id",
    "Sheet1!A1:B2",
    [["Name", "Score"], ["Ada", 98]],
)
rows = client.sheets.read_values("spreadsheet_id", "Sheet1!A1:B10")
print(rows)

Calendar

from datetime import UTC, datetime, timedelta

client = GoogleKit.auto(services=["gcalendar"])
start = datetime.now(UTC)
end = start + timedelta(hours=1)

# Manager
event = client.calendar.events.create(
    "primary",
    summary="Standup",
    start=start,
    end=end,
    conference=True,
)
# Shortcut (equivalent)
event = client.calendar.create_event(
    "primary",
    summary="Standup",
    start=start,
    end=end,
    conference=True,
)
print(event.id)

Docs & Slides

client = GoogleKit.auto(services=["gdocs", "gslides", "gdrive"])

# Docs — manager / shortcut
doc = client.docs.documents.create("Proposal")
doc = client.docs.create_document("Proposal")
client.docs.content.insert_text(doc.id, "Hello from GoogleKit\n", index=1)
client.docs.insert_text(doc.id, "Hello from GoogleKit\n", index=1)

# Slides — manager / shortcut
deck = client.slides.presentations.create("Pitch Deck")
deck = client.slides.create_presentation("Pitch Deck")
client.slides.pages.add(deck.id)
client.slides.add_slide(deck.id)
print(deck.id)

---

OAuth Scopes

GoogleKit uses least-privilege scope presets per service:

Profile	Typical meaning
metadata	Minimal metadata access
readonly	Read-only
readwrite	Default for most apps
full	Broadest service scope

from googlekit import GoogleKit
from googlekit.auth.scopes import ScopeProfile

client = GoogleKit.from_oauth(
    "client_secrets.json",
    services=["gdrive"],
    profile=ScopeProfile.READONLY,
)

Docs/Slides cross-service Drive helpers detect missing Drive scopes locally and raise InsufficientScopesError. Most other calls rely on Google returning HTTP 403 when the credential lacks a required scope. Calendar readwrite includes events, calendars, calendarList, and freebusy so the full CalendarClient surface works under the default preset.

---

Error Handling

GoogleKit raises typed exceptions (it does not return {"success": false} dicts):

from googlekit import GoogleKit
from googlekit.core.exceptions import GoogleKitError, NotFoundError, ValidationError

client = GoogleKit.auto(services=["gdrive"])

try:
    client.drive.files.get("missing-id")
except NotFoundError as exc:
    print(exc)
except ValidationError as exc:
    print(exc)
except GoogleKitError as exc:
    print(exc)

Common types: AuthenticationError, InsufficientScopesError, NotFoundError, RateLimitError, QuotaExceededError, ValidationError, APIError.

---

CLI

uv run googlekit --version
uv run googlekit doctor
uv run googlekit auth status

doctor checks Python, Google client libraries, detected credential files, and token cache paths — without printing secrets.

---

Requirements

• Python 3.11+
• google-api-python-client >= 2.198.0
• google-auth >= 2.55.2
• google-auth-oauthlib >= 1.4.0
• google-auth-httplib2 >= 0.4.0

---

Development

git clone https://github.com/SSujitX/GoogleKit.git
cd GoogleKit
uv sync --group dev
uv run pytest -m "not integration"
uv build

See CONTRIBUTING.md and docs/.

---

License

MIT License — see LICENSE.

---

Disclaimer

This is an independent open-source project. Google, Google Drive, Google Sheets, Google Calendar, Google Docs, Google Slides, and Google Workspace are trademarks of Google LLC. GoogleKit is not affiliated with, endorsed by, or sponsored by Google.