API Reference

Protocols

FlagManagerProtocol

source

Manages the lifecycle of feature flag providers and evaluates flags.

The manager chains multiple FlagProviderProtocol instances in order of priority. Evaluation short-circuits to the first provider that can resolve the flag.

add_provider

def add_provider(
    provider: FlagProviderProtocol,
    priority: int = 50
) -> None

source

Register a flag provider at the given priority level.

Higher priority values are queried first. Providers with equal priority are queried in registration order.

Parameters

Parameter	Type	Description
`provider`	FlagProviderProtocol	The flag provider to register.
`priority`	int	Resolution priority (higher = queried first).

is_enabled

async def is_enabled(
    key: str,
    context: dict[str, Any] | None = None
) -> bool

source

Evaluate a boolean feature flag.

Parameters

Parameter	Type	Description
`key`	str	The flag identifier.
`context`	dict[str, Any] | None	Optional evaluation context (user, tenant, etc.).

Returns

Type	Description
bool	True if the flag is enabled, False otherwise.

Raises

Exception	Description
FlagNotFoundError	If no provider can resolve the flag.

get_value

async def get_value(
    key: str,
    default: FlagValue,
    context: dict[str, Any] | None = None
) -> FlagValue

source

Evaluate a feature flag and return its resolved value.

Parameters

Parameter	Type	Description
`key`	str	The flag identifier.
`default`	FlagValue	Fallback value when the flag cannot be resolved.
`context`	dict[str, Any] | None	Optional evaluation context.

Returns

Type	Description
FlagValue	The resolved FlagValue, or ``default`` if not found.

evaluate

async def evaluate(
    key: str,
    context: dict[str, Any] | None = None
) -> FlagEvaluation

source

Return the full evaluation result including metadata.

Parameters

Parameter	Type	Description
`key`	str	The flag identifier.
`context`	dict[str, Any] | None	Optional evaluation context.

Returns

Type	Description
FlagEvaluation	A FlagEvaluation with value, type, reason, and metadata.

Raises

Exception	Description
FlagNotFoundError	If no provider can resolve the flag.

get_all_flags

async def get_all_flags(context: dict[str, Any] | None = None) -> dict[str, FlagEvaluation]

source

Return evaluations for all known flags.

Parameters

Parameter	Type	Description
`context`	dict[str, Any] | None	Optional evaluation context applied to every flag.

Returns

Type	Description
dict[str, FlagEvaluation]	Mapping of flag key to its FlagEvaluation.

---

FlagProviderProtocol

source

Protocol for reading feature flags.

• Supports synchronous and asynchronous access. Implementations may be backed by in-memory maps, redis, remote services, etc.
• Context parameter is provided for user/tenant/environment lookup.
• Variant resolution is part of the contract, allowing A/B testing or percentage-based flags.
• Write methods are deliberately excluded; see MutableFlagProviderProtocol for providers that support updates.
• Async methods are the primary entry points (no suffix). Sync variants carry a _sync suffix.

get_flag

async def get_flag(
    name: str,
    *,
    default: bool = False,
    context: dict[str, Any] | None = None
) -> bool

source

Asynchronously evaluate the boolean value of a flag.

This is the primary entry point for all applications. context may contain arbitrary data used by the provider to make a decision (e.g. user id, tenant id, request headers).

get_flag_sync

def get_flag_sync(
    name: str,
    *,
    default: bool = False,
    context: dict[str, Any] | None = None
) -> bool

source

Synchronously evaluate the boolean value of a flag.

Only suitable when the backing store is fully in-memory and no I/O is required. Prefer get_flag in async contexts.

get_variant

async def get_variant(
    name: str,
    *,
    default: str = '',
    context: dict[str, Any] | None = None
) -> str

source

Asynchronously return a string variant for an A/B test or multivalue flag.

This is the primary entry point. Not all providers will support variants; those may simply return default.

get_variant_sync

def get_variant_sync(
    name: str,
    *,
    default: str = '',
    context: dict[str, Any] | None = None
) -> str

source

