feat(api-core): move request-id auto-population logic to gapic_v1 public helpers

Introduces method_helpers module containing setup_request_id helper. Exposes the module as public in gapic_v1.

Author: hebaalazzeh

packages/google-api-core/google/api_core/gapic_v1/__init__.py

@@ -25,9 +25,10 @@
 # Older Python versions safely ignore this variable.
 __lazy_modules__: Set[str] = {
     "google.api_core.gapic_v1.client_info",
+    "google.api_core.gapic_v1.method_helpers",
     "google.api_core.gapic_v1.routing_header",
 }
-__all__ = ["client_info", "routing_header"]
+__all__ = ["client_info", "method_helpers", "routing_header"]
 
 if _has_grpc:
     __lazy_modules__.update(
@@ -41,6 +42,7 @@
 
 from google.api_core.gapic_v1 import (  # noqa: E402
     client_info,
+    method_helpers,
     routing_header,
 )
 

packages/google-api-core/google/api_core/gapic_v1/method_helpers.py

@@ -0,0 +1,51 @@
+# -*- 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.
+#
+
+"""Helpers for method requests."""
+
+import uuid
+from typing import Any
+
+
+def setup_request_id(request: Any, field_name: str, is_proto3_optional: bool) -> None:
+    """Populate a UUID4 field in the request if it is not already set.
+
+    Args:
+        request (Union[google.protobuf.message.Message, dict]): The
+            request object.
+        field_name (str): The name of the field to populate.
+        is_proto3_optional (bool): Whether the field is proto3 optional.
+    """
+    if isinstance(request, dict):
+        if is_proto3_optional:
+            if field_name not in request:
+                request[field_name] = str(uuid.uuid4())
+        elif not request.get(field_name):
+            request[field_name] = str(uuid.uuid4())
+        return
+
+    if is_proto3_optional:
+        try:
+            # Pure protobuf messages
+            if not request.HasField(field_name):
+                setattr(request, field_name, str(uuid.uuid4()))
+        except (AttributeError, ValueError):
+            # Proto-plus messages or other objects
+            if not getattr(request, field_name, None):
+                setattr(request, field_name, str(uuid.uuid4()))
+    else:
+        if not getattr(request, field_name):
+            setattr(request, field_name, str(uuid.uuid4()))

packages/google-api-core/noxfile.py

@@ -350,7 +350,7 @@ def prerelease_deps(session):
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def core_deps_from_source(session):
     """Run the test suite installing dependencies from source."""
-    default(session, prerelease=True)
+    default(session, install_deps_from_source=True)
 
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)

packages/google-api-core/tests/conftest.py

@@ -0,0 +1,31 @@
+# -*- 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.
+
+import os
+from unittest import mock
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def mock_mtls_env():
+    """Autouse session-scoped fixture to isolate unit tests from workstation mTLS environments."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false",
+            "CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE": "false",
+        },
+    ):
+        yield

packages/google-api-core/tests/unit/gapic/test_method_helpers.py

@@ -0,0 +1,64 @@
+# -*- 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.
+
+
+from google.api_core.gapic_v1.method_helpers import setup_request_id
+
+
+def test_setup_request_id():
+    import uuid
+
+    # test dict request
+    req = {}
+    setup_request_id(req, "request_id", True)
+    assert "request_id" in req
+    uuid_str = req["request_id"]
+    uuid.UUID(uuid_str)  # verify it is a valid UUID
+
+    # test dict request when already set
+    req = {"request_id": "existing"}
+    setup_request_id(req, "request_id", True)
+    assert req["request_id"] == "existing"
+
+    class DummyRequest:
+        def __init__(self):
+            self.request_id = ""
+
+        def HasField(self, field_name):
+            if not hasattr(self, field_name):
+                raise ValueError()
+            return bool(getattr(self, field_name))
+
+    # test object request proto3 optional true
+    req_obj = DummyRequest()
+    setup_request_id(req_obj, "request_id", True)
+    assert req_obj.request_id != ""
+    uuid.UUID(req_obj.request_id)
+
+    # test object request proto3 optional false
+    req_obj2 = DummyRequest()
+    setup_request_id(req_obj2, "request_id", False)
+    assert req_obj2.request_id != ""
+    uuid.UUID(req_obj2.request_id)
+
+    class CustomRequestWrapper:
+        def __init__(self):
+            self.request_id = ""
+
+    # test custom non-iterable object wrapper
+    req_obj3 = CustomRequestWrapper()
+    setup_request_id(req_obj3, "request_id", True)
+    assert req_obj3.request_id != ""
+    uuid.UUID(req_obj3.request_id)

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

@@ -31,8 +31,7 @@
 except ImportError:  # pragma: NO COVER
     pytest.skip("No GRPC", allow_module_level=True)
 
-from google.api_core import bidi
-from google.api_core import exceptions
+from google.api_core import bidi, exceptions
 
 
 class Test_RequestQueueGenerator(object):
@@ -195,7 +194,7 @@ def test_delays_entry_attempts_above_threshold(self):
         # (NOTE: not using assert all(...), b/c the coverage check would complain)
         for i, entry in enumerate(entries):
             if i != 3:
-                assert entry["reported_wait"] == 0.0
+                assert entry["reported_wait"] < 0.01
 
         # The delayed entry is expected to have been delayed for a significant
         # chunk of the full second, and the actual and reported delay times