API Reference¶
|
Get credentials and default project for accessing Google APIs. |
|
Gets user account credentials. |
|
Gets user account credentials from JSON file at |
|
Gets user account credentials and saves them to a JSON file at |
|
Gets service account credentials from JSON file at |
Shared base class for crentials classes. |
|
Write credentials to disk and read cached credentials from disk. |
|
Write credentials to disk. |
|
Noop impmentation of credentials cache. |
|
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 thepydata_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 onlocalhost
between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults toFalse
, 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
- 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
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 onlocalhost
between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults toFalse
, 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
- 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
- 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
- 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
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 onlocalhost
between 8080 and 8089, inclusive, to receive authentication token. If not set, defaults toFalse
, which requests a token via the console.
- Returns
- Return type
- 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
- 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
- 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.