Metadata-Version: 2.4
Name: flagr-sdk
Version: 0.1.7
Summary: Python SDK for Flagr — OpenFeature-compatible
Project-URL: Homepage, https://flagr.dev
Project-URL: Repository, https://gitlab.com/perodriguezl/flagr-sdk-python
Project-URL: Documentation, https://flagr.dev/docs
Author-email: Flagr <hello@flagr.dev>
License: MIT
Keywords: feature-flags,flagr,openfeature
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.27
Requires-Dist: openfeature-sdk>=0.7
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# flagr-sdk

Python SDK for [Flagr](https://flagr.dev) — OpenFeature-compatible feature flag client.

Connects to the Flagr Evaluation API via SSE, seeds a local in-memory cache from the initial snapshot, and applies real-time updates as flags change. Every flag evaluation is fully local — no network call per check.

## Prerequisites

- Python >= 3.9
- An active Flagr account and an SDK key (`sdk_live_...`) from the [dashboard](https://flagr.dev)

## Install

```bash
pip install flagr-sdk
```

## Quickstart

```python
from flagr import FlagrProvider

provider = FlagrProvider(sdk_key="sdk_live_xxx")

# One-shot evaluation
enabled = provider.is_enabled("new-checkout", tenant_id="user-123")

# Reactive — callback fires immediately and on every flag change.
# .wait() blocks until Ctrl+C, then unsubscribes automatically.
provider.on_change(
    "new-checkout",
    tenant_id="user-123",
    callback=lambda enabled: print(f"new-checkout is now {enabled}"),
).wait()

# Or keep a reference to unsubscribe manually
sub = provider.on_change("new-checkout", tenant_id="user-123", callback=my_callback)
sub.unsubscribe()
```

`tenant_id` is any entity identifier in your product — user ID, org ID, account ID, etc.

## OpenFeature

If you use the [OpenFeature](https://openfeature.dev) standard, `FlagrProvider` is fully compatible:

```python
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from flagr import FlagrProvider

api.set_provider(FlagrProvider(sdk_key="sdk_live_xxx"))
client = api.get_client()

enabled = client.get_boolean_value(
    "new-checkout",
    default_value=False,
    evaluation_context=EvaluationContext(targeting_key="a1b2c3d4-e5f6-7890-abcd-ef1234567890"),
)
```

## Running locally

```bash
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install the package with dev dependencies
pip install -e ".[dev]"
```

## Running tests

```bash
# Unit tests (no server required)
pytest tests/test_provider.py -v

# Integration tests (requires a running Flagr API + valid SDK key)
FLAGR_SDK_KEY=sdk_live_xxx FLAGR_BASE_URL=http://localhost:8080 pytest tests/test_integration.py -v

# Run all tests
pytest -v

# Type-check
mypy src/

# Lint
ruff check src/ tests/
```

## Releasing a new version

Releases are fully automated via GitLab CI using PyPI's OIDC trusted publishing — no API token required.

1. Bump the version in `pyproject.toml`:
   ```toml
   [project]
   version = "0.1.4"
   ```

2. Commit, tag, and push:
   ```bash
   git add pyproject.toml
   git commit -m "bump version to 0.1.4"
   git tag v0.1.4
   git push origin v0.1.4
   ```

   The tag must match the pattern `v*`.

3. GitLab CI runs `.gitlab-ci.yml`, builds with `hatch`, and publishes to PyPI via trusted publishing. No credentials needed locally.

> **PyPI setup (one-time):** The PyPI project must have trusted publishing configured for the GitLab repository and the `pypi` GitLab CI/CD environment. See [PyPI trusted publishing docs](https://docs.pypi.org/trusted-publishers/).