Synchronously return a string variant for an A/B test or multivalue flag.

Only suitable when the backing store is fully in-memory. Prefer get_variant in async contexts.

---

MutableFlagProviderProtocol

source

Optional extension of FlagProviderProtocol that supports writes.

set_flag

async def set_flag(
    name: str,
    value: bool
) -> None

source

Asynchronously create or update a boolean flag value.

This is the primary entry point. Required for providers backed by remote stores (Redis, database, etc.). Implementations with an in-memory backing store may perform the operation synchronously.

set_flag_sync

def set_flag_sync(
    name: str,
    value: bool
) -> None

source

Synchronously create or update a boolean flag value.

Only suitable when the backing store is fully in-memory. Prefer set_flag in async contexts.

set_variant

async def set_variant(
    name: str,
    variant: str
) -> None

source

Asynchronously create or update the active variant for a flag.

This is the primary entry point.

set_variant_sync

def set_variant_sync(
    name: str,
    variant: str
) -> None

source

Synchronously create or update the active variant for a flag.

Only suitable when the backing store is fully in-memory. Prefer set_variant in async contexts.

---

Classes

AbstractFlagProvider

source

Rich abstract flag provider with full per-type evaluation logic.

Subclasses must implement get_flag_definition and get_all_flags. All evaluation helpers and the evaluate coroutine are provided here.

This class is not a FlagProvider protocol implementation — get_flag_definition returns a Flag model, not a bare boolean. Use LocalProvider when you only need the simple boolean protocol.

get_flag_definition

async def get_flag_definition(name: str) -> Flag | None

source

Return the full Flag definition or None if not found.

get_all_flags

async def get_all_flags() -> dict[str, Flag]

source

Return all known flag definitions keyed by flag name.

evaluate

