google-api-core 2.42.0__tar.gz → 2.43.0__tar.gz

{google_api_core-2.42.0/google_api_core.egg-info → google_api_core-2.43.0}/PKG-INFO

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

{google_api_core-2.42.0 → google_api_core-2.43.0}/google/api_core/_observability.py

@@ -18,12 +18,20 @@
 
 from __future__ import annotations
 
+import contextlib
 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
 
+try:
+    from opentelemetry.instrumentation.utils import (
+        suppress_instrumentation as _suppress_instrumentation,
+    )
+except ImportError:
+    _suppress_instrumentation = contextlib.nullcontext
+
 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.
@@ -223,6 +231,140 @@ def _get_tracer_provider(
     return None
 
 
+try:
+    # flake8: `grpc` imported conditionally for runtime interceptor base classes
+    import grpc  # noqa: F811
+    from grpc import (
+        StreamStreamClientInterceptor as _SyncStreamStreamClientInterceptor,
+    )
+    from grpc import (
+        StreamUnaryClientInterceptor as _SyncStreamUnaryClientInterceptor,
+    )
+    from grpc import (
+        UnaryStreamClientInterceptor as _SyncUnaryStreamClientInterceptor,
+    )
+    from grpc import (
+        UnaryUnaryClientInterceptor as _SyncUnaryUnaryClientInterceptor,
+    )
+    from grpc.aio import (
+        StreamStreamClientInterceptor as _AsyncStreamStreamClientInterceptor,
+    )
+    from grpc.aio import (
+        StreamUnaryClientInterceptor as _AsyncStreamUnaryClientInterceptor,
+    )
+    from grpc.aio import (
+        UnaryStreamClientInterceptor as _AsyncUnaryStreamClientInterceptor,
+    )
+    from grpc.aio import (
+        UnaryUnaryClientInterceptor as _AsyncUnaryUnaryClientInterceptor,
+    )
+except ImportError:  # pragma: NO COVER
+    # mypy: Fallbacks:  grpc sentinel when optional grpc is not installed in the environment.
+    # and distinct empty classes avoid duplicate base class 'object' TypeError at runtime.
+    grpc = None  # type: ignore[assignment]
+
+    class _SyncUnaryUnaryClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _SyncUnaryStreamClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _SyncStreamUnaryClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _SyncStreamStreamClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _AsyncUnaryUnaryClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _AsyncUnaryStreamClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _AsyncStreamUnaryClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+    class _AsyncStreamStreamClientInterceptor:  # type: ignore[no-redef]
+        __slots__ = ()
+
+
+class _SuppressingClientInterceptor(
+    _SyncUnaryUnaryClientInterceptor,
+    _SyncUnaryStreamClientInterceptor,
+    _SyncStreamUnaryClientInterceptor,
+    _SyncStreamStreamClientInterceptor,
+):
+    """Client interceptor that suppresses redundant downstream generic auto-instrumentation spans.
+
+    When users enable global OpenTelemetry gRPC auto-instrumentation (e.g. GrpcInstrumentorClient),
+    the underlying channel is wrapped with generic interceptors that emit bare-bones spans.
+    This interceptor wraps downstream calls in OpenTelemetry's native `suppress_instrumentation`
+    context manager so that our feature-rich Google Cloud SDK T4 span is emitted while
+    redundant generic downstream spans are bypassed.
+    """
+
+    __slots__ = ()
+
+    def intercept_unary_unary(
+        self, continuation: Any, client_call_details: Any, request: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return continuation(client_call_details, request)
+
+    def intercept_unary_stream(
+        self, continuation: Any, client_call_details: Any, request: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return continuation(client_call_details, request)
+
+    def intercept_stream_unary(
+        self, continuation: Any, client_call_details: Any, request_iterator: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return continuation(client_call_details, request_iterator)
+
+    def intercept_stream_stream(
+        self, continuation: Any, client_call_details: Any, request_iterator: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return continuation(client_call_details, request_iterator)
+
+
+class _AsyncSuppressingClientInterceptor(
+    _AsyncUnaryUnaryClientInterceptor,
+    _AsyncUnaryStreamClientInterceptor,
+    _AsyncStreamUnaryClientInterceptor,
+    _AsyncStreamStreamClientInterceptor,
+):
+    """AsyncIO client interceptor that suppresses redundant downstream generic auto-instrumentation spans."""
+
+    __slots__ = ()
+
+    async def intercept_unary_unary(
+        self, continuation: Any, client_call_details: Any, request: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return await continuation(client_call_details, request)
+
+    async def intercept_unary_stream(
+        self, continuation: Any, client_call_details: Any, request: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return await continuation(client_call_details, request)
+
+    async def intercept_stream_unary(
+        self, continuation: Any, client_call_details: Any, request_iterator: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return await continuation(client_call_details, request_iterator)
+
+    async def intercept_stream_stream(
+        self, continuation: Any, client_call_details: Any, request_iterator: Any
+    ) -> Any:
+        with _suppress_instrumentation():
+            return await continuation(client_call_details, request_iterator)
+
+
 def get_otel_interceptor(
     client_options: ClientOptions | dict[str, Any] | None = None,
 ) -> Callable[[grpc.Channel], grpc.Channel] | None:
@@ -249,8 +391,15 @@ def get_otel_interceptor(
         request_hook=request_hook,
         response_hook=_grpc_client_response_hook,
     )
+    suppressor = _SuppressingClientInterceptor()
 
     def otel_interceptor(channel: grpc.Channel) -> grpc.Channel:
+        if grpc is not None:
+            try:
+                channel = grpc.intercept_channel(channel, suppressor)
+            except (AttributeError, TypeError):
+                # Fallback if grpc lacks intercept_channel or custom channel type rejects it.
+                pass
         return otel_grpc.intercept_channel(channel, interceptor)
 
     otel_interceptor._is_otel_interceptor = True  # type: ignore[attr-defined]
@@ -279,11 +428,91 @@ def get_otel_async_interceptor(
     endpoint_attrs = _extract_endpoint_attributes(client_options)
     request_hook = _make_grpc_client_request_hook(endpoint_attrs)
 
-    return otel_grpc.aio_client_interceptors(
+    raw_interceptors = otel_grpc.aio_client_interceptors(
         tracer_provider=_get_tracer_provider(client_options),
         request_hook=request_hook,
         response_hook=_grpc_client_response_hook,
     )
+    interceptors = (
+        list(raw_interceptors)
+        if isinstance(raw_interceptors, (list, tuple))
+        else [raw_interceptors]
+    )
+    interceptors.append(_AsyncSuppressingClientInterceptor())
+
+    return interceptors
+
+
+_CHANNEL_INTERCEPTOR_MAPPING = (
+    ("intercept_unary_unary", "_unary_unary_interceptors"),
+    ("intercept_unary_stream", "_unary_stream_interceptors"),
+    ("intercept_stream_unary", "_stream_unary_interceptors"),
+    ("intercept_stream_stream", "_stream_stream_interceptors"),
+)
+
+
+def apply_otel_async_channel_interceptors(
+    channel: Any,
+    client_options: ClientOptions | dict[str, Any] | Sequence[Any] | None = None,
+) -> Any:
+    """Creates and attaches OpenTelemetry client interceptors to the front of an async gRPC channel.
+
+    In grpc.aio, channels maintain internal interceptor lists evaluated in index order.
+    To ensure Google Cloud SDK telemetry wraps outside downstream interceptors and
+    suppresses ambient generic auto-instrumentation, our interceptors are prepended
+    to the front of the channel's interceptor lists.
+
+    Args:
+        channel: The async gRPC channel to intercept.
+        client_options (Optional[Union[ClientOptions, dict[str, Any], Sequence[Any]]]): The client
+            options used to resolve feature flags and tracer provider, or a sequence of
+            pre-resolved interceptors.
+
+    Returns:
+        The channel with interceptors prepended to its internal lists,
+        or the original channel if tracing is disabled or not installed.
+    """
+    otel_interceptors: Sequence[Any] | None
+    if isinstance(client_options, (ClientOptions, dict)) or client_options is None:
+        otel_interceptors = get_otel_async_interceptor(client_options)
+    elif isinstance(client_options, Sequence):
+        otel_interceptors = client_options
+    else:
+        otel_interceptors = None
+
+    if not otel_interceptors:
+        return channel
+
+    interceptor_list = list(otel_interceptors)
+
+    # Section 1: Typed interceptors - prepend matching interceptors to each
+    # corresponding channel list (unary-unary, unary-stream, etc.) in order.
+    # See note in the docstring about why prepending is important here.
+    for method_name, attr_name in _CHANNEL_INTERCEPTOR_MAPPING:
+        target_list = getattr(channel, attr_name, None)
+        if isinstance(target_list, list):
+            matching = [
+                i
+                for i in interceptor_list
+                if hasattr(i, method_name) and i not in target_list
+            ]
+            if matching:
+                target_list[:0] = matching
+
+    # Section 2: Untyped/generic fallback - prepend any remaining interceptors
+    # lacking standard method names directly to the unary-unary list.
+    unary_list = getattr(channel, "_unary_unary_interceptors", None)
+    if isinstance(unary_list, list):
+        standard_methods = tuple(method for method, _ in _CHANNEL_INTERCEPTOR_MAPPING)
+        fallback_items = [
+            i
+            for i in interceptor_list
+            if not any(hasattr(i, m) for m in standard_methods) and i not in unary_list
+        ]
+        if fallback_items:
+            unary_list[:0] = fallback_items
+
+    return channel
 
 
 _TRACE_CONTEXT_PROPAGATOR: Any = None

{google_api_core-2.42.0 → google_api_core-2.43.0}/google/api_core/gapic_v1/method.py

@@ -41,6 +41,10 @@ DEFAULT = _MethodDefault._DEFAULT_VALUE
 """Sentinel value indicating that a retry, timeout, or compression argument was unspecified,
 so the default should be used."""
 
+_TRANSPORT_KIND_GRPC = "grpc"
+_TRANSPORT_KIND_REST = "rest"
+_DEFAULT_TRANSPORT_KIND = _TRANSPORT_KIND_GRPC
+
 
 def _is_not_none_or_false(value):
     return value is not None and value is not False
@@ -122,7 +126,7 @@ def _extract_rpc_identity(
     return method_str, service, method
 
 
-def _extract_status_code(exc: Optional[Exception]) -> str:
+def _extract_status_code(exc: Optional[BaseException]) -> str:
     """Extract canonical status code name string from an exception.
 
     Status code name strings are resolved by inspecting the following locations:
@@ -132,7 +136,7 @@ def _extract_status_code(exc: Optional[Exception]) -> str:
     * Fallback: Defaults to the exception class name for standard Python errors.
 
     Args:
-        exc (Optional[Exception]): The exception to extract the status code name from.
+        exc (Optional[BaseException]): The exception to extract the status code name from.
 
     Returns:
         str: The canonical status code name (e.g. "NOT_FOUND", "UNAVAILABLE") or class name.
@@ -166,7 +170,7 @@ def _extract_status_code(exc: Optional[Exception]) -> str:
     return target.__class__.__name__
 
 
-def _extract_error_attributes(exc: Optional[Exception]) -> dict[str, Any]:
+def _extract_error_attributes(exc: Optional[BaseException]) -> dict[str, Any]:
     """Extract gcp.errors.* and error.type attributes from an exception.
 
     Error details and ErrorInfo structures are resolved by inspecting the following locations:
@@ -176,7 +180,7 @@ def _extract_error_attributes(exc: Optional[Exception]) -> dict[str, Any]:
     * Unified attribute extraction: Extracts domain, reason, and metadata from ErrorInfo or exception attributes.
 
     Args:
-        exc (Optional[Exception]): An exception (such as GoogleAPICallError or grpc.RpcError) or ErrorInfo object.
+        exc (Optional[BaseException]): An exception (such as GoogleAPICallError or grpc.RpcError) or ErrorInfo object.
 
     Returns:
         dict[str, Any]: Extracted error attributes (e.g. gcp.errors.domain, error.type, gcp.errors.metadata.*).
@@ -228,9 +232,10 @@ def _extract_error_attributes(exc: Optional[Exception]) -> dict[str, Any]:
 
     # 5. Extract human-readable error description for cross-language PRD parity
     message = getattr(target_exc, "message", None)
-    if not message and hasattr(target_exc, "details") and callable(target_exc.details):
-        message = target_exc.details()
-    if not message and isinstance(target_exc, Exception):
+    if not message and hasattr(target_exc, "details"):
+        details = target_exc.details
+        message = details() if callable(details) else details
+    if not message and isinstance(target_exc, BaseException):
         message = str(target_exc)
     if message:
         attrs["status.message"] = str(message)
@@ -271,6 +276,8 @@ class _GapicCallable(object):
             Allowed values for OpenTelemetry method tracing are "grpc" and "rest".
     """
 
+    _SUPPORTED_TRACING_KINDS = (_TRANSPORT_KIND_GRPC, _TRANSPORT_KIND_REST)
+
     def __init__(
         self,
         target,
@@ -282,7 +289,7 @@ class _GapicCallable(object):
         method_name=None,
         is_streaming=False,
         client_info=None,
-        kind="grpc",
+        kind=_DEFAULT_TRANSPORT_KIND,
     ):
         self._target = target
         self._retry = retry
@@ -301,11 +308,11 @@ class _GapicCallable(object):
             self._default_metadata = self._static_metadata
 
         # Configure the OpenTelemetry span factory once at initialization.
-        # For now, method tracing is gated to non-streaming gRPC calls where an explicit method_name is provided.
+        # For now, method tracing is gated to non-streaming calls where an explicit method_name is provided.
         self._start_span_fn = None
         if (
             not is_streaming
-            and kind in ("grpc", "rest")
+            and kind in self._SUPPORTED_TRACING_KINDS
             and method_name is not None
             and _observability.is_otel_capabilities_enabled(client_options)
         ):
@@ -323,9 +330,8 @@ class _GapicCallable(object):
                     tracer = trace.get_tracer("google.api_core")
 
                 span_name, _, _ = _extract_rpc_identity(method_name)
-                is_rest = kind in ("rest", "rest_asyncio")
                 span_attributes = {
-                    "rpc.system.name": "http" if is_rest else "grpc",
+                    "rpc.system.name": "http" if kind.startswith("rest") else "grpc",
                     "rpc.method": span_name,
                 }
                 self._start_span_fn = functools.partial(
@@ -338,11 +344,7 @@ class _GapicCallable(object):
                 # Gracefully disable tracing if OpenTelemetry or custom provider fails
                 self._start_span_fn = None
 
-    def __call__(
-        self, *args, timeout=DEFAULT, retry=DEFAULT, compression=DEFAULT, **kwargs
-    ):
-        """Invoke the low-level RPC with retry, timeout, compression, and metadata."""
-
+    def _prepare_call(self, timeout, retry, compression, kwargs):
         if retry is DEFAULT:
             retry = self._retry
 
@@ -376,22 +378,26 @@ class _GapicCallable(object):
         if compression is not None:
             kwargs["compression"] = compression
 
+        return wrapped_func
+
+    @contextlib.contextmanager
+    def _trace_span(self):
         span_cm = contextlib.nullcontext()
         if self._start_span_fn is not None:
             try:
                 span_cm = self._start_span_fn()
-            except (
-                Exception
-            ):  # Fail-open: proceed without span if tracing initialization fails
+            except Exception:
+                # Fail-open: proceed without span if tracing initialization fails
                 span_cm = contextlib.nullcontext()
 
         with span_cm as span:
             try:
-                result = wrapped_func(*args, **kwargs)
+                yield
                 if span is not None and hasattr(span, "set_attribute"):
                     span.set_attribute("rpc.response.status_code", "OK")
-                return result
-            except Exception as exc:
+            except (KeyboardInterrupt, SystemExit, GeneratorExit):
+                raise
+            except BaseException as exc:
                 if span is not None and hasattr(span, "set_attribute"):
                     span.set_attribute(
                         "rpc.response.status_code", _extract_status_code(exc)
@@ -400,6 +406,14 @@ class _GapicCallable(object):
                         span.set_attribute(k, v)
                 raise
 
+    def __call__(
+        self, *args, timeout=DEFAULT, retry=DEFAULT, compression=DEFAULT, **kwargs
+    ):
+        """Invoke the low-level RPC with retry, timeout, compression, and metadata."""
+        wrapped_func = self._prepare_call(timeout, retry, compression, kwargs)
+        with self._trace_span():
+            return wrapped_func(*args, **kwargs)
+
 
 def wrap_method(
     func,
@@ -412,7 +426,7 @@ def wrap_method(
     client_options=None,
     method_name=None,
     is_streaming=False,
-    kind="grpc",
+    kind=_DEFAULT_TRANSPORT_KIND,
 ):
     """Wrap an RPC method with common behavior.
 

google_api_core-2.43.0/google/api_core/gapic_v1/method_async.py

@@ -0,0 +1,120 @@
+# Copyright 2020 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.
+"""AsyncIO helpers for wrapping gRPC and REST methods with common functionality.
+
+This is used by gapic clients to provide common error mapping, retry, timeout,
+compression, pagination, and long-running operations to methods.
+"""
+
+import functools
+import inspect
+
+from google.api_core import grpc_helpers_async
+from google.api_core.gapic_v1 import client_info
+from google.api_core.gapic_v1.method import (  # noqa: F401
+    DEFAULT,
+    USE_DEFAULT_METADATA,
+    _GapicCallable,
+)
+
+_TRANSPORT_KIND_GRPC_ASYNC = "grpc_asyncio"
+_TRANSPORT_KIND_REST_ASYNC = "rest_asyncio"
+_DEFAULT_ASYNC_TRANSPORT_KIND = _TRANSPORT_KIND_GRPC_ASYNC
+
+
+class _AsyncGapicCallable(_GapicCallable):
+    """Async callable object that wraps an async RPC method with retry, timeout, metadata, and tracing."""
+
+    _SUPPORTED_TRACING_KINDS = (
+        _TRANSPORT_KIND_GRPC_ASYNC,
+        _TRANSPORT_KIND_REST_ASYNC,
+    )
+
+    async def __call__(
+        self, *args, timeout=DEFAULT, retry=DEFAULT, compression=DEFAULT, **kwargs
+    ):
+        """Invoke the low-level async RPC with retry, timeout, compression, and metadata."""
+        wrapped_func = self._prepare_call(timeout, retry, compression, kwargs)
+        with self._trace_span():
+            res = wrapped_func(*args, **kwargs)
+            if inspect.isawaitable(res):
+                return await res
+            return res
+
+
+def wrap_method(
+    func,
+    default_retry=None,
+    default_timeout=None,
+    default_compression=None,
+    client_info=client_info.DEFAULT_CLIENT_INFO,
+    kind=_DEFAULT_ASYNC_TRANSPORT_KIND,
+    *,
+    client_options=None,
+    method_name=None,
+    is_streaming=False,
+):
+    """Wrap an async RPC method with common behavior.
+
+    Args:
+        func (Callable): The low-level async RPC method.
+        default_retry (Optional[google.api_core.retry_async.AsyncRetry]): The default
+            retry strategy. If ``None``, the method will not retry by default.
+        default_timeout (Optional[Union[google.api_core.timeout.Timeout, float]]): The
+            default timeout strategy. Can also be specified as an int or float. If
+            ``None``, the method will not have a timeout specified by default.
+        default_compression (Optional[grpc.Compression]): The default
+            grpc.Compression. If ``None``, the method will not have
+            compression specified by default.
+        client_info (Optional[google.api_core.gapic_v1.client_info.ClientInfo]):
+            Client information used to create a user-agent string that's
+            passed as gRPC metadata to the method. If unspecified, then
+            a sane default will be used. If ``None``, then no user agent
+            metadata will be provided to the RPC method.
+        kind (str): The transport kind for the RPC method. Defaults to "grpc_asyncio".
+            Allowed values for OpenTelemetry method tracing are "grpc_asyncio" and "rest_asyncio".
+        client_options
+            (Optional[google.api_core.client_options.ClientOptions]):
+                Client options used to configure client-level behavior, such as
+                custom OpenTelemetry tracer providers. Defaults to None.
+        method_name (Optional[str]): Optional explicit full RPC method name
+            (e.g. "/google.cloud.secretmanager.v1.SecretManagerService/AccessSecretVersion").
+            Used to identify the RPC for observability.
+        is_streaming (bool): Whether the RPC method is streaming. Defaults to False.
+            Streaming methods are currently gated and do not generate Tier 3 spans.
+
+    Returns:
+        Callable: A new callable that takes optional ``retry``, ``timeout``,
+            and ``compression`` arguments and applies the common error mapping,
+            retry, timeout, metadata, and compression behavior to the low-level RPC method.
+    """
+    if kind == _DEFAULT_ASYNC_TRANSPORT_KIND:
+        func = grpc_helpers_async.wrap_errors(func)
+
+    metadata = [client_info.to_grpc_metadata()] if client_info is not None else None
+
+    return functools.wraps(func)(
+        _AsyncGapicCallable(
+            func,
+            default_retry,
+            default_timeout,
+            default_compression,
+            metadata=metadata,
+            client_options=client_options,
+            method_name=method_name,
+            is_streaming=is_streaming,
+            client_info=client_info,
+            kind=kind,
+        )
+    )