tessl/pypi-googleapis-common-protos

Common protocol buffer definitions used across Google APIs and client libraries

—

Pending

Overview

Eval results

Files

API Framework Types

Name: tessl/pypi-googleapis-common-protos
Author: tessl

Core infrastructure types for Google API definition including field behaviors, resource patterns, authentication, HTTP mapping, and client library configuration. These types enable consistent API design and automatic client generation across Google services.

Capabilities

Field Behavior Annotations

Annotations that specify field requirements and constraints in API definitions.

from google.api.field_behavior_pb2 import FieldBehavior

class FieldBehavior(enum.Enum):
    """Field behavior enumeration values."""
    FIELD_BEHAVIOR_UNSPECIFIED = 0
    OPTIONAL = 1
    REQUIRED = 2
    OUTPUT_ONLY = 3
    INPUT_ONLY = 4
    IMMUTABLE = 5
    UNORDERED_LIST = 6
    NON_EMPTY_DEFAULT = 7
    IDENTIFIER = 8

Launch Stage Annotations

API maturity level annotations for features and services.

from google.api.launch_stage_pb2 import LaunchStage

class LaunchStage(enum.Enum):
    """API maturity levels."""
    LAUNCH_STAGE_UNSPECIFIED = 0
    UNIMPLEMENTED = 1
    PRELAUNCH = 2
    EARLY_ACCESS = 3
    ALPHA = 4
    BETA = 5
    GA = 6
    DEPRECATED = 7

Resource Management

Define API resources with patterns, naming conventions, and relationships.

from google.api.resource_pb2 import ResourceDescriptor, ResourceReference

class ResourceDescriptor(message.Message):
    """Defines a resource type."""
    type: str  # Resource type identifier
    pattern: list[str]  # URI pattern templates
    name_field: str  # Field containing resource name
    history: ResourceDescriptor.History
    plural: str  # Plural form of resource name
    singular: str  # Singular form of resource name
    style: list[ResourceDescriptor.Style]

    class History(enum.Enum):
        HISTORY_UNSPECIFIED = 0
        ORIGINALLY_SINGLE_PATTERN = 1
        FUTURE_MULTI_PATTERN = 2

    class Style(enum.Enum):
        STYLE_UNSPECIFIED = 0
        DECLARATIVE_FRIENDLY = 1

class ResourceReference(message.Message):
    """References another resource type."""
    type: str  # Referenced resource type
    child_type: str  # Child resource type

HTTP Rule Mapping

Map gRPC service methods to HTTP/REST endpoints.

from google.api.http_pb2 import Http, HttpRule, CustomHttpPattern

class Http(message.Message):
    """HTTP configuration for a service."""
    rules: list[HttpRule]
    fully_decode_reserved_expansion: bool

class HttpRule(message.Message):
    """HTTP rule for mapping RPC methods to HTTP endpoints."""
    selector: str  # RPC method selector
    get: str  # HTTP GET pattern
    put: str  # HTTP PUT pattern  
    post: str  # HTTP POST pattern
    delete: str  # HTTP DELETE pattern
    patch: str  # HTTP PATCH pattern
    custom: CustomHttpPattern  # Custom HTTP method
    body: str  # HTTP request body field
    response_body: str  # HTTP response body field
    additional_bindings: list[HttpRule]  # Additional HTTP bindings

class CustomHttpPattern(message.Message):
    """Custom HTTP method pattern."""
    kind: str  # HTTP method name
    path: str  # URL path pattern

Authentication Configuration

Configure authentication and authorization for API services.

from google.api.auth_pb2 import (
    Authentication, AuthenticationRule, AuthProvider, 
    JwtLocation, OAuthRequirements, AuthRequirement
)

class Authentication(message.Message):
    """Authentication configuration for a service."""
    rules: list[AuthenticationRule]
    providers: list[AuthProvider]

