Metadata-Version: 2.4
Name: featuregate-sdk
Version: 0.1.0
Summary: Official Python SDK for FeatureGate.
Author: FeatureGate
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Project-URL: Homepage, https://featuregate.dev
Project-URL: Documentation, https://featuregate.dev/docs
Project-URL: Repository, https://github.com/featuregate/featuregate-python
Project-URL: Issues, https://github.com/featuregate/featuregate-python/issues
Description-Content-Type: text/markdown

# FeatureGate Python SDK

The official Python SDK for [FeatureGate](https://featuregate.dev), a feature flag platform for
safely controlling releases in applications.

> [!WARNING]
> **Beta status:** All `0.x` releases are unstable. Public APIs may change or be removed without
> deprecation before `1.0.0`. Only the latest `0.x` release is supported.

The SDK currently supports local in-memory evaluation and does not connect to the FeatureGate API
yet.

## Installation

Install the `featuregate-sdk` distribution with your preferred package manager:

```sh
uv add featuregate-sdk
```

Or with pip:

```sh
pip install featuregate-sdk
```

The distribution is named `featuregate-sdk`, while the package used in Python code is named
`featuregate`.

## Quick start

Create a shared `FeatureGate` instance and provide a safe default whenever you evaluate a flag:

```python
from featuregate import FeatureGate

feature_gate = FeatureGate(
    flags={
        "checkout": {
            "default_value": True,
        },
        "heading": {
            "default_value": "Welcome",
        },
    }
)

checkout_enabled = feature_gate.get_boolean_value("checkout", False)
heading = feature_gate.get_string_value("heading", "Default heading")
```

The caller-provided default is returned when the flag is missing or its value is not Boolean.

Use the details getter when you also need to know why FeatureGate returned a value:

```python
details = feature_gate.get_boolean_details("checkout", False)

print(details.value)  # True
print(details.reason)  # environment_default
print(details.used_default)  # False
```

## Development

FeatureGate requires Python 3.11 or newer and uses
[`uv`](https://docs.astral.sh/uv/) for project and dependency management.

Install the project and its development dependencies:

```sh
uv sync
```

Run the quality checks:

```sh
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv build
```

Use `uv run ruff format .` to format the source files.

## Releasing

Releases are published to PyPI from GitHub Actions using trusted publishing. No PyPI password or
API token is stored in the repository.

1. Update and commit the package version with `uv version <version>`.
2. Wait for CI to pass on the release commit.
3. Publish a GitHub Release whose tag and title are `v<version>`, such as `v0.1.0`.
4. Mark `0.x` GitHub Releases as prereleases.
5. Approve the deployment to the protected `pypi` environment.

The release workflow checks that the Git tag matches the package version, rebuilds and tests the
package, and then publishes the wheel and source distribution.

## License

FeatureGate's Python SDK is available under the [MIT License](./LICENSE).
