Registry / gcp / pydata-google-auth

pydata-google-auth

library1.9.1pypypi✓ verified 28d ago

PyData Google Auth is a Python package that provides helper functions for authenticating to Google APIs, simplifying the process of obtaining and caching user and service account credentials. It wraps the underlying `google-auth` and `google-auth-oauthlib` libraries to offer a more convenient interface. The current version is 1.9.1, and the library maintains an active release cadence with frequent minor and patch updates.

gcp auth-security

pip install pydata-google-auth

github ↗package ↗

INSTALL

IMPORT

SIG · PYDATA-GOOGLE-AUTH

pydata-google-auth

gcppythonv1.9.1

Install

4.0s avg

Import

1069ms

Disk

46MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.106s · 45MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.0s · import 1.032s · 45MB

46MB installed

● package 46MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_user_credentials

✓ from pydata_google_auth import get_user_credentials

Used for authenticating with user accounts via OAuth 2.0 flow.

load_service_account_credentials

✓ from pydata_google_auth import load_service_account_credentials

Used for authenticating with service accounts using a JSON key file.

default

✓ from pydata_google_auth import default

Attempts to get Application Default Credentials and falls back to user credentials if not found.

This quickstart demonstrates how to obtain user credentials using `get_user_credentials` and then use them to initialize a Google Cloud BigQuery client. The process will typically open a browser window for you to authenticate via Google's OAuth 2.0 flow if credentials are not already cached.

import os from pydata_google_auth import get_user_credentials from google.cloud import bigquery # Define the necessary scopes for BigQuery access SCOPES = [ 'https://www.googleapis.com/auth/cloud-platform', 'https://www.googleapis.com/auth/bigquery' ] # Get user credentials (will open a browser for OAuth flow if not cached) # `use_local_webserver=True` is the default and recommended for desktop apps. credentials = get_user_credentials(SCOPES) # Use an environment variable for project_id or replace with your actual ID project_id = os.environ.get('GCP_PROJECT_ID', 'your-gcp-project-id') # Initialize a Google Cloud BigQuery client with the obtained credentials client = bigquery.Client(project=project_id, credentials=credentials) print(f"Authenticated successfully to project: {client.project}.") print("You can now use 'client' to interact with BigQuery.") # Example: List datasets (requires appropriate permissions for the scopes) try: datasets = list(client.list_datasets()) if datasets: print(f"Found {len(datasets)} datasets.") else: print("No datasets found in the project.") except Exception as e: print(f"Error listing datasets: {e}")

Debug

Known issues

breakingThe default behavior of `get_user_credentials` for `use_local_webserver` changed from `False` to `True` in version 1.4.0. This was due to Google's deprecation of the "out of band" (copy-paste token) OAuth flow. If you were explicitly setting `use_local_webserver=False` and relying on the console-based flow, this might break your application if you update without adjustment.

fix

Ensure your environment allows for a local web server (ports 8080-8089 by default) for the OAuth callback, or explicitly set `use_local_webserver=False` and be prepared for the console-based flow, which may eventually cease to function. The `auth_local_webserver` parameter is also deprecated; use `use_local_webserver` instead.

affects: >=1.4.0

breakingVersion 1.9.0 dropped support for Python versions older than 3.9. Projects on Python 3.8 or earlier will need to upgrade their Python interpreter to use this version or newer.

fix

Upgrade your Python environment to 3.9 or newer. Python 3.13 is now officially supported.

affects: >=1.9.0

gotchaWhen developing a tool or library, you should provide your own `client_id` and `client_secret` when calling `get_user_credentials` to prevent masking your API client's identity, as per Google APIs terms of service.

fix

Obtain your own OAuth 2.0 Client ID and secret from the Google Cloud Console and pass them to the `client_id` and `client_secret` parameters of `get_user_credentials`.

affects: All

gotchaFor service account credentials, the JSON key file contains sensitive information. It is critical to manage this file securely, never commit it to source control, and use environment variables or secure storage mechanisms in production environments.

fix

