baseplate.lib.experiments

Configuration Parsing

baseplate.lib.experiments.experiments_client_from_config(app_config, event_logger, prefix='experiments.')[source]

Configure and return an ExperimentsContextFactory object.

The keys useful to experiments_client_from_config() should be prefixed, e.g. experiments.path, etc.

Supported keys:

path: the path to the experiment configuration file generated by the
experiment configuration fetcher daemon.
timeout (optional): the time that we should wait for the file specified by
path to exist. Defaults to None which is infinite.
Parameters:
  • raw_config – The application configuration which should have settings for the experiments client.
  • event_logger (EventLogger) – The EventLogger to be used to log bucketing events.
  • prefix (str) – the prefix used to filter keys (defaults to “experiments.”).
  • backoff – retry backoff time for experiments file watcher. Defaults to None, which is mapped to DEFAULT_FILEWATCHER_BACKOFF.
Return type:

ExperimentsContextFactory

Classes

class baseplate.lib.experiments.ExperimentsContextFactory(path, event_logger=None, timeout=None, backoff=None)[source]

Experiment client context factory.

This factory will attach a new baseplate.lib.experiments.Experiments to an attribute on the RequestContext.

Parameters:
  • path (str) – Path to the experiment configuration file.
  • event_logger (Optional[EventLogger]) – The logger to use to log experiment eligibility events. If not provided, a DebugLogger will be created and used.
  • timeout (Optional[float]) – How long, in seconds, to block instantiation waiting for the watched experiments file to become available (defaults to not blocking).
  • backoff (Optional[float]) – retry backoff time for experiments file watcher. Defaults to None, which is mapped to DEFAULT_FILEWATCHER_BACKOFF.
class baseplate.lib.experiments.Experiments(config_watcher, server_span, context_name, event_logger=None)[source]

Access to experiments with automatic refresh when changed.

This experiments client allows access to the experiments cached on disk by the experiment configuration fetcher daemon. It will automatically reload the cache when changed. This client also handles logging bucketing events to the event pipeline when it is determined that the request is part of an active variant.

get_all_experiment_names()[source]

Return a list of all valid experiment names from the configuration file.

Return type:Sequence[str]
Returns:List of all valid experiment names.
is_valid_experiment(name)[source]

Return true if the provided experiment name is a valid experiment.

Parameters:name (str) – Name of the experiment you want to check.
Return type:bool
Returns:Whether or not a particular experiment is valid.
variant(name, user=None, bucketing_event_override=None, **kwargs)[source]

Return which variant, if any, is active.

If a variant is active, a bucketing event will be logged to the event pipeline unless any one of the following conditions are met:

  1. bucketing_event_override is set to False.
  2. The experiment specified by “name” explicitly disables bucketing events.
  3. We have already logged a bucketing event for the value specified by experiment.get_unique_id(\*\*kwargs) within the current request.

Since checking the status an experiment will fire a bucketing event, it is best to only check the variant when you are making the decision that will expose the experiment to the user. If you absolutely must check the status of an experiment before you are sure that the experiment will be exposed to the user, you can use bucketing_event_override to disabled bucketing events for that check.

Parameters:
  • name (str) – Name of the experiment you want to run.
  • user (Optional[User]) – User object for the user you want to check the experiment variant for. If you set user, the experiment parameters for that user (“user_id”, “logged_in”, and “user_roles”) will be extracted and added to the inputs to the call to Experiment.variant. The user’s event_fields will also be extracted and added to the bucketing event if one is logged. It is recommended that you provide a value for user rather than setting the user parameters manually in kwargs.
  • bucketing_event_override (Optional[bool]) – Set if you need to override the default behavior for sending bucketing events. This parameter should be set sparingly as it breaks the assumption that you will fire a bucketing event when you first check the state of an experiment. If set to False, will never send a bucketing event. If set to None, no override will be applied. Set to None by default. Note that setting bucketing_event_override to True has no effect, it will behave the same as when it is set to None.
  • kwargs (str) – Arguments that will be passed to experiment.variant to determine bucketing, targeting, and overrides. These values will also be passed to the logger.
Return type:

Optional[str]

Returns:

Variant name if a variant is active, None otherwise.

expose(experiment_name, variant_name, user=None, **kwargs)[source]

Log an event to indicate that a user has been exposed to an experimental treatment.

Parameters:
  • experiment_name (str) – Name of the experiment that was exposed.
  • variant_name (str) – Name of the variant that was exposed.
  • user (Optional[User]) – User object for the user you want to check the experiment variant for. If unset, it is expected that user_id and logged_in values will be set in the keyword arguments.
  • kwargs (str) – Additional arguments that will be passed to logger.
Return type:

None