setting — Heksher Settings

---

This module contains the Setting type, which is used to define a variable setting in Heksher. Settings are registered to a global repository upon construction, and are declared and updated by the Heksher Client.

Warning

The settings are registered globally as weak references, so they will not be updated or declared if the setting is destroyed. Therefore it is recommended to initialize settings as global variables.

def foo():
    cache_ttl = heksher.Setting(name="cache_ttl", type=int,
                                configurable_feature= ['environment', 'user'],
                                default_value=60)

foo()
# the setting "cache_ttl" will not be declared

class setting.Setting(name: str, type: SettingType[T] | Type[int] | Type[float] | Type[bool] | Type[str], configurable_features: Sequence[str], default_value: T, metadata: Mapping[str, ...] = None, alias: str = None, version: str = '1.0', on_coerce: Callable[...] | None = ...)

A setting, that is declared to and updated from a Heksher service, by a Heksher client.

Parameters:

• name – The name of the setting.

• type – The type of the setting. Must be a subclass of SettingType, or a valid input to setting_type().

• configurable_features – A sequence of context feature names, will decide which features the setting is configurable by.

• default_value – If specified, and no matching rule is found for the context, this value will be returned instead.

• metadata – additional metadata to use when declaring the setting.

• alias – An alias for the setting, see Renaming a setting.

• version – The version of the setting declaration.

• on_coerce – A callable that will be called when a value for the setting has undergone coercion. The callable should accept 5 positional parameters: the coerced value, the original raw value, a sequence of strings representing the coercions that were applied, the rule object that the value came from (or None if value is supposed to be the default value), and the setting itself. The callable should return a value for the rule or default value. The callable may raise a TypeError to reject the value. Setting on_coerce to None will raise a TypeError on all coercions. Default value is to return the coerced value.

add_validator(validator: Callable)

Adds a validator to be called when the setting’s rules are updated.

Parameters:

validator – A callable that processes a rule or server default and returns its new value. The callable should accept 3 positional arguments: The rule’s value, the rule object (or None for server defaults), and the setting object itself. Validators may raise a TypeError to reject the value.

fields_to_use = Setting('fields_to_use', str, default_value = None)

def compile_value(value: str, *args):
    return re.compile('^' + value + '$')

fields_to_use.add_validator(compile_value)

compiled: Optional[Pattern[str]] = fields_to_use.get()

Local default values are unaffected by validators. If multiple validators are added, they are called in the order they are added.

Returns the validator itself, to be used like a decorator.

Warning

The validators must return an immutable value. Validators may assume that the input is immutable.

get(**contexts: str) → value

Get the value of the setting for a set of context features.

Parameters:

**contexts – the context values of the current context, any configurable context feature specified in the constructor must be either specified here, or provided by the client a as default (see AsyncHeksherClient.set_defaults() and ThreadHeksherClient.set_defaults()).

Returns the value of the highest-priority rule to match the context, or the setting’s default value if not rules matched.