Clients- Heksher clients

class AsyncHeksherClient(service_url: str, update_interval: int, context_features: Sequence[str], *, http_client_args: dict[str, ...] = None)

An asyncrhonous client for Heksher. Updates and declares settings in the background using asyncio tasks.

Parameters:

• service_url – The URL of the Heksher service.

• update_interval – The interval in seconds between updates.

• context_features – The context features to check for existence.

• http_client_args – Additional keyword arguments to pass to the underlying async HTTPX client.

async set_as_main()

Sets the client as the main client for heksher. Will wait until all currently defined settings are declared, and then will wait for an initial update.

If the client is used as an async context manager, this method will be called on entry.

If an error occurs during the declarations or the initial update, the exception will be raised.

Warning

If an error occurs in the update or declarations loops after the method returned, the exception will not be raised, instead the exception will be logged.

async with AsyncHeksherClient(...) as client:
    ...

async aclose()

Closes the client. This will cancel all pending tasks.

If the client is used as an async context manager, this method will be called on exit.

async close()

Deprecated since version 0.2.0: Use aclose() instead.

Legacy alias for aclose().

async reload()

Updates all setting rules. This occurs automatically every update_interval seconds after set_as_main() is called, but calling this method will perform a manual reload. Will also reset the update timer.

If an error occurs during the update, the exception will be raised.

modification_lock: Lock

A lock that can be used to prevent concurrent modification of setting values. To ensure that no modifications are made to settings, acquire this lock.

Warning

Acquiring this lock will block any modification of setting values, including from the context that acquired it. meaning that the following snippet will deadlock:

async with client.modification_lock:
    await client.reload()

set_defaults(**kwargs: str | ContextVar[str])

Sets the default context feature values. The keys of **kwargs should be context feature names. The values can be either an str, in which case default value for the context feature will be the string. Alternatively, the default value may be a context variable, in which case the value will be fetched dynamically.

async ping() → None

Pings the Heksher service.

Raises:

httpx.HTTPError if the ping fails.

async get_settings() → Dict[str, ...]

Queries the Heksher service for all the settings declared on it (not just by this client). Returns a dict that maps setting names to their data. Setting data has the following attributes:

• name (str): The name of the setting.

• configurable_features (list[str]): The context features configurable for this setting.

• type (str): The type of the setting by Heksher specs.

• default_value (Any): The default value of the setting.

• metadata (dict[str, Any]): The metadata of the setting.

• aliases (list[str]): The aliases of the setting.

• version (str): The version of the setting’s latest declaration.

track_contexts(**context_values: str | Collection[str])

Tracks specific context feature values. When rules are queried from heksher, only rules that fully match all the tracked context features will be returned.

The keys of **context_values should be context feature names. The values can be either a single string, in which case the context feature will be tracked with the value only, or the value may be a collection of strings, in which case the context feature will be tracked with all of the strings as its value. Alternatively, a value may be the constant TRACK_ALL, in which case all values of the context feature will be tracked.

on_update_error(exc: Exception) → None

Called when an error occurs during a rule update. Override this method to add special error handling.

Parameters:

exc – The exception that occurred.

on_update_ok() → None

Called when a rule update completed successfully (including when no change is necessary). Override this method to add a callback on successful updates.

class ThreadHeksherClient(service_url: str, update_interval: int, context_features: Sequence[str], *, http_client_args: dict[str, ...] = None)

A synchronous client for Heksher. Updates and declares settings in the background using a separate thread.

Warning

Since the declarations and updates are performed in a separate thread, any errors that occur during these operations will not be raised. Instead, the error will be logged.

Parameters:

• service_url – The URL of the Heksher service.

• update_interval – The interval in seconds between updates.

• context_features – The context features to check for existence.

• http_client_args – Additional keyword arguments to pass to the underlying HTTPX client.

set_as_main()

Sets the client as the main client for heksher. Will wait until all currently defined settings are declared, and then will wait for an initial update.

If the client is used as a context manager, this method will be called on entry.

with ThreadHeksherClient(...) as client:
    ...

close()

Closes the client. This will close the background thread.

If the client is used as a context manager, this method will be called on exit.

reload()

Updates all setting rules. This occurs automatically every update_interval seconds after set_as_main() is called, but calling this method will perform a manual reload. Will also reset the update timer.

modification_lock: Lock

A lock that can be used to prevent concurrent modification of setting values. To ensure that no modifications are made to settings, acquire this lock.

Warning

Acquiring this lock will block any modification of setting values, including from the context that acquired it. meaning that the following snippet will deadlock:

with client.modification_lock:
    client.reload()

set_defaults(**kwargs: str | ContextVar[str])

Sets the default context feature values. The keys of **kwargs should be context feature names. The values can be either an str, in which case default value for the context feature will be the string. Alternatively, the default value may be a context variable, in which case the value will be fetched dynamically.

ping() → None

Pings the Heksher service.

Raises:

httpx.HTTPError if the ping fails.

get_settings() → Dict[str, ...]

Queries the Heksher service for all the settings declared on it (not just by this client). Returns a dict that maps setting names to their data. Setting data has the following attributes:

• name (str): The name of the setting.

• configurable_features (list[str]): The context features configurable for this setting.

• type (str): The type of the setting by Heksher specs.

• default_value (Any): The default value of the setting.

• metadata (dict[str, Any]): The metadata of the setting.

• aliases (list[str]): The aliases of the setting.

• version (str): The version of the setting’s latest declaration.

track_contexts(**context_values: str | Collection[str])

Tracks specific context feature values. When rules are queried from heksher, only rules that fully match all the tracked context features will be returned.

The keys of **context_values should be context feature names. The values can be either a single string, in which case the context feature will be tracked with the value only, or the value may be a collection of strings, in which case the context feature will be tracked with all of the strings as its value. Alternatively, a value may be the constant TRACK_ALL, in which case all values of the context feature will be tracked.

on_update_error(exc: Exception) → None

Called when an error occurs during a rule update. Override this method to add special error handling.

Parameters:

exc – The exception that occurred.

on_update_ok() → None

Called when a rule update completed successfully (including when no change is necessary). Override this method to add a callback on successful updates.