class AuthenticationRule(message.Message):
    """Authentication rule for specific methods."""
    selector: str  # Method selector pattern
    oauth: OAuthRequirements  # OAuth configuration
    allow_without_credential: bool  # Allow unauthenticated access
    requirements: list[AuthRequirement]  # Authentication requirements

class AuthProvider(message.Message):
    """Authentication provider configuration."""
    id: str  # Provider identifier
    issuer: str  # Token issuer
    jwks_uri: str  # JSON Web Key Set URI
    audiences: str  # Valid audiences
    authorization_url: str  # Authorization endpoint
    jwt_locations: list[JwtLocation]  # JWT token locations

class JwtLocation(message.Message):
    """Location of JWT token in request."""
    header: str  # HTTP header name
    query: str  # Query parameter name
    cookie: str  # Cookie name
    value_prefix: str  # Token value prefix

class OAuthRequirements(message.Message):
    """OAuth requirements configuration."""
    canonical_scopes: str  # Required OAuth scopes

class AuthRequirement(message.Message):
    """Authentication requirement."""
    provider_id: str  # Provider identifier
    audiences: str  # Required audiences

Client Library Configuration

Configure automatic client library generation settings.

from google.api.client_pb2 import (
    CommonLanguageSettings, ClientLibrarySettings, Publishing,
    MethodSettings, ClientLibraryOrganization, ClientLibraryDestination
)

class ClientLibraryOrganization(enum.Enum):
    """Client library organization types."""
    CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0
    CLOUD = 1
    ADS = 2
    PHOTOS = 3
    STREET_VIEW = 4
    SHOPPING = 5
    GEO = 6
    GENERATIVE_AI = 7

class ClientLibraryDestination(enum.Enum):
    """Client library publication destinations."""
    CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0
    GITHUB = 10
    PACKAGE_MANAGER = 20

class CommonLanguageSettings(message.Message):
    """Common settings for all language generators."""
    reference_docs_uri: str  # Reference documentation URL
    destinations: list[ClientLibraryDestination]  # Publication destinations

class ClientLibrarySettings(message.Message):
    """Client library generation settings."""
    version: str  # Library version
    launch_stage: LaunchStage  # API maturity stage
    rest_numeric_enums: bool  # Use numeric enums in REST
    java_settings: JavaSettings  # Java-specific settings
    cpp_settings: CppSettings  # C++ specific settings
    php_settings: PhpSettings  # PHP-specific settings
    python_settings: PythonSettings  # Python-specific settings
    node_settings: NodeSettings  # Node.js-specific settings
    dotnet_settings: DotnetSettings  # .NET-specific settings
    ruby_settings: RubySettings  # Ruby-specific settings
    go_settings: GoSettings  # Go-specific settings

class MethodSettings(message.Message):
    """Method-specific client settings."""
    selector: str  # Method selector pattern
    long_running: MethodSettings.LongRunning  # Long-running operation config
    auto_populated_fields: list[str]  # Auto-populated field names

    class LongRunning(message.Message):
        """Long-running operation settings."""
        initial_poll_delay: Duration  # Initial polling delay
        poll_delay_multiplier: float  # Delay multiplier
        max_poll_delay: Duration  # Maximum polling delay
        total_poll_timeout: Duration  # Total timeout

Launch Stages and Visibility

Define API maturity levels and visibility rules.

from google.api.launch_stage_pb2 import LaunchStage
from google.api.visibility_pb2 import Visibility, VisibilityRule

class LaunchStage(enum.Enum):
    """API launch stage enumeration."""
    LAUNCH_STAGE_UNSPECIFIED = 0
    UNIMPLEMENTED = 6
    PRELAUNCH = 7
    EARLY_ACCESS = 1
    ALPHA = 2
    BETA = 3
    GA = 4
    DEPRECATED = 5

class Visibility(message.Message):
    """API visibility configuration."""
    rules: list[VisibilityRule]

class VisibilityRule(message.Message):
    """Visibility rule for API elements."""
    selector: str  # Element selector pattern
    restriction: str  # Visibility restriction

Service Configuration

Complete API service definition and configuration.

from google.api.service_pb2 import Service
from google.api.usage_pb2 import Usage, UsageRule
from google.api.quota_pb2 import Quota, QuotaLimit, MetricRule
from google.api.billing_pb2 import Billing, BillingDestination

class Service(message.Message):
    """Complete API service configuration."""
    name: str  # Service name
    title: str  # Service title
    producer_project_id: str  # Producer project ID
    id: str  # Service ID
    apis: list[Api]  # Service APIs
    types: list[Type]  # Custom types
    enums: list[Enum]  # Custom enums
    documentation: Documentation  # Documentation config
    backend: Backend  # Backend configuration
    http: Http  # HTTP configuration
    quota: Quota  # Quota configuration
    authentication: Authentication  # Auth configuration
    context: Context  # Context configuration
    usage: Usage  # Usage configuration
    endpoints: list[Endpoint]  # Service endpoints
    control: Control  # Service control config
    logs: list[LogDescriptor]  # Log descriptors
    metrics: list[MetricDescriptor]  # Metric descriptors
    monitored_resources: list[MonitoredResourceDescriptor]  # Monitored resources
    billing: Billing  # Billing configuration
    logging: Logging  # Logging configuration
    monitoring: Monitoring  # Monitoring configuration
    system_parameters: SystemParameters  # System parameters
    source_info: SourceInfo  # Source information

class Usage(message.Message):
    """API usage configuration."""
    requirements: list[str]  # Usage requirements
    rules: list[UsageRule]  # Usage rules
    producer_notification_channel: str  # Notification channel

class Quota(message.Message):
    """Quota configuration."""
    limits: list[QuotaLimit]  # Quota limits
    metric_rules: list[MetricRule]  # Metric rules

class Billing(message.Message):
    """Billing configuration."""
    consumer_destinations: list[BillingDestination]  # Consumer billing destinations

Labels and Metadata

Define labels and field information for API elements.

from google.api.label_pb2 import LabelDescriptor
from google.api.field_info_pb2 import FieldInfo

class LabelDescriptor(message.Message):
    """Label descriptor."""
    key: str  # Label key
    value_type: LabelDescriptor.ValueType  # Value type
    description: str  # Label description

    class ValueType(enum.Enum):
        STRING = 0
        BOOL = 1
        INT64 = 2

class FieldInfo(message.Message):
    """Field information and formatting."""
    format: FieldInfo.Format  # Field format
    referenced_types: list[TypeReference]  # Referenced types

    class Format(enum.Enum):
        FORMAT_UNSPECIFIED = 0
        UUID4 = 1
        IPV4 = 2
        IPV6 = 3
        IPV4_OR_IPV6 = 4

Usage Examples

Resource Definition

from google.api.resource_pb2 import ResourceDescriptor

# Define a resource type
resource = ResourceDescriptor()
resource.type = "example.googleapis.com/Book"
resource.pattern.extend([
    "publishers/{publisher}/books/{book}",
    "projects/{project}/books/{book}"
])
resource.name_field = "name"
resource.plural = "books"
resource.singular = "book"

HTTP Rule Configuration

from google.api.http_pb2 import HttpRule

# Map RPC method to HTTP endpoint
rule = HttpRule()
rule.selector = "google.example.Library.GetBook"
rule.get = "/v1/{name=publishers/*/books/*}"

Authentication Setup

from google.api.auth_pb2 import Authentication, AuthenticationRule

# Configure service authentication
auth = Authentication()
rule = AuthenticationRule()
rule.selector = "google.example.Library.*"
rule.oauth.canonical_scopes = "https://www.googleapis.com/auth/cloud-platform"
auth.rules.append(rule)

Install with Tessl CLI

npx tessl i tessl/pypi-googleapis-common-protos

docs