Store the service account key in a secure location and reference its path via an environment variable (e.g., `GOOGLE_APPLICATION_CREDENTIALS`) or load it from a secure secret manager. Avoid hardcoding paths or embedding keys directly in code.

affects: All

gotchaBy default, `pydata-google-auth` caches user credentials on disk in `$HOME/.config/pydata/pydata_google_credentials.json` (or `$APPDATA` on Windows). On shared computing resources like Google Colab or GCE VMs, writing credentials to disk may be undesirable or insecure.

fix

To prevent credentials from being written to disk, pass `credentials_cache=pydata_google_auth.cache.NOOP` to `get_user_credentials` or `default`.

affects: All

gotchaThe `google.cloud` modules (e.g., `google.cloud.bigquery`) are not direct dependencies of `pydata-google-auth` and must be installed separately if you intend to use them. For example, to use BigQuery, you need to install `google-cloud-bigquery`.

fix

Install the specific `google.cloud` package you intend to use (e.g., `pip install google-cloud-bigquery`).

affects: All

gotchaWhen using `pydata-google-auth` in conjunction with Google Cloud client libraries (e.g., `google-cloud-bigquery`, `google-cloud-storage`), ensure those client libraries are explicitly installed. `pydata-google-auth` provides authentication helpers but does not automatically install other `google-cloud` packages.

fix

Install the required Google Cloud client libraries (e.g., `pip install google-cloud-bigquery`) into your environment.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pydata_google_auth'

The `pydata-google-auth` package is not installed in the Python environment where the code is being executed, or the environment lacks access to the installed package.

fix

Install the package using pip: `pip install pydata-google-auth` or conda: `conda install pydata-google-auth --channel conda-forge`.

google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.

The application is attempting to use Google Application Default Credentials (ADC) but cannot find them in the expected locations, such as the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, a service account key file, or the Google Cloud metadata service (for GCE, Cloud Run, etc.).

fix

Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`), or run `gcloud auth application-default login` to set up user application default credentials locally.

pydata_google_auth.exceptions.PyDataCredentialsError: Could not get any valid credentials.

The `pydata-google-auth` library tried multiple methods (e.g., Application Default Credentials, cached user credentials, OAuth 2.0 flow) to obtain valid credentials but failed to retrieve any that were usable for the requested scopes.

fix

Ensure that a `client_secrets.json` file is correctly configured and accessible if using `get_user_credentials`, or that the environment variables for Application Default Credentials are set. Verify that the necessary API scopes are correctly provided and enabled for your Google Cloud project.

google.auth.exceptions.RefreshError: The credentials do not contain the necessary fields need to refresh the access token. You must specify refresh_token, token_uri, client_id, and client_secret.

The loaded credentials object is missing one or more required fields (e.g., `refresh_token`, `token_uri`, `client_id`, `client_secret`) that are essential for refreshing an expired access token, often occurring with manually constructed or incomplete credential objects.

fix

Ensure that when obtaining or loading user credentials, all necessary fields including `refresh_token`, `token_uri`, `client_id`, and `client_secret` are present in the `google.oauth2.credentials.Credentials` object. Re-run the full OAuth 2.0 authorization flow to acquire a complete set of credentials including a refresh token if these fields are missing.

requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))

A network-related issue, such as a firewall, proxy configuration, transient network problem, or an unresponsive server, prevented the HTTP request to Google's authentication or API servers from completing.

fix

Check your internet connection, verify proxy settings if applicable, inspect firewall rules to ensure outbound connections to Google's authentication endpoints (e.g., `accounts.google.com`) are allowed, and consider implementing retry logic for transient network failures.

Upgrade

Version history

1.9.1latest on PyPI · released Jan 23, 2025

Audit

Dependencies

setuptoolsrequiredRequired for package installation.

google-authrequiredCore library for Google authentication and authorization.

google-auth-oauthlibrequiredIntegration with oauthlib for end-user authentication.

sixoptionalDeprecated in 1.9.0; no longer required on Python 3.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pydata/pydata-google-auth ↗

packagehttps://pypi.org/project/pydata-google-auth/ ↗