Top level

gspread.oauth(scopes=['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow=<function local_server_flow>, credentials_filename=PosixPath('/home/docs/.config/gspread/credentials.json'), authorized_user_filename=PosixPath('/home/docs/.config/gspread/authorized_user.json'), client_factory=<class 'gspread.client.Client'>)

Authenticate with OAuth Client ID.

By default this function will use the local server strategy and open the authorization URL in the user’s browser:

gc = gspread.oauth()

Another option is to run a console strategy. This way, the user is instructed to open the authorization URL in their browser. Once the authorization is complete, the user must then copy & paste the authorization code into the application:

gc = gspread.oauth(flow=gspread.auth.console_flow)

scopes parameter defaults to read/write scope available in gspread.auth.DEFAULT_SCOPES. It’s read/write for Sheets and Drive API:

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

You can also use gspread.auth.READONLY_SCOPES for read only access. Obviously any method of gspread that updates a spreadsheet will not work in this case:

gc = gspread.oauth(scopes=gspread.auth.READONLY_SCOPES)

sh = gc.open("A spreadsheet")
sh.sheet1.update('A1', '42')   # <-- this will not work

If you’re storing your user credentials in a place other than the default, you may provide a path to that file like so:

gc = gspread.oauth(
    credentials_filename='/alternative/path/credentials.json',
    authorized_user_filename='/alternative/path/authorized_user.json',
)
Parameters

  • scopes (list) – The scopes used to obtain authorization.

  • flow (function) – OAuth flow to use for authentication. Defaults to local_server_flow()

  • credentials_filename (str) –

    Filepath (including name) pointing to a credentials .json file. Defaults to DEFAULT_CREDENTIALS_FILENAME:

    • %APPDATA%gspreadcredentials.json on Windows

    • ~/.config/gspread/credentials.json everywhere else

  • authorized_user_filename (str) –

    Filepath (including name) pointing to an authorized user .json file. Defaults to DEFAULT_AUTHORIZED_USER_FILENAME:

    • %APPDATA%gspreadauthorized_user.json on Windows

    • ~/.config/gspread/authorized_user.json everywhere else

  • client_factory (gspread.ClientFactory) – A factory function that returns a client class. Defaults to gspread.Client (but could also use gspread.BackoffClient to avoid rate limiting)

Return type

gspread.client.Client

gspread.service_account(filename=PosixPath('/home/docs/.config/gspread/service_account.json'), scopes=['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], client_factory=<class 'gspread.client.Client'>)

Authenticate using a service account.

scopes parameter defaults to read/write scope available in gspread.auth.DEFAULT_SCOPES. It’s read/write for Sheets and Drive API:

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

You can also use gspread.auth.READONLY_SCOPES for read only access. Obviously any method of gspread that updates a spreadsheet will not work in this case.

Parameters

  • filename (str) – The path to the service account json file.

  • scopes (list) – The scopes used to obtain authorization.

  • client_factory (gspread.ClientFactory) – A factory function that returns a client class. Defaults to gspread.Client (but could also use gspread.BackoffClient to avoid rate limiting)

Return type

gspread.client.Client

gspread.authorize(credentials, client_factory=<class 'gspread.client.Client'>)

Login to Google API using OAuth2 credentials. This is a shortcut/helper function which instantiates a client using client_factory. By default gspread.Client is used (but could also use gspread.BackoffClient to avoid rate limiting).

Returns

An instance of the class produced by client_factory.

Return type

gspread.client.Client