# Indie Flags — Python SDK

Feature flags for [Indie Flags](https://indieflags.dev). `is_enabled`, `get_value`, optional 60s cache. **Python 3.9+**, stdlib only (no extra dependencies).

## Install

```bash
pip install indie-flags
```

## Get your API key

In the [Indie Flags dashboard](https://app.indieflags.dev), open your project → **API Keys**. Copy the **client key** (`if_pub_...`).

## Usage

### Init (recommended)

```python
from indie_flags import IndieFlags

flags = IndieFlags(
    api_key="if_pub_xxxxxxxx",
    # base_url="https://your-api.com",  # optional, self-hosted
    # email="user@example.com",          # optional, for overrides
)
flags.init()

if flags.is_enabled("new-checkout"):
    # show new checkout
else:
    # show old checkout

theme = flags.get_value("theme")  # "dark" | "light" | "system"
```

### Without init

```python
flags = IndieFlags(api_key="if_pub_xxxxxxxx")
on = flags.is_enabled("new-feature")
value = flags.get_value("ab-test-variant")
```

### Options

| Option           | Type  | Description                                      |
| ---------------- | ----- | ------------------------------------------------ |
| `api_key`        | str   | **Required.** Project API key from dashboard.   |
| `base_url`       | str   | API base URL. Default `https://api.indieflags.dev`. |
| `env`            | str   | Environment (e.g. `"production"`, `"staging"`).  |
| `email`          | str   | User email for flag overrides.                   |
| `cache_ttl_sec`  | int   | Cache TTL after `init()`. Default 60. Set 0 to disable. |

### Methods

- **`init()`** — Fetch all flags and cache. Call once at startup.
- **`is_enabled(flag_key: str) -> bool`** — Whether the flag is on.
- **`get_value(flag_key: str) -> bool | str`** — Flag value (bool or str for enums).
- **`invalidate_cache()`** — Clear cache.

## API

Uses `GET /eval` and `GET /eval/flags`. See the [REST API docs](https://indieflags.dev/docs) for direct HTTP usage.

## Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## Publishing to PyPI (maintainers)

1. **Create an API token on PyPI**  
   [pypi.org](https://pypi.org) → Account settings → API tokens → Add API token (scope: “Entire account” or limit to project `indie-flags`).

2. **Bump version** in `pyproject.toml` (e.g. `0.1.0` → `0.1.1`).

3. **Build and upload** (from `sdk-python/`):

   ```bash
   python3 -m venv .venv && source .venv/bin/activate   # once
   pip install build twine
   python -m build
   twine upload dist/*
   ```

   On macOS/Homebrew, use a venv (as above); `pip` may not be available system-wide.

4. When Twine asks for credentials:
   - **Username:** `__token__`
   - **Password:** your PyPI API token (starts with `pypi-`).

   Or set once and reuse:  
   `export TWINE_USERNAME=__token__` and `export TWINE_PASSWORD=pypi-...`
