bayesline.api.FeaturesApi

class bayesline.api.FeaturesApi

Abstract base class for feature flag API operations.

__init__()

Methods

__init__()
explain_feature_values(feature_names, *[, ...])	Get the values of a set of features for a user, with their workings.
get_feature_entitlements(*[, feature_names, ...])	Get the stored grants, as made rather than as they apply to anyone.
get_feature_values(feature_names, *[, user_ref])	Get the values of a set of features for a specific user.
list_all_features()	Get the list of all features.
update_feature_values(*[, enabled, data, ...])	Update the values of a set of features for a specific users, groups and roles.

abstractmethod list_all_features() → Sequence[EffectiveFeature]

Get the list of all features.

Returns

Sequence[EffectiveFeature]

List of all features.

abstractmethod get_feature_values(feature_names: Sequence[str], *, user_ref: str | None = None) → dict[str, FeatureValue]

Get the values of a set of features for a specific user.

A name that matches no feature is ignored, i.e. not included in the result.

Parameters

feature_namesSequence[str]

The names of the features to get the values of. Features are named by identity, matched regardless of case.

user_refUserRef | None, default=None

The user, given as a user id or email. Defaults to the requesting user.

Raises

ValueError

If the requested user does not exist.

PermissionDeniedError

If the requesting user may not read the requested user’s feature values.

Returns

dict[str, FeatureValue]

A dictionary mapping each feature to its value for the user. Keys are the canonical lowercase name, which is not necessarily the spelling that was asked for.

abstractmethod explain_feature_values(feature_names: Sequence[str], *, user_ref: str | None = None) → dict[str, FeatureExplanation]

Get the values of a set of features for a user, with their workings.

Reports what get_feature_values reports, plus what the answer was read from: the feature’s own default and every grant bearing on the user, with the one that decided the enabled state marked. Precedence is not something a caller can reconstruct from the grants alone - the role tier is decided by hierarchy specificity rather than by order - so which grant won is stated rather than implied.

Missing features will be ignored, i.e. not included in the result.

Parameters

feature_namesSequence[str]

The names of the features to explain. Features are named by identity.

user_refUserRef | None, default=None

The user, given as a user id or email. Defaults to the requesting user.

Raises

ValueError

If the requested user does not exist or the requesting user does not have permission to access the feature values.

Returns

dict[str, FeatureExplanation]

A dictionary mapping each requested feature name to its explanation for the user.

abstractmethod get_feature_entitlements(*, feature_names: Sequence[str] | None = None, for_users: Sequence[str] | None = None, for_groups: Sequence[str] | None = None, for_roles: Sequence[str] | None = None) → Sequence[FeatureEntitlement]

Get the stored grants, as made rather than as they apply to anyone.

Answers who was given what, which the per-user explanation cannot: explain_feature_values reports only the grants that reach one user. Application defaults are not included, as they are declared in code rather than granted.

Passing no filter at all returns every grant. Naming principals of more than one kind widens the result rather than narrowing it, i.e. the grants to any of them.

Parameters

feature_namesSequence[str] | None, default=None

Only grants on the features with these identities. None means every feature.

for_usersSequence[UserRef] | None, default=None

Only grants made to these users. None means no user filter.

for_groupsSequence[str] | None, default=None

Only grants made to these groups. None means no group filter.

for_rolesSequence[str] | None, default=None

Only grants made to these roles. None means no role filter.

Raises

ValueError

If a named user does not exist.

Returns

Sequence[FeatureEntitlement]

The matching grants.

abstractmethod update_feature_values(*, enabled: dict[str, bool] | None = None, data: dict[str, dict[str, Any]] | None = None, revoke: Sequence[str] | None = None, for_users: Sequence[str] | None = None, for_groups: Sequence[str] | None = None, for_roles: Sequence[str] | None = None) → dict[str, Sequence[FeatureUpdateItem]]

Update the values of a set of features for a specific users, groups and roles.

Passing neither enabled, data nor revoke will do nothing.

Feature names for which enabled is given but data is not will only update the enabled state and vice versa.

Missing features, users, groups, roles are ignored and denoted in the update result. The update is attributed to the requesting user.

Parameters

enabled: dict[str, bool] | None, default=None

A dictionary mapping each feature name to its new enabled state.

data: dict[str, dict[str, Any]] | None, default=None

A dictionary mapping each feature name to its new data.

revoke: Sequence[str] | None, default=None

Feature names to withdraw entirely for the given principals, returning them to whatever a lower precedence grant or the feature’s own default says. A feature named both here and in enabled or data is set rather than withdrawn.

for_users: Sequence[UserRef] | None, default=None

A list of users to update the feature values for.

for_groups: Sequence[str] | None, default=None

A list of groups to update the feature values for.

for_roles: Sequence[str] | None, default=None

A list of roles to update the feature values for.

Returns

dict[str, Sequence[FeatureUpdateItem]]

A dictionary mapping each updated feature name to its update result.