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