pygsheets Reference

pygsheets is a simple `Google Spreadsheets v4 `_ API wrapper.

Top Level Interface

pygsheets.authorize(outh_file='client_secret.json', outh_creds_store=None, outh_nonlocal=False, service_file=None, credentials=None, **client_kwargs)[source]

Login to Google API using OAuth2 credentials.

This function instantiates Client and performs authentication.

Parameters:
  • outh_file – path to outh2 credentials file, or tokens file
  • outh_creds_store – path to directory where tokens should be stored ‘global’ if you want to store in system-wide location None if you want to store in current script directory
  • outh_nonlocal – if the authorization should be done in another computer, this will provide a url which when run will ask for credentials
  • service_file – path to service credentials file
  • credentials – outh2 credentials object
  • no_cache – (http client arg) do not ask http client to use a cache in tmp dir, useful for environments where filesystem access prohibited default: False
Returns:

Client instance.

class pygsheets.Client(oauth, http_client=None, retries=1, no_cache=False)[source]

An instance of this class communicates with Google API.

Parameters:
  • oauth – An OAuth2 credential object. Credential objects are those created by the oauth2client library. https://github.com/google/oauth2client
  • http_client – (optional) A object capable of making HTTP requests
  • retries – (optional) The number of times connection will be tried before raising a timeout error.
>>> c = pygsheets.Client(oauth=OAuthCredentialObject)
create(title, parent_id=None)[source]

Creates a spreadsheet, returning a Spreadsheet instance.

Parameters:
  • parent_id – id of the parent folder, where the spreadsheet is to be created
  • title – A title of a spreadsheet.
delete(title=None, spreadsheet_id=None)[source]

Deletes, a spreadsheet by title or id.

Parameters:
  • title – title of a spreadsheet.
  • spreadsheet_id – id of a spreadsheet this takes precedence if both given.
Raises:

pygsheets.SpreadsheetNotFound – if no spreadsheet is found.

open(title)[source]

Opens a spreadsheet, returning a Spreadsheet instance.

Parameters:title – A title of a spreadsheet.

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

Raises:pygsheets.SpreadsheetNotFound – if no spreadsheet with specified title is found.
open_by_key(key, returnas='spreadsheet')[source]

Opens a spreadsheet specified by key, returning a Spreadsheet instance.

Parameters:
  • key – A key of a spreadsheet as it appears in a URL in a browser.
  • returnas – return as spreadsheet or json object
Raises:

pygsheets.SpreadsheetNotFound – if no spreadsheet with specified key is found.

>>> c = pygsheets.authorize()
>>> c.open_by_key('0BmgG6nO_6dprdS1MN3d3MkdPa142WFRrdnRRUWl1UFE')
open_by_url(url)[source]

Opens a spreadsheet specified by url,

Parameters:url – URL of a spreadsheet as it appears in a browser.
Raises:pygsheets.SpreadsheetNotFound – if no spreadsheet with specified url is found.
Returns:a :class: pygsheets.Spreadsheet instance.
>>> c = pygsheets.authorize()
>>> c.open_by_url('https://docs.google.com/spreadsheet/ccc?key=0Bm...FE&hl')
open_all(title=None)[source]

Opens all available spreadsheets,

Parameters:title – (optional) If specified can be used to filter spreadsheets by title.
Returns:list of Spreadsheet instances
list_ssheets()[source]

Lists all spreadsheets

Models

The models represent common spreadsheet objects: spreadsheet, worksheet and cell.

Exceptions

exception pygsheets.AuthenticationError[source]

An error during authentication process.

exception pygsheets.SpreadsheetNotFound[source]

Trying to open non-existent or inaccessible spreadsheet.

exception pygsheets.WorksheetNotFound[source]

Trying to open non-existent or inaccessible worksheet.

exception pygsheets.NoValidUrlKeyFound[source]

No valid key found in URL.

exception pygsheets.IncorrectCellLabel[source]

The cell label is incorrect.

exception pygsheets.RequestError[source]

Error while sending API request.

exception pygsheets.InvalidUser[source]

Invalid user/domain

exception pygsheets.InvalidArgumentValue[source]

Invalid value for argument

Indices and tables