Metadata-Version: 2.4
Name: gogreen-sdk
Version: 1.0.1
Summary: GoGreen feature flag and experimentation SDK for Python
Author: GoGreen
License: ISC
Project-URL: Homepage, https://github.com/MarkDurbin104/GoGreen
Project-URL: Documentation, https://gogreenflags.com/docs
Project-URL: Repository, https://github.com/MarkDurbin104/GoGreen
Keywords: feature-flags,feature-toggles,experimentation,gogreen
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: openfeature-sdk>=0.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: responses>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"

# GoGreen Python SDK

Official Python SDK for [GoGreen](https://gogreenflags.com) feature flags and experimentation.

## Requirements

- Python 3.10+
- GoGreen evaluation API (e.g. `https://eval.gogreenflags.com`)

## Installation

### From PyPI (when published)

```bash
pip install gogreen-sdk
```

### From source (GitHub)

```bash
pip install git+https://github.com/MarkDurbin104/GoGreen.git#subdirectory=sdk/python
```

Or clone and install in editable mode:

```bash
git clone https://github.com/MarkDurbin104/GoGreen.git
cd GoGreen/sdk/python
pip install -e .
```

## Quick start

```python
from gogreen import GoGreenClient
from gogreen.config import GoGreenConfig

config = GoGreenConfig(
    sdk_key="YOUR_SDK_KEY",
    environment_id="YOUR_ENV_ID",
    default_context={"key": "user-123", "custom": {"plan": "enterprise"}},
    api_base_url="https://eval.gogreenflags.com",
)

client = GoGreenClient(config)
client.wait_for_initialization(timeout=5.0)

# Boolean flag
if client.bool_variation("new-checkout", False):
    show_new_checkout()

# With optional context override
user = {"key": "user-456", "custom": {"country": "US"}}
theme = client.string_variation("ui-theme", "light", context=user)

# Number flag (e.g. for gradual rollouts)
limit = client.number_variation("rate-limit", 100)

# JSON flag
config_value = client.json_variation("feature-config", {})

# Detail (value + variation id, reason, prerequisite_key)
detail = client.bool_variation_detail("new-checkout", False)
print(detail.value, detail.reason, detail.variation_id)

# Track custom events for experimentation
client.track("checkout_completed", {"revenue": 49.99})

client.close()
```

## API reference

### GoGreenConfig

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sdk_key` | str | Yes | SDK key from your GoGreen environment |
| `environment_id` | str | Yes | Environment ID (e.g. UUID) |
| `default_context` | dict | Yes | Default evaluation context; must include `"key"` |
| `api_base_url` | str | No | Evaluation API base URL (default: `http://localhost:8092`) |
| `stream_url` | str | No | Streaming SSE URL (default: same as api_base_url) |
| `events_url` | str | No | Events ingestion URL (default: same as api_base_url) |
| `enable_streaming` | bool | No | Enable real-time flag updates via SSE (default: True) |
| `offline` | bool | No | Start in offline mode (default: False) |
| `bootstrap` | dict | No | Initial flags `{"flags": {flag_key: result}}` to skip first fetch |
| `request_timeout` | float | No | HTTP timeout in seconds (default: 10.0) |
| `flush_interval` | float | No | Event batch flush interval in seconds (default: 30.0) |
| `private_attributes` | list[str] | No | Attribute names to redact in events (PII) |

### GoGreenClient

- **Variations:** `bool_variation`, `string_variation`, `number_variation`, `json_variation`  
  Each has a `*_variation_detail` variant returning `EvaluationDetail` (value, variation_id, reason, rule_index, prerequisite_key).
- **Lifecycle:** `wait_for_initialization(timeout=None)`, `initialized()`, `close()`
- **Context:** `set_context(context)`, `identify(context)`
- **Offline:** `enter_offline_mode()`, `exit_offline_mode()`
- **Events:** `on(event, handler)` / `off(event, handler)` for `"ready"`, `"update"`, `"error"`; `track(event_key, properties=None)`
- **All flags:** `all_flags()` → `dict[str, Any]`
- **Test helper:** `GoGreenClient.test_client(flags: dict)` for unit tests (offline client with fixed flag values).

### OpenFeature provider

```python
from gogreen import GoGreenClient, GoGreenProvider
from gogreen.config import GoGreenConfig
from openfeature import api

config = GoGreenConfig(
    sdk_key="YOUR_SDK_KEY",
    environment_id="YOUR_ENV_ID",
    default_context={"key": "user-123", "custom": {}},
)
client = GoGreenClient(config)
api.set_provider(GoGreenProvider(client))

client = api.get_client()
value = client.get_boolean_value("my-flag", False)
```

## Development

```bash
pip install -e ".[dev]"
ruff check src tests && ruff format src tests
pytest tests/ -v --cov=src/gogreen --cov-report=term-missing --cov-fail-under=80
```

## Publishing (PyPI)

Releases are built and published via GitHub Actions when a tag `sdk/python/vX.Y.Z` is pushed. PyPI Trusted Publishing (OIDC) must be configured once on the PyPI project. See the workflow file `.github/workflows/sdk-python.yml` for setup steps.

## License

ISC
