gsheets

raw JSON →

0.6.1 verified Mon Apr 27 auth: no python

Pythonic wrapper for the Google Sheets API (v4). Current version 0.6.1, requires Python >=3.7. Low release cadence.

pip install gsheets

Common errors

error ImportError: cannot import name 'SheetsManager' from 'gsheets' ↓

cause SheetsManager was renamed to Sheets in v0.3.

fix

Change import to 'from gsheets import Sheets'

error AttributeError: 'Sheets' object has no attribute 'from_files' ↓

cause Using an older version (<0.3) that didn't have the class-based API.

fix

Upgrade to latest: pip install --upgrade gsheets

error google.auth.exceptions.RefreshError: invalid_grant ↓

cause OAuth token expired or client_secret.json is incorrect.

fix

Delete storage.json and re-authenticate, or regenerate client_secret.json from Google Cloud Console.

Warnings

gotcha The library uses oauth2client (deprecated). For new projects, consider switching to google-auth directly. ↓

fix Use google-auth and google-api-python-client with manual credentials.

deprecated SheetsManager was renamed to Sheets in v0.3. Importing SheetsManager will break. ↓

fix Use 'from gsheets import Sheets' instead.

gotcha Spreadsheet keys are case-sensitive and must be the full ID from URL, not the URL itself. ↓

fix Extract the key from the URL: https://docs.google.com/spreadsheets/d/<KEY>/edit

gotcha Rows returned are 1-indexed and include header row by default. The first data row is row 2. ↓

fix Use sheet.to_frame(head=1) to skip header if using pandas.

Imports

SheetsManager
wrong
```
from gsheets import SheetsManager
```
correct
```
from gsheets import Sheets
```
Old class name; SheetsManager was renamed to Sheets in v0.3
Sheets
```
from gsheets import Sheets
```

Quickstart

Initialize with OAuth client secret file, then access spreadsheet by key.

from gsheets import Sheets

sheets = Sheets.from_files('client_secret.json', 'storage.json')
# Or via environment variable for CI:
import os
sheets = Sheets.from_files(os.environ.get('GSHEETS_CLIENT_SECRET', 'client_secret.json'), os.environ.get('GSHEETS_STORAGE', 'storage.json'))

sheet = sheets['<SPREADSHEET_KEY>']
print(sheet.title)