Client
- class gspread.Client(auth, session=None)
An instance of this class communicates with Google API.
- Parameters:
auth – An OAuth2 credential object. Credential objects created by google-auth.
session – (optional) A session object capable of making HTTP requests while persisting some parameters across requests. Defaults to google.auth.transport.requests.AuthorizedSession.
>>> c = gspread.Client(auth=OAuthCredentialObject)
- copy(file_id, title=None, copy_permissions=False, folder_id=None, copy_comments=True)
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, folder_id=None)
Creates a new spreadsheet.
- del_spreadsheet(file_id)
Deletes a spreadsheet.
- Parameters:
file_id (str) – a spreadsheet ID (a.k.a file ID).
- export(file_id, format='application/pdf')
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)
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, data)
Imports data into the first page of the spreadsheet.
- Parameters:
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, value, perm_type, role, notify=True, email_message=None, with_link=False)
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 ‘default’ 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)
Retrieve a list of permissions for a file.
- Parameters:
file_id (str) – a spreadsheet ID (aka file ID).
- list_spreadsheet_files(title=None, folder_id=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, folder_id=None)
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)
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)
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=None)
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, permission_id)
Deletes a permission from a file.
- set_timeout(timeout)
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).
- class gspread.client.BackoffClient(auth)
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.