feat: global variables in Python

[fahad19]

What's done

This PR aligns the Featurevisor Python SDK with the latest JavaScript SDK behaviour and prepares the next breaking release as Python SDK v3.

It adds complete support for global variables, updates feature dependency evaluation, aligns sticky state and lifecycle modules, improves datafile change events, extends the optional OpenFeature provider, and substantially expands conformance coverage.

What changed

Global variables

• Added support for independently defined global variables.
• Added overloaded variable evaluation methods that omit the feature key.
• Added Boolean, string, integer, float, array, object, and JSON helpers.
• Added get_variable_keys for global variable keys.
• Added get_variable_evaluations for aggregate global variable evaluation.
• Added support for caller defaults, sticky values, ordered and nested overrides, conditions, segments, and requiredFeatures.
• Included override keys and nested override paths in evaluation details.
• Added equivalent global variable support to child instances.

Example:

message = f.get_variable_string("welcomeMessage", context)
settings = f.get_variable("checkoutSettings", context)
evaluation = f.evaluate_variable("checkoutSettings", context)

Required features

• Added the canonical requiredFeatures datafile model.
• Supported required feature checks using enabled state, variation, or both.
• Applied required feature checks to features, feature variables, global variables, and variable overrides.
• Ensured required feature evaluations pass through the complete module pipeline.
• Added the required_features_unmet evaluation reason and corresponding metadata.

Sticky features and variables

• Split sticky state into sticky_features and sticky_variables.
• Added set_sticky_features and set_sticky_variables.
• Added sticky_features_set and sticky_variables_set events.
• Added separate sticky feature and global variable support to child instances.
• Aligned sticky replacement and inheritance behaviour with the JavaScript SDK.

Aggregate evaluations

• Added get_feature_evaluations for feature snapshots.
• Added get_variable_evaluations for global variable snapshots.
• Added support for selecting specific feature or global variable keys.
• Applied context and caller override options consistently.

Evaluation modules

• Added beforeEvaluation and afterEvaluation callbacks that work with both feature and global variable evaluations.
• Preserved feature specific before and after callbacks.
• Defined deterministic callback ordering.
• Ensured required feature checks use the complete module pipeline.
• Preserved transformed caller defaults through evaluation.

Datafile updates and events

• Added global variables to datafile parsing, merging, and replacement.
• Added dependency aware change detection across features, segments, required features, and global variables.
• Updated datafile_set events to report affected feature and global variable keys.
• Kept partial datafile update behaviour aligned with the JavaScript SDK.

OpenFeature provider

• Added global variable resolution through keys such as variable:supportEmail.
• Added configurable global_variable_prefix.
• Added global variable override metadata and required feature reason mapping.
• Preserved ownership semantics when using an existing Featurevisor instance.
• Expanded provider tests for global variables, custom prefixes, metadata, and defaults.
• Kept OpenFeature optional through the featurevisor[openfeature] package extra.

CLI and integration

• Added global variable support to the test and benchmark commands.
• Added support for sticky global variables in project assertions.
• Added global variable evaluation metadata to CLI output.
• Expanded the shared SDK v3 conformance fixture and tests.

Breaking changes

• The Python package version is now 3.0.0.
• Sticky APIs now distinguish between features and global variables.
• Aggregate feature evaluations use get_feature_evaluations.
• Global aggregate evaluations use get_variable_evaluations.
• Event names, evaluation details, and public typing structures have been aligned with the latest JavaScript SDK.
• Datafile dependency declarations use requiredFeatures.

Install the base SDK with:

pip install featurevisor

Applications using OpenFeature should install:

pip install "featurevisor[openfeature]"

Verification

• Python SDK unit tests.
• OpenFeature provider tests.
• CLI tests.
• Shared Featurevisor SDK v3 conformance suite.
• Global variable and requiredFeatures alignment tests.
• Module ordering and transformed default tests.
• Child instance tests.
• Datafile event dependency tests.
• Static typing checks.
• Package build and Twine validation.
• Clean installation and OpenFeature extra verification.
• Supported Python version matrix.

Release

This PR prepares the Python package for tag:

v3.0.0

The tag workflow builds and validates the distribution before publishing it to PyPI through trusted publishing.