reddit_experiments (legacy)

Please consider upgrading your service to use the latest reddit_decider SDK to gain access to new features, such as Mutually Exclusive Groups, Holdout Groups, and Dynamic Configurations.

Initialize Experiments instance on Baseplate context

Add the Experiments client to your application via:

baseplate.configure_context(
   {
      ...
      "experiments": ExperimentsClient(event_logger),
      ...
   }
)

or alternatively using:

experiments_factory = experiments_client_from_config(
                          app_config=app_config,
                          event_logger=ExperimentLogger
)
baseplate.add_to_context("experiments", experiments_factory)

Configure Experiments client

Configure the client in your application’s configuration file:

[app:main]

...

# optional: a path to the file where experiment configuration is written
# (default: /var/local/experiments.json)
experiments.path = /var/local/foo.json

# optional: how long to wait for the experiments file to exist before failing
# (default: do not wait. fail immediately if not available)
experiments.timeout = 60 seconds

# optional: the base amount of time for exponential backoff while waiting
# for the file to be available.
# (default: no backoff time between tries)
experiments.backoff = 1 second

...

Usage

Use the attached Experiments object in request to get a variant:

def my_method(request):
    if request.experiments.variant("foo") == "bar":
        pass

Experiments API

class reddit_experiments.Experiments(config_watcher, server_span, context_name, cfg_data=None, global_cache=None, 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]

DEPRECATED.

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: str, user: Optional[reddit_edgecontext.User] = 'None', bucketing_event_override: Optional[bool] = 'None', **kwargs: str) → Optional[str][source]
variant(*, experiment_name: str, user: Optional[reddit_edgecontext.User] = 'None', bucketing_event_override: Optional[bool] = 'None', **kwargs: str) → Optional[str]

DEPRECATED.

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

  • experiment_name (Optional[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]

DEPRECATED.

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

Configuration Class

class reddit_experiments.ExperimentsClient(event_logger)[source]

DEPRECATED.

Configure an experiments client.

This is meant to be used with baseplate.Baseplate.configure_context().

See experiments_client_from_config() for available configuration settings.

Parameters

event_logger (EventLogger) – The EventLogger instance to be used to log bucketing events.

Configuration Function

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

DEPRECATED.

Configure and return an ExperimentsContextFactory object.

The keys used in your app’s some_config.ini file should be prefixed, e.g. experiments.path, etc.

Supported config keys:

path (optional)

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 not blocking).

backoff (optional)

The base amount of time for exponential backoff when trying to find the experiments config file. Defaults to no backoff between tries.

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.”).

Return type

ExperimentsContextFactory

Configuration Context Factory

class reddit_experiments.ExperimentsContextFactory(path, event_logger=None, timeout=None, backoff=None)[source]

Experiment client context factory.

This factory will attach a new reddit_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.