Metadata-Version: 2.4
Name: feature-switch-client
Version: 0.2.2
Summary: Async Python client for Feature Switch API
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic<3.0,>=2.7
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"

# feature-switch-client

Асинхронная Python-библиотека для работы с Feature Switch API.

## Установка

```bash
pip install "feature-switch-client==0.2.1"
```

## Использование

Библиотека хранит один клиент на процесс. Настройте её при старте приложения:

```python
from feature_switch_client import feature_flags

feature_flags.configure_from_env()

enabled = await feature_flags.is_enabled("<FEATURE_FLAG_NAME>", default=False)
```

При остановке приложения закройте клиент:

```python
await feature_flags.aclose()
```

Клиент запрашивает только актуальные флаги и использует короткий in-memory cache.
При временной недоступности API возвращается последнее известное значение или
`default`.

## Основные методы

```python
await feature_flags.is_enabled("<FEATURE_FLAG_NAME>", default=False)
await feature_flags.get_flag("<FEATURE_FLAG_NAME>")
await feature_flags.get_flags()
await feature_flags.refresh()
feature_flags.clear_cache()
await feature_flags.aclose()
```

## Переменные окружения

```text
FEATURE_SWITCH_API_URL=<feature-switch-api-url>
FEATURE_SWITCH_SERVICE_NAME=<service-name>
FEATURE_SWITCH_TIMEOUT_SECONDS=2
FEATURE_SWITCH_RETRIES=2
FEATURE_SWITCH_CACHE_TTL_SECONDS=5
```

Обязательные переменные: `FEATURE_SWITCH_API_URL` и
`FEATURE_SWITCH_SERVICE_NAME`. Остальные имеют значения по умолчанию.

Переменные должны быть доступны каждому процессу отдельно: API, worker и другим
процессам приложения. В Docker Compose используйте `env_file` или `environment`,
в Kubernetes — `env` или `envFrom`.

## Поведение при сбое API

1. Если в cache есть свежее значение, используется оно.
2. Если cache устарел, выполняется запрос к API.
3. При успешном ответе cache обновляется.
4. При ошибке используется последнее известное значение.
5. Если значения ещё нет, возвращается `default`.
6. Если `default` не задан, возвращается `False`.

## Низкоуровневый клиент

Если нужен отдельный клиент с настройками:

```python
from feature_switch_client import AsyncFeatureSwitchClient

flags = AsyncFeatureSwitchClient(
    "<feature-switch-api-url>",
    service_name="<service-name>",
)

enabled = await flags.is_enabled("<FEATURE_FLAG_NAME>", default=False)
await flags.aclose()
```
