gspread_asyncio
An asyncio wrapper for burnash's excellent Google Spreadsheet API library. gspread_asyncio isn't just a plain asyncio wrapper around the gspread API, it implements several useful and helpful features on top of those APIs. It's useful for long-running processes and one-off scripts.
Requires Python >= 3.11.
Features
- Complete async wrapping of the
gspreadAPI. AllgspreadAPI calls are run off the main thread in a threadpool executor. - Internal caching and reuse of
gspreadClient/Spreadsheet/Worksheetobjects. - Automatic renewal of expired credentials.
- Automatic retries of spurious failures from Google's servers (HTTP 5xx).
- Automatic rate limiting with defaults set to Google's default API limits.
- Many methods that don't need to return a value can optionally return an already-scheduled
Future(thenowaitkwarg). You can ignore that future, allowing forward progress on your calling coroutine while the asyncio event loop schedules and runs the Google Spreadsheet API call at a later time for you.
Example usage
import asyncio
import gspread_asyncio
# from google-auth package
from google.oauth2.service_account import Credentials
# First, set up a callback function that fetches our credentials off the disk.
# gspread_asyncio needs this to re-authenticate when credentials expire.
def get_creds():
# To obtain a service account JSON file, follow these steps:
# https://gspread.readthedocs.io/en/latest/oauth2.html#for-bots-using-service-account
creds = Credentials.from_service_account_file("serviceacct_spreadsheet.json")
scoped = creds.with_scopes([
"https://spreadsheets.google.com/feeds",
"https://www.googleapis.com/auth/spreadsheets",
"https://www.googleapis.com/auth/drive",
])
return scoped
# Create a ClientManager object which
# will give us access to the Spreadsheet API.
cm = gspread_asyncio.ClientManager(get_creds)
# Here's an example of how you use the API:
async def example(cm):
# Always authorize first.
# If you have a long-running program call authorize() repeatedly.
c = await cm.authorize()
ss = await c.create("Test Spreadsheet")
print("Spreadsheet URL: https://docs.google.com/spreadsheets/d/{0}".format(ss.id))
print("Open the URL in your browser to see gspread_asyncio in action!")
# Allow anyone with the URL to write to this spreadsheet.
await c.insert_permission(ss.id, None, perm_type="anyone", role="writer")
# Create a new spreadsheet but also grab a reference to the default one.
ws = await ss.add_worksheet("My Test Worksheet", 10, 5)
zero_ws = await ss.get_worksheet(0)
# Write some stuff to both spreadsheets.
for row in range(1, 11):
for col in range(1, 6):
val = "{0}/{1}".format(row, col)
await ws.update_cell(row, col, val + " ws")
await zero_ws.update_cell(row, col, val + " zero ws")
print("All done!")
# Turn on debugging if you're new to asyncio!
asyncio.run(example(cm), debug=True)
Observational notes and gotchas
- This module does not define its own exceptions, it propagates instances of
gspread.exceptions.GSpreadException. - Always call
ClientManager.authorize(),Client.open_*()andSpreadsheet.get_worksheet()before doing any work on a spreadsheet. These methods keep an internal cache so it is painless to call them many times, even inside of a loop. This makes sure you always have a valid set of authentication credentials from Google. - The only object you should store in your application is the
ClientManager(cm). - Right now the
gspreadlibrary does not support bulk appends of rows or bulk changes of cells. When this is donegspread_asynciowill support batching of these Google API calls without any changes to the Pythongspread_asyncioAPI. - I came up with the default 1.1 second delay between API calls (the
gspread_delaykwarg) after extensive experimentation. The official API rate limit is one call every second but however Google measures these things introduces a tiny bit of jitter that will get you rate blocked if you ride that limit exactly. - Google's service reliability on these endpoints is surprisingly bad. There are frequent HTTP 500s and the retry logic will save your butt in long-running scripts or short, one-shot, one-off ones.
- Experimentation also found that Google's credentials expire after an hour and the default
reauth_intervalof 45 minutes takes care of that just fine.
License
MIT
Sponsorship
Development of gspread_asyncio is sponsored by Pro Football History.com, your source for NFL coaching biographies.
Metadata
Release files for gspread-asyncio 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gspread_asyncio-3.0.0.tar.gz | 28.3 kB | Without provenance | Details for gspread_asyncio-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gspread_asyncio-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for gspread_asyncio-3.0.0-py3-none-any.whl |
Total release size: 54.2 kB
Release files / gspread_asyncio-3.0.0.tar.gz
| Download URL | gspread_asyncio-3.0.0.tar.gz |
|---|---|
| Size | 28.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0d332e48717cdf8455707e5fb8ee00f1ffe6f998e93df9d24e5d307a26cae81d
|
|
BLAKE2b-256 checksum How to use checksums |
c3ad55372b07a4d982cbb93def5ff0c9e3e3cf639033a5e7f0e0f17d9ef1154e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / gspread_asyncio-3.0.0-py3-none-any.whl
| Download URL | gspread_asyncio-3.0.0-py3-none-any.whl |
|---|---|
| Size | 25.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6caf9f04933c9eb722c8188610921f5a4a8bebcf2031a0387c346852a020b495
|
|
BLAKE2b-256 checksum How to use checksums |
c902655dfd97686aa8393dd1cd5661d8877848cd6097c693cc3c566f39d7f895
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for gspread-asyncio 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.