refactor(api-core): rename gapic internal helper modules and functions to public

Rename _client_cert, _config_helpers, _method_helpers, and _routing submodules and their functions to public names, as they are consumed across package boundaries by generated client libraries. Updates unit tests and top-level gapic_v1 imports accordingly.

Author: hebaalazzeh

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

@@ -25,9 +25,20 @@
 # Older Python versions safely ignore this variable.
 __lazy_modules__: Set[str] = {
     "google.api_core.gapic_v1.client_info",
+    "google.api_core.gapic_v1.client_cert",
+    "google.api_core.gapic_v1.config_helpers",
+    "google.api_core.gapic_v1.method_helpers",
+    "google.api_core.gapic_v1.routing",
     "google.api_core.gapic_v1.routing_header",
 }
-__all__ = ["client_info", "routing_header"]
+__all__ = [
+    "client_info",
+    "client_cert",
+    "config_helpers",
+    "method_helpers",
+    "routing",
+    "routing_header",
+]
 
 if _has_grpc:
     __lazy_modules__.update(
@@ -40,7 +51,11 @@
     )
 
 from google.api_core.gapic_v1 import (  # noqa: E402
+    client_cert,
     client_info,
+    config_helpers,
+    method_helpers,
+    routing,
     routing_header,
 )
 

…google/api_core/gapic_v1/_client_cert.py …/google/api_core/gapic_v1/client_cert.pypackages/google-api-core/google/api_core/gapic_v1/_client_cert.py renamed to packages/google-api-core/google/api_core/gapic_v1/client_cert.py packages/google-api-core/google/api_core/gapic_v1/_client_cert.py renamed to packages/google-api-core/google/api_core/gapic_v1/client_cert.py

@@ -22,7 +22,7 @@
 from google.auth.transport import mtls  # type: ignore
 
 
-def _use_client_cert_effective() -> bool:
+def use_client_cert_effective() -> bool:
     """Returns whether client certificate should be used for mTLS if the
     google-auth version supports should_use_client_cert automatic mTLS
     enablement.
@@ -53,7 +53,7 @@ def _use_client_cert_effective() -> bool:
         return use_client_cert_str == "true"
 
 
-def _get_client_cert_source(
+def get_client_cert_source(
     provided_cert_source: Optional[Callable[[], Tuple[bytes, bytes]]],
     use_cert_flag: bool,
 ) -> Optional[Callable[[], Tuple[bytes, bytes]]]:
@@ -77,3 +77,4 @@ def _get_client_cert_source(
         ):
             client_cert_source = mtls.default_client_cert_source()
     return client_cert_source
+

…gle/api_core/gapic_v1/_config_helpers.py …ogle/api_core/gapic_v1/config_helpers.pypackages/google-api-core/google/api_core/gapic_v1/_config_helpers.py renamed to packages/google-api-core/google/api_core/gapic_v1/config_helpers.py packages/google-api-core/google/api_core/gapic_v1/_config_helpers.py renamed to packages/google-api-core/google/api_core/gapic_v1/config_helpers.py

@@ -21,10 +21,10 @@
 
 from google.auth.exceptions import MutualTLSChannelError  # type: ignore
 
-from google.api_core.gapic_v1._client_cert import _use_client_cert_effective
+from google.api_core.gapic_v1.client_cert import use_client_cert_effective
 
 
-def _read_environment_variables() -> Tuple[bool, str, Optional[str]]:
+def read_environment_variables() -> Tuple[bool, str, Optional[str]]:
     """Returns the environment variables used by the client.
 
     Returns:
@@ -39,7 +39,7 @@ def _read_environment_variables() -> Tuple[bool, str, Optional[str]]:
             GOOGLE_API_USE_MTLS_ENDPOINT is not any of
             ["auto", "never", "always"].
     """
-    use_client_cert = _use_client_cert_effective()
+    use_client_cert = use_client_cert_effective()
     use_mtls_endpoint = os.getenv("GOOGLE_API_USE_MTLS_ENDPOINT", "auto").lower()
     universe_domain_env = os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
     if use_mtls_endpoint not in ("auto", "never", "always"):

…gle/api_core/gapic_v1/_method_helpers.py …ogle/api_core/gapic_v1/method_helpers.pypackages/google-api-core/google/api_core/gapic_v1/_method_helpers.py renamed to packages/google-api-core/google/api_core/gapic_v1/method_helpers.py packages/google-api-core/google/api_core/gapic_v1/_method_helpers.py renamed to packages/google-api-core/google/api_core/gapic_v1/method_helpers.py

@@ -20,7 +20,7 @@
 from typing import Any
 
 
-def _setup_request_id(request: Any, field_name: str, is_proto3_optional: bool) -> None:
+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:

…ore/google/api_core/gapic_v1/_routing.py …core/google/api_core/gapic_v1/routing.pypackages/google-api-core/google/api_core/gapic_v1/_routing.py renamed to packages/google-api-core/google/api_core/gapic_v1/routing.py packages/google-api-core/google/api_core/gapic_v1/_routing.py renamed to packages/google-api-core/google/api_core/gapic_v1/routing.py

@@ -27,7 +27,7 @@
 )
 
 
-def _get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
+def get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
     """Converts api endpoint to mTLS endpoint.
 
     Convert "*.sandbox.googleapis.com" and "*.googleapis.com" to
