gspread-asyncio

What it is and what it does

gspread_asyncio wraps gspread to make Google Spreadsheet API calls non-blocking via asyncio. Instead of freezing your program during network calls, it runs all API operations in a thread pool, allowing your coroutines to continue. The package handles several operational concerns automatically: it caches Client, Spreadsheet, and Worksheet objects to avoid redundant setup; it renews expired credentials; it retries HTTP 5xx errors from Google's servers; and it enforces rate limiting with a default 1.1-second delay between calls.

The library is designed for both long-running services and one-off scripts that need to read or write Google Sheets without blocking. You provide a callback function that loads your credentials, then create an AsyncioGspreadClientManager and await its methods. All gspread exceptions propagate unchanged, and the package offers an optional `nowait` keyword argument on certain methods to schedule work and continue immediately while the event loop handles the API call later.

Use it for

• Concurrent updates to multiple spreadsheets in a long-running service without blocking other tasks.
• Batch writing rows or cells to a spreadsheet from an async web application or data pipeline.
• Polling and updating a spreadsheet on a schedule while handling other async I/O in the same event loop.
• One-off async scripts that read from multiple spreadsheets in parallel to reduce total wall-clock time.
• Building a bot or automation that monitors and modifies spreadsheets without freezing on network latency.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

gspread-asyncio on PyPI

Before you install

Low install friction with only two runtime dependencies (requests and gspread). Maintenance is dormant—last commit was 2024-05-13 and no release since 2024-02-10—but the package is marked Production/Stable and the repository remains active and unarchived.

Requires Python >= 3.8 and a service account credentials callback function that returns appropriately scoped credentials.

License in practice

MIT license is permissive, allowing commercial and private use with minimal restrictions; you may use, modify, and distribute the package freely as long as you include the license notice.

Quickstart

import asyncio
import gspread_asyncio

def get_creds():
    # Load credentials from disk
    pass

agcm = gspread_asyncio.AsyncioGspreadClientManager(get_creds)

async def main():
    agc = await agcm.authorize()
    ss = await agc.create("Test Spreadsheet")
    print(ss.id)

asyncio.run(main())

Package facts

Evidence: gspread_asyncio-2.0.0-py3-none-any.whl

Tags

More WWW/HTTP packages

See also gspread · gspread-pandas · gspread-dataframe · gspread-formatting · gsheets · df2gspread · pygsheets · py-memoize · asynciolimiter · pyserial-asyncio