gspread_asyncio

一个asyncio包装器，用于burnash的出色Google电子表格API库。 gspread_asyncio不仅仅是对gspread API的普通asyncio包装，它在那些API之上实现了几个有用和有帮助的功能。它适用于长时间运行的过程和一次性脚本。

需要Python >= 3.8。

特性

• 完整地异步包装了gspread API。所有gspread API调用都在threadpool executor的主线程外运行。
• 内部缓存和重用gspread的Client/Spreadsheet/Worksheet对象。
• 自动更新过期的凭证。
• 自动重试来自Google服务器的错误（HTTP 5xx）。
• 自动速率限制，默认设置为Google默认API限制。
• 许多不需要返回值的函数可以选择返回一个已安排的Future（nowait关键字参数）。您可以忽略该future，允许您的调用协程在asyncio事件循环安排和运行Google电子表格API调用时继续前进。

示例用法

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 an AsyncioGspreadClientManager object which
# will give us access to the Spreadsheet API.

agcm = gspread_asyncio.AsyncioGspreadClientManager(get_creds)

# Here's an example of how you use the API:

async def example(agcm):
    # Always authorize first.
    # If you have a long-running program call authorize() repeatedly.
    agc = await agcm.authorize()

    ss = await agc.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 agc.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(agcm), debug=True)

观察性笔记和注意事项

• 此模块未定义自己的异常，它传播gspread.exceptions.GSpreadException的实例。
• 在进行任何电子表格操作之前，始终调用AsyncioGspreadClientManager.authorize()、AsyncioGspreadClient.open_*()和AsyncioGspreadSpreadsheet.get_worksheet()。这些方法会保持内部缓存，因此即使是在循环中多次调用它们也很方便。这确保您始终从Google获得有效的认证凭据。
• 您应该在应用程序中存储的唯一对象是AsyncioGspreadClientManager（agcm）。
• 目前，gspread库不支持批量添加行或批量更改单元格。当这样做时，gspread_asyncio将支持这些Google API调用批处理，而无需对Python gspread_asyncio API进行任何更改。
• 经过大量实验后，我提出了API调用之间的默认1.1秒延迟（gspread_delay关键字参数）。官方API速率限制为每秒一个调用，但无论如何Google衡量这些事情都会引入一点点抖动，如果您恰好遵循这个限制，就会遇到速率限制。
• Google在这些端点的服务可靠性出奇地差。经常出现HTTP 500错误，而重试逻辑将有助于长时间运行的脚本或短期的、一次性的脚本。
• 实验还发现，Google的凭证在1小时后过期，默认的reauth_interval（45分钟）可以很好地解决这个问题。

许可证

麻省理工学院

赞助

gspread_asyncio的开发由Pro Football History.com赞助，您获取NFL教练传记的来源。