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.
- fetch_sheet_metadata(id: str, params: MutableMapping[str, str | int | bool | float | List[str] | None] | None = None) 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).
- set_timeout(timeout: float | Tuple[float, float]) None
How long to wait for the server to send data before giving up, as a float, or a
(connect timeout, read timeout)
tuple.Value 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.