Metadata-Version: 2.4
Name: flagr-sdk
Version: 0.1.3
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 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,
    # targeting_key maps to tenant_id — use a user ID, org ID, account ID, or any entity identifier
    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 GitHub Actions using PyPI's OIDC trusted publishing — no API token required.

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

2. Commit and push the version bump, then create and push the tag:
   ```bash
   git add pyproject.toml
   git commit -m "chore: bump sdk-python to v0.1.1"
   git tag sdk-python/v0.1.1
   git push origin sdk-python/v0.1.1
   ```

   The tag must match the pattern `sdk-python/v*`.

3. GitHub Actions runs `.github/workflows/publish.yml`, which builds the distributions with `hatch` and publishes them to PyPI via trusted publishing. No credentials needed locally.

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