Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .speakeasy/gen.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ generation:
versioningStrategy: automatic
mockServer:
disabled: false
persistentEdits: {}
persistentEdits:
enabled: "true"
tests:
generateTests: true
generateNewTests: true
Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1042,7 +1042,7 @@ You can also enable a default debug logger by setting an environment variable `G

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

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

### Configuration Options
Expand All @@ -1056,7 +1056,7 @@ import os

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

from glean.api_client import Glean

Expand All @@ -1077,7 +1077,7 @@ glean = Glean(
api_token=os.environ.get("GLEAN_API_TOKEN", ""),
server_url="https://mycompany-be.glean.com",
exclude_deprecated_after="2026-10-15",
include_experimental=True,
include_beta=True,
)
```

Expand All @@ -1086,13 +1086,16 @@ glean = Glean(
| Option | Environment Variable | Type | Description |
| ------ | -------------------- | ---- | ----------- |
| `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. |
| `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. |
| `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. |
| `include_experimental` | `X_GLEAN_INCLUDE_EXPERIMENTAL` | `bool` | Alias of `include_beta`. Existing code that uses it keeps working. |

> [!NOTE]
> Environment variables take precedence over SDK constructor options when both are set.
> 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`.
>
> `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.

> [!WARNING]
> Experimental features may change or be removed without notice. Do not rely on experimental features in production environments.
> Beta features may change or be removed without notice. Do not rely on beta features in production environments.

<!-- Placeholder for Future Speakeasy SDK Sections -->

Expand Down
30 changes: 27 additions & 3 deletions src/glean/api_client/_hooks/x_glean.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
"""Hook to set X-Glean headers for experimental features and deprecation testing."""
"""Hook to set X-Glean headers for beta features and deprecation testing."""

import os
from typing import Optional, Union
Expand All @@ -12,6 +12,7 @@
# Environment variable names
EXCLUDE_DEPRECATED_AFTER_ENV_VAR = "X_GLEAN_EXCLUDE_DEPRECATED_AFTER"
INCLUDE_EXPERIMENTAL_ENV_VAR = "X_GLEAN_INCLUDE_EXPERIMENTAL"
INCLUDE_BETA_ENV_VAR = "X_GLEAN_INCLUDE_BETA"


def _get_first_value(
Expand All @@ -29,13 +30,26 @@ def _get_first_value(
return None


def _resolve_boolean_option(env_value: Optional[str], config_value: object) -> bool:
"""Resolve a boolean opt-in from its environment variable and SDK option.

The environment variable takes precedence: "true" (case-insensitive)
enables it, any other non-empty value disables it, and an unset or blank
value falls back to the SDK option.
"""
if env_value is not None and env_value.strip():
return env_value.strip().lower() == "true"
return config_value is True


class XGlean(BeforeRequestHook):
"""
Hook that sets X-Glean headers for experimental features and deprecation testing.
Hook that sets X-Glean headers for beta features and deprecation testing.

This hook adds the following headers when configured:
- X-Glean-Exclude-Deprecated-After: Excludes API endpoints deprecated after this date
- X-Glean-Include-Experimental: Enables experimental API features
- X-Glean-Include-Experimental: Enables beta API features. Set by either
include_beta or its include_experimental alias.

Configuration can be done via environment variables or SDK constructor options.
Environment variables take precedence over SDK constructor options.
Expand Down Expand Up @@ -69,6 +83,16 @@ def before_request(
config_experimental,
)

# include_experimental is an alias of include_beta. Each one resolves on
# its own, and either one enables the header. Disabling one never
# disables the other. Keep sending X-Glean-Include-Experimental for both:
# older deployments do not allow X-Glean-Beta in their CORS preflight.
if _resolve_boolean_option(
os.environ.get(INCLUDE_BETA_ENV_VAR),
getattr(hook_ctx.config, "include_beta", None),
):
experimental_value = "true"

if deprecated_value:
request.headers[EXCLUDE_DEPRECATED_AFTER_HEADER] = deprecated_value

Expand Down
9 changes: 9 additions & 0 deletions src/glean/api_client/sdk.py
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,9 @@ def __init__(
retry_config: OptionalNullable[RetryConfig] = UNSET,
timeout_ms: Optional[int] = None,
debug_logger: Optional[Logger] = None,
exclude_deprecated_after: Optional[str] = None,
include_beta: Optional[bool] = None,
include_experimental: Optional[bool] = None,
) -> None:
r"""Instantiates the SDK configuring it with the provided parameters.

Expand All @@ -97,6 +100,9 @@ def __init__(
:param async_client: The Async HTTP client to use for all asynchronous methods
:param retry_config: The retry configuration to use for all supported methods
:param timeout_ms: Optional request timeout applied to each operation in milliseconds
:param exclude_deprecated_after: Exclude API endpoints deprecated after this date (YYYY-MM-DD)
:param include_beta: When True, enables beta API features
:param include_experimental: Alias of include_beta
"""
client_supplied = True
if client is None:
Expand Down Expand Up @@ -151,6 +157,9 @@ def __init__(
retry_config=retry_config,
timeout_ms=timeout_ms,
debug_logger=debug_logger,
exclude_deprecated_after=exclude_deprecated_after,
include_beta=include_beta,
include_experimental=include_experimental,
),
parent_ref=self,
)
Expand Down
17 changes: 17 additions & 0 deletions src/glean/api_client/sdkconfiguration.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,23 @@ class SDKConfiguration:
user_agent: str = __user_agent__
retry_config: OptionalNullable[RetryConfig] = Field(default_factory=lambda: UNSET)
timeout_ms: Optional[int] = None
exclude_deprecated_after: Optional[str] = None
"""
Exclude API endpoints that will be deprecated after this date.
Use this to test your integration against upcoming deprecations.
Format: YYYY-MM-DD (e.g., '2026-10-15')

More information: https://developers.glean.com/deprecations/overview
"""
include_beta: Optional[bool] = None
"""
When True, enables beta API features that are not yet generally available.
Use this to preview and test new functionality.
"""
include_experimental: Optional[bool] = None
"""
Alias of include_beta. Either option enables beta API features.
"""

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