Python SDK

Python SDK 为服务器端 Python 应用程序提供了一个兼容 OpenFeature 的 FlagshipServerProvider。它通过 HTTP 评估标志，并且不支持 Cloudflare Workers 绑定。

安装

使用 uv 或 pip 安装：

uv add cloudflare-flagship

pip install cloudflare-flagship

设置

使用您的 Flagship 应用 ID、Cloudflare 账户 ID 以及具有 Flagship Evaluate 权限的 API 令牌来配置提供商。

from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from flagship import FlagshipServerProvider

api.set_provider(
    FlagshipServerProvider(
        app_id="<APP_ID>",
        account_id="<ACCOUNT_ID>",
        auth_token="<API_TOKEN>",
    )
)

client = api.get_client()
enabled = client.get_boolean_value(
    "new-checkout",
    False,
    EvaluationContext(targeting_key="user-42", attributes={"plan": "enterprise"}),
)

标志类型

Python SDK 支持所有 OpenFeature 标志类型。Python 的 OpenFeature SDK 将数字值分为整数方法和浮点数方法。

enabled = client.get_boolean_value("new-checkout", False, context)
variant = client.get_string_value("homepage-hero", "control", context)
limit = client.get_integer_value("upload-limit", 10, context)
rate = client.get_float_value("sample-rate", 0.1, context)
config = client.get_object_value("ui-config", {"theme": "light"}, context)

当您需要解析的值、理由 (reason)、变体 (variant) 或错误代码时，请使用 *_details 方法。

配置选项

Option	Type	Default	Description
`app_id`	`str`	None	Flagship 应用 ID。
`account_id`	`str`	None	需要与 `app_id` 一起使用。
`auth_token`	`str`	None	添加到每个请求的 Bearer 令牌。
`headers_factory`	`Callable[[], dict[str, str]]`	None	动态每个请求的标头。
`timeout`	`float`	`5.0`	请求超时时间，单位为秒。
`retries`	`int`	`1`	发生临时错误时的重试次数，最高上限为 `10`。
`retry_delay`	`float`	`1.0`	重试之间的延迟时间，单位为秒，最高上限为 `30.0`。
`logging`	`bool`	`False`	通过 SDK 记录器启用 SDK 级别的调试输出。
`cache_ttl`	`float`	None	缓存 TTL，单位为秒。设置时启用缓存。
`cache_max_size`	`int`	`1000`	最近最少使用 (LRU) 驱逐前的最大缓存条目数。

响应缓存

服务器端响应缓存默认是关闭的。当您希望具有相同标志、类型和评估上下文的重复评估能重用最近的结果时，请使用 cache_ttl 启用它。

FlagshipServerProvider(
    app_id="<APP_ID>",
    account_id="<ACCOUNT_ID>",
    auth_token="<API_TOKEN>",
    cache_ttl=30.0,
    cache_max_size=1000,
)

在 TTL 过期之前，缓存的值可能是过时的。对于那些您期望在活动推出期间更改的标志，请保持较短的 TTL。提供商不会缓存禁用的标志或错误。

评估上下文

上下文属性作为 URL 查询参数发送。支持的值包括字符串、整数、浮点数、布尔值和 datetime 值。字典 (Dictionaries)、列表 (lists)、元组 (tuples) 和其他复杂值会引发 InvalidContextError。

异步评估

异步 API 与同步 API 相对应：

enabled = await client.get_boolean_value_async("new-checkout", False, context)
details = await client.get_boolean_details_async("new-checkout", False, context)

在异步上下文中关闭时，使用 shutdown_async()：

await api.shutdown_async()