Samples

Samples are on a given percentage of the time. They do not require a request object and can be used in other contexts, such as management commands and tasks.

Warning

Sample values are random: if you check a Sample twice, there is no guarantee you will get the same value both times. If you need to rely on the value more than once, you should store it in a variable.

# YES
foo_on = sample_is_active('foo')
if foo_on:
    pass

# ...later...
if foo_on:
    pass

# NO!
if sample_is_active('foo'):
    pass

# ...later...
if sample_is_active('foo'):  # INDEPENDENT of the previous check
    pass

Sample Attributes

Samples can be administered through the Django admin site or the command line. They have the following attributes:

Name:The name of the Sample. Percent:A number from 0.0 to 100.0 that determines how often the Sample will be active. Note:Describe where the Sample is used.

Custom Sample Models

For many cases, the default Sample model provides all the necessary functionality. If you would like additional fields not supported by the default Sample model, you can use a custom Sample model.

An application needs to define a WAFFLE_SAMPLE_MODEL settings. The default is waffle.Sample but can be pointed to an arbitrary object.

Note

It is not possible to change the Sample model and generate working migrations. Ideally, the Sample model should be defined at the start of a new project. This is a limitation of the swappable Django magic. Please use magic responsibly.

The custom Sample model must inherit from waffle.models.AbstractBaseSample.

When using a custom Sample model, you must run Django’s makemigrations before running migrations as outlined in the installation docs.

If you need to reference the class that is being used as the Sample model in your project, use the get_waffle_model('SAMPLE_MODEL') method. If you reference the Switch a lot, it may be convenient to add Switch = get_waffle_model('SAMPLE_MODEL') right below your imports and reference the Sample model as if it had been imported directly.

Example:

# settings.py
WAFFLE_SAMPLE_MODEL = 'myapp.Sample'

# models.py
from waffle.models import AbstractBaseSample, CACHE_EMPTY

class Sample(AbstractBaseSample):

    owner = models.CharField(
        max_length=100,
        blank=True,
        help_text=_('The individual/team who owns this sample.'),
    )

# admin.py
from waffle.admin import SampleAdmin as WaffleSampleAdmin

class SampleAdmin(WaffleSampleAdmin):
    raw_id_fields = tuple(list(WaffleSampleAdmin.raw_id_fields) + ['owner'])
admin.site.register(Sample, SampleAdmin)

Auto Create Missing

When a sample is evaluated in code that is missing in the database the sample returns the WAFFLE_SAMPLE_DEFAULT value but does not create a sample in the database. If you’d like waffle to create missing samples in the database whenever it encounters a missing sample you can set WAFFLE_CREATE_MISSING_SAMPLES to True. If WAFFLE_SAMPLE_DEFAULT is True then the Percent attribute of the sample will be created as 100.0 (so that when the sample is checked it always evaluates to True). Otherwise the value will be set to 0.0 so that the sample always evaluates to False.

Log Missing

Whether or not you enabled Auto Create Missing Sample, it can be practical to be informed that a sample was or is missing. If you’d like waffle to log a warning, error, … you can set WAFFLE_LOG_MISSING_SAMPLES to any level known by Python default logger.