HTTP Client
Note
This class is not intended to be used directly. It is used by all gspread models to interact with the Google API
- class gspread.HTTPClient(auth: Credentials, session: Session | None = None)
An instance of this class communicates with Google API.
- Parameters:
auth (Credentials) –
An instance of google.auth.Credentials used to authenticate requests created by either:
gspread.auth.oauth()
gspread.auth.oauth_from_dict()
gspread.auth.service_account()
gspread.auth.service_account_from_dict()
session (Session) –
(Optional) An OAuth2 credential object. Credential objects created by google-auth.
You can pass you own Session object, simply pass
auth=None
andsession=my_custom_session
.
This class is not intended to be created manually. It will be created by the gspread.Client class.
- batch_update(id: str, body: Mapping[str, Any] | None) Any
Lower-level method that directly calls spreadsheets/<ID>:batchUpdate.
- Parameters:
body (dict) – Batch Update Request body.
- Returns:
- Return type:
New in version 3.0.
- export(file_id: str, format: str = ExportFormat.PDF) bytes
Export the spreadsheet in the given format.
- Parameters:
file_id (str) – The key of the spreadsheet to export
format (
ExportFormat
) –The format of the resulting file. Possible values are:
ExportFormat.PDF
ExportFormat.EXCEL
ExportFormat.CSV
ExportFormat.OPEN_OFFICE_SHEET
ExportFormat.TSV
ExportFormat.ZIPPED_HTML
See ExportFormat in the Drive API.
- Returns bytes:
The content of the exported file.
- fetch_sheet_metadata(id: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None) Mapping[str, Any]
Similar to :method spreadsheets_get:gspread.http_client.spreadsheets_get, get the spreadsheet form the API but by default does not get the cells data. It only retrieve the the metadata from the spreadsheet.
- get_file_drive_metadata(id: str) Any
Get the metadata from the Drive API for a specific file This method is mainly here to retrieve the create/update time of a file (these metadata are only accessible from the Drive API).
- import_csv(file_id: str, data: str | bytes) Any
Imports data into the first page of the spreadsheet.
- Parameters:
data (str) – A CSV string of data.
Example:
# Read CSV file contents content = open('file_to_import.csv', 'r').read() gc.import_csv(spreadsheet.id, content)
Note
This method removes all other worksheets and then entirely replaces the contents of the first worksheet.
- insert_permission(file_id: str, email_address: str | None, perm_type: str | None, role: str | None, notify: bool = True, email_message: str | None = None, with_link: bool = False) Response
Creates a new permission for a file.
- Parameters:
file_id (str) – a spreadsheet ID (aka file ID).
email_address (str, None) – user or group e-mail address, domain name or None for ‘anyone’ type.
perm_type (str) – (optional) The account type. Allowed values are:
user
,group
,domain
,anyone
role (str) – (optional) The primary role for this user. Allowed values are:
owner
,writer
,reader
notify (bool) – Whether to send an email to the target user/domain. Default
True
.email_message (str) – (optional) An email message to be sent if
notify=True
.with_link (bool) – Whether the link is required for this permission to be active. Default
False
.
- Returns dict:
the newly created permission
Examples:
# Give write permissions to otto@example.com gc.insert_permission( '0BmgG6nO_6dprnRRUWl1UFE', 'otto@example.org', perm_type='user', role='writer' ) # Make the spreadsheet publicly readable gc.insert_permission( '0BmgG6nO_6dprnRRUWl1UFE', None, perm_type='anyone', role='reader' )
- list_permissions(file_id: str) List[Dict[str, str | bool]]
Retrieve a list of permissions for a file.
- Parameters:
file_id (str) – a spreadsheet ID (aka file ID).
- set_timeout(timeout: float | Tuple[float, float] | None) None
How long to wait for the server to send data before giving up, as a float, or a
(connect timeout, read timeout)
tuple.Use value
None
to restore default timeoutValue for
timeout
is in seconds (s).
- spreadsheets_get(id: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None) Any
A method stub that directly calls spreadsheets.get.
- spreadsheets_sheets_copy_to(id: str, sheet_id: int, destination_spreadsheet_id: str) Any
Lower-level method that directly calls spreadsheets.sheets.copyTo.
- values_append(id: str, range: str, params: MutableMapping[str, str | int | bool | float | List[str] | None], body: Mapping[str, Any] | None) Any
Lower-level method that directly calls spreadsheets/<ID>/values:append.
- Parameters:
range (str) – The A1 notation of a range to search for a logical table of data. Values will be appended after the last row of the table.
params (dict) – Values Append Query parameters.
body (dict) – Values Append Request body.
- Returns:
- Return type:
New in version 3.0.
- values_batch_clear(id: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None, body: Mapping[str, Any] | None = None) Any
Lower-level method that directly calls spreadsheets/<ID>/values:batchClear
- Parameters:
params (dict) – (optional) Values Batch Clear Query parameters.
body (dict) – (optional) Values Batch Clear request body.
- Return type:
- values_batch_get(id: str, ranges: List[str], params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None) Any
Lower-level method that directly calls spreadsheets/<ID>/values:batchGet.
- Parameters:
ranges (list) –
List of ranges in the A1 notation of the values to retrieve.
params (dict) – (optional) Values Batch Get Query parameters.
- Returns:
- Return type:
- values_batch_update(id: str, body: Mapping[str, Any] | None = None) Any
Lower-level method that directly calls spreadsheets/<ID>/values:batchUpdate.
- Parameters:
body (dict) – (optional) Values Batch Update Request body.
- Returns:
- Return type:
- values_clear(id: str, range: str) Any
Lower-level method that directly calls spreadsheets/<ID>/values:clear.
- Parameters:
range (str) –
The A1 notation of the values to clear.
- Returns:
- Return type:
New in version 3.0.
- values_get(id: str, range: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None) Any
Lower-level method that directly calls GET spreadsheets/<ID>/values/<range>.
- Parameters:
range (str) –
The A1 notation of the values to retrieve.
params (dict) – (optional) Values Get Query parameters.
- Returns:
- Return type:
New in version 3.0.
- values_update(id: str, range: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None, body: Mapping[str, Any] | None = None) Any
Lower-level method that directly calls PUT spreadsheets/<ID>/values/<range>.
- Parameters:
range (str) –
The A1 notation of the values to update.
params (dict) – (optional) Values Update Query parameters.
body (dict) – (optional) Values Update Request body.
- Returns:
- Return type:
Example:
sh.values_update( 'Sheet1!A2', params={ 'valueInputOption': 'USER_ENTERED' }, body={ 'values': [[1, 2, 3]] } )
New in version 3.0.
- class gspread.BackOffHTTPClient(auth: Credentials, session: Session | None = None)
BackoffClient is a gspread client with exponential backoff retries.
In case a request fails due to some API rate limits, it will wait for some time, then retry the request.
This can help by trying the request after some time and prevent the application from failing (by raising an APIError exception).
Warning
This Client is not production ready yet. Use it at your own risk !
Note
To use with the auth module, make sure to pass this backoff client factory using the
client_factory
parameter of the method used.Note
Currently known issues are:
will retry exponentially even when the error should raise instantly. Due to the Drive API that raises 403 (Forbidden) errors for forbidden access and for api rate limit exceeded.