feat(api-core): rename channel wrapper terminology to interceptor

Author: chalmerlowe

packages/google-api-core/google/api_core/_observability.py

@@ -22,9 +22,9 @@
 from google.api_core.client_options import ClientOptions
 
 if TYPE_CHECKING:
-    from google.api_core.grpc_helpers import ChannelWrapperCallable
+    from google.api_core.grpc_helpers import ClientInterceptorCallable
 else:
-    ChannelWrapperCallable = Callable[[Any], Any]
+    ClientInterceptorCallable = Callable[[Any], Any]
 
 _TRACER_PROVIDER = "tracer_provider"
 
@@ -67,7 +67,7 @@ def _get_otel_interceptor(
 
     Args:
         client_options: The client options object or dictionary.
-        is_async: If True, returns an async interceptor (`aio_client_interceptor`),
+        is_async: If True, returns an async interceptor (`aio_client_interceptors`),
             otherwise returns a sync interceptor (`client_interceptor`).
 
     Returns:
@@ -86,17 +86,17 @@ def _get_otel_interceptor(
     return otel_grpc.client_interceptor(tracer_provider=tracer_provider)
 
 
-def get_otel_channel_wrapper(
+def get_otel_interceptor(
     client_options: ClientOptions | dict[str, Any] | None = None,
-) -> ChannelWrapperCallable | None:
-    """Returns a channel wrapper callable that wraps a sync gRPC channel with OpenTelemetry tracing.
+) -> ClientInterceptorCallable | 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:
-        Optional[ChannelWrapperCallable]: A channel-wrapping callable if OpenTelemetry
+        Optional[ClientInterceptorCallable]: An interceptor callable if OpenTelemetry
             tracing is enabled and installed, None otherwise.
     """
     if not is_otel_capabilities_enabled(client_options):
@@ -106,23 +106,23 @@ def get_otel_channel_wrapper(
 
     interceptor = _get_otel_interceptor(client_options, is_async=False)
 
-    def channel_wrapper(channel: Any) -> Any:
+    def otel_interceptor(channel: Any) -> Any:
         return otel_grpc.intercept_channel(channel, interceptor)
 
-    return channel_wrapper
+    return otel_interceptor
 
 
 def get_otel_async_interceptor(
     client_options: ClientOptions | dict[str, Any] | None = None,
 ) -> Any | None:
-    """Returns an async gRPC client interceptor for OpenTelemetry tracing.
+    """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:
-        Optional[Any]: An instantiated OpenTelemetry async client interceptor
+        Optional[Any]: Instantiated OpenTelemetry async client interceptors
             if tracing is enabled and installed, None otherwise.
     """
     if not is_otel_capabilities_enabled(client_options):

packages/google-api-core/google/api_core/grpc_helpers.py

@@ -35,7 +35,6 @@
 import google.auth.transport.requests
 import google.protobuf
 import grpc
-
 from google.api_core import exceptions, general_helpers
 
 # The list of gRPC Callable interfaces that return iterators.
@@ -55,11 +54,11 @@
 # Runtime tuple of gRPC client interceptor base classes for isinstance checks
 _CLIENT_INTERCEPTOR_CLASSES = get_args(ClientInterceptor)
 
-# Type alias representing a channel-wrapping callable
-ChannelWrapperCallable: TypeAlias = Callable[[grpc.Channel], grpc.Channel]
+# Type alias representing a channel-intercepting callable
+ClientInterceptorCallable: TypeAlias = Callable[[grpc.Channel], grpc.Channel]
 
-# Generic type alias representing any channel wrapper (interceptor or callable)
-ChannelWrapper: TypeAlias = ClientInterceptor | ChannelWrapperCallable
+# Generic type alias representing any client interceptor (standard interceptor or callable)
+ClientInterceptorType: TypeAlias = ClientInterceptor | ClientInterceptorCallable
 
 
 def _patch_callable_name(callable_):
@@ -446,43 +445,43 @@ def _modify_target_for_direct_path(target: str) -> str:
     return target
 
 
-def apply_channel_wrappers(
+def apply_channel_interceptors(
     channel: grpc.Channel,
-    wrappers: Sequence[ChannelWrapper] | None = None,
+    interceptors: Sequence[ClientInterceptorType] | None = None,
 ) -> grpc.Channel:
-    """Applies channel wrappers (client interceptors or channel-wrapping callables) to a gRPC channel.
+    """Applies client interceptors or channel-intercepting callables to a gRPC channel.
 
-    Executes in reverse order so the first wrapper in the sequence becomes the
-    outermost layer on outbound requests and the innermost layer on inbound responses.
+    Executes in reverse order so the first interceptor in the sequence becomes the
+    outermost layer on outbound requests and the innermost layer on inbound responses,
+    aligning with the behavior of ``grpc.intercept_channel``.
 
     Args:
-        channel (grpc.Channel): The channel to wrap.
-        wrappers (Optional[Sequence[ChannelWrapper]]):
-            An optional sequence of client interceptors or channel-wrapping
-            callables to apply.
+        channel (grpc.Channel): The channel to intercept.
+        interceptors (Optional[Sequence[Union[ClientInterceptor, Callable[[grpc.Channel], grpc.Channel]]]]):
+            Additional interceptors (or callables that apply interceptors) to apply to the gRPC channel.
 
     Returns:
-        grpc.Channel: The wrapped channel, or the original channel if no
-            wrappers were provided.
+        grpc.Channel: The intercepted channel, or the original channel if no
+            interceptors were provided.
 
     Raises:
-        TypeError: If an item in ``wrappers`` is neither a gRPC ClientInterceptor
+        TypeError: If an item in ``interceptors`` is neither a gRPC ClientInterceptor
             nor a Callable[[Channel], Channel].
     """
-    if not wrappers:
+    if not interceptors:
         return channel
 
     modified_channel = channel
     # Reverse the inputs to align with the behavior of grpc.create_channel(*interceptors)
-    for wrapper in reversed(list(wrappers)):
-        if isinstance(wrapper, _CLIENT_INTERCEPTOR_CLASSES):
-            modified_channel = grpc.intercept_channel(modified_channel, wrapper)
-        elif callable(wrapper):
-            wrapper_callable = cast(ChannelWrapperCallable, wrapper)
-            modified_channel = wrapper_callable(modified_channel)
+    for interceptor in reversed(list(interceptors)):
+        if isinstance(interceptor, _CLIENT_INTERCEPTOR_CLASSES):
+            modified_channel = grpc.intercept_channel(modified_channel, interceptor)
+        elif callable(interceptor):
+            interceptor_callable = cast(ClientInterceptorCallable, interceptor)
+            modified_channel = interceptor_callable(modified_channel)
         else:
             raise TypeError(
-                f"Expected ChannelWrapper (ClientInterceptor or Callable[[Channel], Channel]), got {type(wrapper).__name__}"
+                f"Expected ClientInterceptor or Callable[[Channel], Channel], got {type(interceptor).__name__}"
             )
 
     return modified_channel

packages/google-api-core/tests/unit/test_grpc_helpers.py

@@ -24,9 +24,8 @@
     pytest.skip("No GRPC", allow_module_level=True)
 
 import google.auth.credentials
-from google.longrunning import operations_pb2
-
 from google.api_core import exceptions, grpc_helpers
+from google.longrunning import operations_pb2
 
 
 def test__patch_callable_name():
@@ -934,15 +933,17 @@ def test_close(self):
         assert channel.close() is None
 
 
-@pytest.mark.parametrize("falsy_wrappers", [None, [], ()])
-def test_apply_channel_wrappers_passthrough(falsy_wrappers):
-    """Verify that falsy or empty wrapper sequences return the channel unmodified."""
+@pytest.mark.parametrize("falsy_interceptors", [None, [], ()])
+def test_apply_channel_interceptors_passthrough(falsy_interceptors):
+    """Verify that falsy or empty interceptor sequences return the channel unmodified."""
     mock_base_channel = mock.Mock(name="base_channel")
-    result = grpc_helpers.apply_channel_wrappers(mock_base_channel, falsy_wrappers)
+    result = grpc_helpers.apply_channel_interceptors(
+        mock_base_channel, falsy_interceptors
+    )
     assert result is mock_base_channel
 
 
-def test_apply_channel_wrappers_grpc_client_interceptors():
+def test_apply_channel_interceptors_grpc_client_interceptors():
     """Verify that standard gRPC ClientInterceptor instances are applied via grpc.intercept_channel."""
 
     class DummyUnaryInterceptor(grpc.UnaryUnaryClientInterceptor):
@@ -966,7 +967,7 @@ def intercept_stream_stream(
         "grpc.intercept_channel",
         side_effect=[mock_chan_after_i2, mock_chan_after_i1],
     ) as mock_intercept:
-        result = grpc_helpers.apply_channel_wrappers(
+        result = grpc_helpers.apply_channel_interceptors(
             mock_base_channel, [interceptor1, interceptor2]
         )
 
@@ -981,53 +982,53 @@ def intercept_stream_stream(
     )
 
 
-def test_apply_channel_wrappers_callables():
-    """Verify that channel-wrapping callables Callable[[Channel], Channel] are invoked in sequence."""
+def test_apply_channel_interceptors_callables():
+    """Verify that channel-intercepting callables Callable[[Channel], Channel] are invoked in sequence."""
     mock_base_channel = mock.Mock(name="base_channel")
     mock_chan_1 = mock.Mock(name="chan_1")
     mock_chan_2 = mock.Mock(name="chan_2")
 
-    wrapper1 = mock.Mock(side_effect=lambda ch: mock_chan_2)
-    wrapper2 = mock.Mock(side_effect=lambda ch: mock_chan_1)
+    interceptor1 = mock.Mock(side_effect=lambda ch: mock_chan_2)
+    interceptor2 = mock.Mock(side_effect=lambda ch: mock_chan_1)
 
-    result = grpc_helpers.apply_channel_wrappers(
-        mock_base_channel, [wrapper1, wrapper2]
+    result = grpc_helpers.apply_channel_interceptors(
+        mock_base_channel, [interceptor1, interceptor2]
     )
 
     assert result is mock_chan_2
-    # Executed in reverse order: wrapper2 runs first on base channel, then wrapper1
-    wrapper2.assert_called_once_with(mock_base_channel)
-    wrapper1.assert_called_once_with(mock_chan_1)
+    # Executed in reverse order: interceptor2 runs first on base channel, then interceptor1
+    interceptor2.assert_called_once_with(mock_base_channel)
+    interceptor1.assert_called_once_with(mock_chan_1)
 
 
-def test_apply_channel_wrappers_interspersed():
-    """Verify that a mixed sequence of gRPC interceptors and channel wrapper callables are applied."""
+def test_apply_channel_interceptors_interspersed():
+    """Verify that a mixed sequence of gRPC interceptors and interceptor callables are applied."""
 
     class DummyUnaryInterceptor(grpc.UnaryUnaryClientInterceptor):
         def intercept_unary_unary(self, continuation, client_call_details, request):
             return continuation(client_call_details, request)
 
     interceptor = DummyUnaryInterceptor()
     mock_base_channel = mock.Mock(name="base_channel")
-    mock_chan_after_wrapper = mock.Mock(name="chan_after_wrapper")
+    mock_chan_after_callable = mock.Mock(name="chan_after_callable")
     mock_chan_after_interceptor = mock.Mock(name="chan_after_interceptor")
 
-    wrapper = mock.Mock(return_value=mock_chan_after_wrapper)
+    interceptor_callable = mock.Mock(return_value=mock_chan_after_callable)
 
     with mock.patch(
         "grpc.intercept_channel", return_value=mock_chan_after_interceptor
     ) as mock_intercept:
-        result = grpc_helpers.apply_channel_wrappers(
-            mock_base_channel, [interceptor, wrapper]
+        result = grpc_helpers.apply_channel_interceptors(
+            mock_base_channel, [interceptor, interceptor_callable]
         )
 
     assert result is mock_chan_after_interceptor
-    wrapper.assert_called_once_with(mock_base_channel)
-    mock_intercept.assert_called_once_with(mock_chan_after_wrapper, interceptor)
+    interceptor_callable.assert_called_once_with(mock_base_channel)
+    mock_intercept.assert_called_once_with(mock_chan_after_callable, interceptor)
 
 
-def test_apply_channel_wrappers_invalid_type_raises():
+def test_apply_channel_interceptors_invalid_type_raises():
     """Verify that passing an invalid object that is neither an interceptor nor callable raises TypeError."""
     mock_base_channel = mock.Mock(name="base_channel")
-    with pytest.raises(TypeError, match="Expected ChannelWrapper"):
-        grpc_helpers.apply_channel_wrappers(mock_base_channel, [12345])
+    with pytest.raises(TypeError, match="Expected ClientInterceptor or Callable"):
+        grpc_helpers.apply_channel_interceptors(mock_base_channel, [12345])

packages/google-api-core/tests/unit/test_observability.py

@@ -16,7 +16,6 @@
 from unittest import mock
 
 import pytest
-
 from google.api_core import _observability
 from google.api_core._feature_gating_helpers import FeatureGatingError
 from google.api_core.client_options import ClientOptions
@@ -178,18 +177,18 @@ def test_get_otel_interceptor_async(monkeypatch):
     )
 
 
-def test_get_otel_channel_wrapper_disabled(monkeypatch):
+def test_get_otel_interceptor_disabled(monkeypatch):
     monkeypatch.setenv("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", "false")
-    assert _observability.get_otel_channel_wrapper() is None
+    assert _observability.get_otel_interceptor() is None
 
 
-def test_get_otel_channel_wrapper_otel_missing(monkeypatch):
+def test_get_otel_interceptor_otel_missing(monkeypatch):
     monkeypatch.setenv("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", "true")
     monkeypatch.setitem(sys.modules, "opentelemetry.instrumentation.grpc", None)
-    assert _observability.get_otel_channel_wrapper() is None
+    assert _observability.get_otel_interceptor() is None
 
 
-def test_get_otel_channel_wrapper_enabled(monkeypatch):
+def test_get_otel_interceptor_enabled(monkeypatch):
     monkeypatch.setenv("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", "true")
     mock_tracer_provider = object()
     options = ClientOptions(tracer_provider=mock_tracer_provider)
@@ -212,22 +211,22 @@ def test_get_otel_channel_wrapper_enabled(monkeypatch):
         sys.modules, "opentelemetry.instrumentation.grpc", mock_otel_grpc
     )
 
-    wrapper = _observability.get_otel_channel_wrapper(client_options=options)
-    assert callable(wrapper)
+    interceptor = _observability.get_otel_interceptor(client_options=options)
+    assert callable(interceptor)
 
     mock_otel_grpc.client_interceptor.assert_called_once_with(
         tracer_provider=mock_tracer_provider
     )
 
-    result = wrapper(mock_raw_channel)
+    result = interceptor(mock_raw_channel)
     assert result is mock_wrapped_channel
     mock_otel_grpc.intercept_channel.assert_called_once_with(
         mock_raw_channel, mock_interceptor
     )
 
 
-def test_get_otel_channel_wrapper_with_apply_channel_wrappers(monkeypatch):
-    """Proves that get_otel_channel_wrapper integrates seamlessly into apply_channel_wrappers."""
+def test_get_otel_interceptor_with_apply_channel_interceptors(monkeypatch):
+    """Proves that get_otel_interceptor integrates seamlessly into apply_channel_interceptors."""
     pytest.importorskip("grpc")
     from google.api_core import grpc_helpers
 
@@ -253,11 +252,11 @@ def test_get_otel_channel_wrapper_with_apply_channel_wrappers(monkeypatch):
         sys.modules, "opentelemetry.instrumentation.grpc", mock_otel_grpc
     )
 
-    otel_wrapper = _observability.get_otel_channel_wrapper(client_options=options)
-    assert callable(otel_wrapper)
+    otel_interceptor = _observability.get_otel_interceptor(client_options=options)
+    assert callable(otel_interceptor)
 
-    result = grpc_helpers.apply_channel_wrappers(
-        mock_raw_channel, wrappers=[otel_wrapper]
+    result = grpc_helpers.apply_channel_interceptors(
+        mock_raw_channel, interceptors=[otel_interceptor]
     )
     assert result is mock_wrapped_channel
     mock_otel_grpc.intercept_channel.assert_called_once_with(