API Reference¶

`default`(scopes[, client_id, client_secret, …])	Get credentials and default project for accessing Google APIs.
`get_user_credentials`(scopes[, client_id, …])	Gets user account credentials.
`load_user_credentials`(path)	Gets user account credentials from JSON file at `path`.
`save_user_credentials`(scopes, path[, …])	Gets user account credentials and saves them to a JSON file at `path`.
`load_service_account_credentials`(path[, scopes])	Gets service account credentials from JSON file at `path`.
`cache.CredentialsCache`()	Shared base class for crentials classes.
`cache.READ_WRITE`	Write credentials to disk and read cached credentials from disk.
`cache.REAUTH`	Write credentials to disk.
`cache.NOOP`	Noop impmentation of credentials cache.
`exceptions.PyDataCredentialsError`	Raised when invalid credentials are provided, or tokens have expired.

pydata_google_auth.default(scopes, client_id=None, client_secret=None, credentials_cache=<pydata_google_auth.cache.ReadWriteCredentialsCache object>, use_local_webserver=True, auth_local_webserver=None, redirect_uri=None)¶

Get credentials and default project for accessing Google APIs.

This method first attempts to get credentials via the google.auth.default() function. If it is unable to get valid credentials, it then attempts to get user account credentials via the pydata_google_auth.get_user_credentials() function.

Parameters

