Skip to content

Commit 347b60c

Browse files
feat: add include_beta option, keep include_experimental as an alias
1 parent 998d3a7 commit 347b60c

3 files changed

Lines changed: 183 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1042,7 +1042,7 @@ You can also enable a default debug logger by setting an environment variable `G
10421042

10431043
The SDK provides options to test upcoming API changes before they become the default behavior. This is useful for:
10441044

1045-
- **Testing experimental features** before they are generally available
1045+
- **Testing beta features** before they are generally available
10461046
- **Preparing for deprecations** by excluding deprecated endpoints ahead of their removal
10471047

10481048
### Configuration Options
@@ -1056,7 +1056,7 @@ import os
10561056

10571057
# Set environment variables before initializing the SDK
10581058
os.environ["X_GLEAN_EXCLUDE_DEPRECATED_AFTER"] = "2026-10-15"
1059-
os.environ["X_GLEAN_INCLUDE_EXPERIMENTAL"] = "true"
1059+
os.environ["X_GLEAN_INCLUDE_BETA"] = "true"
10601060

10611061
from glean.api_client import Glean
10621062

@@ -1077,7 +1077,7 @@ glean = Glean(
10771077
api_token=os.environ.get("GLEAN_API_TOKEN", ""),
10781078
server_url="https://mycompany-be.glean.com",
10791079
exclude_deprecated_after="2026-10-15",
1080-
include_experimental=True,
1080+
include_beta=True,
10811081
)
10821082
```
10831083

@@ -1086,13 +1086,16 @@ glean = Glean(
10861086
| Option | Environment Variable | Type | Description |
10871087
| ------ | -------------------- | ---- | ----------- |
10881088
| `exclude_deprecated_after` | `X_GLEAN_EXCLUDE_DEPRECATED_AFTER` | `str` (date) | Exclude API endpoints that will be deprecated after this date (format: `YYYY-MM-DD`). Use this to test your integration against upcoming deprecations. |
1089-
| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | When `True`, enables experimental API features that are not yet generally available. Use this to preview and test new functionality. |
1089+
| `include_beta` | `X_GLEAN_INCLUDE_BETA` | `bool` | When `True`, enables beta API features that are not yet generally available. Use this to preview and test new functionality. |
1090+
| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | Alias of `include_beta`. Existing code that uses it keeps working. |
10901091

10911092
> [!NOTE]
1092-
> Environment variables take precedence over SDK constructor options when both are set.
1093+
> Environment variables take precedence over SDK constructor options when both are set. `X_GLEAN_INCLUDE_BETA=true` (case-insensitive) enables beta features, and any other non-empty value overrides `include_beta=True`.
1094+
>
1095+
> `include_beta` and `include_experimental` are resolved separately, and either one enables beta features. Disabling one does not disable the other. Both send the `X-Glean-Include-Experimental: true` header.
10931096
10941097
> [!WARNING]
1095-
> Experimental features may change or be removed without notice. Do not rely on experimental features in production environments.
1098+
> Beta features may change or be removed without notice. Do not rely on beta features in production environments.
10961099
10971100
<!-- Placeholder for Future Speakeasy SDK Sections -->
10981101

‎src/glean/api_client/_hooks/x_glean.py‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""Hook to set X-Glean headers for experimental features and deprecation testing."""
1+
"""Hook to set X-Glean headers for beta features and deprecation testing."""
22

33
import os
44
from typing import Optional, Union
@@ -12,6 +12,7 @@
1212
# Environment variable names
1313
EXCLUDE_DEPRECATED_AFTER_ENV_VAR = "X_GLEAN_EXCLUDE_DEPRECATED_AFTER"
1414
INCLUDE_EXPERIMENTAL_ENV_VAR = "X_GLEAN_INCLUDE_EXPERIMENTAL"
15+
INCLUDE_BETA_ENV_VAR = "X_GLEAN_INCLUDE_BETA"
1516

1617

1718
def _get_first_value(
@@ -29,13 +30,26 @@ def _get_first_value(
2930
return None
3031

3132

33+
def _resolve_boolean_option(env_value: Optional[str], config_value: object) -> bool:
34+
"""Resolve a boolean opt-in from its environment variable and SDK option.
35+
36+
The environment variable takes precedence: "true" (case-insensitive)
37+
enables it, any other non-empty value disables it, and an unset or blank
38+
value falls back to the SDK option.
39+
"""
40+
if env_value is not None and env_value.strip():
41+
return env_value.strip().lower() == "true"
42+
return config_value is True
43+
44+
3245
class XGlean(BeforeRequestHook):
3346
"""
34-
Hook that sets X-Glean headers for experimental features and deprecation testing.
47+
Hook that sets X-Glean headers for beta features and deprecation testing.
3548
3649
This hook adds the following headers when configured:
3750
- X-Glean-Exclude-Deprecated-After: Excludes API endpoints deprecated after this date
38-
- X-Glean-Include-Experimental: Enables experimental API features
51+
- X-Glean-Include-Experimental: Enables beta API features. Set by either
52+
include_beta or its include_experimental alias.
3953
4054
Configuration can be done via environment variables or SDK constructor options.
4155
Environment variables take precedence over SDK constructor options.
@@ -69,6 +83,16 @@ def before_request(
6983
config_experimental,
7084
)
7185

86+
# include_experimental is an alias of include_beta. Each one resolves on
87+
# its own, and either one enables the header. Disabling one never
88+
# disables the other. Keep sending X-Glean-Include-Experimental for both:
89+
# older deployments do not allow X-Glean-Beta in their CORS preflight.
90+
if _resolve_boolean_option(
91+
os.environ.get(INCLUDE_BETA_ENV_VAR),
92+
getattr(hook_ctx.config, "include_beta", None),
93+
):
94+
experimental_value = "true"
95+
7296
if deprecated_value:
7397
request.headers[EXCLUDE_DEPRECATED_AFTER_HEADER] = deprecated_value
7498

‎tests/test_x_glean_hook.py‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@
1212
INCLUDE_EXPERIMENTAL_HEADER,
1313
EXCLUDE_DEPRECATED_AFTER_ENV_VAR,
1414
INCLUDE_EXPERIMENTAL_ENV_VAR,
15+
INCLUDE_BETA_ENV_VAR,
1516
)
17+
from src.glean.api_client import Glean
1618
from src.glean.api_client._hooks.types import BeforeRequestContext, HookContext
1719
from src.glean.api_client.sdkconfiguration import SDKConfiguration
1820

