Registry / gcp / gspread-dataframe

gspread-dataframe

JSON →
library4.0.0pypypi✓ verified 28d ago

gspread-dataframe (version 4.0.0) is a Python library that simplifies reading from and writing to Google Sheets using pandas DataFrames. It acts as an extension to the `gspread` library, providing convenient functions to convert worksheet data into DataFrames and vice-versa. The library is actively maintained, with a focus on seamless integration between Google Sheets and pandas.

pip install gspread-dataframe
INSTALL
IMPORT
SIG · GSPREAD-DATAFRAME
G
gspread-dataframe
gcppythonv4.0.0
Install
10.5s avg
Import
1948ms
Disk
193MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v4.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.014s · 192.2MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 10.5s · import 1.882s · 185MB
193MB installed
● package 193MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_as_dataframe
✓ from gspread_dataframe import get_as_dataframe
set_with_dataframe
✓ from gspread_dataframe import set_with_dataframe

This quickstart demonstrates how to read data from a Google Sheet into a pandas DataFrame using `get_as_dataframe` and write a DataFrame back to a sheet using `set_with_dataframe`. It includes a mock gspread worksheet for immediate runnability. In a real scenario, you'd authenticate with `gspread` (e.g., via a service account JSON file) and obtain a `worksheet` object from your Google Spreadsheet.

