Python API

8 minute readReference

The following information is for the latest version of the Python SDK. If you are running an older version, please check the CloudBees Feature Management - Python changelog for any differences.

Class Rox

from rox.server.rox_server import Rox
▼

The Rox class provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values in the provided container are marked as feature flags and display in the CloudBees Feature Management UI 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, and fetch handler.

Setup

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

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

Parameter Modifier and Type Description

apiKey

string

The environment key provided by the CloudBees Feature Management 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.

Shutdown

Rox.shutdown()
▼

Perform graceful shutdown of the Rox object; this will close and clean all background tasks and threads. Shutdown can only be used when Rox was successfully Setup; calling Shutdown when it’s not possible will result a log warning. You can call Setup again after Shutdown and right after Shutdown, all Register and SetCustomProperty will use new Rox, and will register the objects to the Dashboard on the next Setup call.

Register

Rox.register(container)
▼
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 Management 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 (defaults to '')

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 or leave it out as it defaults 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.

set_userspace_unhandled_error_handler

def user_unhandled_error_invoker(errorDetails):
    print('Unhandled error. trigger type: {}, source: {}, exception: {}.'.format(errorDetails.exception_trigger, errorDetails.exception_source, errorDetails.exception))

Rox.set_userspace_unhandled_error_handler(user_unhandled_error_invoker)
▼

A handler for all user function errors, which might help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger. Note: it is recommended to wrap all user methods with try-except in order to handle it while in the relevant context, and not afterward.

The user_unhandled_error_invoker function should accept a single argument of type rox.core.error_handling.userspace_unhandled_error_invoker.UserspaceUnhandledErrorArgs. From this you can get details of the error in the following properties:

Property Modifier and Type Description

exception_source

function

The handler function that raised the error.

exception_trigger

ExceptionTrigger

the area of functionality where the error originated. See below for the possible values of ExceptionTrigger.

exception

Exception

The Exception that occurred in the identified exception_source.

The exception_trigger will be one of the following values:

class ExceptionTrigger(Enum):
    DYNAMIC_PROPERTIES_RULE = 1,
    CONFIGURATION_FETCHED_HANDLER = 2,
    IMPRESSION_HANDLER = 3,
    CUSTOM_PROPERTY_GENERATOR = 4
▼

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(
    version="1.0.4"
    fetch_interval=60
    logger=application_log
    configuration_fetched_handler=lambda sender, e: # TODO: add things to do when configuration was fetched
    impression_handler=lambda sender, e: # TODO: add things to do on impression
    dynamic_property_rule_handler=lambda property, context: # TODO: return dynamic rule for properties
    hosting="eu"
)


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

version

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

fetch_interval

Set the polling interval (in seconds) for fetching configuration from the CloudBees Feature Management 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.

Arguments to be passed into the configuration_fetched_handler

Property Description 
fetcher_status
▼

enum indicating the fetch result, can be one of APPLIED_FROM_EMBEDDED, APPLIED_FROM_LOCAL_STORAGE, APPLIED_FROM_NETWORK or ERROR_FETCHED_FAILED

 
creation_date
▼

The time the fetched configurations were created and signed

 
error_details
▼

enum indicating which error occured while fetching and setting up the new configurations. Can be one of CORRUPTED_JSON, EMPTY_JSON, SIGNATURE_VERIFICATION_ERROR, NETWORK_ERROR, MISMATCH_APP_KEY, UNKNOWN, NO_ERROR

For an example, see Flag update flow.

impression_handler

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

Arguments to be passed into the impression_handler

Property Description 
reporting_value
▼

Object that contains name (string), value (string) and targeting (boolean).

 
context
▼

The context in which the impression was called (this is a merged context containing the global context, and the call’s context)

For an example, see Impression handler.

dynamic_property_rule_handler

The Dynamic Custom Property Generator is called when an explicit Custom Property definiton does not exist on the client side.

If you do not set the dynamic_property_rule_handler, it will then activate the default method which tries to extract the property value from context.

def __default_dynamic_handler(self, prop_name, context):
  if context:
    return context[prop_name]
  return None
▼

roxy_url

A Roxy url - see Microservices automated testing and local development.

hosting

Set hosting location

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 RoxString

from rox.core.entities.rox_string import RoxString
▼

RoxString is a feature flag object that can have string values. RoxString 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.

Example

title_colors_options = ['Black', 'Blue', 'Green']
title_colors_flag = RoxString('Black', title_colors_options)

if title_colors_flag.get_value() == 'Black':
  # set the title color to black

if title_colors_flag.get_value() == 'Green':
  # set the title color to green
▼

get_value

flag.get_value(context=None):
▼

Returns the RoxString’s value considering the given context.

Class RoxInt

from rox.core.entities.rox_int import RoxInt
▼

RoxInt is a feature flag object that can have int values. RoxInt accepts a list of possible int 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.

Example

title_size_flag = RoxInt(14, [14, 18, 24])

title_size = title_size_flag.get_int()
▼

get_int

flag.get_int(context=None)
▼

Returns the RoxInt’s value considering the given context.

get_value

flag.get_value(context=None)
▼

Returns the RoxInt’s value considering the given context. Note: this calls get_int().

Class RoxDouble

from rox.core.entities.rox_double import RoxDouble
▼

RoxDouble is a feature flag object that can have double values. RoxDouble accepts a list of possible double 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.

Example

price_options_flag = RoxDouble(19.99, [19.99, 29.99, 40.5])

price = price_options_flag.get_double()
▼

get_double

flag.get_double(context=None)
▼

Returns the RoxDouble’s value considering the given context.

get_value

flag.get_value(context=None)
▼

Returns the RoxDouble’s value considering the given context. Note: this calls get_double().

Rox.DynamicApi()

Rox.dynamic_api()
▼

An alternative of using container with register. This allows you to evaluate flags without having a static container. DynamicApi will create flags as if they were registered, including sending them to the dashboard.

See also Dynamic api.

isEnabled

Evaluate a boolean flag.

is_enabled(name, defaultValue, context = None);
▼

name

type

description

name

string

the flag’s name - throws an error if None

defaultValue

boolean

the default value to use if no dashboard configurations

context

object

a context to evalute the flag with, will be merged with the global context

value

Evaluate a string flag

value(name, defaultValue, options = [], context = None);
▼

name

type

description

name

string

the flag’s name - throws an error if none

defaultValue

string

the default value to use if no dashboard configurations, or value was set to default on dashboard throws an error if null

options

string[]

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

object

a context to evalute the flag with, will be merged with the global context

get_int

Evaluate an int flag

get_int(name, defaultValue, options = [], context = None);
▼
name type description

name

string

the flag’s name - throws an error if none

defaultValue

int

the default value to use if no dashboard configurations, or value was set to default on dashboard

variations

int[]

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

object

a context to evalute the flag with, will be merged with the global context

get_double

Evaluate a double flag

get_double(name, defaultValue, options = [], context = None);
▼
name type description

name

string

the flag’s name - throws an error if none

defaultValue

double

the default value to use if no dashboard configurations, or value was set to default on dashboard

variations

double[]

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

object

a context to evalute the flag with, will be merged with the global context
PHP API
React Native API