refactor: rename parameters and enforce keyword-only in feature gating

Author: chalmerlowe

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

@@ -50,24 +50,25 @@ def _get_env_bool(name: str) -> Optional[bool]:
 
 
 def _has_provider(
-    client_options: Optional[Union[Dict[str, Any], Any]], provider_key: str
+    *, configuration: Optional[Union[Dict[str, Any], Any]], feature_key: str
 ) -> bool:
-    """Checks if a specific provider key is present and not None in client_options."""
-    if client_options is None:
+    """Checks if a specific feature key is present and not None in configuration."""
+    if configuration is None:
         return False
 
-    if isinstance(client_options, dict):
-        return client_options.get(provider_key) is not None
+    if isinstance(configuration, dict):
+        return configuration.get(feature_key) is not None
 
-    return getattr(client_options, provider_key, None) is not None
+    return getattr(configuration, feature_key, None) is not None
 
 
 def resolve_feature_flags(
+    *,
     env_var: str,
-    provider_key: str,
-    client_options: Optional[Union[Dict[str, Any], Any]] = None,
+    feature_key: str,
+    configuration: Optional[Union[Dict[str, Any], Any]] = None,
 ) -> bool:
-    """Determines if a feature is enabled based on environment variables and client options.
+    """Determines if a feature is enabled based on environment variables and configuration.
 
     Behavior depends on whether the `env_var` name contains "EXPERIMENTAL":
 
@@ -82,8 +83,8 @@ def resolve_feature_flags(
 
     Args:
         env_var: The name of the environment variable controlling this feature.
-        provider_key: The key in client_options/attributes for the programmatic provider.
-        client_options: Optional. A dictionary or object containing client configuration.
+        feature_key: The key in configuration/attributes for the programmatic provider.
+        configuration: Optional. A dictionary or object containing client configuration.
 
     Returns:
         bool: True if the feature is resolved to enabled, False otherwise.
@@ -93,7 +94,9 @@ def resolve_feature_flags(
     """
 
     # Check for programmatic feature provider
-    has_provider = _has_provider(client_options, provider_key)
+    has_provider = _has_provider(
+        configuration=configuration, feature_key=feature_key
+    )
 
     # Read environment variable
     env_var_setting = _get_env_bool(env_var)

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

@@ -74,8 +74,8 @@ def test_resolve_feature_flags_ga_enabled_via_env(monkeypatch):
     # Action
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=None,
+        feature_key="tracer_provider",
+        configuration=None,
     )
 
     # Assertion
@@ -96,26 +96,26 @@ def test_resolve_feature_flags_exp_blocked_with_provider_fails_fast(
         monkeypatch.delenv(
             "GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", raising=False
         )
-    client_options = {"tracer_provider": object()}
+    configuration = {"tracer_provider": object()}
 
     # Action & Assertion
     with pytest.raises(ValueError, match="Experimental feature"):
         feature_gating_helpers.resolve_feature_flags(
             env_var="GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
-            provider_key="tracer_provider",
-            client_options=client_options,
+            feature_key="tracer_provider",
+            configuration=configuration,
         )
 
 
 def test_resolve_feature_flags_exp_enabled_with_provider(monkeypatch):
     """Verify that experimental feature is enabled if the experimental environment variable is enabled and a provider is provided."""
     monkeypatch.setenv("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", "true")
-    client_options = {"tracer_provider": object()}
+    configuration = {"tracer_provider": object()}
 
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=client_options,
+        feature_key="tracer_provider",
+        configuration=configuration,
     )
     assert result is True
 
@@ -126,8 +126,8 @@ def test_resolve_feature_flags_exp_enabled_without_provider(monkeypatch):
 
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=None,
+        feature_key="tracer_provider",
+        configuration=None,
     )
     assert result is True
 
@@ -138,8 +138,8 @@ def test_resolve_feature_flags_exp_disabled_without_provider(monkeypatch):
 
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=None,
+        feature_key="tracer_provider",
+        configuration=None,
     )
     assert result is False
 
@@ -148,12 +148,12 @@ def test_resolve_feature_flags_ga_enabled_via_provider(monkeypatch):
     """Verify that a GA feature is enabled if a provider is provided, ignoring the environment variable."""
     # Env var is False, but provider is present
     monkeypatch.setenv("GOOGLE_SDK_PYTHON_TRACING_ENABLED", "false")
-    client_options = {"tracer_provider": object()}
+    configuration = {"tracer_provider": object()}
 
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=client_options,
+        feature_key="tracer_provider",
+        configuration=configuration,
     )
     assert result is True
 
@@ -169,8 +169,8 @@ def test_resolve_feature_flags_ga_fallback_to_false(monkeypatch, env_val):
         monkeypatch.delenv("GOOGLE_SDK_PYTHON_TRACING_ENABLED", raising=False)
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=None,
+        feature_key="tracer_provider",
+        configuration=None,
     )
     assert result is False
 
@@ -181,19 +181,19 @@ def __init__(self):
 
 
 @pytest.mark.parametrize(
-    "client_options",
+    "configuration",
     [
         {"other_option": "value"},
         _MockOptions(),
     ],
     ids=["dict_without_key", "object_without_key"],
 )
-def test_resolve_feature_flags_options_without_key(client_options):
-    """Verify behavior when client_options is present but missing the provider key."""
+def test_resolve_feature_flags_options_without_key(configuration):
+    """Verify behavior when configuration is present but missing the provider key."""
     # GA Path: should fall through to env var / fallback
     result = feature_gating_helpers.resolve_feature_flags(
         env_var="GOOGLE_SDK_PYTHON_TRACING_ENABLED",
-        provider_key="tracer_provider",
-        client_options=client_options,
+        feature_key="tracer_provider",
+        configuration=configuration,
     )
     assert result is False