Metadata-Version: 2.5
Name: gofeatureflag-python-provider
Version: 1.3.0
Summary: GO Feature Flag provider for OpenFeature
Project-URL: Bug Tracker, https://github.com/thomaspoignant/go-feature-flag/issues
Project-URL: Source Code, https://github.com/thomaspoignant/go-feature-flag/tree/main/openfeature/providers/python-provider
Project-URL: Documentation, https://github.com/thomaspoignant/go-feature-flag/tree/main/openfeature/providers/python-provider
Author: Thomas Poignant
License-Expression: Apache-2.0
Keywords: feature flags,feature toggles,go-feature-flag,gofeatureflag,open-feature,openfeature
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: openfeature-provider-ofrep>=0.3.0
Requires-Dist: openfeature-sdk<0.11.0,>=0.8.4
Requires-Dist: pydantic>=2.13.4
Requires-Dist: urllib3>=2.7.0
Requires-Dist: wasmtime>=47.0.1
Description-Content-Type: text/markdown

# GO Feature Flag Python Provider

GO Feature Flag provider allows you to connect to your GO Feature Flag instance.

[GO Feature Flag](https://gofeatureflag.org) believes in simplicity and offers a simple and lightweight solution to use feature flags.  
Our focus is to avoid any complex infrastructure work to use GO Feature Flag.

This is a complete feature flagging solution with the possibility to target only a group of users, use any types of flags, store your configuration in various location and advanced rollout functionality. You can also collect usage data of your flags and be notified of configuration changes.

# Python SDK usage

## Install dependencies

The first things we will do is install the **Open Feature SDK** and the **GO Feature Flag provider**.

```shell
pip install gofeatureflag-python-provider
```

## Evaluation modes

The provider supports two evaluation modes:

| Mode | Description |
|------|-------------|
| **In-Process** _(default)_ | Flag configuration is fetched and cached locally; evaluation runs via a WASM module — no per-evaluation network call. |
| **Remote** | Each flag evaluation makes an HTTP request to the GO Feature Flag relay proxy using the OFREP API. |

## Initialize your Open Feature client

### In-Process evaluation (default)

In-Process evaluation fetches the flag configuration from the relay proxy at startup and on a configurable polling interval. Flags are evaluated locally using a bundled WASM module, which gives you lower latency and no per-evaluation network dependency.

```python
from gofeatureflag_python_provider.provider import GoFeatureFlagProvider
from gofeatureflag_python_provider.options import GoFeatureFlagOptions, EvaluationType
from openfeature import api
from openfeature.evaluation_context import EvaluationContext

goff_provider = GoFeatureFlagProvider(
    options=GoFeatureFlagOptions(
        endpoint="https://gofeatureflag.org/",
        evaluation_type=EvaluationType.INPROCESS,  # default
    )
)
api.set_provider(goff_provider)
client = api.get_client(domain="test-client")
```

### Remote evaluation

Remote evaluation sends each flag evaluation as an HTTP request to the relay proxy.

```python
from gofeatureflag_python_provider.provider import GoFeatureFlagProvider
from gofeatureflag_python_provider.options import GoFeatureFlagOptions, EvaluationType
from openfeature import api

goff_provider = GoFeatureFlagProvider(
    options=GoFeatureFlagOptions(
        endpoint="https://gofeatureflag.org/",
        evaluation_type=EvaluationType.REMOTE,
    )
)
api.set_provider(goff_provider)
client = api.get_client(domain="test-client")
```

## Evaluate your flag

This code block explains how you can create an `EvaluationContext` and use it to evaluate your flag.

> In this example we are evaluating a `boolean` flag, but other types are available.
>
> **Refer to the [Open Feature documentation](https://docs.openfeature.dev/docs/reference/concepts/evaluation-api#basic-evaluation) to know more about it.**

```python
# Context of your flag evaluation.
# With GO Feature Flag you MUST have a targetingKey that is a unique identifier of the user.
evaluation_ctx = EvaluationContext(
    targeting_key="d45e303a-38c2-11ed-a261-0242ac120002",
    attributes={
        "email": "john.doe@gofeatureflag.org",
        "firstname": "john",
        "lastname": "doe",
        "anonymous": False,
        "professional": True,
        "rate": 3.14,
        "age": 30,
        "company_info": {"name": "my_company", "size": 120},
        "labels": ["pro", "beta"],
    },
)

admin_flag = client.get_boolean_value(
    flag_key="flag-only-for-admin",
    default_value=False,
    evaluation_context=evaluation_ctx,
)

if admin_flag:
    # flag "flag-only-for-admin" is true for the user
    pass
else:
    # flag "flag-only-for-admin" is false for the user
    pass
```

## Configuration options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `endpoint` | `str` | _(required)_ | URL of the GO Feature Flag relay proxy |
| `evaluation_type` | `EvaluationType` | `INPROCESS` | Evaluation mode: `INPROCESS` or `REMOTE` |
| `data_collector_base_url` | `str` | `endpoint` | Base URL of the data collector only. Replaces the whole base — scheme, host, port and path prefix. Flag configuration and evaluation keep using `endpoint` |
| `timeout` | `int` | `10000` | Timeout (ms) for flag configuration, remote evaluation and data collection requests. Carried by the HTTP client the provider builds, so a custom `urllib3_pool_manager` replaces it with its own |
| `data_flush_interval` | `int` | `60000` | Interval (ms) to flush usage data to the relay proxy |
| `disable_data_collection` | `bool` | `False` | Set to `True` to disable usage analytics |
| `flag_config_poll_interval_seconds` | `int` | `120` | Polling interval (seconds) for flag configuration _(in-process mode)_ |
| `api_key` | `str` | `None` | API key for authenticated relay proxy requests, sent as `Authorization: Bearer` |
| `exporter_metadata` | `dict` | `{}` | Static metadata attached to evaluation events. Values must be `str`, `bool`, `int` or `float`. The reserved keys `provider` and `openfeature` are always added and win over your values |
| `max_pending_events` | `int` | `10000` | Buffered events that trigger an immediate flush. The buffer holds up to twice this many, above which the oldest are dropped |
| `wasm_file_path` | `str` | `None` | Path to a custom WASM/WASI evaluation binary _(in-process mode, uses bundled binary by default)_ |
| `wasm_pool_size` | `int` | CPU core count | Pool size for concurrent WASM evaluation instances _(in-process mode)_ |
| `evaluation_flag_list` | `list[str]` | `None` | Restrict the fetched flag configuration to these keys. Unset or empty means all flags _(in-process mode)_ |
| `custom_headers` | `dict[str, str]` | `None` | Extra headers on every relay proxy request, for deployments behind a gateway with its own authentication. Applied before the provider's own headers, so a configured `api_key` wins over a custom `Authorization` |
| `log_level` | `str\|int` | `"WARNING"` | Logging level (`"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`). Applied only if your application has not configured the `gofeatureflag_python_provider` logger itself — see [Logging](#logging) |
| `urllib3_pool_manager` | `urllib3.PoolManager` | `None` | Custom HTTP client for flag configuration and data collection. Remote evaluation uses the OFREP client, which builds its own |

Usage analytics are collected only while the provider is running — between `initialize()`
(called for you by `set_provider`) and `shutdown()`. Evaluations outside that window are not
recorded: no flush runs to deliver them, and a buffer left to fill would post to the collector
after `shutdown()` reported it was done. Each such period logs one warning, and the number of
events dropped is reported if the provider is started again.

## Logging

Every module logs through the standard library under the **`gofeatureflag_python_provider`**
logger, with one child logger per module (`gofeatureflag_python_provider.wasm.evaluate_wasm`,
`gofeatureflag_python_provider.services.event_publisher`, and so on). Attach your handler to the
package logger to capture all of it:

```python
import logging

logging.getLogger("gofeatureflag_python_provider").setLevel(logging.INFO)
logging.getLogger("gofeatureflag_python_provider").addHandler(logging.StreamHandler())
```

The provider ships a `NullHandler` on that logger, so it stays silent until your application
configures logging.

Two things worth knowing:

- **`log_level` yields to your configuration.** The provider applies it to the package logger only
  when nothing has set a level there yet, because that level is process-wide state. If you
  configure the logger yourself (directly or through `logging.config.dictConfig`), your setting
  wins. If several providers are created with different `log_level` values, the first one applies.
- **Exceptions raised inside hooks are logged by the OpenFeature SDK**, under its own `openfeature`
  logger, not this one. `log_level` does not affect them — configure `logging.getLogger("openfeature")`
  if you need to see them.

## Conformance

This provider targets version **1.0** of the
[GO Feature Flag Provider Specification](https://gofeatureflag.org/specification/openfeature-provider),
exposed as `gofeatureflag_python_provider.__specification_version__`.

The evaluation engine it is pinned to is recorded in
`gofeatureflag_python_provider/wasm/_wasi_version.txt`, which is the single source of truth
for the bundled WASI binary version.
