tessl/pypi-google-api-core

Google API client core library providing common helpers, utilities, and components for Python client libraries

—

Pending

Overview

Eval results

Files

Universe Domain Support

Name: tessl/pypi-google-api-core
Author: tessl

Universe domain configuration and validation for multi-environment Google Cloud deployments. This module enables Google API clients to operate across different Google Cloud universes (environments) with proper domain validation and configuration management.

Capabilities

Domain Determination

Determine the appropriate universe domain based on client configuration and environment variables with fallback to default behavior.

def determine_domain(client_universe_domain, universe_domain_env): ...

DEFAULT_UNIVERSE = "googleapis.com"

Domain Validation

Compare and validate universe domains between client configuration and authentication credentials to ensure compatibility.

def compare_domains(client_universe, credentials): ...

Error Handling

Specialized exceptions for universe domain configuration errors and validation failures.

class EmptyUniverseError(ValueError): ...

class UniverseMismatchError(ValueError): ...

Usage Examples

Basic Universe Domain Configuration

from google.api_core import universe
import os

# Determine universe domain from multiple sources
client_universe = None  # Not explicitly configured
env_universe = os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")

# Get the effective universe domain
effective_domain = universe.determine_domain(client_universe, env_universe)
print(f"Using universe domain: {effective_domain}")
# Output: "Using universe domain: googleapis.com" (default)

# With explicit client configuration
client_universe = "my-universe.googleapis.com"
effective_domain = universe.determine_domain(client_universe, env_universe)
print(f"Using universe domain: {effective_domain}")  
# Output: "Using universe domain: my-universe.googleapis.com"

Environment Variable Configuration

import os
from google.api_core import universe

# Set universe domain via environment variable
os.environ["GOOGLE_CLOUD_UNIVERSE_DOMAIN"] = "staging.googleapis.com"

# Determine domain (environment variable takes precedence over default)
domain = universe.determine_domain(None, os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"))
print(f"Universe domain: {domain}")
# Output: "Universe domain: staging.googleapis.com"

Credentials Validation

from google.api_core import universe
from google.auth import credentials

# Assume we have credentials with a universe domain
# credentials.universe_domain = "staging.googleapis.com"

client_universe = "staging.googleapis.com"

try:
    # Validate that client and credentials use the same universe
    is_compatible = universe.compare_domains(client_universe, credentials)
    print("Universe domains are compatible")
except universe.UniverseMismatchError as e:
    print(f"Universe mismatch: {e}")
    # Handle the mismatch appropriately

Error Handling

from google.api_core import universe

# Handle empty universe domain
try:
    invalid_domain = universe.determine_domain("", None)
except universe.EmptyUniverseError as e:
    print(f"Error: {e}")
    # Output: "Error: Universe Domain cannot be an empty string."

# Handle universe mismatch
try:
    universe.compare_domains("prod.googleapis.com", mock_credentials_with_staging)
except universe.UniverseMismatchError as e:
    print(f"Mismatch detected: {e}")
    # Output details about the client vs credentials universe domains

Client Integration Pattern

from google.api_core import universe
from google.auth import default
import os

def create_client_with_universe_validation():
    # Get default credentials
    credentials, project = default()
    
    # Determine client universe domain
    client_universe = universe.determine_domain(
        client_universe_domain=None,  # Could come from client options
        universe_domain_env=os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
    )
    
    # Validate compatibility
    try:
        universe.compare_domains(client_universe, credentials)
        print(f"Creating client for universe: {client_universe}")
        # Proceed with client creation
    except universe.UniverseMismatchError:
        print("Universe domain mismatch - cannot create client")
        raise

Domain Resolution Priority

The universe domain is determined using the following priority order:

Client Configuration: Explicitly set universe domain in client options
Environment Variable: GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable
Default: googleapis.com (production Google Cloud)

# Priority demonstration
def demonstrate_priority():
    # Scenario 1: Client config takes highest priority
    domain1 = universe.determine_domain("custom.googleapis.com", "env.googleapis.com")
    assert domain1 == "custom.googleapis.com"
    
    # Scenario 2: Environment variable used when client config is None
    domain2 = universe.determine_domain(None, "env.googleapis.com") 
    assert domain2 == "env.googleapis.com"
    
    # Scenario 3: Default when both are None
    domain3 = universe.determine_domain(None, None)
    assert domain3 == "googleapis.com"

Multi-Universe Deployment Patterns

Development/Staging/Production Environments

import os
from google.api_core import universe

def get_environment_universe():
    """Get universe domain based on deployment environment."""
    env = os.getenv("DEPLOYMENT_ENV", "production")
    
    universe_mappings = {
        "development": "dev.googleapis.com",
        "staging": "staging.googleapis.com", 
        "production": "googleapis.com"
    }
    
    configured_universe = universe_mappings.get(env, universe.DEFAULT_UNIVERSE)
    
    return universe.determine_domain(
        configured_universe,
        os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
    )

Custom Universe Configuration

from google.api_core import universe

class UniverseConfig:
    def __init__(self, environment="production"):
        self.environment = environment
        self._universe_domain = None
    
    @property
    def universe_domain(self):
        if self._universe_domain:
            return self._universe_domain
            
        return universe.determine_domain(
            client_universe_domain=self._get_environment_domain(),
            universe_domain_env=os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
        )
    
    def _get_environment_domain(self):
        if self.environment == "staging":
            return "staging.googleapis.com"
        elif self.environment == "development":
            return "dev.googleapis.com"
        return None  # Use default for production

Import Patterns

from google.api_core import universe

# Use constants
default_domain = universe.DEFAULT_UNIVERSE

# Domain determination
domain = universe.determine_domain(client_config, env_config)

# Validation
universe.compare_domains(client_domain, credentials)

# Exception handling
try:
    domain = universe.determine_domain("", None)
except universe.EmptyUniverseError:
    # Handle empty domain error
    pass
except universe.UniverseMismatchError:
    # Handle universe mismatch
    pass

Types

from typing import Any, Optional

# Function signatures
UniverseDomain = str
CredentialsType = Any  # Credentials object with optional universe_domain attribute

# Configuration types
ClientUniverseDomain = Optional[str]
EnvironmentUniverseDomain = Optional[str]

Error Categories

EmptyUniverseError

Cause: Universe domain is an empty string or whitespace-only
Resolution: Provide a valid non-empty universe domain
Prevention: Validate configuration before passing to determine_domain()

UniverseMismatchError

Cause: Client universe domain doesn't match credentials universe domain
Resolution: Ensure client and credentials use the same universe
Prevention: Validate universe compatibility during client initialization

Architecture Considerations

Universe Domain Hierarchy

Production: googleapis.com (default)
Staging: staging.googleapis.com
Development: dev.googleapis.com
Custom: Organization-specific domains

Configuration Sources

Explicit Client Options: Highest priority, set programmatically
Environment Variables: System-level configuration
Default Values: Fallback to production universe

Security Implications

Universe domains control which Google Cloud environment is accessed
Mismatched domains can lead to authentication failures
Proper validation prevents accidental cross-environment access
Environment isolation is maintained through domain separation

This module ensures proper universe domain handling for Google API clients operating across different Google Cloud environments while maintaining security and configuration consistency.

Install with Tessl CLI