{"id":13461681,"url":"https://github.com/burnash/gspread","last_synced_at":"2025-09-09T21:09:40.364Z","repository":{"id":1966951,"uuid":"2897853","full_name":"burnash/gspread","owner":"burnash","description":"Google Sheets Python API","archived":false,"fork":false,"pushed_at":"2025-04-02T18:17:10.000Z","size":3684,"stargazers_count":7283,"open_issues_count":62,"forks_count":958,"subscribers_count":156,"default_branch":"master","last_synced_at":"2025-05-05T16:04:03.499Z","etag":null,"topics":["google-sheets","google-sheets-api","google-sheets-api-v4","gspread","spreadsheet","spreadsheets"],"latest_commit_sha":null,"homepage":"https://docs.gspread.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/burnash.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-12-02T10:46:20.000Z","updated_at":"2025-05-04T20:45:38.000Z","dependencies_parsed_at":"2023-12-15T02:33:38.699Z","dependency_job_id":"aee564d9-09af-485b-b40b-7f6997f105b3","html_url":"https://github.com/burnash/gspread","commit_stats":{"total_commits":1563,"total_committers":185,"mean_commits":8.448648648648648,"dds":0.6826615483045426,"last_synced_commit":"94617c94ed6507dd21abb485bdaa70a82c75f1f4"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burnash%2Fgspread","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burnash%2Fgspread/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burnash%2Fgspread/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/burnash%2Fgspread/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/burnash","download_url":"https://codeload.github.com/burnash/gspread/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253801163,"owners_count":21966604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-sheets","google-sheets-api","google-sheets-api-v4","gspread","spreadsheet","spreadsheets"],"created_at":"2024-07-31T11:00:52.290Z","updated_at":"2025-05-12T18:44:14.239Z","avatar_url":"https://github.com/burnash.png","language":"Python","funding_links":[],"categories":["Third-party APIs","Python","资源列表","第三方api","第三方 API","Third-party Web APIs","Third-party APIs [🔝](#readme)","Awesome Python"],"sub_categories":["第三方 API","Third-party APIs"],"readme":"# Google Spreadsheets Python API v4\n\n![main workflow](https://img.shields.io/github/actions/workflow/status/burnash/gspread/main.yaml?logo=github)\n![GitHub licence](https://img.shields.io/pypi/l/gspread?logo=github)\n![GitHub downloads](https://img.shields.io/github/downloads-pre/burnash/gspread/latest/total?logo=github)\n![documentation](https://img.shields.io/readthedocs/gspread?logo=readthedocs)\n![PyPi download](https://img.shields.io/pypi/dm/gspread?logo=pypi)\n![PyPi version](https://img.shields.io/pypi/v/gspread?logo=pypi)\n![python version](https://img.shields.io/pypi/pyversions/gspread?style=pypi)\n\nSimple interface for working with Google Sheets.\n\nFeatures:\n\n- Open a spreadsheet by **title**, **key** or **URL**.\n- Read, write, and format cell ranges.\n- Sharing and access control.\n- Batching updates.\n\n## Installation\n\n```sh\npip install gspread\n```\n\nRequirements: Python 3.8+.\n\n## Basic Usage\n\n1. [Create credentials in Google API Console](http://gspread.readthedocs.org/en/latest/oauth2.html)\n\n2. Start using gspread\n\n```python\nimport gspread\n\n# First you need access to the Google API. Based on the route you\n# chose in Step 1, call either service_account(), oauth() or api_key().\ngc = gspread.service_account()\n\n# Open a sheet from a spreadsheet in one go\nwks = gc.open(\"Where is the money Lebowski?\").sheet1\n\n# Update a range of cells using the top left corner address\nwks.update([[1, 2], [3, 4]], \"A1\")\n\n# Or update a single cell\nwks.update_acell(\"B42\", \"it's down there somewhere, let me take another look.\")\n\n# Format the header\nwks.format('A1:B1', {'textFormat': {'bold': True}})\n```\n\n## v5.12 to v6.0 Migration Guide\n\n### Upgrade from Python 3.7\n\nPython 3.7 is [end-of-life](https://devguide.python.org/versions/). gspread v6 requires a minimum of Python 3.8.\n\n### Change `Worksheet.update` arguments\n\nThe first two arguments (`values` \u0026 `range_name`) have swapped (to `range_name` \u0026 `values`). Either swap them (works in v6 only), or use named arguments (works in v5 \u0026 v6).\n\nAs well, `values` can no longer be a list, and must be a 2D array.\n\n```diff\n- file.sheet1.update([[\"new\", \"values\"]])\n+ file.sheet1.update([[\"new\", \"values\"]]) # unchanged\n\n- file.sheet1.update(\"B2:C2\", [[\"54\", \"55\"]])\n+ file.sheet1.update([[\"54\", \"55\"]], \"B2:C2\")\n# or\n+ file.sheet1.update(range_name=\"B2:C2\", values=[[\"54\", \"55\"]])\n```\n\n### More\n\n\u003cdetails\u003e\u003csummary\u003eSee More Migration Guide\u003c/summary\u003e\n\n### Change colors from dictionary to text\n\nv6 uses hexadecimal color representation. Change all colors to hex. You can use the compatibility function `gspread.utils.convert_colors_to_hex_value()` to convert a dictionary to a hex string.\n\n```diff\n- tab_color = {\"red\": 1, \"green\": 0.5, \"blue\": 1}\n+ tab_color = \"#FF7FFF\"\nfile.sheet1.update_tab_color(tab_color)\n```\n\n### Switch lastUpdateTime from property to method\n\n```diff\n- age = spreadsheet.lastUpdateTime\n+ age = spreadsheet.get_lastUpdateTime()\n```\n\n### Replace method `Worksheet.get_records`\n\nIn v6 you can now only get *all* sheet records, using `Worksheet.get_all_records()`. The method `Worksheet.get_records()` has been removed. You can get some records using your own fetches and combine them with `gspread.utils.to_records()`.\n\n```diff\n+ from gspread import utils\n  all_records = spreadsheet.get_all_records(head=1)\n- some_records = spreadsheet.get_all_records(head=1, first_index=6, last_index=9)\n- some_records = spreadsheet.get_records(head=1, first_index=6, last_index=9)\n+ header = spreadsheet.get(\"1:1\")[0]\n+ cells = spreadsheet.get(\"6:9\")\n+ some_records = utils.to_records(header, cells)\n```\n\n### Silence warnings\n\nIn version 5 there are many warnings to mark deprecated feature/functions/methods.\nThey can be silenced by setting the `GSPREAD_SILENCE_WARNINGS` environment variable to `1`\n\n### Add more data to `gspread.Worksheet.__init__`\n\n```diff\n  gc = gspread.service_account(filename=\"google_credentials.json\")\n  spreadsheet = gc.open_by_key(\"{{key}}\")\n  properties = spreadsheet.fetch_sheet_metadata()[\"sheets\"][0][\"properties\"]\n- worksheet = gspread.Worksheet(spreadsheet, properties)\n+ worksheet = gspread.Worksheet(spreadsheet, properties, spreadsheet.id, gc.http_client)\n```\n\n\u003c/details\u003e\n\n## More Examples\n\n### Opening a Spreadsheet\n\n```python\n# You can open a spreadsheet by its title as it appears in Google Docs\nsh = gc.open('My poor gym results') # \u003c-- Look ma, no keys!\n\n# If you want to be specific, use a key (which can be extracted from\n# the spreadsheet's url)\nsht1 = gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')\n\n# Or, if you feel really lazy to extract that key, paste the entire url\nsht2 = gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE\u0026hl')\n```\n\n### Creating a Spreadsheet\n\n```python\nsh = gc.create('A new spreadsheet')\n\n# But that new spreadsheet will be visible only to your script's account.\n# To be able to access newly created spreadsheet you *must* share it\n# with your email. Which brings us to…\n```\n\n### Sharing a Spreadsheet\n\n```python\nsh.share('otto@example.com', perm_type='user', role='writer')\n```\n\n### Selecting a Worksheet\n\n```python\n# Select worksheet by index. Worksheet indexes start from zero\nworksheet = sh.get_worksheet(0)\n\n# By title\nworksheet = sh.worksheet(\"January\")\n\n# Most common case: Sheet1\nworksheet = sh.sheet1\n\n# Get a list of all worksheets\nworksheet_list = sh.worksheets()\n```\n\n### Creating a Worksheet\n\n```python\nworksheet = sh.add_worksheet(title=\"A worksheet\", rows=\"100\", cols=\"20\")\n```\n\n### Deleting a Worksheet\n\n```python\nsh.del_worksheet(worksheet)\n```\n\n### Getting a Cell Value\n\n```python\n# With label\nval = worksheet.get('B1').first()\n\n# With coords\nval = worksheet.cell(1, 2).value\n```\n\n### Getting All Values From a Row or a Column\n\n```python\n# Get all values from the first row\nvalues_list = worksheet.row_values(1)\n\n# Get all values from the first column\nvalues_list = worksheet.col_values(1)\n```\n\n### Getting All Values From a Worksheet as a List of Lists\n\n```python\nfrom gspread.utils import GridRangeType\nlist_of_lists = worksheet.get(return_type=GridRangeType.ListOfLists)\n```\n\n### Getting a range of values\n\nReceive only the cells with a value in them.\n\n```python\n\u003e\u003e\u003e worksheet.get(\"A1:B4\")\n[['A1', 'B1'], ['A2']]\n```\n\nReceive a rectangular array around the cells with values in them.\n\n```python\n\u003e\u003e\u003e worksheet.get(\"A1:B4\", pad_values=True)\n[['A1', 'B1'], ['A2', '']]\n```\n\nReceive an array matching the request size regardless of if values are empty or not.\n\n```python\n\u003e\u003e\u003e worksheet.get(\"A1:B4\", maintain_size=True)\n[['A1', 'B1'], ['A2', ''], ['', ''], ['', '']]\n```\n\n### Finding a Cell\n\n```python\n# Find a cell with exact string value\ncell = worksheet.find(\"Dough\")\n\nprint(\"Found something at R%sC%s\" % (cell.row, cell.col))\n\n# Find a cell matching a regular expression\namount_re = re.compile(r'(Big|Enormous) dough')\ncell = worksheet.find(amount_re)\n```\n\n### Finding All Matched Cells\n\n```python\n# Find all cells with string value\ncell_list = worksheet.findall(\"Rug store\")\n\n# Find all cells with regexp\ncriteria_re = re.compile(r'(Small|Room-tiering) rug')\ncell_list = worksheet.findall(criteria_re)\n```\n\n### Updating Cells\n\n```python\n# Update a single cell\nworksheet.update_acell('B1', 'Bingo!')\n\n# Update a range\nworksheet.update([[1, 2], [3, 4]], 'A1:B2')\n\n# Update multiple ranges at once\nworksheet.batch_update([{\n    'range': 'A1:B2',\n    'values': [['A1', 'B1'], ['A2', 'B2']],\n}, {\n    'range': 'J42:K43',\n    'values': [[1, 2], [3, 4]],\n}])\n```\n\n### Get unformatted cell value or formula\n\n```python\nfrom gspread.utils import ValueRenderOption\n\n# Get formatted cell value as displayed in the UI\n\u003e\u003e\u003e worksheet.get(\"A1:B2\")\n[['$12.00']]\n\n# Get unformatted value from the same cell range\n\u003e\u003e\u003e worksheet.get(\"A1:B2\", value_render_option=ValueRenderOption.unformatted)\n[[12]]\n\n# Get formula from a cell\n\u003e\u003e\u003e worksheet.get(\"C2:D2\", value_render_option=ValueRenderOption.formula)\n[['=1/1024']]\n```\n\n### Add data validation to a range\n\n```python\nimport gspread\nfrom gspread.utils import ValidationConditionType\n\n# Restrict the input to greater than 10 in a single cell\nworksheet.add_validation(\n  'A1',\n  ValidationConditionType.number_greater,\n  [10],\n  strict=True,\n  inputMessage='Value must be greater than 10',\n)\n\n# Restrict the input to Yes/No for a specific range with dropdown\nworksheet.add_validation(\n  'C2:C7',\n   ValidationConditionType.one_of_list,\n   ['Yes',\n   'No',]\n   showCustomUi=True\n)\n```\n\n## Documentation\n\n[Documentation]\\: [https://gspread.readthedocs.io/][Documentation]\n\n[Documentation]: https://gspread.readthedocs.io/en/latest/\n\n### Ask Questions\n\nThe best way to get an answer to a question is to ask on [Stack Overflow with a gspread tag](http://stackoverflow.com/questions/tagged/gspread?sort=votes\u0026pageSize=50).\n\n## Contributors\n\n[List of contributors](https://github.com/burnash/gspread/graphs/contributors)\n\n## How to Contribute\n\nPlease make sure to take a moment and read the [Code of Conduct](https://github.com/burnash/gspread/blob/master/.github/CODE_OF_CONDUCT.md).\n\n### Report Issues\n\nPlease report bugs and suggest features via the [GitHub Issues](https://github.com/burnash/gspread/issues).\n\nBefore opening an issue, search the tracker for possible duplicates. If you find a duplicate, please add a comment saying that you encountered the problem as well.\n\n### Improve Documentation\n\n[Documentation](https://gspread.readthedocs.io/) is as important as code. If you know how to make it more consistent, readable and clear, please submit a pull request. The documentation files are in [`docs`](https://github.com/burnash/gspread/tree/master/docs) folder, use [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index) markup and rendered by [Sphinx](http://www.sphinx-doc.org/).\n\n### Contribute code\n\nPlease make sure to read the [Contributing Guide](https://github.com/burnash/gspread/blob/master/.github/CONTRIBUTING.md) before making a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburnash%2Fgspread","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fburnash%2Fgspread","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fburnash%2Fgspread/lists"}