Metadata-Version: 2.4
Name: flagbase-sdk
Version: 0.1.0
Summary: Python SDK for FlagBase — a self-hostable feature flag and A/B testing platform
Project-URL: Homepage, https://github.com/avdheshMANDLOI/flagbase-python-sdk
Project-URL: Repository, https://github.com/avdheshMANDLOI/flagbase-python-sdk
Project-URL: Issues, https://github.com/avdheshMANDLOI/flagbase-python-sdk/issues
Author-email: Avdhesh Mandloi <avdheshmandloi@gmail.com>
License-Expression: MIT
Keywords: a/b testing,feature flags,feature toggles,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

# flagbase-python-sdk

Official Python SDK for [FlagBase](https://github.com/avdheshMANDLOI/Flagbase_Version1) — a self-hostable feature flag and A/B testing platform.

## Installation

```bash
pip install flagbase
```

## Quick Start

```python
from flagbase import FlagClient

client = FlagClient(
    api_key="proj_sk_...",       # Generate in your FlagBase dashboard
    host="http://localhost:8000", # Your FlagBase server URL
)

# Basic flag check
if client.is_enabled("new_checkout_ui", user_id="user_123"):
    show_new_checkout()
else:
    show_old_checkout()

client.close()
```

## Usage

### Initialisation

```python
client = FlagClient(
    api_key="proj_sk_...",   # Required
    host="http://...",        # Required — your FlagBase server URL
    cache_ttl=30,             # Optional — local cache TTL in seconds (default 30)
    timeout=0.5,              # Optional — HTTP timeout in seconds (default 0.5)
    default_value=False,      # Optional — returned if server unreachable (default False)
)
```

### `is_enabled(flag_name, user_id, context=None, default_value=None)`

Returns `True` or `False`. Never raises.

```python
enabled = client.is_enabled("dark_mode", user_id="user_123")

# With targeting context
enabled = client.is_enabled(
    "premium_feature",
    user_id="user_123",
    context={
        "email": "user@example.com",
        "country": "IN",
        "custom_attributes": {"plan": "premium"}
    }
)
```

### `evaluate(flag_name, user_id, context=None)`

Returns an `EvaluationResult` with `enabled`, `variant`, `reason`, and `flag_name`.

```python
result = client.evaluate("new_checkout_ui", user_id="user_123")
print(result.enabled)  # True
print(result.reason)   # "rollout_included"
print(result.variant)  # None (variants available in v4 A/B testing)
```

### `track(event_name, user_id, flag_name, variant=None)`

Track a conversion event. Non-blocking — returns immediately.

```python
client.track(
    event_name="purchase_completed",
    user_id="user_123",
    flag_name="new_checkout_ui",
)
```

### Context manager

```python
with FlagClient(api_key="proj_sk_...", host="http://...") as client:
    enabled = client.is_enabled("my_flag", user_id="user_123")
# client.close() called automatically
```

## Error Handling

The SDK **never raises exceptions** in normal use. All errors are caught internally and `default_value` is returned instead:

| Error | Behaviour |
|-------|-----------|
| Network timeout | Returns `default_value`, logs warning |
| HTTP 401 (bad API key) | Returns `default_value`, logs error |
| Server error (5xx) | Returns `default_value`, logs warning |
| Any unexpected error | Returns `default_value`, logs error |

## Caching

Flag results are cached locally for 30 seconds (configurable via `cache_ttl`). This means:
- Repeated calls to `is_enabled()` for the same flag + user don't hit the network
- Flag changes take up to `cache_ttl` seconds to propagate to the SDK

## Requirements

- Python 3.10+
- httpx >= 0.27.0

## Running the Backend

This SDK requires a running FlagBase server. See the [FlagBase backend repo](https://github.com/avdheshMANDLOI/Flagbase_Version1) for setup instructions.

## License

MIT