scopes (list[str]) – A list of scopes to use when authenticating to Google APIs. See the list of OAuth 2.0 scopes for Google APIs.
client_id (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client ID associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client ID associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
client_secret (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client secret associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client secret associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
credentials_cache (pydata_google_auth.cache.CredentialsCache, optional) –
An object responsible for loading and saving user credentials.

By default, pydata-google-auth reads and writes credentials in $HOME/.config/pydata/pydata_google_credentials.json or $APPDATA/.config/pydata/pydata_google_credentials.json on Windows.
use_local_webserver (bool, optional) – Use a local webserver for the user authentication google_auth_oauthlib.flow.InstalledAppFlow. Binds a webserver to an open port on localhost between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults to False, which requests a token via the console.
auth_local_webserver (deprecated) – Use the use_local_webserver parameter instead.
redirect_uri (str, optional) –
Redirect URIs are endpoints to which the OAuth 2.0 server can send responses. They may be used in situations such as
- an organization has an org specific authentication endpoint
- an organization can not use an endpoint directly because of constraints on access to the internet (i.e. when running code on a remotely hosted device).

Returns

credentials, project_id – credentials : OAuth 2.0 credentials for accessing Google APIs

project_id : A default Google developer project ID, if one could be determined from the credentials. For example, this returns the project ID associated with a service account when using a service account key file. It returns None when using user-based credentials.

Return type

tuple[google.auth.credentials.Credentials, str or None]

Raises

pydata_google_auth.exceptions.PyDataCredentialsError – If unable to get valid credentials.

pydata_google_auth.get_user_credentials(scopes, client_id=None, client_secret=None, credentials_cache=<pydata_google_auth.cache.ReadWriteCredentialsCache object>, use_local_webserver=True, auth_local_webserver=None, redirect_uri=None)¶

Gets user account credentials.

This function authenticates using user credentials, either loading saved credentials from the cache or by going through the OAuth 2.0 flow.

The default read-write cache attempts to read credentials from a file on disk. If these credentials are not found or are invalid, it begins an OAuth 2.0 flow to get credentials. You’ll open a browser window asking for you to authenticate to your Google account using the product name PyData Google Auth. The permissions it requests correspond to the scopes you’ve provided.

Additional information on the user credentials authentication mechanism can be found here.

Parameters

scopes (list[str]) –
A list of scopes to use when authenticating to Google APIs. See the list of OAuth 2.0 scopes for Google APIs.
client_id (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client ID associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client ID associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
client_secret (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client secret associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client secret associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
credentials_cache (pydata_google_auth.cache.CredentialsCache, optional) –
An object responsible for loading and saving user credentials.

By default, pydata-google-auth reads and writes credentials in $HOME/.config/pydata/pydata_google_credentials.json or $APPDATA/.config/pydata/pydata_google_credentials.json on Windows.
use_local_webserver (bool, optional) – Use a local webserver for the user authentication google_auth_oauthlib.flow.InstalledAppFlow. Binds a webserver to an open port on localhost between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults to False, which requests a token via the console.
auth_local_webserver (deprecated) – Use the use_local_webserver parameter instead.
redirect_uri (str, optional) –
Redirect URIs are endpoints to which the OAuth 2.0 server can send responses. They may be used in situations such as
- an organization has an org specific authentication endpoint
- an organization can not use an endpoint directly because of constraints on access to the internet (i.e. when running code on a remotely hosted device).

Returns

credentials – Credentials for the user, with the requested scopes.

Return type

google.oauth2.credentials.Credentials

Raises

pydata_google_auth.exceptions.PyDataCredentialsError – If unable to get valid user credentials.

pydata_google_auth.load_service_account_credentials(path, scopes=None)¶

Gets service account credentials from JSON file at path.

Parameters

path (str) – Path to credentials JSON file.
scopes (list[str], optional) –
A list of scopes to use when authenticating to Google APIs. See the list of OAuth 2.0 scopes for Google APIs.

Returns

Return type

google.oauth2.service_account.Credentials

Raises

pydata_google_auth.exceptions.PyDataCredentialsError – If unable to load service credentials.

Examples

Load credentials and use them to construct a BigQuery client.

import pydata_google_auth
import google.cloud.bigquery

credentials = pydata_google_auth.load_service_account_credentials(
    "/home/username/keys/google-service-account-credentials.json",
)
client = google.cloud.bigquery.BigQueryClient(
    credentials=credentials,
    project=credentials.project_id
)

pydata_google_auth.load_user_credentials(path)¶

Gets user account credentials from JSON file at path.

Parameters: path (str) – Path to credentials JSON file.
Returns
Return type: google.auth.credentials.Credentials
Raises: pydata_google_auth.exceptions.PyDataCredentialsError – If unable to load user credentials.

Examples

Load credentials and use them to construct a BigQuery client.

import pydata_google_auth
import google.cloud.bigquery

credentials = pydata_google_auth.load_user_credentials(
    "/home/username/keys/google-credentials.json",
)
client = google.cloud.bigquery.BigQueryClient(
    credentials=credentials,
    project="my-project-id"
)

pydata_google_auth.save_user_credentials(scopes, path, client_id=None, client_secret=None, use_local_webserver=True)¶

Gets user account credentials and saves them to a JSON file at path.

This function authenticates using user credentials by going through the OAuth 2.0 flow.

Parameters

scopes (list[str]) –
A list of scopes to use when authenticating to Google APIs. See the list of OAuth 2.0 scopes for Google APIs.
path (str) – Path to save credentials JSON file.
client_id (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client ID associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client ID associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
client_secret (str, optional) –
The client secrets to use when prompting for user credentials. Defaults to a client secret associated with pydata-google-auth.

If you are a tool or library author, you must override the default value with a client secret associated with your project. Per the Google APIs terms of service, you must not mask your API client’s identity when using Google APIs.
use_local_webserver (bool, optional) – Use a local webserver for the user authentication google_auth_oauthlib.flow.InstalledAppFlow. Binds a webserver to an open port on localhost between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults to False, which requests a token via the console.

Returns

Return type

None

Raises

pydata_google_auth.exceptions.PyDataCredentialsError – If unable to get valid user credentials.

Examples

Get credentials for Google Cloud Platform and save them to /home/username/keys/google-credentials.json.

pydata_google_auth.save_user_credentials(
    ["https://www.googleapis.com/auth/cloud-platform"],
    "/home/username/keys/google-credentials.json",
    use_local_webserver=True,
)

Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to use these credentials with Google Application Default Credentials.

export GOOGLE_APPLICATION_CREDENTIALS='/home/username/keys/google-credentials.json'

Caching implementations for reading and writing user credentials.

class pydata_google_auth.cache.CredentialsCache¶

Bases: object

Shared base class for crentials classes.

This class also functions as a noop implementation of a credentials class.

load()¶

Load credentials from disk.

Does nothing in this base class.

Returns: Returns user account credentials loaded from disk or None if no credentials could be found.
Return type: google.oauth2.credentials.Credentials, optional

save(credentials)¶

Write credentials to disk.

Does nothing in this base class.

Parameters: credentials (google.oauth2.credentials.Credentials) – User credentials to save to disk.

pydata_google_auth.cache.NOOP = <pydata_google_auth.cache.CredentialsCache object>¶

Noop impmentation of credentials cache.

This cache always reauthorizes and never save credentials to disk. Recommended for shared machines.

pydata_google_auth.cache.READ_WRITE = <pydata_google_auth.cache.ReadWriteCredentialsCache object>¶: Write credentials to disk and read cached credentials from disk.

pydata_google_auth.cache.REAUTH = <pydata_google_auth.cache.WriteOnlyCredentialsCache object>¶

Write credentials to disk. Never read cached credentials from disk.

Use this to reauthenticate and refresh the cached credentials.

class pydata_google_auth.cache.ReadWriteCredentialsCache(dirname='pydata', filename='pydata_google_credentials.json')¶

Bases: pydata_google_auth.cache.CredentialsCache

A CredentialsCache which writes to disk and reads cached credentials from disk.

Parameters

dirname (str, optional) – Name of directory to write credentials to. This directory is created within the .config subdirectory of the HOME (APPDATA on Windows) directory.
filename (str, optional) – Name of the credentials file within the credentials directory.

load()¶

Load credentials from disk.

Returns: Returns user account credentials loaded from disk or None if no credentials could be found.
Return type: google.oauth2.credentials.Credentials, optional

save(credentials)¶

Write credentials to disk.

Parameters: credentials (google.oauth2.credentials.Credentials) – User credentials to save to disk.

class pydata_google_auth.cache.WriteOnlyCredentialsCache(dirname='pydata', filename='pydata_google_credentials.json')¶

Bases: pydata_google_auth.cache.CredentialsCache

A CredentialsCache which writes to disk, but doesn’t read from disk.

Use this class to reauthorize against Google APIs and cache your credentials for later.

Parameters

dirname (str, optional) – Name of directory to write credentials to. This directory is created within the .config subdirectory of the HOME (APPDATA on Windows) directory.
filename (str, optional) – Name of the credentials file within the credentials directory.

save(credentials)¶

Write credentials to disk.

Parameters: credentials (google.oauth2.credentials.Credentials) – User credentials to save to disk.

exception pydata_google_auth.exceptions.PyDataConnectionError¶

Bases: RuntimeError

Raised when unable to fetch credentials due to connection error.

exception pydata_google_auth.exceptions.PyDataCredentialsError¶

Bases: ValueError

Raised when invalid credentials are provided, or tokens have expired.