Google API Extensions (GAX)

Common errors

• ModuleNotFoundError: No module named 'google.gax'

  cause The `google-gax` library is not installed, or you are trying to import it in an environment where it's not present or shadowed.
  fix If you intend to use the deprecated `google-gax`, install it via `pip install google-gax`. However, the recommended fix is to migrate your code to use `google-api-core` and its relevant modules instead (e.g., `from google.api_core import retry`).

• DeprecationWarning: google-gax is deprecated and will no longer be developed. It has been wholly replaced by google-api-core.

  cause Your code is still using `google-gax` imports or functionality, triggering the official deprecation warning.
  fix This is an informative warning indicating you should migrate. Update your code to use `google-api-core` for equivalent functionalities. For instance, `from google.gax import retry` should become `from google.api_core import retry`.

• AttributeError: module 'google.gax' has no attribute 'config' (or 'api_callable', 'operations_client', etc.)

  cause You are attempting to access a module or attribute from `google.gax` that either never existed, was moved, or you are running an environment where `google-gax` is not correctly installed/imported, potentially conflicting with parts of `google-api-core`.
  fix Ensure you are importing from the correct, modern library. Replace `from google.gax import config` with `from google.api_core.gapic_v1 import config` and similarly for other GAX-specific components. Refer to the `google-api-core` documentation for updated import paths.

Warnings

• breaking The `google-gax` library is officially deprecated as of version 0.16.0 and will no longer receive updates or support. All functionality has been migrated to `google-api-core`.
  Fix: Migrate all existing code to use `google-api-core`. Update imports and adjust configuration settings as documented in `google-api-core`'s official documentation. See problem section for specific import changes.
• gotcha Using `google-gax` in new projects or alongside modern Google Cloud client libraries can lead to dependency conflicts, outdated behavior, and lack of support for new features or security patches.
  Fix: Always use `google-api-core` and the latest versions of Google Cloud client libraries. Review your project dependencies to ensure `google-gax` is not implicitly pulled in by older transitive dependencies.

Install

• pip install google-gax Install google-gax (Deprecated)
• pip install google-api-core Install its replacement: google-api-core

Imports

• api_callable
  wrong:

  from google.gax import api_callable

  correct:

  from google.api_core.gapic_v1 import api_callable

  Replaced by api_callable in google-api-core for GAX configuration.
• config
  wrong:

  from google.gax import config

  correct:

  from google.api_core.gapic_v1 import config

  Replaced by config in google-api-core for GAX configuration.
• retry
  wrong:

  from google.gax import retry

  correct:

  from google.api_core import retry

  Retry logic moved directly into google-api-core.

Quickstart

This quickstart demonstrates how to use `google-api-core`'s `Retry` mechanism, which directly replaces core functionality previously found in `google-gax`. It shows a simple example of retrying an intermittently failing function, illustrating the correct modern approach for handling transient errors in Google Cloud client libraries. **Note:** Direct usage of `google-gax` is deprecated and not recommended for new projects.

from google.api_core.retry import Retry
from google.api_core.exceptions import ServiceUnavailable
import time

# --- This example demonstrates google-api-core, the replacement for google-gax ---

_failure_count = 0
def might_fail_api_call():
    """A dummy function simulating an API call that fails intermittently."""
    global _failure_count
    _failure_count += 1
    if _failure_count < 3:
        print(f"Attempt {_failure_count}: API call failing with ServiceUnavailable...")
        raise ServiceUnavailable("Backend service is temporarily unavailable.")
    print(f"Attempt {_failure_count}: API call succeeded!")
    return "Data Retrieved!"

# Define a retry policy for ServiceUnavailable errors
# This replaces similar functionality found in google-gax.retry
retry_policy = Retry(
    predicate=Retry.if_exception_type(ServiceUnavailable),
    initial=1.0,  # Initial delay of 1 second
    multiplier=2.0, # Double delay each time
    maximum=10.0, # Max delay of 10 seconds
    deadline=30.0 # Total operation timeout of 30 seconds
)

try:
    print("\n--- Calling the API with google-api-core retry policy ---")
    result = retry_policy(might_fail_api_call)
    print(f"Final Result: {result}")
except Exception as e:
    print(f"Operation failed after retries: {e}")

# For actual Google Cloud client libraries, this retry mechanism
# is often automatically configured and used internally.