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 and session=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:

Batch Update Response body.

Return type:

dict

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.

Parameters:

  • id (str) – the spreadsheet ID key

  • params (dict) – (optional) the HTTP params for the GET request. By default sets the parameter includeGridData to false.

Returns:

The raw spreadsheet

Return type:

dict

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:
Returns:

Values Append Response body.

Return type:

dict

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:
Return type:

dict

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:
Returns:

Values Batch Get Response body.

Return type:

dict

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:

Values Batch Update Response body.

Return type:

dict

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:

Values Clear Response body.

Return type:

dict

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:
Returns:

Values Get Response body.

Return type:

dict

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:
Returns:

Values Update Response body.

Return type:

dict

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.