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.
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=False, auth_local_webserver=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. Defaults to False, which requests a token via the console.
  • auth_local_webserver (deprecated) – Use the use_local_webserver parameter instead.
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=False, auth_local_webserver=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 credentails 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. Defaults to False, which requests a token via the console.
  • auth_local_webserver (deprecated) – Use the use_local_webserver parameter instead.
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_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=False)

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

Bases: ValueError

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