Python API

Class Rox

from rox.server.rox_server import Rox

The Rox class provides your application its primary interface with feature flags in the CloudBees Feature Flags system. This is the central repository for your application’s flags. It handles communications with the server to obtain the latest values, experiment settings, and configurations. It provides a mechanism through which you can use the feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided container will be marked as feature flags and will appear in your application’s CloudBees Feature Flags dashboard once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, int, float and semver. You can use a lambda or functions class to provide a custom property that is dependent upon code state.

You can also use a RoxOptions object to configure some aspects of this class. You can set the verbosity level, custom platform, impression handler, fetch handler,

Setup

Rox.setup(apiKey)
Rox.setup(apiKey, options)

Configures the Rox object to work with the provided Android application.

Parameter Modifier and Type Description

apiKey

string

The environment key provided by the CloudBees Feature Flags dashboard

options

RoxOptions

A RoxOptions instance with the desired configuration for this application

Returns

Returns a Future object representing the execution of the call. It is called when the SDK loads the configuration from the network for the first time.

Register

Rox.register(namespace, container)

Registers a feature flag container with the Rox client. The public member variables of this container will become a flag in your CloudBees Feature Flags dashboard and will be named with the object name.

Parameter Modifier and Type Description

namespace

string

The prefix namespace for all flags in this container

container

object

An object that contains your application’s feature flags

For example, assuming we have the following container:

from rox.server.flags.rox_flag import RoxFlag

class MyContainer:
     def __init__(self):
        self.include_facebook = RoxFlag()
        self.include_github = RoxFlag();

and we register the container with the following code:

from rox.server.rox_server import Rox

my_container = MyContainer()

Rox.register(Login', myContainer)
Rox.setup(<ROLLOUT_KEY>)

The flags and configurations in the dashboard will have the names Login.includeFacebook and Login.includeGithub. This can be used to create several namespaces, each with its own group of flags and configurations.

If you don’t need a namespace, you can set the namespace to an empty string.

set_custom_boolean_property

Rox.set_custom_boolean_property(name, value)

Sets a custom boolean property on the Rox client. The value can be either a boolean value or a function that gets invoked with the context that was passed to the flag is_enabled function. The function should return a boolean value.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

boolean

function (context) → boolean

set_custom_string_property

Rox.set_custom_string_property(name, value)

Sets a custom string property on the Rox client. The value can be either a string value or a function that gets invoked with the context that was passed to the flag is_enabled function. The function should return a string value.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

string

function (context) → string

set_custom_int_property

Rox.set_custom_int_property(name, value)

Sets a custom integer property on the Rox client. The value can be either a string value or a function that gets invoked with the context that was passed to the flag is_enabled function. The function should return an integer value.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

int

function (context) → int

set_custom_semver_property

Rox.set_custom_semver_property(name, value)

Sets a custom semver property on the Rox client. The value can be either a string value or a function that gets invoked with the context that was passed to the flag is_enabled function. The function should return an string value.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

string

function (context) → string

set_custom_float_property

Rox.set_custom_float_property(name, value)

Sets a custom float property on the Rox client. The value can be either a string value or a function that gets invoked with the context that was passed to the flag is_enabled function. The function should return a float value.

Parameter Modifier and Type Description

name

string

The property name

value

float

function (context) → float

set_context

Rox.set_context(context)

Set a global context, which will be available to all flag evaluations.

fetch

Rox.fetch()

Create a network request for the latest configuration.

Returns

Returns a Future object representing the execution of the call.

Class RoxOptions

from roxserver.rox_options import RoxOptions

RoxOptions covers configuration options for the Rox client. This includes settings like the verbosity of the logging. Instances of this class should be created using RoxOptions.Builder.

Example

Here is an example of setting up a new RoxOptions object. This object sets the version, logger, provides an impression handler, and includes a fetch handler.

from rox.server.rox import Rox
from rox.server.rox_options import RoxOptions



# setup configuration_fetched_handler in the options object
options = RoxOptions(
    configuration_fetched_handler=on_configuration_fetched
      impression_handler=on_impression
)


cancel_event = Rox.setup('<key>', options).result();

version

Set the version of the service running the CloudBees Feature Flags SDK (semver string).

fetch_interval

Set the polling interval (in seconds) for fetching configuration from the CloudBees Feature Flags storage service. The default setting is 60 seconds, and the minimum time setting is 30 seconds.

logger

Set the logger to be used for logging.

The logger should implement the following:

def debug(self, message, ex=None)
def error(self, message, ex=None)
def warn(self, message, ex=None)

See Turning on verbose logging for an example.

configuration_fetched_handler

Set the configuration event handler, to add actions after configurations are fetched.

For an example, see Flag update flow.

impression_handler

Set the impression event handler, to add actions after an impression.

For an example, see Impression handler.

Class RoxFlag

from rox.server.flags.rox_flag import RoxFlag

RoxFlag is a boolean feature flag. It can be either true or false.

is_enabled

flag.is_enabled(Context = null)

Returns true if the flag is enabled.

name

flag.name

The name of the Flag.

Class RoxVariant

from rox.server.flags.rox_variant import RoxVariant

RoxVariant is a feature flag object that can have values more complex than a simple boolean true or false. RoxVariant accepts a list of possible values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

get_value

variant.get_value(context=None):

Returns

name

variant.name

The name of the Variant.

Using impression_handler

The impression_handler delegate/method (you can provide to RoxOptions) has a couple of useful parameters which can help you decide on further actions. This event handler data type is ImpressionArgs.

ImpressionArgs class

This object has two properties: flag name and the value.

Property Description

name

The flag name

value

The evaluation result

public Experiment Experiment { get; }

The experiment of the flag:

name

Experiment name

identifier

Experiment id

is_archived

If the experiment is archived

labels

Experiment’s labels

For an example, see Impression handler.