Metadata-Version: 2.4
Name: gradual-sdk
Version: 0.1.0
Summary: Gradual feature flag SDK for Python
Author-email: Elijah Nikolov <eli@gradual.so>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# Gradual Python SDK

[![CI](https://github.com/elijahnikov/gradual-python/actions/workflows/ci.yml/badge.svg)](https://github.com/elijahnikov/gradual-python/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/gradual-sdk)](https://pypi.org/project/gradual-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/gradual-sdk)](https://pypi.org/project/gradual-sdk/)

The official Python SDK for [Gradual](https://gradual.dev) feature flags.

## Installation

```bash
pip install gradual-sdk
```

## Quick Start

```python
from gradual import create_gradual, GradualOptions

client = create_gradual(GradualOptions(
    api_key="gra_xxx",
    environment="production",
))
client.wait_until_ready()

if client.is_enabled("new-feature"):
    # new code path
    pass

theme = client.get("theme", fallback="dark")

client.identify({"user": {"id": "user-123", "plan": "pro"}})
client.close()
```

## API Reference

- **`create_gradual(options: GradualOptions)`** -- Create and return a new Gradual client instance.
- **`client.wait_until_ready()`** -- Block until the client has fetched its initial flag configuration.
- **`client.is_enabled(flag: str) -> bool`** -- Check whether a boolean feature flag is enabled.
- **`client.get(flag: str, fallback=None)`** -- Get the value of a feature flag, returning `fallback` if the flag is not found.
- **`client.identify(context: dict)`** -- Set the evaluation context (e.g. user attributes) for subsequent flag checks.
- **`client.close()`** -- Shut down the client and release resources.

## Development

Install the package in development mode with test dependencies:

```bash
pip install -e ".[dev]"
```

Run the tests:

```bash
PYTHONPATH=src pytest tests/ -v
```

## License

MIT
