Migrating the Python SDK for Featurevisor v4

• Minimal migration path
• Breaking changes
  • Root condition reasonBreaking
  • Datafile update resultBreaking
  • Replace removed module hooksBreaking
  • Update detailed evaluation fieldsBreaking
  • Number getterBreaking
• OpenFeature
• Migration checklist
  • Required for the migration
  • Only if adopting optional features

Upgrade Python applications to SDK 4.0.0 for Featurevisor v4 support.

Follow the shared migration order: prepare canonical prerequisite datafiles, upgrade consumers, then upgrade the project CLI. Before publishing new runtime fields, follow Adopt new syntax safely.

Minimal migration path#

1. Prepare existing feature prerequisites using the central migration order.
2. Replace the removed module hooks and detailed evaluation fields below if your application uses them.
3. Upgrade the Python SDK to 4.0.0. If the application uses the OpenFeature extra, upgrade that installation at the same time.
4. Follow the mixed version deployment guidance before enabling any new v4 datafile capability.

Most application source code can stay unchanged after datafile preparation. The factory, standard getters, child instances, sticky setters and separate evaluation snapshots keep their existing names:

f = create_featurevisor({"datafile": datafile})
enabled = f.is_enabled("checkout", context)
variation = f.get_variation("checkout", context)
label = f.get_variable("checkout", "label", context)
support_email = f.get_variable("supportEmail", context)
f.set_sticky_features(sticky_features)
f.set_sticky_variables(sticky_variables)
feature_evaluations = f.get_feature_evaluations()
variable_evaluations = f.get_variable_evaluations()
child = f.spawn({"country": "nl"})

There is no sticky API or snapshot API rename to perform for these canonical methods.

Breaking changes#

Root condition reason Breaking#

An unmet root gate reports conditions_unmet for feature flags and global variables, replacing the v3 required reason for feature flags and required_features_unmet for global variables. This applies to attribute, segment, feature and variable leaves in root conditions. Update callbacks, analytics and test expectations. Variation and feature variable evaluations retain their disabled reasons. See the shared migration guidance.

unmet_requirement = evaluation["reason"] == "required"

unmet_requirement = evaluation["reason"] == "conditions_unmet"

Datafile update result Breaking#

set_datafile now returns True when it accepts the update, including unchanged content, and False when it rejects the update or the instance is closed. A rejected update keeps the previous datafile and reports details through diagnostics. Calls that ignore the result keep working. Update any wrapper or interface that declares the old return type. Merging remains the default.

f.set_datafile(datafile)

accepted = f.set_datafile(datafile)
if not accepted:
    print("Datafile rejected. Check diagnostics.")

Replace removed module hooks Breaking#

The old before and after module hooks are removed. Use beforeEvaluation and afterEvaluation, which already existed in the previous SDK line and are now the only evaluation hooks.

my_module = {
    "name": "application-module",
    "before": lambda options: options,
    "after": lambda evaluation, options: evaluation,
}
f = create_featurevisor({
    "datafile": datafile,
    "modules": [my_module],
})

my_module = {
    "name": "application-module",
    "beforeEvaluation": lambda options: options,
    "afterEvaluation": lambda evaluation, options: evaluation,
}
f = create_featurevisor({
    "datafile": datafile,
    "modules": [my_module],
})

The canonical hooks also run for global variable evaluation. If a module contains feature specific behaviour, guard it with "featureKey" in options.

Update detailed evaluation fields Breaking#

Only code that reads detailed evaluation dictionaries needs these changes:

New variable prerequisite failures are exposed through evaluation["conditions"]. Ordinary getter return types do not change.

Number getter Breaking#

Variables that hold numbers have the type number, so the typed getter is now get_variable_number(). It reads number variables and the double variables of datafiles built before v4. get_variable_double() and the camelCase getVariableDouble() were removed. Rename calls to the number getter, which returns the same value.

threshold = f.get_variable_double("freeShippingThreshold", context)

threshold = f.get_variable_number("freeShippingThreshold", context)

OpenFeature #

The Python OpenFeature provider remains an optional extra of the featurevisor package. If your application uses it, upgrade the installation that provides featurevisor[openfeature] with the core runtime when upgrading the Python SDK. The updated provider maps conditions_unmet to OpenFeature's disabled reason.

The provider distinguishes a received empty targeting key from an absent one: empty replaces the configured userId or targeting field, while omission preserves it. Python's upstream client can lose an empty key while merging contexts. Set the configured field itself to "" in attributes if needed, after clearing any inherited nonempty targeting key at its source.

See the Python SDK OpenFeature guide for provider setup.

Migration checklist#

Required for the migration#

1. Confirm every consumer uses a compatible SDK release and that existing prerequisites use conditions and feature.
2. Confirm no module still declares before or after, and detailed evaluation readers use the canonical fields.
3. Rename get_variable_double() and getVariableDouble() calls to get_variable_number().
4. Upgrade the project CLI last, review mutation order and date and regex comparisons, and retain a prepared rollback datafile.

Only if adopting optional features#

Follow Adopt new syntax safely before publishing new datafile syntax. Upgrade every CLI runner before adding checks or scenarios.