Client

class gspread.Client(auth, session=None)

An instance of this class communicates with Google API.

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

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)

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.

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

open(title, folder_id=None)

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)

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.

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

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

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, session=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.