async def evaluate(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Evaluate flag name for context and return a FlagEvaluation.

Returns a flag_not_found evaluation (enabled=False) when the flag does not exist, so callers can safely treat unknown flags the same as disabled ones.

evaluate_sync

def evaluate_sync(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Synchronous evaluation — only valid when the store is in-memory.

Subclasses that back their data with a sync structure should override this if they need to avoid the event loop. The default raises NotImplementedError to prevent accidental blocking I/O.

get_flag

async def get_flag(
    name: str,
    *,
    default: bool = False,
    context: dict[str, Any] | None = None
) -> bool

source

Asynchronous boolean access (primary) — delegates to evaluate.

get_flag_sync

def get_flag_sync(
    name: str,
    *,
    default: bool = False,
    context: dict[str, Any] | None = None
) -> bool

source

Synchronous boolean access — delegates to evaluate_sync.

get_variant

async def get_variant(
    name: str,
    *,
    default: str = '',
    context: dict[str, Any] | None = None
) -> str

source

Asynchronous variant access (primary) — delegates to evaluate.

get_variant_sync

def get_variant_sync(
    name: str,
    *,
    default: str = '',
    context: dict[str, Any] | None = None
) -> str

source

Synchronous variant access — delegates to evaluate_sync.

---

CacheBackendFlagProvider

source

Feature-flag provider backed by a CacheBackendProtocol.

Flags are stored as JSON-encoded objects in the cache under keys of the form {prefix}{name}. Each entry is given an independent TTL so that flags expire and are treated as absent after the TTL elapses.

Parameters

Parameter	Type	Description
`cache`		The cache backend to use for flag storage and retrieval.
`ttl`		Time-to-live in seconds for each cached flag entry. Defaults to 3 600 seconds (1 hour).
`prefix`		Key prefix applied to every flag name to avoid collisions with other cache users. Defaults to ``"lexigram:features:flag:"``.

__init__

def __init__(
    cache: CacheBackendProtocol,
    ttl: int = 3600,
    prefix: str = 'lexigram:features:flag:'
) -> None

source

get_flag

async def get_flag(name: str) -> Flag

source

Return the Flag definition stored under name.

Parameters

Parameter	Type	Description
`name`	str	The flag name to look up.

Returns

Type	Description
Flag	The Flag stored in the cache.

Raises

Exception	Description
FlagNotFoundError	If no flag with *name* exists in the cache.

add_flag

async def add_flag(flag: Flag) -> None

source

Write flag to the cache with the configured TTL.

Parameters

Parameter	Type	Description
`flag`	Flag	The Flag definition to persist.

remove_flag

async def remove_flag(name: str) -> None

source

Delete the flag with name from the cache.

A no-op if the flag does not exist (the cache backend returns False from delete, which is silently ignored here).

Parameters

Parameter	Type	Description
`name`	str	The flag name to remove.

list_flags

async def list_flags() -> list[Flag]

source

Return all known flags.

Note This method always returns an empty list because the standard CacheBackendProtocol protocol does not expose a key-scan or key-enumeration operation (e.g. Redis SCAN). If you need to enumerate flags, maintain a separate index in the cache (a set under a dedicated key) or use a provider that natively supports enumeration such as LocalProvider.

Returns

Type	Description
list[Flag]	Always an empty list.

evaluate

async def evaluate(
    name: str,
    context: dict[str, Any] | None = None
) -> bool

source

Evaluate whether the flag name is enabled.

Fetches the flag from the cache and returns its enabled field. This is a simple boolean check; for richer evaluation (percentage rollout, user-list, variant, etc.) use a full AbstractFlagProvider.

Parameters

Parameter	Type	Description
`name`	str	The flag to evaluate.
`context`	dict[str, Any] | None	Optional context dict (not used by this provider; included for API consistency with other providers).

Returns

Type	Description
bool	``True`` if the flag exists and is enabled; ``False`` if the flag is disabled.

Raises

Exception	Description
FlagNotFoundError	If the flag does not exist in the cache.

---

ChainedProvider

source

Layered provider that queries multiple providers in order.

The first provider that returns a non-None flag definition wins. When merging all flags, earlier providers take precedence over later ones.

__init__

def __init__(providers: list[AbstractFlagProvider]) -> None

source

get_flag_definition

async def get_flag_definition(name: str) -> Flag | None

source

Return the first match across the provider chain, or None.

get_all_flags

async def get_all_flags() -> dict[str, Flag]

source

Merge flags from all providers; earlier providers take precedence.

---

EnvProvider

source

Feature flag provider that reads from environment variables.

Flag names are lowercased by stripping the prefix.

__init__

def __init__(prefix: str = ENV_PREFIX) -> None

source

get_flag_definition

async def get_flag_definition(name: str) -> Flag | None

source

Return the parsed Flag for name, or None.

get_all_flags

async def get_all_flags() -> dict[str, Flag]

source

Return all flags parsed from the current environment.

evaluate_sync

def evaluate_sync(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Synchronous evaluation using the last-loaded env snapshot.

invalidate

def invalidate() -> None

source

Discard the cached snapshot so the next read re-reads env vars.

---

FeatureFlagEvaluatedHook

source

Payload fired when a feature flag is evaluated for a given context.

Attributes: flag_key: Unique key of the feature flag that was evaluated. enabled: Resolved boolean result of the evaluation.

---

FeatureFlagUpdatedHook

source

Payload fired when a feature flag definition is created or updated.

Attributes: flag_key: Unique key of the feature flag that changed.

---

FeatureFlagsModule

source

In-memory and extensible feature flag evaluation.

Call configure to seed initial flag state from a FeatureFlagsConfig.

Usage

from lexigram.features.config import FeatureFlagsConfig

@module(
    imports=[
        FeatureFlagsModule.configure(
            FeatureFlagsConfig(initial_flags={"beta_feature": True})
        )
    ]
)
class AppModule(Module):
    pass

from lexigram.features.config import FeatureFlagsConfig

@module(
    imports=[
        FeatureFlagsModule.configure(
            FeatureFlagsConfig(initial_flags={"beta_feature": True})
        )
    ]
)
class AppModule(Module):
    pass

configure

def configure(
    cls,
    config: Any | None = None
) -> DynamicModule

source

Create a FeatureFlagsModule with explicit configuration.

Parameters

Parameter	Type	Description
`config`	Any | None	FeatureFlagsConfig or ``None`` for framework defaults (all flags disabled).

Returns

Type	Description
DynamicModule	A DynamicModule descriptor.

stub

def stub(
    cls,
    config: Any = None
) -> DynamicModule

source

Return an in-memory FeatureFlagsModule for testing.

Registers the feature flag provider with no flags enabled by default. Suitable for unit and integration tests.

Returns

Type	Description
DynamicModule	A DynamicModule with all flags disabled.

---

FeatureFlagsProvider

source

Provider that registers feature-flag infrastructure in the container.

Registers:

• FlagProviderProtocol (simple boolean contract) as a singleton backed by LocalProvider.
• FlagManager as a singleton wrapping a LocalProvider seeded from initial_flags.

__init__

def __init__(config: FeatureFlagsConfig | None = None) -> None

source

Create the feature-flags provider.

Parameters

Parameter	Type	Description
`config`	FeatureFlagsConfig | None	Optional feature-flag configuration. When omitted, defaults are used (all flags disabled, cache TTL 60 s).

from_config

def from_config(
    cls,
    config: FeatureFlagsConfig,
    **context: Any
) -> Self

source

Create provider from config object.

register

async def register(container: ContainerRegistrarProtocol) -> None

source

Register flag infrastructure in the container.

Registers FlagProviderProtocol (simple boolean API) and FlagManager (rich evaluation API) as singletons, seeded from the provider config.

boot

async def boot(container: BootContainerProtocol) -> None

source

Wire the event bus into the flag manager when one is available.

health_check

async def health_check(timeout: float = 5.0) -> HealthCheckResult

source

Check health of feature flags.

Feature flags are in-memory and have no external dependencies, so this always returns HEALTHY.

Parameters

Parameter	Type	Description
`timeout`	float	Not used - feature flags have no external dependencies.

Returns

Type	Description
HealthCheckResult	HealthCheckResult showing healthy status.

shutdown

async def shutdown() -> None

source

No resources to release for the feature-flags module.

get_simple_provider

def get_simple_provider() -> LocalProvider | None

source

Return the registered simple provider after registration.

Returns

Type	Description
LocalProvider | None	The ``LocalProvider`` instance, or ``None`` before registration.

get_manager

def get_manager() -> FlagManager | None

source

Return the registered manager after registration.

Returns

Type	Description
FlagManager | None	The ``FlagManager`` instance, or ``None`` before registration.

---

Flag

source

Full definition of a feature flag including its evaluation strategy.

---

FlagChangeEvent

source

Published when a feature-flag runtime override is applied or cleared.

Attributes: flag_name: Name of the feature flag that changed. old_enabled: State before the change (None if no prior override). new_enabled: State after the change. actor: Optional identifier of the entity that triggered the change.

__init__

def __init__(
    flag_name: str,
    old_enabled: bool | None,
    new_enabled: bool,
    actor: str | None = None
) -> None

source

Create a FlagChangeEvent.

Parameters

Parameter	Type	Description
`flag_name`	str	Name of the feature flag that changed.
`old_enabled`	bool | None	Prior override state (``None`` if no override was set).
`new_enabled`	bool	New override state after the change.
`actor`	str | None	Optional identifier of who triggered the change.

---

FlagContext

source

Evaluation context passed alongside a flag name.

Providers use the attributes here to resolve percentage rollouts, user lists, attribute rules, and variant assignments deterministically.

get_attribute

def get_attribute(
    key: str,
    default: Any = None
) -> Any

source

Return an attribute from user_attributes or custom, or default.

Checks user_attributes first, then custom, then returns default.

as_dict

def as_dict() -> dict[str, Any]

source

Serialise to a plain dict for cache key computation.

context_hash

def context_hash() -> str

source

Return a deterministic 12-char hex hash of the non-empty context fields.

---

FlagEvaluation

source

Result of evaluating a feature flag for a given context.

enabled is the boolean result; value holds the full evaluation value — a bool for boolean/percentage/list/attribute/time flags, or a variant name string for VARIANT flags.

---

FlagManager

source

Central feature flag manager with caching, overrides, and variant support.

Wraps an AbstractFlagProvider and handles cache invalidation, runtime overrides, and change notification.

Example

provider = LocalProvider({
    "new_checkout": Flag("new_checkout", enabled=True),
})
manager = FlagManager(provider, cache_ttl=60)

ctx = FlagContext(user_id="user-123")
if await manager.is_enabled("new_checkout", ctx):
    ...

provider = LocalProvider({
    "new_checkout": Flag("new_checkout", enabled=True),
})
manager = FlagManager(provider, cache_ttl=60)

ctx = FlagContext(user_id="user-123")
if await manager.is_enabled("new_checkout", ctx):
    ...

__init__

def __init__(
    provider: AbstractFlagProvider | None = None,
    *,
    cache_ttl: int = 300,
    default_enabled: bool = False,
    event_bus: EventBusProtocol | None = None
) -> None

source

is_enabled

async def is_enabled(
    name: str,
    context: FlagContext | None = None,
    *,
    default: bool | None = None
) -> bool

source

Return whether name is enabled for context.

Runtime overrides take precedence over the provider result.

Parameters

Parameter	Type	Description
`name`	str	Flag name.
`context`	FlagContext | None	Optional evaluation context.
`default`	bool | None	Override the instance's ``default_enabled`` for this call.

Returns

Type	Description
bool	True if the flag is enabled.

evaluate

async def evaluate(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Evaluate name for context, using the TTL cache when available.

Parameters

Parameter	Type	Description
`name`	str	Flag name.
`context`	FlagContext | None	Optional evaluation context.

Returns

Type	Description
FlagEvaluation	A FlagEvaluation result.

get_variant

async def get_variant(
    name: str,
    context: FlagContext | None = None,
    *,
    default: str = ''
) -> str

source

Return the variant string for a VARIANT-type flag.

Returns default if the flag is not found, disabled, or is not a VARIANT flag.

Parameters

Parameter	Type	Description
`name`	str	Flag name.
`context`	FlagContext | None	Optional evaluation context.
`default`	str	Fallback value when no variant string is available.

Returns

Type	Description
str	The variant string or *default*.

add_provider

def add_provider(
    provider: AbstractFlagProvider,
    priority: int = 50
) -> None

source

Register a flag provider at the given priority level.

get_value

async def get_value(
    key: str,
    default: object,
    context: FlagContext | None = None
) -> object

source

Evaluate a feature flag and return its resolved value.

get_all_flags

async def get_all_flags(context: FlagContext | None = None) -> dict[str, Any]

source

Return evaluations for all known flags.

get_override_state

def get_override_state(name: str) -> bool | None

source

Return the current runtime override for name.

Returns

Type	Description
bool | None	``True`` if force-enabled, ``False`` if force-disabled, ``None`` if no override is active.

enable

def enable(
    name: str,
    *,
    actor: str | None = None
) -> None

source

Force-enable name regardless of provider result.

disable

def disable(
    name: str,
    *,
    actor: str | None = None
) -> None

source

Force-disable name regardless of provider result.

set_override

def set_override(
    name: str,
    enabled: bool,
    *,
    actor: str | None = None
) -> None

source

Convenience wrapper that calls enable or disable.

clear_override

def clear_override(name: str) -> None

source

Remove any runtime override for name, restoring provider control.

get_audit_log

def get_audit_log() -> list[FlagAuditEntry]

source

Return a copy of all recorded flag change audit entries.

Each entry captures the flag name, actor, old value, new value, and the UTC timestamp of the change. Entries are ordered oldest-first.

Returns

Type	Description
list[FlagAuditEntry]	List of FlagAuditEntry instances representing every enable / disable / set_override call since this manager was created.

clear_cache

async def clear_cache() -> None

source

Flush all cached evaluations.

clear_cache_for

def clear_cache_for(name: str) -> None

source

Flush cached evaluations for a single flag name.

add_listener_sync

def add_listener_sync(fn: FlagChangeListener) -> None

source

Register a sync callback invoked when a flag override changes.

remove_listener_sync

def remove_listener_sync(fn: FlagChangeListener) -> None

source

Deregister a previously registered sync listener.

add_listener

def add_listener(fn: AsyncFlagChangeListener) -> None

source

Register an async callback invoked when a flag override changes.

remove_listener

def remove_listener(fn: AsyncFlagChangeListener) -> None

source

Deregister a previously registered async listener.

provider

property provider() -> AbstractFlagProvider

source

The underlying flag provider instance.

---

FlagType

source

Evaluation strategy for a feature flag.

---

LocalProvider

source

In-memory provider backed by a ``dict[str, Flag]``.

Dynamic update methods (add_flag, remove_flag, set_enabled) mutate the store safely within a single process.

__init__

def __init__(flags: dict[str, Flag] | None = None) -> None

source

get_flag_definition

async def get_flag_definition(name: str) -> Flag | None

source

Return the Flag definition for name, or None.

get_all_flags

async def get_all_flags() -> dict[str, Flag]

source

Return a snapshot copy of all defined flags.

evaluate_sync

def evaluate_sync(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Synchronous evaluation — safe because the backing store is in-memory.

add_flag

def add_flag(flag: Flag) -> None

source

Add or replace a flag definition.

remove_flag

def remove_flag(name: str) -> bool

source

Remove a flag by name; returns True if it existed.

set_enabled

def set_enabled(
    name: str,
    enabled: bool
) -> bool

source

Toggle the master enabled switch; returns True if the flag exists.

set_flag

async def set_flag(
    name: str,
    value: bool
) -> None

source

Store a boolean flag (async primary).

set_flag_sync

def set_flag_sync(
    name: str,
    value: bool
) -> None

source

Store a boolean flag (sync).

set_variant

async def set_variant(
    name: str,
    variant: str
) -> None

source

Store a variant flag (async primary).

set_variant_sync

def set_variant_sync(
    name: str,
    variant: str
) -> None

source

Store a variant flag (sync).

clear

def clear() -> None

source

Remove all stored flags and variants.

---

ManagerConfig

source

Configuration for FlagManager instances.

---

MemoryProvider

source

Lightweight in-memory provider designed for use in tests.

Unlike LocalProvider this provider works with plain booleans and supports per-flag overrides that short-circuit normal evaluation.

Note Choosing between in-memory providers:

* Use <a href='/packages/infra/lexigram-features/api/#memoryprovider' style='color:inherit;text-decoration:underline;text-decoration-color:rgba(128,128,128,0.3);text-underline-offset:2px;'>MemoryProvider</a> (this class) in **unit tests** — the
  ``_overrides`` dict lets you force specific flag outcomes without
  touching the flag configuration.

* Use <a href='/packages/infra/lexigram-features/api/#localprovider' style='color:inherit;text-decoration:underline;text-decoration-color:rgba(128,128,128,0.3);text-underline-offset:2px;'>LocalProvider</a>
  for production single-node deployments or integration tests where
  you only need ``set_flag`` / ``get_flag`` semantics and do not need
  per-test overrides.

Typical usage in tests

provider = MemoryProvider()
provider.set_flag("new_billing", enabled=True)
manager = FlagManager(provider)

provider = MemoryProvider()
provider.set_flag("new_billing", enabled=True)
manager = FlagManager(provider)

__init__

def __init__() -> None

source

evaluate

async def evaluate(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Evaluate, applying any explicit test override first.

evaluate_sync

def evaluate_sync(
    name: str,
    context: FlagContext | None = None
) -> FlagEvaluation

source

Synchronous evaluation, applying overrides first.

set_flag_sync

def set_flag_sync(
    name: str,
    value: bool
) -> None

source

Define a simple boolean flag (sync version).

set_flag

async def set_flag(
    name: str,
    value: bool
) -> None

source

Define a simple boolean flag.

override

def override(
    name: str,
    *,
    enabled: bool,
    value: Any = None,
    reason: str = 'test_override'
) -> None

source

Register a hard override for name that bypasses normal evaluation.

clear_override

def clear_override(name: str) -> None

source

Remove the test override for name.

reset

def reset() -> None

source

Clear all flags and overrides.

---

Functions

feature_flag

feature_flag

def feature_flag(
    name: str,
    *,
    manager: FlagManager | None = None,
    fallback: Callable[Ellipsis, Any] | None = None,
    context: FlagContext | None = None
) -> Callable[[F], F]

source

Decorate an async function so it only runs when *name* is enabled.

When the flag is disabled:

• If fallback is provided it is called with the same arguments and its return value is returned.
• Otherwise FeatureFlagDisabledError is raised.

Parameters

Parameter	Type	Description
`name`	str	Feature flag name to check.
`manager`	FlagManager | None	Explicit FlagManager; resolved via DI or a default when ``None``.
`fallback`	Callable[Ellipsis, Any] | None	Optional callable invoked when the flag is disabled.
`context`	FlagContext | None	Optional evaluation context passed to the manager.

Returns

Type	Description
Callable[[F], F]	A decorator for async functions.

---

feature_flag_sync

feature_flag_sync

def feature_flag_sync(
    name: str,
    *,
    manager: FlagManager | None = None,
    fallback: Callable[Ellipsis, Any] | None = None,
    context: FlagContext | None = None
) -> Callable[[F], F]

source

Decorate a **synchronous** function so it only runs when *name* is enabled.

Evaluation uses evaluate_sync on the underlying provider.

Parameters

Parameter	Type	Description
`name`	str	Feature flag name to check.
`manager`	FlagManager | None	Explicit manager; resolved via DI or a default when ``None``.
`fallback`	Callable[Ellipsis, Any] | None	Optional callable invoked when the flag is disabled.
`context`	FlagContext | None	Optional evaluation context.

Returns

Type	Description
Callable[[F], F]	A decorator for synchronous functions.

---

require_flag

require_flag

def require_flag(
    name: str,
    *,
    manager: FlagManager | None = None,
    context: FlagContext | None = None
) -> Callable[[F], F]

source

Decorate an async function to raise when *name* is disabled.

Semantically identical to feature_flag with no fallback, but the intent is clearer when used as an access guard.

Parameters

Parameter	Type	Description
`name`	str	Feature flag name to check.
`manager`	FlagManager | None	Explicit manager; resolved via DI or a default when ``None``.
`context`	FlagContext | None	Optional evaluation context.

Returns

Type	Description
Callable[[F], F]	A decorator for async functions.

---

require_flag_sync

require_flag_sync

def require_flag_sync(
    name: str,
    *,
    manager: FlagManager | None = None,
    context: FlagContext | None = None
) -> Callable[[F], F]

source

Synchronous variant of require_flag.

Raises FeatureFlagDisabledError when name is disabled.

Parameters

Parameter	Type	Description
`name`	str	Feature flag name to check.
`manager`	FlagManager | None	Explicit manager; resolved via DI or a default when ``None``.
`context`	FlagContext | None	Optional evaluation context.

Returns

Type	Description
Callable[[F], F]	A decorator for synchronous functions.

---

Exceptions

FeatureFlagDisabledError

source

Raised when a feature-guarded path is called with the flag disabled.

__init__

def __init__(flag_name: str) -> None

source

---

FeatureFlagError

source

Base error for the feature flag subsystem.

__init__

def __init__(
    message: str = 'Feature flag error',
    **kwargs: Any
) -> None

source

---

FlagEvaluationError

source

Raised when a flag provider fails during evaluation.

Attributes: flag_key: The key of the flag that failed to evaluate.

__init__

def __init__(
    flag_key: str,
    message: str = 'Flag evaluation failed',
    **kwargs: Any
) -> None

source

---

FlagNotFoundError

source

Raised when a requested feature flag does not exist in any provider.

Attributes: flag_key: The key of the missing flag.

__init__

def __init__(
    flag_key: str,
    **kwargs: Any
) -> None

source

---