@@ -25,11 +27,13 @@ def create_mock_request() -> httpx.Request:
2527
def create_mock_context(
2628
exclude_deprecated_after: str = None,
2729
include_experimental: bool = None,
30+
include_beta: bool = None,
2831
) -> BeforeRequestContext:
2932
"""Create a mock BeforeRequestContext with the given SDK configuration options."""
3033
config = Mock(spec=SDKConfiguration)
3134
config.exclude_deprecated_after = exclude_deprecated_after
3235
config.include_experimental = include_experimental
36+
config.include_beta = include_beta
3337

3438
hook_ctx = Mock(spec=HookContext)
3539
hook_ctx.config = config
@@ -51,13 +55,20 @@ def clear_env_vars(self):
5155
# Store original values
5256
original_deprecated = os.environ.get(EXCLUDE_DEPRECATED_AFTER_ENV_VAR)
5357
original_experimental = os.environ.get(INCLUDE_EXPERIMENTAL_ENV_VAR)
58+
original_beta = os.environ.get(INCLUDE_BETA_ENV_VAR)
5459

5560
# Clear for test
5661
os.environ.pop(EXCLUDE_DEPRECATED_AFTER_ENV_VAR, None)
5762
os.environ.pop(INCLUDE_EXPERIMENTAL_ENV_VAR, None)
63+
os.environ.pop(INCLUDE_BETA_ENV_VAR, None)
5864

5965
yield
6066

67+
if original_beta is not None:
68+
os.environ[INCLUDE_BETA_ENV_VAR] = original_beta
69+
else:
70+
os.environ.pop(INCLUDE_BETA_ENV_VAR, None)
71+
6172
# Restore original values
6273
if original_deprecated is not None:
6374
os.environ[EXCLUDE_DEPRECATED_AFTER_ENV_VAR] = original_deprecated
@@ -267,5 +278,141 @@ def test_handles_multipart_streaming_request(self):
267278
assert result.method == "POST"
268279

269280

