Auth
gspread.auth
Simple authentication with OAuth.
- class gspread.auth.FlowCallable(*args, **kwargs)
Protocol for OAuth flow callables.
- gspread.auth.api_key(token: str, http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) Client
Authenticate using an API key.
Allows you to open public spreadsheet files.
Warning
This method only allows you to open public spreadsheet files. It does not work for private spreadsheet files.
- Parameters:
str (token) – The actual API key to use
http_client (
gspread.http_client.HTTPClient
) – A factory function that returns a client class. Defaults togspread.http_client.HTTPClient
(but could also usegspread.http_client.BackOffHTTPClient
to avoid rate limiting)
- Return type:
- gspread.auth.authorize(credentials: ~google.auth.credentials.Credentials, http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>, session: ~requests.Session | None = None) Client
Login to Google API using OAuth2 credentials. This is a shortcut/helper function which instantiates a client using http_client. By default
gspread.HTTPClient
is used (but could also usegspread.BackOffHTTPClient
to avoid rate limiting).It can take an additional requests.Session object in order to provide you own session object.
Note
When providing your own requests.Session object, use the value None as credentials.
- Returns:
An instance of the class produced by http_client.
- Return type:
- gspread.auth.get_config_dir(config_dir_name: str = 'gspread', os_is_windows: bool = False) Path
Construct a config dir path.
- By default:
%APPDATA%gspread on Windows
~/.config/gspread everywhere else
- gspread.auth.local_server_flow(client_config: Mapping[str, Any], scopes: Iterable[str], port: int = 0) Credentials
Run an OAuth flow using a local server strategy.
Creates an OAuth flow and runs google_auth_oauthlib.flow.InstalledAppFlow.run_local_server. This will start a local web server and open the authorization URL in the user’s browser.
Pass this function to
flow
parameter ofoauth()
to run a local server flow.
- gspread.auth.oauth(scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow: ~gspread.auth.FlowCallable = <function local_server_flow>, credentials_filename: str | ~pathlib.Path = PosixPath('/home/docs/.config/gspread/credentials.json'), authorized_user_filename: str | ~pathlib.Path = PosixPath('/home/docs/.config/gspread/authorized_user.json'), http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) 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 ingspread.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 ofgspread
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_acell('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
http_client (
gspread.http_client.HTTPClient
) – A factory function that returns a client class. Defaults togspread.http_client.HTTPClient
(but could also usegspread.http_client.BackOffHTTPClient
to avoid rate limiting)
- Return type:
- gspread.auth.oauth_from_dict(credentials: ~typing.Mapping[str, ~typing.Any] | None = None, authorized_user_info: ~typing.Mapping[str, ~typing.Any] | None = None, scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], flow: ~gspread.auth.FlowCallable = <function local_server_flow>, http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) Tuple[Client, Dict[str, Any]]
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_from_dict()
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_from_dict(flow=gspread.auth.console_flow)
scopes
parameter defaults to read/write scope available ingspread.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 ofgspread
that updates a spreadsheet will not work in this case:gc = gspread.oauth_from_dict(scopes=gspread.auth.READONLY_SCOPES) sh = gc.open("A spreadsheet") sh.sheet1.update_acell('A1', '42') # <-- this will not work
This function requires you to pass the credentials directly as a python dict. After the first authentication the function returns the authenticated user info, this can be passed again to authenticate the user without the need to run the flow again.
gc = gspread.oauth_from_dict( credentials=my_creds, authorized_user_info=my_auth_user )
- Parameters:
credentials (dict) – The credentials from google cloud platform
authorized_user_info (dict) – The authenticated user if already authenticated.
scopes (list) – The scopes used to obtain authorization.
flow (function) – OAuth flow to use for authentication. Defaults to
local_server_flow()
http_client (
gspread.http_client.HTTPClient
) – A factory function that returns a client class. Defaults togspread.http_client.HTTPClient
(but could also usegspread.http_client.BackOffHTTPClient
to avoid rate limiting)
- Return type:
(
gspread.client.Client
, str)
- gspread.auth.service_account(filename: ~pathlib.Path | str = PosixPath('/home/docs/.config/gspread/service_account.json'), scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) Client
Authenticate using a service account.
scopes
parameter defaults to read/write scope available ingspread.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 ofgspread
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.
http_client (
gspread.http_client.HTTPClient
) – A factory function that returns a client class. Defaults togspread.HTTPClient
(but could also usegspread.BackOffHTTPClient
to avoid rate limiting)
- Return type:
- gspread.auth.service_account_from_dict(info: ~typing.Mapping[str, ~typing.Any], scopes: ~typing.Iterable[str] = ['https://www.googleapis.com/auth/spreadsheets', 'https://www.googleapis.com/auth/drive'], http_client: ~typing.Type[~gspread.http_client.HTTPClient] = <class 'gspread.http_client.HTTPClient'>) Client
Authenticate using a service account (json).
scopes
parameter defaults to read/write scope available ingspread.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 ofgspread
that updates a spreadsheet will not work in this case.- Parameters:
str]) (info (Mapping[str,) – The service account info in Google format
scopes (list) – The scopes used to obtain authorization.
http_client (
gspread.http_client.HTTPClient
) – A factory function that returns a client class. Defaults togspread.http_client.HTTPClient
(but could also usegspread.http_client.BackOffHTTPClient
to avoid rate limiting)
- Return type: