google-api-core 2.37.0__tar.gz → 2.39.0__tar.gz

{google_api_core-2.37.0/google_api_core.egg-info → google_api_core-2.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-api-core
-Version: 2.37.0
+Version: 2.39.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

google_api_core-2.39.0/google/api_core/_observability.py

@@ -0,0 +1,281 @@
+# -*- coding: utf-8 -*-
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""OpenTelemetry helpers for resolving and instantiating interceptors."""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import TYPE_CHECKING, Any, Callable, Sequence
+
+from google.api_core import _feature_gating_helpers
+from google.api_core.client_options import ClientOptions
+
+if TYPE_CHECKING:
+    # flake8: grpc, trace, and ClientInterceptor are imported only for static analysis and type annotations
+    # The 'noqa: F401' comment avoids flake8 "imported but not used" errors.
+    import grpc  # noqa: F401
+    import opentelemetry.trace  # noqa: F401
+
+    from google.api_core.grpc_helpers import ClientInterceptor  # noqa: F401
+
+_TRACER_PROVIDER = "tracer_provider"
+
+
+def is_otel_capabilities_enabled(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+    env_var: str = "GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
+) -> bool:
+    """Checks if OTel capabilities are enabled and installed.
+
+    Args:
+        client_options: The client options object or dictionary.
+        env_var: The environment variable to check for enablement.
+
+    Returns:
+        bool: True if enabled and installed, False otherwise.
+    """
+    is_tracing_enabled = _feature_gating_helpers.resolve_feature_flags(
+        env_var=env_var,
+        feature_key=_TRACER_PROVIDER,
+        configuration=client_options,
+    )
+
+    if is_tracing_enabled:
+        try:
+            import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found] # noqa: F401
+
+            return True
+        except ImportError:
+            pass
+
+    return False
+
+
+def _extract_endpoint_attributes(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Extracts server.address, server.port (if non-default), and url.domain from client options if present.
+
+    Args:
+        client_options: The client options object or dictionary.
+
+    Returns:
+        dict[str, Any]: A dictionary containing url.domain and, if an api_endpoint is configured,
+            server.address and non-default server.port.
+    """
+    attrs: dict[str, Any] = {}
+    endpoint = None
+    universe_domain = None
+
+    if isinstance(client_options, dict):
+        endpoint = client_options.get("api_endpoint")
+        universe_domain = client_options.get("universe_domain")
+    elif client_options is not None:
+        endpoint = getattr(client_options, "api_endpoint", None)
+        universe_domain = getattr(client_options, "universe_domain", None)
+
+    attrs["url.domain"] = universe_domain or "googleapis.com"
+
+    if endpoint and isinstance(endpoint, str):
+        target = endpoint if "//" in endpoint else f"//{endpoint}"
+        parsed = None
+        hostname = None
+        port = None
+        try:
+            parsed = urllib.parse.urlsplit(target)
+            hostname = parsed.hostname
+            port = parsed.port
+        except ValueError:
+            pass
+
+        if hostname:
+            attrs["server.address"] = hostname
+        if port and parsed:
+            scheme = parsed.scheme.lower()
+            is_default_port = (port == 443 and scheme in ("https", "")) or (
+                port == 80 and scheme == "http"
+            )
+            if not is_default_port:
+                attrs["server.port"] = port
+    return attrs
+
+
+def _make_grpc_client_request_hook(
+    endpoint_attrs: dict[str, Any] | None = None,
+) -> Callable[[Any, Any], None]:
+    """Creates an OpenTelemetry gRPC client request hook with optional endpoint attributes.
+
+    Args:
+        endpoint_attrs: Optional static endpoint attributes to attach to every span.
+
+    Returns:
+        Callable[[Any, Any], None]: The request hook callback.
+    """
+    static_attrs = dict(endpoint_attrs) if endpoint_attrs else {}
+
+    def client_request_hook(span: Any, request: Any) -> None:
+        if span is None or not getattr(span, "is_recording", lambda: True)():
+            return
+
+        # Upstream opentelemetry-instrumentation-grpc may format span names with a
+        # leading slash (e.g. "/package.Service/Method"). Normalize the span name
+        # and ensure rpc.method is always captured as the clean, fully-qualified name.
+        span_name = getattr(span, "name", None)
+        if isinstance(span_name, str) and span_name:
+            clean_method_name = span_name.lstrip("/")
+            if span_name.startswith("/") and hasattr(span, "update_name"):
+                span.update_name(clean_method_name)
+            span.set_attribute("rpc.method", clean_method_name)
+
+        attrs: dict[str, Any] = {
+            "rpc.system.name": "grpc",
+        }
+        if static_attrs:
+            attrs.update(static_attrs)
+        for key, value in attrs.items():
+            span.set_attribute(key, value)
+
+    return client_request_hook
+
+
+_grpc_client_request_hook = _make_grpc_client_request_hook()
+
+
+def _grpc_client_response_hook(span: Any, response: Any) -> None:
+    """OpenTelemetry gRPC client response hook to record successful response status.
+
+    Upstream ``opentelemetry-instrumentation-grpc`` sets the integer status code
+    ``rpc.grpc.status_code`` (e.g. 0), but does not record the modern string status
+    ``rpc.response.status_code`` (e.g. "OK") required by Cloud Trace and current
+    OpenTelemetry semantic conventions (v1.27.0+).
+
+    This hook enriches successful RPC attempt spans with ``rpc.response.status_code = "OK"``.
+    Errors and non-OK statuses are handled at the Tier 3 method span layer or upstream.
+
+    Upstream handles synchronous and asynchronous invocations differently:
+    - **Synchronous gRPC**: Upstream only invokes the response hook when an RPC call
+      succeeds. On failure, the hook is bypassed entirely.
+    - **Asynchronous gRPC**: Upstream invokes the response hook unconditionally for
+      both successes and failures (passing exception details on error). However, it
+      always marks ``span.status`` with an error status before calling the hook.
+
+    Because of this disparity, this hook checks ``span.status`` to guard against
+    async failure callbacks while allowing synchronous and successful asynchronous
+    calls to be marked "OK".
+
+    Note:
+        If upstream ``opentelemetry-instrumentation-grpc`` adds native support for
+        modern ``rpc.response.status_code`` in future releases, this hook can be retired.
+
+    Args:
+        span: The OpenTelemetry span.
+        response: The gRPC response object or details.
+    """
+    if not span.is_recording():
+        return
+
+    # Guard against upstream async calls that invoke this hook on failures.
+    status = getattr(span, "status", None)
+    status_code = getattr(status, "status_code", None)
+    if (
+        getattr(status_code, "name", None) == "ERROR"
+        or getattr(status_code, "value", None) == 2
+    ):
+        return
+
+    span.set_attribute("rpc.response.status_code", "OK")
+
+
+def _get_tracer_provider(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> opentelemetry.trace.TracerProvider | None:
+    """Extracts the OpenTelemetry tracer provider from client options if present.
+
+    Args:
+        client_options: The client options object or dictionary.
+
+    Returns:
+        opentelemetry.trace.TracerProvider | None: The tracer provider if present,
+            None otherwise.
+    """
+    if isinstance(client_options, dict):
+        return client_options.get(_TRACER_PROVIDER)
+    elif client_options is not None:
+        return getattr(client_options, _TRACER_PROVIDER, None)
+    return None
+
+
+def get_otel_interceptor(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> Callable[[grpc.Channel], grpc.Channel] | None:
+    """Returns an interceptor callable that wraps a sync gRPC channel with OpenTelemetry tracing.
+
+    Args:
+        client_options: The client options object or dictionary used for feature gating
+            and extracting the tracer provider.
+
+    Returns:
+        Callable[[grpc.Channel], grpc.Channel] | None: An interceptor callable if OpenTelemetry
+            tracing is enabled and installed, None otherwise.
+    """
+    if not is_otel_capabilities_enabled(client_options):
+        return None
+
+    import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found]
+
+    endpoint_attrs = _extract_endpoint_attributes(client_options)
+    request_hook = _make_grpc_client_request_hook(endpoint_attrs)
+
+    interceptor: ClientInterceptor = otel_grpc.client_interceptor(
+        tracer_provider=_get_tracer_provider(client_options),
+        request_hook=request_hook,
+        response_hook=_grpc_client_response_hook,
+    )
+
+    def otel_interceptor(channel: grpc.Channel) -> grpc.Channel:
+        return otel_grpc.intercept_channel(channel, interceptor)
+
+    return otel_interceptor
+
+
+def get_otel_async_interceptor(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> Sequence[grpc.aio.ClientInterceptor] | None:
+    """Returns async gRPC client interceptors for OpenTelemetry tracing.
+
+    Args:
+        client_options: The client options object or dictionary used for feature gating
+            and extracting the tracer provider.
+
+    Returns:
+        Sequence[grpc.aio.ClientInterceptor] | None: Instantiated OpenTelemetry async
+            client interceptors if tracing is enabled and installed, None otherwise.
+    """
+    if not is_otel_capabilities_enabled(client_options):
+        return None
+
+    # Ignored by mypy: Optional dependency only loaded if early-return is skipped
+    import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found]
+
+    endpoint_attrs = _extract_endpoint_attributes(client_options)
+    request_hook = _make_grpc_client_request_hook(endpoint_attrs)
+
+    return otel_grpc.aio_client_interceptors(
+        tracer_provider=_get_tracer_provider(client_options),
+        request_hook=request_hook,
+        response_hook=_grpc_client_response_hook,
+    )

{google_api_core-2.37.0 → google_api_core-2.39.0}/google/api_core/_python_package_support.py

@@ -42,7 +42,7 @@ DependencyConstraint = namedtuple(
 PQC_GRPC_WARNING_TEMPLATE = (
     "Package {consumer_package} depends on {dependency_package}, currently installed at version {version_used_string}. "
     "grpcio < 1.83.0 does not support Post-Quantum Cryptography (PQC). "
-    "Support for non-PQC environments is deprecated. In October 2026, "
+    "Support for non-PQC environments is deprecated. In April 2027, "
     "Google Cloud Python packages will raise their minimum requirements "
     "(including google-api-core, grpcio, and grpcio-status) to enforce grpcio >= 1.83.0. "
     "For more details on Google Cloud's post-quantum security migration, visit: "

{google_api_core-2.37.0 → google_api_core-2.39.0}/google/api_core/exceptions.py

@@ -446,6 +446,41 @@ class AsyncRestUnsupportedParameterError(NotImplementedError):
     pass
 
 
+class ResumableTransferError(GoogleAPICallError):
+    """Base class for resumable transfer errors."""
+
+    upload_url: Optional[str] = None
+    chunk_size: Optional[int] = None
+
+    def __init__(
+        self,
+        message: str,
+        *args,
+        upload_url: Optional[str] = None,
+        chunk_size: Optional[int] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, *args, **kwargs)
+        self.upload_url = upload_url
+        self.chunk_size = chunk_size
+
+
+class TransferStalledError(ResumableTransferError):
+    """Raised when upload throughput stays below minimum rate past stall timeout."""
+
+
+class UnseekableStreamError(ResumableTransferError):
+    """Raised when server recovery requires rewinding a non-seekable stream."""
+
+
+class UploadCancelledError(ResumableTransferError):
+    """Raised when the upload is cancelled by the client or server."""
+
+
+class MissingStatusHeaderError(ResumableTransferError):
+    """Raised when server response lacks the required X-Goog-Upload-Status header."""
+
+
 def exception_class_for_http_status(status_code):
     """Return the exception class for a specific HTTP status code.
 

google_api_core-2.39.0/google/api_core/resumable_transfer/__init__.py

@@ -0,0 +1,49 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resumable transfer library for Google APIs."""
+
+from google.api_core.exceptions import (
+    MissingStatusHeaderError,
+    ResumableTransferError,
+    TransferStalledError,
+    UnseekableStreamError,
+    UploadCancelledError,
+)
+from google.api_core.resumable_transfer.common import (
+    DEFAULT_CHUNK_SIZE,
+    ProgressState,
+    ResumableUploadConfig,
+    UploadProgress,
+)
+from google.api_core.resumable_transfer.upload import ResumableUploadSession
+from google.api_core.resumable_transfer.upload_async import (
+    AsyncResumableUploadSession,
+    AsyncUploadOperation,
+)
+
+__all__ = [
+    "DEFAULT_CHUNK_SIZE",
+    "MissingStatusHeaderError",
+    "ProgressState",
+    "ResumableTransferError",
+    "TransferStalledError",
+    "UnseekableStreamError",
+    "UploadCancelledError",
+    "UploadProgress",
+    "ResumableUploadConfig",
+    "ResumableUploadSession",
+    "AsyncResumableUploadSession",
+    "AsyncUploadOperation",
+]

google_api_core-2.39.0/google/api_core/resumable_transfer/common.py

@@ -0,0 +1,191 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Common constants, headers, and shared configuration for Resumable Upload protocol."""
+
+import dataclasses
+import datetime
+import enum
+from typing import Any, Mapping, Optional, Sequence, Tuple, Union
+
+import google.protobuf.message
+import proto
+from google.protobuf import json_format
+
+from google.api_core import exceptions
+
+# Default chunk size: 10 MiB
+DEFAULT_CHUNK_SIZE = 10 * 1024 * 1024
+
+# Default timeout in seconds for the initial start request
+DEFAULT_START_TIMEOUT = 60.0
+
+# Protocol Headers
+HEADER_PROTOCOL = "X-Goog-Upload-Protocol"
+HEADER_COMMAND = "X-Goog-Upload-Command"
+HEADER_STATUS = "X-Goog-Upload-Status"
+HEADER_URL = "X-Goog-Upload-URL"
+HEADER_OFFSET = "X-Goog-Upload-Offset"
+HEADER_SIZE_RECEIVED = "X-Goog-Upload-Size-Received"
+HEADER_CONTENT_TYPE = "X-Goog-Upload-Header-Content-Type"
+HEADER_CONTENT_LENGTH = "X-Goog-Upload-Header-Content-Length"
+HEADER_CHUNK_GRANULARITY = "X-Goog-Upload-Chunk-Granularity"
+
+PROTOCOL_RESUMABLE = "resumable"
+
+
+class _Command(str, enum.Enum):
+    """Protocol commands."""
+
+    START = "start"
+    UPLOAD = "upload"
+    FINALIZE = "finalize"
+    QUERY = "query"
+    CANCEL = "cancel"
+
+
+class _Status(str, enum.Enum):
+    """Server upload status values."""
+
+    ACTIVE = "active"
+    FINAL = "final"
+    CANCELLED = "cancelled"
+
+
+class ProgressState(str, enum.Enum):
+    """Progress notification state values."""
+
+    STARTED = "started"
+    UPLOADING = "uploading"
+    RECOVERING = "recovering"
+    OFFSET_RECEIVED = "offset received"
+    FINALIZED = "finalized"
+
+
+@dataclasses.dataclass(frozen=True)
+class UploadProgress:
+    """Upload progress notification payload.
+
+    Attributes:
+        upload_url: The unique session URL for this upload.
+        chunk_size: The actual negotiated chunk size.
+        bytes_uploaded: The total confirmed bytes committed so far.
+        total_bytes: The total size of the stream in bytes, if known.
+        state: The current progress state.
+    """
+
+    upload_url: str
+    chunk_size: int
+    bytes_uploaded: int
+    total_bytes: Optional[int]
+    state: ProgressState
+
+
+# HTTP status codes indicating transient retryable errors (Category 1)
+RETRYABLE_STATUS_CODES = (408, 429, 500, 502, 503, 504)
+
+# HTTP status codes indicating state consistency errors requiring recovery (Category 2)
+RECOVERABLE_STATUS_CODES = (400, 412, 416)
+
+# Exception types indicating unrecoverable terminal conditions (Category 3)
+TERMINAL_ERRORS = (
+    exceptions.DeadlineExceeded,
+    exceptions.TransferStalledError,
+    exceptions.UploadCancelledError,
+    exceptions.UnseekableStreamError,
+)
+
+
+@dataclasses.dataclass
+class ResumableUploadConfig:
+    """Configuration options for a resumable upload.
+
+    Attributes:
+        chunk_size: Size in bytes for each uploaded data chunk. Defaults to 10 MiB.
+        stall_minimum_rate: Minimum transfer rate in bytes per second. Defaults to 64 KiB/s.
+        stall_timeout: Stall duration threshold in seconds. Defaults to 120s.
+        headers: Additional HTTP headers dispatched exclusively with start request.
+        deadline: Optional overall wall-clock deadline for the entire upload process.
+            When set, each HTTP request timeout is trimmed to the remaining time before
+            the deadline, and DeadlineExceeded is raised immediately when the deadline
+            elapses (even on healthy streams). Timezone-aware datetimes (e.g.,
+            ``datetime.now(timezone.utc) + timedelta(...)``) are recommended;
+            timezone-naive datetimes are assumed to be in local system time. When
+            None (default), transfer duration is governed by stall control
+            (stall_minimum_rate and stall_timeout), allowing healthy streams
+            transferring above the minimum rate to continue indefinitely.
+    """
+
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    stall_minimum_rate: int = 64 * 1024
+    stall_timeout: float = 120.0
+    headers: Optional[Union[Mapping[str, str], Sequence[Tuple[str, str]]]] = None
+    deadline: Optional[datetime.datetime] = None
+
+    def __post_init__(self) -> None:
+        if self.deadline is not None:
+            self.deadline = self.deadline.astimezone(datetime.timezone.utc)
+
+    @property
+    def start_headers(self) -> Optional[Sequence[Tuple[str, str]]]:
+        """Returns normalized additional headers for the start request."""
+        if self.headers is None:
+            return None
+        if isinstance(self.headers, Mapping):
+            return list(self.headers.items())
+        return list(self.headers)
+
+
+def _format_response_payload(
+    response: Union[Any, bytes],
+    response_type: Optional[Any],
+) -> Any:
+    """Formats raw response or bytes into protobuf or proto-plus message type if configured.
+
+    Args:
+        response: Raw HTTP response object or response body bytes.
+        response_type: Deserializer callable, proto.Message class, or
+            google.protobuf.message.Message class or instance.
+
+    Returns:
+        Deserialized protobuf message, or raw response bytes if
+        ``response_type`` is ``None``.
+    """
+    content: bytes
+    if isinstance(response, bytes):
+        content = response
+    elif hasattr(response, "content"):
+        content = response.content
+    else:
+        content = bytes(response)
+
+    if response_type is None:
+        return content
+
+    from_json_fn = getattr(response_type, "from_json", None)
+    if callable(from_json_fn):
+        if isinstance(response_type, type) and issubclass(response_type, proto.Message):
+            return from_json_fn(content, ignore_unknown_fields=True)
+        return from_json_fn(content)
+    if isinstance(response_type, type) and issubclass(
+        response_type, google.protobuf.message.Message
+    ):
+        instance = response_type()
+        return json_format.Parse(content, instance, ignore_unknown_fields=True)
+    if isinstance(response_type, google.protobuf.message.Message):
+        return json_format.Parse(content, response_type, ignore_unknown_fields=True)
+    if callable(response_type):
+        return response_type(content)
+
+    return content