baseplate.experiments

Configuration Parsing

baseplate.experiments.experiments_client_from_config(app_config, event_logger, prefix='experiments.')

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 config file generated by the experiment
config 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 (dict) – The application configuration which should have settings for the experiments client.
  • event_logger (baseplate.events.EventLogger) – The EventLogger to be used to log bucketing events.
  • prefix (str) – the prefix used to filter keys (defaults to “experiments.”).
Return type:

ExperimentsContextFactory

baseplate.experiments.providers.parse_experiment(config)

Parse an experiment config dict and return an appropriate Experiment class.

The config dict is expected to have the following values:

  • id: Integer experiment ID, should be unique for each experiment.
  • name: String experiment name, should be unique for each experiment.
  • owner: The group or individual that owns this experiment.
  • version: String to identify the specific version of the experiment.
  • start_ts: A float of seconds since the epoch of date and time when you want the experiment to start. If an experiment has not been started yet, it is considered disabled.
  • stop_ts: A float of seconds since the epoch of date and time when you want the experiment to stop. Once an experiment is stopped, it is considered disabled.
  • type: String specifying the type of experiment to run. If this value is not recognized, the experiment will be considered disabled.
  • experiment: The experiment config dict for the specific type of experiment. The format of this is determined by the specific experiment type.
  • enabled: (Optional) If set to False, the experiment will be disabled and calls to experiment.variant will always return None and will not log bucketing events to the event pipeline. Defaults to True.
  • global_override: (Optional) If this is set, calls to experiment.variant will always return the override value and will not log bucketing events to the event pipeline.
Parameters:config (dict) – Configuration dict for the experiment you wish to run.
Return type:baseplate.experiments.providers.base.Experiment
Returns:A subclass of Experiment for the given experiment type.

Classes

class baseplate.experiments.ExperimentsContextFactory(path, event_logger=None, timeout=None)

Experiment client context factory.

This factory will attach a new baseplate.experiments.Experiments to an attribute on the context object.

Parameters:
  • path (str) – Path to the experiment config file.
  • event_logger (baseplate.events.EventLogger) – The logger to use to log experiment eligibility events. If not provided, a baseplate.events.DebugLogger will be created and used.
  • timeout (float) – How long, in seconds, to block instantiation waiting for the watched experiments file to become available (defaults to not blocking).
class baseplate.experiments.Experiments(config_watcher, server_span, context_name, event_logger=None)

Access to experiments with automatic refresh when changed.

This experiments client allows access to the experiments cached on disk by the experiment config 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()

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

Return type:list
Returns:List of all valid experiment names.
is_valid_experiment(name)

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)

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 (baseplate.core.User) – (Optional) 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 (bool) – (Optional) 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 – 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:

str

Returns:

Variant name if a variant is active, None otherwise.

expose(experiment_name, variant_name, user=None, **kwargs)

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 (baseplate.core.User) – (Optional) 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 kwargs
  • kwargs – Additional arguments that will be passed to logger.