Google Spreadsheets Python API
项目描述
Google Spreadsheets Python API v4
用于处理Google Sheets的简单接口。
功能
- 通过标题、密钥或URL打开电子表格。
- 读取、写入和格式化单元格范围。
- 共享和访问控制。
- 批量更新。
安装
pip install gspread
需求：Python 3.8+。
基本用法
-
开始使用gspread
import gspread
gc = gspread.service_account()
# Open a sheet from a spreadsheet in one go
wks = gc.open("Where is the money Lebowski?").sheet1
# Update a range of cells using the top left corner address
wks.update([[1, 2], [3, 4]], "A1")
# Or update a single cell
wks.update_acell("B42", "it's down there somewhere, let me take another look.")
# Format the header
wks.format('A1:B1', {'textFormat': {'bold': True}})
从v5.12到v6.0迁移指南
从Python 3.7升级
Python 3.7 已达到生命周期的结束。gspread v6 至少需要 Python 3.8。
更改 Worksheet.update 参数
前两个参数（values 和 range_name）已交换（变为 range_name 和 values）。可以交换它们（仅在 v6 中有效），或者使用命名参数（在 v5 和 v6 中都有效）。
此外，values 不能再是列表，而必须是二维数组。
- file.sheet1.update([["new", "values"]])
+ file.sheet1.update([["new", "values"]]) # unchanged
- file.sheet1.update("B2:C2", [["54", "55"]])
+ file.sheet1.update([["54", "55"]], "B2:C2")
# or
+ file.sheet1.update(range_name="B2:C2", values=[["54", "55"]])
更多
查看更多迁移指南
将颜色从字典更改为文本
v6 使用十六进制颜色表示。将所有颜色更改为十六进制。可以使用兼容函数 gspread.utils.convert_colors_to_hex_value() 将字典转换为十六进制字符串。
- tab_color = {"red": 1, "green": 0.5, "blue": 1}
+ tab_color = "#FF7FFF"
file.sheet1.update_tab_color(tab_color)
将 lastUpdateTime 从属性更改为方法
- age = spreadsheet.lastUpdateTime
+ age = spreadsheet.get_lastUpdateTime()
替换方法 Worksheet.get_records
在 v6 中，现在您只能使用 Worksheet.get_all_records() 获取所有工作表记录。已删除 Worksheet.get_records() 方法。您可以通过自己的获取操作获取一些记录，并使用 gspread.utils.to_records() 将它们组合起来。
+ from gspread import utils
all_records = spreadsheet.get_all_records(head=1)
- some_records = spreadsheet.get_all_records(head=1, first_index=6, last_index=9)
- some_records = spreadsheet.get_records(head=1, first_index=6, last_index=9)
+ header = spreadsheet.get("1:1")[0]
+ cells = spreadsheet.get("6:9")
+ some_records = utils.to_records(header, cells)
静音警告
在版本 5 中，有许多警告用于标记已弃用的功能/函数/方法。可以通过将环境变量 GSPREAD_SILENCE_WARNINGS 设置为 1 来静音它们。
向 gspread.Worksheet.__init__ 添加更多数据
gc = gspread.service_account(filename="google_credentials.json")
spreadsheet = gc.open_by_key("{{key}}")
properties = spreadsheet.fetch_sheet_metadata()["sheets"][0]["properties"]
- worksheet = gspread.Worksheet(spreadsheet, properties)
+ worksheet = gspread.Worksheet(spreadsheet, properties, spreadsheet.id, gc.http_client)
更多示例
打开电子表格
# You can open a spreadsheet by its title as it appears in Google Docs
sh = gc.open('My poor gym results') # <-- Look ma, no keys!
# If you want to be specific, use a key (which can be extracted from
# the spreadsheet's url)
sht1 = gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')
# Or, if you feel really lazy to extract that key, paste the entire url
sht2 = gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')
创建电子表格
sh = gc.create('A new spreadsheet')
# But that new spreadsheet will be visible only to your script's account.
# To be able to access newly created spreadsheet you *must* share it
# with your email. Which brings us to…
共享电子表格
sh.share('otto@example.com', perm_type='user', role='writer')
选择工作表
# Select worksheet by index. Worksheet indexes start from zero
worksheet = sh.get_worksheet(0)
# By title
worksheet = sh.worksheet("January")
# Most common case: Sheet1
worksheet = sh.sheet1
# Get a list of all worksheets
worksheet_list = sh.worksheets()
创建工作表
worksheet = sh.add_worksheet(title="A worksheet", rows="100", cols="20")
删除工作表
sh.del_worksheet(worksheet)
获取单元格值
# With label
val = worksheet.get('B1').first()
# With coords
val = worksheet.cell(1, 2).value
获取一行或一列的所有值
# Get all values from the first row
values_list = worksheet.row_values(1)
# Get all values from the first column
values_list = worksheet.col_values(1)
以列表列表的形式获取工作表的所有值
from gspread.utils import GridRangeType
list_of_lists = worksheet.get(return_type=GridRangeType.ListOfLists)
获取值范围
仅接收有值的单元格。
>>> worksheet.get("A1:B4")
[['A1', 'B1'], ['A2']]
接收围绕有值单元格的矩形数组。
>>> worksheet.get("A1:B4", pad_values=True)
[['A1', 'B1'], ['A2', '']]
接收与请求大小匹配的数组，无论值是否为空。
>>> worksheet.get("A1:B4", maintain_size=True)
[['A1', 'B1'], ['A2', ''], ['', ''], ['', '']]
查找单元格
# Find a cell with exact string value
cell = worksheet.find("Dough")
print("Found something at R%sC%s" % (cell.row, cell.col))
# Find a cell matching a regular expression
amount_re = re.compile(r'(Big|Enormous) dough')
cell = worksheet.find(amount_re)
查找所有匹配的单元格
# Find all cells with string value
cell_list = worksheet.findall("Rug store")
# Find all cells with regexp
criteria_re = re.compile(r'(Small|Room-tiering) rug')
cell_list = worksheet.findall(criteria_re)
更新单元格
# Update a single cell
worksheet.update_acell('B1', 'Bingo!')
# Update a range
worksheet.update([[1, 2], [3, 4]], 'A1:B2')
# Update multiple ranges at once
worksheet.batch_update([{
'range': 'A1:B2',
'values': [['A1', 'B1'], ['A2', 'B2']],
}, {
'range': 'J42:K43',
'values': [[1, 2], [3, 4]],
}])
获取未格式化的单元格值或公式
from gspread.utils import ValueRenderOption
# Get formatted cell value as displayed in the UI
>>> worksheet.get("A1:B2")
[['$12.00']]
# Get unformatted value from the same cell range
>>> worksheet.get("A1:B2", value_render_option=ValueRenderOption.unformatted)
[[12]]
# Get formula from a cell
>>> worksheet.get("C2:D2", value_render_option=ValueRenderOption.formula)
[['=1/1024']]
### Add data validation to a range
```python
import gspread
from gspread.utils import ValidationConditionType
# Restrict the input to greater than 10 in a single cell
worksheet.add_validation(
'A1',
ValidationConditionType.number_greater,
[10],
strict=True,
inputMessage='Value must be greater than 10',
)
# Restrict the input to Yes/No for a specific range with dropdown
worksheet.add_validation(
'C2:C7',
ValidationConditionType.one_of_list,
['Yes',
'No',]
showCustomUi=True
)
文档
文档: https://gspread.readthedocs.io/
提问
在带有 gspread 标签的 Stack Overflow 上提问是获取答案的最佳方式。
贡献者
如何贡献
请花点时间阅读 行为准则。
报告问题
请通过 GitHub Issues 报告错误和提出功能建议。
在提交问题之前，请在跟踪器中搜索可能的重复项。如果您发现重复项，请添加一条评论，说明您也遇到了该问题。
改进文档
文档 与代码一样重要。如果您知道如何使其更一致、可读和清晰，请提交一个拉取请求。文档文件位于 docs 文件夹中，使用 reStructuredText 标记，并由 Sphinx 渲染。
贡献代码
在提交拉取请求之前，请确保阅读 贡献指南。
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
源分布
gspread-6.1.3.tar.gz (78.3 kB 查看哈希值)
构建分布
gspread-6.1.3-py3-none-any.whl (57.6 kB 查看哈希值)