@@ -57,7 +57,7 @@ def _get_default_mtls_endpoint(api_endpoint: Optional[str]) -> Optional[str]:
     return api_endpoint.replace(".googleapis.com", ".mtls.googleapis.com")
 
 
-def _get_api_endpoint(
+def get_api_endpoint(
     api_override: Optional[str],
     client_cert_source: Optional[Any],
     universe_domain: str,
@@ -85,7 +85,7 @@ def _get_api_endpoint(
         )
 
 
-def _get_universe_domain(
+def get_universe_domain(
     client_universe_domain: Optional[str],
     universe_domain_env: Optional[str],
     default_universe: str,

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

@@ -19,46 +19,46 @@
 import pytest
 
 
-from google.api_core.gapic_v1._client_cert import (
-    _get_client_cert_source,
-    _use_client_cert_effective,
+from google.api_core.gapic_v1.client_cert import (
+    get_client_cert_source,
+    use_client_cert_effective,
 )
 
 
 @mock.patch("google.auth.transport.mtls.should_use_client_cert", create=True)
 def test_use_client_cert_effective_with_google_auth(mock_method):
     # Test when google-auth supports the method
     mock_method.return_value = True
-    assert _use_client_cert_effective() is True
+    assert use_client_cert_effective() is True
 
     mock_method.return_value = False
-    assert _use_client_cert_effective() is False
+    assert use_client_cert_effective() is False
 
 
 @mock.patch.dict(os.environ, {}, clear=True)
 def test_use_client_cert_effective_fallback():
     # We must patch hasattr to simulate google-auth lacking the method
     with mock.patch(
-        "google.api_core.gapic_v1._client_cert.hasattr", return_value=False
+        "google.api_core.gapic_v1.client_cert.hasattr", return_value=False
     ):
         # Default is false
-        assert _use_client_cert_effective() is False
+        assert use_client_cert_effective() is False
 
         env_true = {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "true"}
         with mock.patch.dict(os.environ, env_true):
-            assert _use_client_cert_effective() is True
+            assert use_client_cert_effective() is True
 
         with mock.patch.dict(
             os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "false"}
         ):
-            assert _use_client_cert_effective() is False
+            assert use_client_cert_effective() is False
 
         with mock.patch.dict(
             os.environ, {"GOOGLE_API_USE_CLIENT_CERTIFICATE": "invalid"}
         ):
             match_str = "must be either `true` or `false`"
             with pytest.raises(ValueError, match=match_str):
-                _use_client_cert_effective()
+                use_client_cert_effective()
 
 
 @mock.patch(
@@ -72,10 +72,10 @@ def test_get_client_cert_source(mock_default, mock_has_default):
     mock_has_default.return_value = True
 
     # When use_cert_flag is False, return None
-    assert _get_client_cert_source(b"provided", False) is None
+    assert get_client_cert_source(b"provided", False) is None
 
     # When provided_cert_source is given, return provided
-    assert _get_client_cert_source(b"provided", True) == b"provided"  # noqa: E501
+    assert get_client_cert_source(b"provided", True) == b"provided"  # noqa: E501
 
     # When no provided cert but default is available
-    assert _get_client_cert_source(None, True) == b"default_cert"
+    assert get_client_cert_source(None, True) == b"default_cert"

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

@@ -20,19 +20,19 @@
 
 from google.auth.exceptions import MutualTLSChannelError
 
-from google.api_core.gapic_v1._config_helpers import _read_environment_variables
+from google.api_core.gapic_v1.config_helpers import read_environment_variables
 
 
 @mock.patch(
-    "google.api_core.gapic_v1._config_helpers._use_client_cert_effective"
+    "google.api_core.gapic_v1.config_helpers.use_client_cert_effective"
 )  # noqa: E501
 @mock.patch.dict(os.environ, clear=True)
 def test_read_environment_variables(mock_effective):
     mock_effective.return_value = True
     os.environ["GOOGLE_API_USE_MTLS_ENDPOINT"] = "always"
     os.environ["GOOGLE_CLOUD_UNIVERSE_DOMAIN"] = "custom.com"
 
-    cert, mtls, domain = _read_environment_variables()
+    cert, mtls, domain = read_environment_variables()
     assert cert is True
     assert mtls == "always"
     assert domain == "custom.com"
@@ -44,4 +44,4 @@ def test_read_environment_variables_invalid_mtls():
     with pytest.raises(
         MutualTLSChannelError, match="must be `never`, `auto` or `always`"
     ):
-        _read_environment_variables()
+        read_environment_variables()

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

@@ -14,22 +14,22 @@
 # limitations under the License.
 
 
-from google.api_core.gapic_v1._method_helpers import _setup_request_id
+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)
+    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)
+    setup_request_id(req, "request_id", True)
     assert req["request_id"] == "existing"
 
     class DummyRequest:
@@ -43,13 +43,13 @@ def HasField(self, field_name):
 
     # test object request proto3 optional true
     req_obj = DummyRequest()
-    _setup_request_id(req_obj, "request_id", True)
+    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)
+    setup_request_id(req_obj2, "request_id", False)
     assert req_obj2.request_id != ""
     uuid.UUID(req_obj2.request_id)
 
@@ -59,6 +59,6 @@ def __init__(self):
 
     # test custom non-iterable object wrapper
     req_obj3 = CustomRequestWrapper()
-    _setup_request_id(req_obj3, "request_id", True)
+    setup_request_id(req_obj3, "request_id", True)
     assert req_obj3.request_id != ""
     uuid.UUID(req_obj3.request_id)