Python SDK

The Winning Variant Python SDK makes it easier to implement split tests directly in your python applicatios, AI/ML workloads, or Streamlit apps. It uses an existing Winning Variant Snowflake Native App installation, accessed via a session object provided to the client.

​

Installation

​

General Installation

Install the SDK by running the following:

pip install winningvariant

​

Import into Snowflake UDFs and procedures using Artifact Registry

The Snowflake Artifact Registry allows you to directly use Python packages from the Python Package Index (PyPI) within Snowpark Python user-defined functions (UDFs) and stored procedures.

Follow the instructions in the linked article to use the winningvariant package.

​

Use in Snowflake Notebooks / Worksheets

Coming soon!

​

Initialization

To initialize the SDK, import the object and inintialize it using a Snowflake Snowpark session object:

from winningvariant import WinningVariantClient
from snowflake.snowpark import Session

connection_parameters = {
    "user": "<USER>",
    "password": "<PASSWORD>",
    "account": "<ACCOUNT IDENTIFIER>",
    "warehouse": "<WAREHOUSE>",
    "database": "<WINNING VARIANT APP NAME>"
}

session = Session.builder.configs(connection_parameters).create()

wv = WinningVariantClient(session)

​

Options

The following intializing parameters are available:

Caching

Caching can be enabled/disabled after client initialization by calling wv.enable_cache() or wv.disable_cache(), respectively.

​

Assignment Object

The SDK includes an Assignment object that is used to identify the ID of a variant that a subject is assigned within an experiment. Read more here.

The Assignment object includes a reference to the subject_id, experiment_id, and the variant it’s assigned to.

​

Assignment Comparison

To test if an assignment is for a given variant, you can call is_variant("<Variant>") or do a string comparison:

if assignment.is_variant("control"):
  print("Control group")

if assignment == "control":
  print("Also control group")

​

Assignment Management

The SDK provides various ways to get/create experiment assignments based on your needs.

​

Get Assignment

This read-only method gets an existing assignment for a subject ID inside of an experiment. If none exists, it will not be created.

<client>.get_assignment(subject_id="...", experiment_id="...")

Returns an Assignment object if one exists, otherwise None.

assignment = wv.get_assignment(subject_id="user_123", experiment_id="my-exp")

if assignment == None:
  print("No assignment for this subject")
elif assignment == "TREATMENT":
  print("Subject is in the treatment group")
elif assignment == "CONTROL":
  print("Subject is in the control group")

​

Get or Create Assignment

Gets an assignment if one exists, otherwise it creates a new one according to the experiment definition.

<client>.create_assignment(subject_id="...", experiment_id="...")

Returns an Assignment object upon success, None if something went wrong.

assignment = wv.create_assignment(subject_id="user_123", experiment_id="my-exp")

if assignment == "TREATMENT":
  print("Subject is in the treatment group")
elif assignment == "CONTROL":
  print("Subject is in the control group")
else:
  print("Something went wrong")

​

Check if a subject has a specific assignment with an experiment

If you have a subject for which you want to do a quick check to see if they have a particular assignment or not, you can use the shorthand check_variant function. A good use case for this would be in 2-variant A/B tests or feature flag scenarios where you want to quickly check if a subject is in the treatment group.

<client>.check_variant(subject_id="...", experiment_id="...", variant_id="...")

Returns a boolean indicating if the subject has the given assignment in the experiment.

is_treatment = wv.check_variant(subject_id="user_123", experiment_id="my-exp", variant_id="treatment")

if is_treatment:
  print("In the treatment group")
else:
  print("Not in the treatment group")

​

Decorators

The SDK provides a number of function decorators to provide optionality in how you implement split tests in our codebase.

Each decorator requires the following:

1. An explicit subject_id OR subject_arg that specifes the argument passed to the function that will include the subject ID.
2. An explicit experiment_id OR experiment_arg that specifies the argument passed to the function that will include the experiment ID.

​

@<client>.assignment

This decorator provides the assignment to the wrapped function. If no assignment exist for the subject, one is created. Supports syncronous and asyncronous functions.

@wv.assignment(subject_arg="subject_id", experiment_arg="experiment_id")
def my_func(subject_id, experiment_id, assignment = None):
    return f"Subject {subject_id} assigned to {assignment.variant}"

my_func(subject_id="user_123", experiment_id="my-exp")

​

@<client>.if_assignment

This decorator executes the wrapped function only if the subject has the given assignment within the experiment. In addition to the general required parameter combinations defined above, this decorator has a few additional parameters:

@wv.if_assignment(subject_arg="subject_id", experiment_arg="experiment_id", variant_id="treatment")
def my_func(subject_id, experiment_id):
    print("Subject is assigned to the treatment variant")

# The function will only be run if `user_123` is assigned to the `treatment` variant
my_func(subject_id="user_123", experiment_id="my-exp")

​

@<client>.unless_assignment

This decorator executes the wrapped function only if the subject DOES NOT HAVE the given assignment within the experiment. In addition to the general required parameter combinations defined above, this decorator has a few additional parameters:

@wv.unless_assignment(subject_arg="subject_id", experiment_arg="experiment_id", variant_id="treatment")
def my_func(subject_id, experiment_id):
    print("Subject is NOT assigned to the treatment variant")

# The function will only be run if `user_123` is NOT assigned to the `treatment` variant
my_func(subject_id="user_123", experiment_id="my-exp")