feat: use custom FeatureGatingError in feature gating helpers

Author: chalmerlowe

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

@@ -28,6 +28,11 @@
 _FALSY_VALUES = ("n", "no", "f", "false", "off", "0")
 
 
+class FeatureGatingError(ValueError):
+    """Raised when feature gating resolution fails or is misconfigured."""
+    pass
+
+
 def _strtobool(val: str) -> bool | None:
     """Convert a string representation of truth to a boolean."""
     clean_val = val.lower().strip()
@@ -114,7 +119,7 @@ def resolve_feature_flags(
     if "EXPERIMENTAL" in env_var:
         # Fail Fast if provider present but experimental environment variable is not enabled
         if env_var_setting is not True and has_provider:
-            raise ValueError(
+            raise FeatureGatingError(
                 f"Experimental feature requires {env_var} to be set to 'true' to use programmatic providers."
             )
 

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

@@ -15,6 +15,7 @@
 import pytest
 from google.api_core import _feature_gating_helpers
 from google.api_core._feature_gating_helpers import (
+    FeatureGatingError,
     _get_env_bool,
     _strtobool,
 )
@@ -99,8 +100,8 @@ def test_resolve_feature_flags_exp_blocked_with_provider_fails_fast(
     configuration = {"tracer_provider": object()}
 
     # Action & Assertion
-    with pytest.raises(ValueError, match="Experimental feature"):
-        feature_gating_helpers.resolve_feature_flags(
+    with pytest.raises(FeatureGatingError, match="Experimental feature"):
+        _feature_gating_helpers.resolve_feature_flags(
             env_var="GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
             feature_key="tracer_provider",
             configuration=configuration,