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.

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) → 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).

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).

remove_permission(file_id: str, permission_id: str) → None

Deletes a permission from a file.

Parameters:

  • file_id (str) – a spreadsheet ID (aka file ID.)

  • permission_id (str) – an ID for the permission.

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.