Skip to content

Commit b557f41

Browse files
Merge pull request #197 from gleanwork/thoov/devplat-1598-include-beta
2 parents f1c6775 + 9035bb0 commit b557f41

6 files changed

Lines changed: 272 additions & 10 deletions

File tree

‎.speakeasy/gen.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,8 @@ generation:
2929
versioningStrategy: automatic
3030
mockServer:
3131
disabled: false
32-
persistentEdits: {}
32+
persistentEdits:
33+
enabled: "true"
3334
tests:
3435
generateTests: true
3536
generateNewTests: true

‎README.md‎

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

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

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

10471047
### Configuration Options
@@ -1055,7 +1055,7 @@ import os
10551055

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

10601060
from glean.api_client import Glean
10611061

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

@@ -1085,13 +1085,16 @@ glean = Glean(
10851085
| Option | Environment Variable | Type | Description |
10861086
| ------ | -------------------- | ---- | ----------- |
10871087
| `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. |
1088-
| `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. |
1088+
| `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. |
1089+
| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | Alias of `include_beta`. Existing code that uses it keeps working. |
10891090

10901091
> [!NOTE]
1091-
> Environment variables take precedence over SDK constructor options when both are set.
1092+
> 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`.
1093+
>
1094+
> `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.
10921095
10931096
> [!WARNING]
1094-
> Experimental features may change or be removed without notice. Do not rely on experimental features in production environments.
1097+
> Beta features may change or be removed without notice. Do not rely on beta features in production environments.
10951098
10961099
<!-- Placeholder for Future Speakeasy SDK Sections -->
10971100

‎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

‎src/glean/api_client/sdk.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@ def __init__(
8585
retry_config: OptionalNullable[RetryConfig] = UNSET,
8686
timeout_ms: Optional[int] = None,
8787
debug_logger: Optional[Logger] = None,
88+
exclude_deprecated_after: Optional[str] = None,
89+
include_beta: Optional[bool] = None,
90+
include_experimental: Optional[bool] = None,
8891
) -> None:
8992
r"""Instantiates the SDK configuring it with the provided parameters.
9093
@@ -97,6 +100,9 @@ def __init__(
97100
:param async_client: The Async HTTP client to use for all asynchronous methods
98101
:param retry_config: The retry configuration to use for all supported methods
99102
:param timeout_ms: Optional request timeout applied to each operation in milliseconds
103+
:param exclude_deprecated_after: Exclude API endpoints deprecated after this date (YYYY-MM-DD)
104+
:param include_beta: When True, enables beta API features
105+
:param include_experimental: Alias of include_beta
100106
"""
101107
client_supplied = True
102108
if client is None:
@@ -151,6 +157,9 @@ def __init__(
151157
retry_config=retry_config,
152158
timeout_ms=timeout_ms,
153159
debug_logger=debug_logger,
160+
exclude_deprecated_after=exclude_deprecated_after,
161+
include_beta=include_beta,
162+
include_experimental=include_experimental,
154163
),
155164
parent_ref=self,
156165
)

‎src/glean/api_client/sdkconfiguration.py‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,23 @@ class SDKConfiguration:
3939
user_agent: str = __user_agent__
4040
retry_config: OptionalNullable[RetryConfig] = Field(default_factory=lambda: UNSET)
4141
timeout_ms: Optional[int] = None
42+
exclude_deprecated_after: Optional[str] = None
43+
"""
44+
Exclude API endpoints that will be deprecated after this date.
45+
Use this to test your integration against upcoming deprecations.
46+
Format: YYYY-MM-DD (e.g., '2026-10-15')
47+
48+
More information: https://developers.glean.com/deprecations/overview
49+
"""
50+
include_beta: Optional[bool] = None
51+
"""
52+
When True, enables beta API features that are not yet generally available.
53+
Use this to preview and test new functionality.
54+
"""
55+
include_experimental: Optional[bool] = None
56+
"""
57+
Alias of include_beta. Either option enables beta API features.
58+
"""
4259

4360
def get_server_details(self) -> Tuple[str, Dict[str, str]]:
4461
if self.server_url is not None and self.server_url:

0 commit comments

Comments
 (0)