Client

class gspread.Client(auth: ~google.auth.credentials.Credentials, http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>, session: ~requests.Session | None = None)

An instance of this class Manages Spreadsheet files

It is used to:

open/create/list/delete spreadsheets
create/delete/list spreadsheet permission
etc

It is the gspread entry point. It will handle creating necessary Spreadsheet instances.

copy(file_id: str, title: str | None = None, copy_permissions: bool = False, folder_id: str | None = None, copy_comments: bool = True) → Spreadsheet

Copies a spreadsheet.

Parameters:

file_id (str) – A key of a spreadsheet to copy.
title (str) – (optional) A title for the new spreadsheet.
copy_permissions (bool) – (optional) If True, copy permissions from the original spreadsheet to the new spreadsheet.
folder_id (str) – Id of the folder where we want to save the spreadsheet.
copy_comments (bool) – (optional) If True, copy the comments from the original spreadsheet to the new spreadsheet.

Returns:

a Spreadsheet instance.

New in version 3.1.0.

Note

If you’re using custom credentials without the Drive scope, you need to add https://www.googleapis.com/auth/drive to your OAuth scope in order to use this method.

Example:

scope = [
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/drive'
]

Otherwise, you will get an Insufficient Permission error when you try to copy a spreadsheet.

create(title: str, folder_id: str | None = None) → Spreadsheet

Creates a new spreadsheet.

Parameters:

title (str) – A title of a new spreadsheet.
folder_id (str) – Id of the folder where we want to save the spreadsheet.

Returns:

a Spreadsheet instance.

del_spreadsheet(file_id: str) → None

Deletes a spreadsheet.

Parameters:: file_id (str) – a spreadsheet ID (a.k.a file ID).

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.

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) → None

Imports data into the first page of the spreadsheet.

Parameters:

file_id (str) –
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, value: str | None = None, perm_type: str | None = None, role: str | None = 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).
value (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) – (optional) Whether to send an email to the target user/domain.
email_message (str) – (optional) An email message to be sent if notify=True.
with_link (bool) – (optional) Whether the link is required for this permission to be active.

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

list_spreadsheet_files(title: str | None = None, folder_id: str | None = None) → List[Dict[str, Any]]

List all the spreadsheet files

Will list all spreadsheet files owned by/shared with this user account.

Parameters:

title (str) – Filter only spreadsheet files with this title
folder_id (str) – Only look for spreadsheet files in this folder The parameter folder_id can be obtained from the URL when looking at a folder in a web browser as follow: https://drive.google.com/drive/u/0/folders/<folder_id>

Returns:

a list of dicts containing the keys id, name, createdTime and modifiedTime.

open(title: str, folder_id: str | None = None) → Spreadsheet

Opens a spreadsheet.

Parameters:

title (str) – A title of a spreadsheet.
folder_id (str) – (optional) If specified can be used to filter spreadsheets by parent folder ID.

Returns:

a Spreadsheet instance.

If there’s more than one spreadsheet with same title the first one will be opened.

Raises:: gspread.SpreadsheetNotFound – if no spreadsheet with specified title is found.

>>> gc.open('My fancy spreadsheet')

open_by_key(key: str) → Spreadsheet

Opens a spreadsheet specified by key (a.k.a Spreadsheet ID).

Parameters:: key (str) – A key of a spreadsheet as it appears in a URL in a browser.
Returns:: a Spreadsheet instance.

>>> gc.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')

open_by_url(url: str) → Spreadsheet

Opens a spreadsheet specified by url.

Parameters:: url (str) – URL of a spreadsheet as it appears in a browser.
Returns:: a Spreadsheet instance.
Raises:: gspread.SpreadsheetNotFound – if no spreadsheet with specified url is found.

>>> gc.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')

openall(title: str | None = None) → List[Spreadsheet]

Opens all available spreadsheets.

Parameters:: title (str) – (optional) If specified can be used to filter spreadsheets by title.
Returns:: a list of Spreadsheet instances.

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.