281+
@pytest.fixture(name="clean_x_glean_env")
282+
def fixture_clean_x_glean_env(monkeypatch):
283+
"""Unset every X-Glean environment variable for the test."""
284+
for name in (
285+
EXCLUDE_DEPRECATED_AFTER_ENV_VAR,
286+
INCLUDE_EXPERIMENTAL_ENV_VAR,
287+
INCLUDE_BETA_ENV_VAR,
288+
):
289+
monkeypatch.delenv(name, raising=False)
290+
return monkeypatch
291+
292+
293+
@pytest.mark.parametrize(
294+
"beta_env, experimental_env, config, expected",
295+
[
296+
pytest.param(None, None, {}, None, id="neither option set"),
297+
pytest.param(None, None, {"include_beta": True}, "true", id="include_beta alone"),
298+
pytest.param(None, None, {"include_beta": False}, None, id="include_beta false"),
299+
pytest.param(
300+
None, None, {"include_experimental": True}, "true", id="include_experimental alone"
301+
),
302+
pytest.param(
303+
None,
304+
None,
305+
{"include_beta": True, "include_experimental": True},
306+
"true",
307+
id="both options true",
308+
),
309+
pytest.param(
310+
None,
311+
None,
312+
{"include_beta": True, "include_experimental": False},
313+
"true",
314+
id="include_beta true, include_experimental false",
315+
),
316+
pytest.param("true", None, {}, "true", id="X_GLEAN_INCLUDE_BETA alone"),
317+
pytest.param(" TRUE ", None, {}, "true", id="X_GLEAN_INCLUDE_BETA is case-insensitive"),
318+
pytest.param("true", "true", {}, "true", id="both env vars true"),
319+
pytest.param(
320+
"false",
321+
None,
322+
{"include_beta": True},
323+
None,
324+
id="X_GLEAN_INCLUDE_BETA=false overrides include_beta",
325+
),
326+
pytest.param(
327+
"true",
328+
None,
329+
{"include_beta": False},
330+
"true",
331+
id="X_GLEAN_INCLUDE_BETA=true overrides include_beta=False",
332+
),
333+
pytest.param(
334+
" ",
335+
None,
336+
{"include_beta": True},
337+
"true",
338+
id="empty X_GLEAN_INCLUDE_BETA falls back to include_beta",
339+
),
340+
pytest.param(
341+
"false",
342+
None,
343+
{"include_experimental": True},
344+
"true",
345+
id="X_GLEAN_INCLUDE_BETA=false does not turn off include_experimental",
346+
),
347+
pytest.param(
348+
"false",
349+
"true",
350+
{},
351+
"true",
352+
id="X_GLEAN_INCLUDE_BETA=false does not turn off X_GLEAN_INCLUDE_EXPERIMENTAL",
353+
),
354+
pytest.param(
355+
None,
356+
"false",
357+
{"include_beta": True},
358+
"true",
359+
id="X_GLEAN_INCLUDE_EXPERIMENTAL=false does not turn off include_beta",
360+
),
361+
],
362+
)
363+
def test_include_beta(clean_x_glean_env, beta_env, experimental_env, config, expected):
364+
"""include_beta and its include_experimental alias both set X-Glean-Include-Experimental."""
365+
if beta_env is not None:
366+
clean_x_glean_env.setenv(INCLUDE_BETA_ENV_VAR, beta_env)
367+
if experimental_env is not None:
368+
clean_x_glean_env.setenv(INCLUDE_EXPERIMENTAL_ENV_VAR, experimental_env)
369+
370+
result = XGlean().before_request(create_mock_context(**config), create_mock_request())
371+
372+
assert result.headers.get(INCLUDE_EXPERIMENTAL_HEADER) == expected
373+
assert "X-Glean-Beta" not in result.headers
374+
375+
376+
@pytest.mark.parametrize(
377+
"env, expected",
378+
[
379+
pytest.param({}, None, id="neither env var"),
380+
pytest.param({INCLUDE_BETA_ENV_VAR: "true"}, "true", id="X_GLEAN_INCLUDE_BETA"),
381+
pytest.param(
382+
{INCLUDE_EXPERIMENTAL_ENV_VAR: "true"}, "true", id="X_GLEAN_INCLUDE_EXPERIMENTAL"
383+
),
384+
pytest.param(
385+
{INCLUDE_BETA_ENV_VAR: "true", INCLUDE_EXPERIMENTAL_ENV_VAR: "true"},
386+
"true",
387+
id="both env vars",
388+
),
389+
],
390+
)
391+
def test_sdk_sends_include_experimental_header(clean_x_glean_env, env, expected):
392+
"""A real Glean client sends the header that the env vars ask for."""
393+
for name, value in env.items():
394+
clean_x_glean_env.setenv(name, value)
395+
396+
captured = []
397+
398+
def handler(request: httpx.Request) -> httpx.Response:
399+
captured.append(request)
400+
return httpx.Response(200, json={})
401+
402+
glean = Glean(
403+
api_token="test-token",
404+
server_url="https://example.com",
405+
client=httpx.Client(transport=httpx.MockTransport(handler)),
406+
)
407+
try:
408+
glean.search.query(query="test")
409+
except Exception: # pylint: disable=broad-exception-caught
410+
pass # The empty response body may not validate; only the request matters.
411+
412+
assert captured, "expected a request to be sent"
413+
assert captured[0].headers.get(INCLUDE_EXPERIMENTAL_HEADER) == expected
414+
assert "X-Glean-Beta" not in captured[0].headers
415+
416+
270417
if __name__ == "__main__":
271418
pytest.main([__file__])

0 commit comments

Comments
 (0)