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/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)