# Liteguard Python SDK

[![Python SDK](https://github.com/liteguard/liteguard/actions/workflows/test-python.yml/badge.svg)](https://github.com/liteguard/liteguard/actions/workflows/test-python.yml)
[![PyPI](https://img.shields.io/pypi/v/liteguard)](https://pypi.org/project/liteguard/)

- Website: [liteguard.io](https://liteguard.io)
- Project Page: [https://github.com/liteguard/liteguard](https://github.com/liteguard/liteguard)
- Issues: [https://github.com/liteguard/liteguard/issues/new](https://github.com/liteguard/liteguard/issues/new)

## Installation

```bash
pip install liteguard
```

Requires Python 3.9+.

## Quick Start

```python
from liteguard import ClientOptions, LiteguardClient

client = LiteguardClient(
    "pct-...",
    ClientOptions(environment="env-production"),
)
client.start()

scope = client.create_scope({"user_id": "user-123", "plan": "pro"})

if scope.is_open("payments.checkout"):
    ...

client.shutdown()
```

## Primary API

- `LiteguardClient(project_client_token, options)` creates a client.
- `client.start()` fetches the initial bundle and starts refresh and flush workers.
- `client.create_scope(properties=None)` creates an immutable request scope.
- `scope.is_open(name, options=None)` evaluates a guard locally.
- `scope.execute_if_open(name, fn, options=None)` measures guarded execution.
- `scope.bind_protected_context(protected_context)` returns a derived protected scope.
- `client.flush_signals()` flushes buffered telemetry.
- `client.shutdown()` flushes and stops background workers.

## Notes

- Guard evaluation is fully local after the initial fetch.
- Scopes are immutable and request-scoped.
- `contextvars` keep overlapping async request scopes isolated.
- Unadopted guards default open and emit no signals.

## Development

```bash
make test-python
```

## License

Apache 2.0 see [LICENSE](https://github.com/liteguard/liteguard/blob/main/LICENSE).