import gspread import pandas as pd from gspread_dataframe import get_as_dataframe, set_with_dataframe import os # --- Gspread Authentication (replace with your actual setup) --- # For service account authentication, ensure 'service_account.json' is in your path # and shared with the client_email in that file. # For a runnable example, we'll mock gspread client/worksheet objects. # In a real application, you would use: # gc = gspread.service_account(filename=os.environ.get('GOOGLE_APPLICATION_CREDENTIALS')) # spreadsheet = gc.open('Your Spreadsheet Name') # worksheet = spreadsheet.worksheet('Sheet1') class MockWorksheet: def __init__(self, data=None): self._values = [list(row) for row in data] if data else [] def get_all_values(self): return self._values def update(self, range_name, values): # Simple mock update for demonstration if range_name == 'A1': # Assume A1 starts the update for r_idx, row in enumerate(values): if r_idx < len(self._values): for c_idx, val in enumerate(row): if c_idx < len(self._values[r_idx]): self._values[r_idx][c_idx] = val else: self._values[r_idx].append(val) else: self._values.append(list(row)) # Create a mock worksheet with some initial data mock_data = [ ['Name', 'Age', 'City'], ['Alice', '30', 'New York'], ['Bob', '24', 'London'], ['Charlie', '35', 'Paris'] ] worksheet = MockWorksheet(mock_data) # Read worksheet into a DataFrame df = get_as_dataframe(worksheet) print("DataFrame from Worksheet:") print(df) # Modify the DataFrame df['Age'] = df['Age'].astype(int) + 1 df['Country'] = ['USA', 'UK', 'France'] # Write DataFrame back to worksheet # Note: resize=True will clear existing data and resize the sheet. # include_index=False by default. set_with_dataframe(worksheet, df, resize=True, include_column_header=True) print("\nUpdated Worksheet (mocked values):") print(worksheet.get_all_values()) # Example of reading with pandas options # df_parsed = get_as_dataframe(worksheet, parse_dates=['birth_date'], skiprows=1, header=None) # print(df_parsed)
Debug
Known issues
breakingIn version 4.0.0, the `get_as_dataframe` function's `drop_empty_rows` and `drop_empty_columns` parameters changed their default value to `True`. This means empty rows and columns at the end of a sheet will now be automatically discarded when reading, which might alter the DataFrame structure for existing code expecting these rows/columns.
fix
If you need to retain all rows and columns, including trailing empty ones, explicitly set `drop_empty_rows=False` and `drop_empty_columns=False` when calling `get_as_dataframe`.
affects: 4.0.0 and later
gotchaVersion 4.0.0 and later of `gspread-dataframe` officially support Python 3 only. If you are using Python 2.7, you must use `gspread-dataframe` releases prior to 4.0.0 (e.g., 2.1.1 or earlier).
fix
Upgrade to Python 3 or pin your `gspread-dataframe` dependency to a version compatible with Python 2.7 (e.g., `gspread-dataframe<4.0.0`).
affects: 4.0.0 and later
gotcha`gspread-dataframe` requires specific versions of its core dependencies. For `gspread-dataframe` versions 4.0.0+, you need `gspread>=3.0.0` and `pandas>=0.24.0`. Using older `gspread-dataframe` versions (2.1.1 or earlier) is necessary if you are tied to older `gspread` versions.
fix
Ensure your `gspread` and `pandas` installations meet the minimum requirements for your `gspread-dataframe` version to avoid compatibility issues.
affects: All versions
gotchaThe `get_as_dataframe` function uses the 'python' engine for pandas' text parsing, which means only options supported by this engine can be passed via the `**options` argument (e.g., `parse_dates`, `skiprows`, `header`). Some advanced `pandas.read_csv` options might not work.
fix
Consult the pandas documentation for `pandas.read_csv` and ensure any passed options are compatible with the 'python' parsing engine. Process the DataFrame further with pandas after initial loading if more complex parsing is needed.
affects: All versions
gotchaThe underlying `gspread` library, and by extension `gspread-dataframe`, requires careful handling of Google Sheets API authentication (e.g., Service Account or OAuth Client ID) and explicit sharing of the target spreadsheet with the authenticated client email. Misconfiguration is a common source of `gspread.exceptions.SpreadsheetNotFound` or permission errors.
fix
Follow the `gspread` authentication guide to set up credentials correctly. Crucially, share your Google Sheet with the client email address specified in your service account JSON file or OAuth client ID.
affects: All versions (inherent to gspread)
gotchaWhen reading data from Google Sheets, `get_as_dataframe` may initially return all columns with a pandas 'object' dtype. This requires manual type conversion (e.g., to `int`, `float`, `datetime`) if numeric or date-time operations are intended.
fix
After loading the DataFrame, use `df['column'].astype(type)` or `pd.to_numeric(df['column'])`, `pd.to_datetime(df['column'])` to cast columns to their appropriate data types.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gspread_dataframe'
The `gspread-dataframe` library is not installed in the Python environment you are using.
fix
Install the library using pip: `pip install gspread-dataframe`
NameError: name 'set_with_dataframe' is not defined
The `set_with_dataframe` function was called without being properly imported from the `gspread_dataframe` module, or the library itself is not installed.
fix
Ensure you have imported the function: `from gspread_dataframe import set_with_dataframe` (and `pip install gspread-dataframe` if not already installed).
This action would increase the number of cells in the workbook above the limit of 10000000 cells.
Attempting to write a pandas DataFrame to a Google Sheet that would exceed Google Sheets' maximum cell limit (10 million cells) due to the DataFrame's size or the sheet's current dimensions.
fix
To replace the sheet's content entirely and resize it to fit the DataFrame, use `set_with_dataframe(worksheet, dataframe, replace=True)`. For very large datasets, consider resizing the sheet to 1x1 first: `worksheet.resize(1, 1)`.
TypeError: Object of type int64 is not JSON serializable
When writing a pandas DataFrame to Google Sheets, some NumPy-specific data types (like `numpy.int64` or `numpy.float64`) are not directly JSON serializable by the Google Sheets API.
fix
Convert problematic DataFrame columns to standard Python types or strings before writing. For example, `df = df.astype(object)` or convert specific columns: `df['int_column'] = df['int_column'].astype(int)` or `df['float_column'] = df['float_column'].astype(float)`.
AttributeError: module 'gspread' has no attribute 'service_account'
This error occurs when an older version of the `gspread` library is installed. The `service_account` method for authentication was introduced in `gspread` v4.0.0.
fix
Upgrade your `gspread` library to the latest version: `pip install --upgrade gspread`. Ensure `gspread-dataframe` is also updated to a compatible version.
Upgrade
Version history
4.0.0latest on PyPI · released Jun 12, 2024
Audit
Dependencies
gspreadrequiredCore library for interacting with Google Sheets.
pandasrequiredRequired for DataFrame operations.
gspread-formattingoptionalOptional, for advanced worksheet formatting based on DataFrame data.
Agent activity
30 hits · last 30 days
node
24
OpenAI (training)
1
Resources
gspread-dataframe — pip install gspread-dataframe · libregistry