Python

Getting Started with the Python SDK

Github | PyPI

Add sdk-reforge to your package dependencies

# pyproject.toml
[tool.poetry.dependencies]
sdk-reforge = "1.0.1"

Initialize Client

If you set REFORGE_BACKEND_SDK_KEY as an environment variable, initializing the client is as easy as

from sdk_reforge import ReforgeSDK, Options

sdk = ReforgeSDK(Options())

Unless your options are configured to run using only local data, the client will attempt to connect to the remote CDN.

Special Considerations with Forking servers like Gunicorn that use workers

Webservers like gunicorn can be configured to either use threads or fork child process workers. When forking, the Reforge SDK client must be re-created in order to continue to fetch updated configuration.

from sdk_reforge import ReforgeSDK, Options

# gunicorn configuration hook
def post_worker_init(worker):
    global sdk
    sdk = ReforgeSDK(Options())

You may also do something like using uWSGI decorators

from sdk_reforge import ReforgeSDK, Options

@uwsgidecorators.postfork
def post_fork():
    global sdk
    sdk = ReforgeSDK(Options())

This re-creates the SDK client after forking to ensure proper configuration updates.

Basic Usage

Defaults

Here we ask for the value of a config named max-jobs-per-second, and we specify 10 as a default value if no value is available.

sdk.get("max-jobs-per-second", default=10) # => 10

If no default is provided, the default behavior is to raise a MissingDefaultException.

# raises a `MissingDefaultException`
sdk.get("max-jobs-per-second")

Handling Undefined Configs

If you would prefer your application return None instead of raising an error, you can set on_no_default="RETURN_NONE" when creating your Options object.

from sdk_reforge import ReforgeSDK, Options

options = Options(
    on_no_default="RETURN_NONE"
)
sdk = ReforgeSDK(options)
sdk.get("max-jobs-per-second") # => None

Getting Started

Now create a config named my-first-int-config in the Reforge UI. Set a default value to 50 and sync your change to the API.

Add a feature flag named my-first-feature-flag in the Reforge UI. Add boolean variants of true and false. Set the inactive variant to false, make the flag active and add a rule of type ALWAYS_TRUE with the variant to serve as true. Remember to sync your change to the API.

config_key = "my-first-int-config"
print(config_key, sdk.get(config_key))

ff_key = "my-first-feature-flag"
print(ff_key, sdk.enabled(ff_key))

Run the code above and you should see:

my-first-int-config 50
my-first-feature-flag true

Congrats! You're ready to rock!

Feature Flags

Feature flags become more powerful when we give the flag evaluation rules more information to work with.

We do this by providing a context for the current user (and/or team, request, etc)

context = {
    "user": {
        "key": 123,
        "subscription_level": "pro",
        "email": "bob@example.com"
    },
    "team": {
        "key": 432,
    },
    "device": {
        "key": "abcdef",
        "mobile": False
    }
}

result = sdk.enabled("my-first-feature-flag", context=context)

Feature flags don't have to return just true or false. You can get other data types using get:

sdk.get("ff-with-string", default="default-string", context=context)
sdk.get("ff-with-int", default=5)

Thread-local context

To avoid having to pass a context explicitly to every call to get or enabled, it is possible to set a thread-local context that will be evaluated as the default argument to context= if none is given.

from sdk_reforge import ReforgeSDK, Options, Context

context = {
    "user": {
        "key": 123,
        "subscription_level": "pro",
        "email": "bob@example.com"
    },
    "team": {
        "key": 432,
    },
    "device": {
        "key": "abcdef",
        "mobile": False
    }
}

shared_context = Context(context)

Context.set_current(shared_context)

# with this set, the following two client calls are equivalent

result = sdk.enabled("my-first-feature-flag")
result = sdk.enabled("my-first-feature-flag", context=context)

Scoped context

It is also possible to scope a context for a particular block of code, without needing to set and unset the thread-local context

from sdk_reforge import ReforgeSDK, Options

context = {
    "user": {
        "key": 123,
        "subscription_level": "pro",
        "email": "bob@example.com"
    },
    "team": {
        "key": 432,
    },
    "device": {
        "key": "abcdef",
        "mobile": False
    }
}

sdk = ReforgeSDK(Options())

with sdk.scoped_context(context):
    result1 = sdk.enabled("my-first-feature-flag")

result2 = sdk.enabled("my-first-feature-flag", context=context)

result1 == result2 #=> True

Debugging

At this time, it's not possible to dynamically control the loglevel of the Reforge client itself. Instead control the Reforge client's log level by changing the bootstrap_loglevel in the Options class at start up.

By default this level is set to Logging.WARNING

Testing

from sdk_reforge import ReforgeSDK, Options

sdk = ReforgeSDK(Options(data_sources="LOCAL_ONLY"))
sdk.get(...)

Reference

Available Option parameters

• sdk_key - your reforge.com SDK key
• reforge_api_url - the API endpoint your SDK key has been created for (i.e. https://api.reforge.com)
• datafile - datafile to load
• on_no_default - one of "RAISE" (default) or "RETURN_NONE". This determines how the client behaves when a request for a config cannot find a value, and no default is supplied. These settings will, respectively, raise a MissingDefaultException, or return None.
• on_connection_failure - one of "RETURN" (default) or "RAISE". This determines what should happen if the connection to a remote datasource times out. These settings will, respectively, return whatever is in the local cache from the latest sync from the remote source, or else raise an InitializationTimeoutException.
• collect_sync_interval - how often to send telemetry to Reforge (seconds, defaults to 30)
• collect_evaluation_summaries - send aggregate data about config and feaure flag evaluations, results (defaults to True) Evaluation Summary telemetry Implemented in v0.10+
• collect_logs - send aggregate logger volume data to Reforge (defaults to True)
• context_upload_mode - send context information to Reforge. Values (from the Options.ContextUploadMode enum) are NONE (don't send any context data), SHAPE_ONLY to only send the schema of the contexts to Reforge (field name, data types), PERIODIC_EXAMPLE to send the data types AND the actual contexts being used to Reforge Context telemetry Implemented in v0.10+
• global_context - an immutable global context to be used in all lookups. Use this for things like availability zone, machine type...
• on_ready_callback - register a single method to be called when the client has loaded its first configuration and is ready for use