greenflags 0.1.0__tar.gz

greenflags-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+.pytest_cache/

greenflags-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Format based on [Keep a Changelog](https://keepachangelog.com/). Versioning: [SemVer](https://semver.org/) (while in `0.x`, a MINOR release may include breaking changes; strict semver applies from `1.0.0` onward).
+
+## [0.1.0] - 2026-07-10
+
+### Added
+- Initial release, mirroring `@greenflags/client` 0.2.x semantics in pure Python (3.9+, zero dependencies, `py.typed`).
+- `GreenFlagsClient` with `refresh`, `get_snapshot`, `get_all_flags`, `get_flag` (with `default`), `is_enabled`, `subscribe`, `start_polling`/`stop_polling` (daemon thread, fail-open), `set_coordinates`.
+- Thread-safe snapshot access (RLock) for multi-worker servers.
+- Client-side geofence evaluation (haversine): outside the radius a `boolean` flag evaluates to `False`, other types to `None`. Every read path goes through evaluation — the raw snapshot is never exposed.
+- Typed `GreenFlagsError` with API error `code`, `message` and HTTP `status` (`NETWORK_ERROR`/`PARSE_ERROR` client-side).
+- Injectable `http_get` transport (default: stdlib `urllib`), auth via `Authorization: Bearer` against `GET /v1/flags`.

greenflags-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GreenFlags
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

greenflags-0.1.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: greenflags
+Version: 0.1.0
+Summary: Python SDK for GreenFlags feature flags: snapshot + cache reads, polling, geofence evaluation. Zero dependencies.
+Project-URL: Homepage, https://greenflags.dev
+Project-URL: Documentation, https://greenflags.dev/docs/
+Project-URL: Repository, https://github.com/greenflags-dev/greenflags-python
+Project-URL: Changelog, https://github.com/greenflags-dev/greenflags-python/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 GreenFlags
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: feature-flags,feature-toggles,greenflags
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# greenflags
+
+Official Python SDK for consuming **GreenFlags feature flags** from any Python service: Django, FastAPI, Flask, Celery workers, scripts, or anything else that runs Python 3.9+.
+
+**Zero dependencies** — standard library only. Built to minimize billable requests: one network call fetches the whole environment; every read after that is served from memory. Thread-safe by design for multi-worker servers.
+
+> **Status:** `0.1.0`, published on PyPI. Full changelog in [`CHANGELOG.md`](./CHANGELOG.md).
+
+```sh
+pip install greenflags
+```
+
+---
+
+## Table of Contents
+
+- [Why it exists](#why-it-exists)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Usage Guide](#usage-guide)
+- [API Reference](#api-reference)
+- [Geofence](#geofence)
+- [Types](#types)
+- [Error Handling](#error-handling)
+- [Billing Model](#billing-model)
+- [Handling the `api_token`](#handling-the-api_token)
+- [Framework Recipes](#framework-recipes)
+- [Development](#development)
+- [Versioning](#versioning)
+
+---
+
+## Why it exists
+
+GreenFlags exposes a read endpoint (`GET /v1/flags`) where **every 2xx response counts as a billable read**. A naive integration that fetches a flag on every request handler, or on every conditional check, can generate thousands of unnecessary requests and burn through your quota for no reason.
+
+`greenflags` solves this with a **snapshot + cache** model:
+
+1. One call (`refresh()`) fetches **every** flag in the `project + environment` tied to your API token.
+2. That response is stored in memory.
+3. Every read after that (`get_flag`, `is_enabled`, `get_all_flags`, `get_snapshot`) is local — **zero additional requests**.
+
+There is intentionally no method to fetch a single flag over the network — that would break the billing model.
+
+## Features
+
+- ✅ Zero dependencies — `urllib` from the standard library, nothing else.
+- ✅ Snapshot + in-memory cache — billing-safe by design.
+- ✅ Thread-safe — one client instance can be shared across WSGI/ASGI workers and threads.
+- ✅ Opt-in polling (`start_polling`) on a daemon thread — you decide if and how often it refreshes.
+- ✅ Fail-open — if the network fails, your app keeps working with the last good snapshot (or the `default` you set).
+- ✅ Client-side geofence evaluation — the end-user's location never leaves your process.
+- ✅ Fully typed (`py.typed`) — mypy/pyright friendly.
+- ✅ Injectable HTTP layer — trivial to mock in tests, or to swap for `requests`/`httpx` if you prefer.
+
+## Requirements
+
+- **Python 3.9+**.
+- A GreenFlags **API token**, generated from the [dashboard](https://app.greenflags.dev) for a specific `project + environment`. The token determines which flags the SDK sees — there's no separate `project`/`environment` to pass. See the [API docs](https://greenflags.dev/docs/) for the full contract.
+
+## Quick Start
+
+```python
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(
+    url="https://app.greenflags.dev",
+    api_token="gf_your_token_here",
+)
+
+flags.refresh()  # 1 billable request — fetches the whole environment
+
+if flags.is_enabled("new-checkout"):
+    ...
+```
+
+## Usage Guide
+
+```python
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(url="https://app.greenflags.dev", api_token="gf_...")
+
+# 1. Fetch the initial snapshot (required before reading real flag values)
+flags.refresh()
+
+# 2. Read flags — always from memory, never hits the network
+enabled = flags.is_enabled("my-feature")                 # bool sugar
+theme = flags.get_flag("theme", default="light")         # str
+limit = flags.get_flag("rate-limit", default=100)        # number
+config = flags.get_flag("config", default={})            # json/dict
+
+# 3. List everything available
+all_flags = flags.get_all_flags()      # list[Flag]
+snapshot = flags.get_snapshot()        # dict[str, Flag]
+
+# 4. Subscribe to updates (fires on every successful refresh())
+unsubscribe = flags.subscribe(lambda snapshot: print("flags updated"))
+
+# 5. Opt-in polling — without this, the SDK NEVER fetches data on its own
+flags.start_polling(60)  # seconds; every tick = 1 billable request
+
+# 6. Stop polling (the in-memory snapshot is preserved)
+flags.stop_polling()
+unsubscribe()
+```
+
+### Ground rules
+
+- `get_flag` / `is_enabled` **never raise for missing flags** — `get_flag` returns your `default` and `is_enabled` returns `False` until data arrives or when the key doesn't exist.
+- `refresh()` **can raise** `GreenFlagsError` (network error, invalid token, quota exceeded) — wrap it in `try/except` if you want to log failures. The previous snapshot is kept either way.
+- Create **one client per process** and share it — don't build a client (or call `refresh()`) per request. Refresh once at startup and use `start_polling` only if you need near-live data.
+- Polling runs on a daemon thread: it never blocks interpreter shutdown, and a failed tick doesn't break the next one.
+
+## API Reference
+
+### `GreenFlagsClient(...)`
+
+```python
+GreenFlagsClient(
+    url: str,                          # API base URL, trailing slash optional
+    api_token: str,                    # token for the environment you're consuming
+    coordinates: Coordinates | None = None,  # optional — enables geofence evaluation
+    http_get = ...,                    # optional — inject the HTTP layer: (url, headers) -> (status, body)
+)
+```
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `refresh` | `() -> None` | 1 request to `GET /v1/flags`. Replaces the snapshot and notifies subscribers. Raises `GreenFlagsError` on network/API error. |
+| `get_snapshot` | `() -> dict[str, Flag]` | Copy of the current snapshot, keyed by flag key, geofence-evaluated (see [Geofence](#geofence)). |
+| `get_all_flags` | `() -> list[Flag]` | Every flag in the current snapshot, geofence-evaluated. |
+| `get_flag` | `(key, default=None) -> FlagValue` | Evaluated value of one flag. Fail-open: returns `default` if missing. |
+| `is_enabled` | `(key) -> bool` | `True` only when the flag exists and currently evaluates to `True`. |
+| `subscribe` | `(listener) -> unsubscribe` | `listener(snapshot)` runs after every successful `refresh()`. Returns an unsubscribe callable. |
+| `start_polling` | `(interval_seconds) -> None` | Automatic `refresh()` on a daemon thread. Opt-in — no default. Fail-open. |
+| `stop_polling` | `() -> None` | Stops polling. The in-memory snapshot is preserved. |
+| `set_coordinates` | `(Coordinates \| None) -> None` | Sets or clears the end-user location used for geofence evaluation. No network request. |
+
+## Geofence
+
+Some flags can carry an optional geofence — a `latitude/longitude/radius` target configured in the dashboard. When the SDK has coordinates (constructor or `set_coordinates`), it evaluates each geofenced flag **locally** — coordinates are never sent to the server:
+
+- **Inside the radius** (on-edge counts as inside): the flag's normal value is returned.
+- **Outside the radius**: the flag returns its off value — `False` for `boolean` flags, `None` for `string`/`number`/`json` flags.
+- **No coordinates supplied, or no geofence on the flag**: the flag's normal value is returned, unaffected.
+
+> **Fail-open, by design:** a geofence is not a security boundary — any caller that omits coordinates sees the flag's normal value regardless of location.
+
+```python
+from greenflags import Coordinates
+
+flags.set_coordinates(Coordinates(latitude=19.4326, longitude=-99.1332))
+flags.is_enabled("store-promo")   # evaluated against the geofence, if any
+flags.set_coordinates(None)        # back to "ignore geofence" for every flag
+```
+
+## Types
+
+```python
+FlagType = Literal["boolean", "string", "number", "json"]
+FlagValue = bool | str | int | float | dict | None  # None: geofenced-off for non-boolean
+
+@dataclass(frozen=True)
+class Coordinates:
+    latitude: float
+    longitude: float
+
+@dataclass(frozen=True)
+class Flag:
+    key: str
+    type: FlagType
+    value: FlagValue
+    geofence: Geofence | None
+
+class GreenFlagsError(Exception):
+    code: str      # API error code, or NETWORK_ERROR / PARSE_ERROR
+    message: str
+    status: int    # HTTP status; 0 for network failures
+```
+
+These types mirror the backend contract (`GET /v1/flags`) exactly.
+
+## Error Handling
+
+```python
+from greenflags import GreenFlagsError
+
+try:
+    flags.refresh()
+except GreenFlagsError as err:
+    print(err.code, err.status, err.message)
+```
+
+Codes that `GET /v1/flags` can actually return:
+
+| `err.code` | `err.status` | Cause |
+|---|---|---|
+| `INVALID_TOKEN` | 401 | Token missing, invalid, or revoked |
+| `QUOTA_EXCEEDED` | 429 | Monthly read quota exhausted |
+| `BILLING_NO_SUBSCRIPTION` | 429 | The workspace has no active subscription |
+| `BILLING_CANCELED` | 429 | Subscription canceled |
+| `BILLING_PAST_DUE` | 429 | Payment past due |
+| `BILLING_TRIAL_EXPIRED` | 429 | Trial expired |
+| `BILLING_LIMIT_REACHED` | 429 | Billing limit reached |
+| `NETWORK_ERROR` | 0 | The request failed before a response was received |
+| `PARSE_ERROR` | response status | Body wasn't valid JSON, or was missing `data.flags` |
+| `REQUEST_ERROR` | response status | Non-2xx response with no parseable error code |
+
+`get_flag()`, `is_enabled()`, `get_all_flags()` and `get_snapshot()` **never** raise any of these — they're always local reads.
+
+## Billing Model
+
+Every call to `refresh()` (manual or from `start_polling`) is **exactly one HTTP request**, and every 2xx response counts as one billable read. All flag reads are 100% in memory — **zero requests**, no matter how many times you call them.
+
+Recommendation: `refresh()` once at process startup, then `start_polling(60)` or more if you need periodic updates. With N workers each running its own poller, remember you pay N reads per tick — prefer fewer, longer-lived clients.
+
+## Handling the `api_token`
+
+The token is a secret — treat it like a database password:
+
+- **Never hardcode it.** Read it from the environment: `os.environ["GREENFLAGS_API_TOKEN"]`.
+- Keep it out of version control (`.env` + `.gitignore`; ship a `.env.example` without values).
+- Python services run server-side, so the mobile-extraction concern doesn't apply — but per-token **monthly quotas** (dashboard → API Tokens) are still a good blast-radius cap for leaked CI logs or misconfigured staging.
+
+```python
+import os
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(
+    url=os.environ.get("GREENFLAGS_URL", "https://app.greenflags.dev"),
+    api_token=os.environ["GREENFLAGS_API_TOKEN"],
+)
+```
+
+## Framework Recipes
+
+**FastAPI** — refresh at startup, poll in the background, read anywhere:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    flags.refresh()
+    flags.start_polling(60)
+    yield
+    flags.stop_polling()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/checkout")
+def checkout():
+    if flags.is_enabled("new-checkout"):
+        ...
+```
+
+**Django** — call `flags.refresh()` in `AppConfig.ready()` and share the module-level client. **Celery** — same client per worker process; refresh in `worker_process_init`.
+
+## Development
+
+```sh
+cd sdks/python
+PYTHONPATH=src python3 -m pytest   # 12 tests, mocked HTTP — no real network
+```
+
+Tests cover envelope parsing, error mapping, geofence evaluation, fail-open behavior, subscriptions, and polling.
+
+## Versioning
+
+Semver, while in `0.x`: `MINOR` can include API changes (no stability guarantee yet), `PATCH` are fixes. Version-by-version detail in [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Related
+
+- [API reference](https://greenflags.dev/docs/)
+- [`@greenflags/client`](https://www.npmjs.com/package/@greenflags/client) — JavaScript/TypeScript SDK
+- [`@greenflags/react`](https://www.npmjs.com/package/@greenflags/react) — React hooks
+- [`greenflags`](https://pub.dev/packages/greenflags) — Dart/Flutter SDK
+- [`@greenflags/mcp`](https://www.npmjs.com/package/@greenflags/mcp) — MCP server for AI agents

greenflags-0.1.0/README.md

@@ -0,0 +1,283 @@
+# greenflags
+
+Official Python SDK for consuming **GreenFlags feature flags** from any Python service: Django, FastAPI, Flask, Celery workers, scripts, or anything else that runs Python 3.9+.
+
+**Zero dependencies** — standard library only. Built to minimize billable requests: one network call fetches the whole environment; every read after that is served from memory. Thread-safe by design for multi-worker servers.
+
+> **Status:** `0.1.0`, published on PyPI. Full changelog in [`CHANGELOG.md`](./CHANGELOG.md).
+
+```sh
+pip install greenflags
+```
+
+---
+
+## Table of Contents
+
+- [Why it exists](#why-it-exists)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Usage Guide](#usage-guide)
+- [API Reference](#api-reference)
+- [Geofence](#geofence)
+- [Types](#types)
+- [Error Handling](#error-handling)
+- [Billing Model](#billing-model)
+- [Handling the `api_token`](#handling-the-api_token)
+- [Framework Recipes](#framework-recipes)
+- [Development](#development)
+- [Versioning](#versioning)
+
+---
+
+## Why it exists
+
+GreenFlags exposes a read endpoint (`GET /v1/flags`) where **every 2xx response counts as a billable read**. A naive integration that fetches a flag on every request handler, or on every conditional check, can generate thousands of unnecessary requests and burn through your quota for no reason.
+
+`greenflags` solves this with a **snapshot + cache** model:
+
+1. One call (`refresh()`) fetches **every** flag in the `project + environment` tied to your API token.
+2. That response is stored in memory.
+3. Every read after that (`get_flag`, `is_enabled`, `get_all_flags`, `get_snapshot`) is local — **zero additional requests**.
+
+There is intentionally no method to fetch a single flag over the network — that would break the billing model.
+
+## Features
+
+- ✅ Zero dependencies — `urllib` from the standard library, nothing else.
+- ✅ Snapshot + in-memory cache — billing-safe by design.
+- ✅ Thread-safe — one client instance can be shared across WSGI/ASGI workers and threads.
+- ✅ Opt-in polling (`start_polling`) on a daemon thread — you decide if and how often it refreshes.
+- ✅ Fail-open — if the network fails, your app keeps working with the last good snapshot (or the `default` you set).
+- ✅ Client-side geofence evaluation — the end-user's location never leaves your process.
+- ✅ Fully typed (`py.typed`) — mypy/pyright friendly.
+- ✅ Injectable HTTP layer — trivial to mock in tests, or to swap for `requests`/`httpx` if you prefer.
+
+## Requirements
+
+- **Python 3.9+**.
+- A GreenFlags **API token**, generated from the [dashboard](https://app.greenflags.dev) for a specific `project + environment`. The token determines which flags the SDK sees — there's no separate `project`/`environment` to pass. See the [API docs](https://greenflags.dev/docs/) for the full contract.
+
+## Quick Start
+
+```python
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(
+    url="https://app.greenflags.dev",
+    api_token="gf_your_token_here",
+)
+
+flags.refresh()  # 1 billable request — fetches the whole environment
+
+if flags.is_enabled("new-checkout"):
+    ...
+```
+
+## Usage Guide
+
+```python
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(url="https://app.greenflags.dev", api_token="gf_...")
+
+# 1. Fetch the initial snapshot (required before reading real flag values)
+flags.refresh()
+
+# 2. Read flags — always from memory, never hits the network
+enabled = flags.is_enabled("my-feature")                 # bool sugar
+theme = flags.get_flag("theme", default="light")         # str
+limit = flags.get_flag("rate-limit", default=100)        # number
+config = flags.get_flag("config", default={})            # json/dict
+
+# 3. List everything available
+all_flags = flags.get_all_flags()      # list[Flag]
+snapshot = flags.get_snapshot()        # dict[str, Flag]
+
+# 4. Subscribe to updates (fires on every successful refresh())
+unsubscribe = flags.subscribe(lambda snapshot: print("flags updated"))
+
+# 5. Opt-in polling — without this, the SDK NEVER fetches data on its own
+flags.start_polling(60)  # seconds; every tick = 1 billable request
+
+# 6. Stop polling (the in-memory snapshot is preserved)
+flags.stop_polling()
+unsubscribe()
+```
+
+### Ground rules
+
+- `get_flag` / `is_enabled` **never raise for missing flags** — `get_flag` returns your `default` and `is_enabled` returns `False` until data arrives or when the key doesn't exist.
+- `refresh()` **can raise** `GreenFlagsError` (network error, invalid token, quota exceeded) — wrap it in `try/except` if you want to log failures. The previous snapshot is kept either way.
+- Create **one client per process** and share it — don't build a client (or call `refresh()`) per request. Refresh once at startup and use `start_polling` only if you need near-live data.
+- Polling runs on a daemon thread: it never blocks interpreter shutdown, and a failed tick doesn't break the next one.
+
+## API Reference
+
+### `GreenFlagsClient(...)`
+
+```python
+GreenFlagsClient(
+    url: str,                          # API base URL, trailing slash optional
+    api_token: str,                    # token for the environment you're consuming
+    coordinates: Coordinates | None = None,  # optional — enables geofence evaluation
+    http_get = ...,                    # optional — inject the HTTP layer: (url, headers) -> (status, body)
+)
+```
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `refresh` | `() -> None` | 1 request to `GET /v1/flags`. Replaces the snapshot and notifies subscribers. Raises `GreenFlagsError` on network/API error. |
+| `get_snapshot` | `() -> dict[str, Flag]` | Copy of the current snapshot, keyed by flag key, geofence-evaluated (see [Geofence](#geofence)). |
+| `get_all_flags` | `() -> list[Flag]` | Every flag in the current snapshot, geofence-evaluated. |
+| `get_flag` | `(key, default=None) -> FlagValue` | Evaluated value of one flag. Fail-open: returns `default` if missing. |
+| `is_enabled` | `(key) -> bool` | `True` only when the flag exists and currently evaluates to `True`. |
+| `subscribe` | `(listener) -> unsubscribe` | `listener(snapshot)` runs after every successful `refresh()`. Returns an unsubscribe callable. |
+| `start_polling` | `(interval_seconds) -> None` | Automatic `refresh()` on a daemon thread. Opt-in — no default. Fail-open. |
+| `stop_polling` | `() -> None` | Stops polling. The in-memory snapshot is preserved. |
+| `set_coordinates` | `(Coordinates \| None) -> None` | Sets or clears the end-user location used for geofence evaluation. No network request. |
+
+## Geofence
+
+Some flags can carry an optional geofence — a `latitude/longitude/radius` target configured in the dashboard. When the SDK has coordinates (constructor or `set_coordinates`), it evaluates each geofenced flag **locally** — coordinates are never sent to the server:
+
+- **Inside the radius** (on-edge counts as inside): the flag's normal value is returned.
+- **Outside the radius**: the flag returns its off value — `False` for `boolean` flags, `None` for `string`/`number`/`json` flags.
+- **No coordinates supplied, or no geofence on the flag**: the flag's normal value is returned, unaffected.
+
+> **Fail-open, by design:** a geofence is not a security boundary — any caller that omits coordinates sees the flag's normal value regardless of location.
+
+```python
+from greenflags import Coordinates
+
+flags.set_coordinates(Coordinates(latitude=19.4326, longitude=-99.1332))
+flags.is_enabled("store-promo")   # evaluated against the geofence, if any
+flags.set_coordinates(None)        # back to "ignore geofence" for every flag
+```
+
+## Types
+
+```python
+FlagType = Literal["boolean", "string", "number", "json"]
+FlagValue = bool | str | int | float | dict | None  # None: geofenced-off for non-boolean
+
+@dataclass(frozen=True)
+class Coordinates:
+    latitude: float
+    longitude: float
+
+@dataclass(frozen=True)
+class Flag:
+    key: str
+    type: FlagType
+    value: FlagValue
+    geofence: Geofence | None
+
+class GreenFlagsError(Exception):
+    code: str      # API error code, or NETWORK_ERROR / PARSE_ERROR
+    message: str
+    status: int    # HTTP status; 0 for network failures
+```
+
+These types mirror the backend contract (`GET /v1/flags`) exactly.
+
+## Error Handling
+
+```python
+from greenflags import GreenFlagsError
+
+try:
+    flags.refresh()
+except GreenFlagsError as err:
+    print(err.code, err.status, err.message)
+```
+
+Codes that `GET /v1/flags` can actually return:
+
+| `err.code` | `err.status` | Cause |
+|---|---|---|
+| `INVALID_TOKEN` | 401 | Token missing, invalid, or revoked |
+| `QUOTA_EXCEEDED` | 429 | Monthly read quota exhausted |
+| `BILLING_NO_SUBSCRIPTION` | 429 | The workspace has no active subscription |
+| `BILLING_CANCELED` | 429 | Subscription canceled |
+| `BILLING_PAST_DUE` | 429 | Payment past due |
+| `BILLING_TRIAL_EXPIRED` | 429 | Trial expired |
+| `BILLING_LIMIT_REACHED` | 429 | Billing limit reached |
+| `NETWORK_ERROR` | 0 | The request failed before a response was received |
+| `PARSE_ERROR` | response status | Body wasn't valid JSON, or was missing `data.flags` |
+| `REQUEST_ERROR` | response status | Non-2xx response with no parseable error code |
+
+`get_flag()`, `is_enabled()`, `get_all_flags()` and `get_snapshot()` **never** raise any of these — they're always local reads.
+
+## Billing Model
+
+Every call to `refresh()` (manual or from `start_polling`) is **exactly one HTTP request**, and every 2xx response counts as one billable read. All flag reads are 100% in memory — **zero requests**, no matter how many times you call them.
+
+Recommendation: `refresh()` once at process startup, then `start_polling(60)` or more if you need periodic updates. With N workers each running its own poller, remember you pay N reads per tick — prefer fewer, longer-lived clients.
+
+## Handling the `api_token`
+
+The token is a secret — treat it like a database password:
+
+- **Never hardcode it.** Read it from the environment: `os.environ["GREENFLAGS_API_TOKEN"]`.
+- Keep it out of version control (`.env` + `.gitignore`; ship a `.env.example` without values).
+- Python services run server-side, so the mobile-extraction concern doesn't apply — but per-token **monthly quotas** (dashboard → API Tokens) are still a good blast-radius cap for leaked CI logs or misconfigured staging.
+
+```python
+import os
+from greenflags import GreenFlagsClient
+
+flags = GreenFlagsClient(
+    url=os.environ.get("GREENFLAGS_URL", "https://app.greenflags.dev"),
+    api_token=os.environ["GREENFLAGS_API_TOKEN"],
+)
+```
+
+## Framework Recipes
+
+**FastAPI** — refresh at startup, poll in the background, read anywhere:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    flags.refresh()
+    flags.start_polling(60)
+    yield
+    flags.stop_polling()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/checkout")
+def checkout():
+    if flags.is_enabled("new-checkout"):
+        ...
+```
+
+**Django** — call `flags.refresh()` in `AppConfig.ready()` and share the module-level client. **Celery** — same client per worker process; refresh in `worker_process_init`.
+
+## Development
+
+```sh
+cd sdks/python
+PYTHONPATH=src python3 -m pytest   # 12 tests, mocked HTTP — no real network
+```
+
+Tests cover envelope parsing, error mapping, geofence evaluation, fail-open behavior, subscriptions, and polling.
+
+## Versioning
+
+Semver, while in `0.x`: `MINOR` can include API changes (no stability guarantee yet), `PATCH` are fixes. Version-by-version detail in [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Related
+
+- [API reference](https://greenflags.dev/docs/)
+- [`@greenflags/client`](https://www.npmjs.com/package/@greenflags/client) — JavaScript/TypeScript SDK
+- [`@greenflags/react`](https://www.npmjs.com/package/@greenflags/react) — React hooks
+- [`greenflags`](https://pub.dev/packages/greenflags) — Dart/Flutter SDK
+- [`@greenflags/mcp`](https://www.npmjs.com/package/@greenflags/mcp) — MCP server for AI agents

greenflags-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "greenflags"
+version = "0.1.0"
+description = "Python SDK for GreenFlags feature flags: snapshot + cache reads, polling, geofence evaluation. Zero dependencies."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+keywords = ["feature-flags", "feature-toggles", "greenflags"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://greenflags.dev"
+Documentation = "https://greenflags.dev/docs/"
+Repository = "https://github.com/greenflags-dev/greenflags-python"
+Changelog = "https://github.com/greenflags-dev/greenflags-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/greenflags"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

greenflags-0.1.0/src/greenflags/__init__.py

@@ -0,0 +1,19 @@
+"""GreenFlags — feature flags evaluated at the edge.
+
+See https://greenflags.dev/docs/ for the API reference.
+"""
+
+from .client import GreenFlagsClient
+from .types import Coordinates, Flag, FlagType, FlagValue, Geofence, GreenFlagsError
+
+__all__ = [
+    "Coordinates",
+    "Flag",
+    "FlagType",
+    "FlagValue",
+    "Geofence",
+    "GreenFlagsClient",
+    "GreenFlagsError",
+]
+
+__version__ = "0.1.0"

greenflags-0.1.0/src/greenflags/client.py

@@ -0,0 +1,158 @@
+"""GreenFlags client: snapshot + cache reads over GET /v1/flags.
+
+Thread-safe: reads and refreshes may happen from different threads (WSGI
+workers, background pollers). Every read path goes through geofence
+evaluation — the raw cached snapshot is never exposed.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, Dict, List, Optional
+
+from .geo import haversine_meters
+from .transport import HttpGet, _default_http_get, request_flags
+from .types import Coordinates, Flag, FlagValue
+
+Listener = Callable[[Dict[str, Flag]], None]
+
+
+class GreenFlagsClient:
+    """Client for the GreenFlags read API.
+
+    >>> flags = GreenFlagsClient(url="https://app.greenflags.dev", api_token="gf_...")
+    >>> flags.refresh()
+    >>> if flags.is_enabled("new-checkout"):
+    ...     ...
+    """
+
+    def __init__(
+        self,
+        url: str,
+        api_token: str,
+        coordinates: Optional[Coordinates] = None,
+        http_get: HttpGet = _default_http_get,
+    ) -> None:
+        self._url = url.strip().rstrip("/")
+        self._api_token = api_token
+        self._http_get = http_get
+        self._coordinates = coordinates
+        self._snapshot: Dict[str, Flag] = {}
+        self._listeners: List[Listener] = []
+        self._lock = threading.RLock()
+        self._poll_timer: Optional[threading.Timer] = None
+        self._poll_interval: Optional[float] = None
+
+    # -- network -----------------------------------------------------------
+
+    def refresh(self) -> None:
+        """One billable request: fetches every flag of the token's environment.
+
+        Raises :class:`GreenFlagsError` on failure; the previous snapshot is
+        kept either way.
+        """
+        flags = request_flags(self._url, self._api_token, self._http_get)
+        with self._lock:
+            self._snapshot = flags
+            listeners = list(self._listeners)
+            evaluated = self._evaluated_snapshot()
+        for listener in listeners:
+            listener(evaluated)
+
+    # -- local reads (never hit the network) --------------------------------
+
+    def get_snapshot(self) -> Dict[str, Flag]:
+        with self._lock:
+            return self._evaluated_snapshot()
+
+    def get_all_flags(self) -> List[Flag]:
+        with self._lock:
+            return [self._evaluate(flag) for flag in self._snapshot.values()]
+
+    def get_flag(self, key: str, default: FlagValue = None) -> FlagValue:
+        """Evaluated value of ``key``; ``default`` when the flag is missing.
+
+        Never raises for missing flags — fail-open by design.
+        """
+        with self._lock:
+            flag = self._snapshot.get(key)
+            if flag is None:
+                return default
+            return self._evaluate(flag).value
+
+    def is_enabled(self, key: str) -> bool:
+        """True only when ``key`` exists and currently evaluates to ``True``."""
+        return self.get_flag(key) is True
+
+    # -- subscriptions -------------------------------------------------------
+
+    def subscribe(self, listener: Listener) -> Callable[[], None]:
+        """Registers ``listener``; called with the evaluated snapshot after
+        every successful :meth:`refresh`. Returns an unsubscribe callable."""
+        with self._lock:
+            self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            with self._lock:
+                if listener in self._listeners:
+                    self._listeners.remove(listener)
+
+        return unsubscribe
+
+    # -- polling -------------------------------------------------------------
+
+    def start_polling(self, interval_seconds: float) -> None:
+        """Refreshes every ``interval_seconds`` on a daemon timer thread until
+        :meth:`stop_polling`. Errors are swallowed (previous snapshot stays)."""
+        self.stop_polling()
+        with self._lock:
+            self._poll_interval = interval_seconds
+        self._schedule_poll()
+
+    def stop_polling(self) -> None:
+        with self._lock:
+            self._poll_interval = None
+            if self._poll_timer is not None:
+                self._poll_timer.cancel()
+                self._poll_timer = None
+
+    # -- geofence -------------------------------------------------------------
+
+    def set_coordinates(self, coordinates: Optional[Coordinates]) -> None:
+        """Sets (or clears with ``None``) the end-user location used for
+        geofence evaluation. No network request is made."""
+        with self._lock:
+            self._coordinates = coordinates
+
+    # -- internals -------------------------------------------------------------
+
+    def _schedule_poll(self) -> None:
+        with self._lock:
+            interval = self._poll_interval
+            if interval is None:
+                return
+            timer = threading.Timer(interval, self._poll_tick)
+            timer.daemon = True
+            self._poll_timer = timer
+            timer.start()
+
+    def _poll_tick(self) -> None:
+        try:
+            self.refresh()
+        except Exception:  # noqa: BLE001 — polling is fail-open by design
+            pass
+        self._schedule_poll()
+
+    def _evaluated_snapshot(self) -> Dict[str, Flag]:
+        return {key: self._evaluate(flag) for key, flag in self._snapshot.items()}
+
+    def _evaluate(self, flag: Flag) -> Flag:
+        coords = self._coordinates
+        geofence = flag.geofence
+        if coords is None or geofence is None:
+            return flag
+        center = Coordinates(latitude=geofence.latitude, longitude=geofence.longitude)
+        outside = haversine_meters(coords, center) > geofence.radius_meters
+        if not outside:
+            return flag
+        return flag.with_value(False if flag.type == "boolean" else None)

greenflags-0.1.0/src/greenflags/geo.py

@@ -0,0 +1,27 @@
+"""Haversine distance — mirrors the JS/Dart SDK implementations exactly.
+
+Internal, not part of the public surface.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .types import Coordinates
+
+_EARTH_RADIUS_METERS = 6_371_000
+
+
+def haversine_meters(a: Coordinates, b: Coordinates) -> float:
+    phi1 = math.radians(a.latitude)
+    phi2 = math.radians(b.latitude)
+    delta_phi = math.radians(b.latitude - a.latitude)
+    delta_lambda = math.radians(b.longitude - a.longitude)
+
+    h = (
+        math.sin(delta_phi / 2) ** 2
+        + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2) ** 2
+    )
+    c = 2 * math.atan2(math.sqrt(h), math.sqrt(1 - h))
+
+    return _EARTH_RADIUS_METERS * c

greenflags-0.1.0/src/greenflags/transport.py

@@ -0,0 +1,70 @@
+"""HTTP transport for GET /v1/flags. Internal.
+
+Zero dependencies: urllib from the standard library. An ``http_get`` callable
+can be injected (tests, custom clients); it must return ``(status, body)``.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Callable, Dict, Tuple
+
+from .types import Flag, GreenFlagsError
+
+HttpGet = Callable[[str, Dict[str, str]], Tuple[int, str]]
+
+
+def _default_http_get(url: str, headers: Dict[str, str]) -> Tuple[int, str]:
+    request = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return response.status, response.read().decode("utf-8")
+    except urllib.error.HTTPError as err:
+        return err.code, err.read().decode("utf-8", errors="replace")
+
+
+def request_flags(
+    url: str,
+    api_token: str,
+    http_get: HttpGet = _default_http_get,
+) -> Dict[str, Flag]:
+    base = url.strip().rstrip("/")
+    endpoint = f"{base}/v1/flags"
+    headers = {"authorization": f"Bearer {api_token}"}
+
+    try:
+        status, raw_body = http_get(endpoint, headers)
+    except GreenFlagsError:
+        raise
+    except Exception as err:  # noqa: BLE001 — network layer catch-all by design
+        raise GreenFlagsError("NETWORK_ERROR", str(err), 0) from err
+
+    try:
+        body = json.loads(raw_body)
+    except ValueError as err:
+        raise GreenFlagsError(
+            "PARSE_ERROR", "Invalid response from server", status
+        ) from err
+
+    if status < 200 or status >= 300:
+        envelope = body if isinstance(body, dict) else {}
+        raise GreenFlagsError(
+            envelope.get("error") or "REQUEST_ERROR",
+            envelope.get("message") or "Request failed",
+            status,
+        )
+
+    flags_raw = (
+        body.get("data", {}).get("flags") if isinstance(body, dict) else None
+    )
+    if not isinstance(flags_raw, list):
+        raise GreenFlagsError("PARSE_ERROR", "Invalid response from server", status)
+
+    result: Dict[str, Flag] = {}
+    for item in flags_raw:
+        if isinstance(item, dict):
+            flag = Flag.from_json(item)
+            result[flag.key] = flag
+    return result

greenflags-0.1.0/src/greenflags/types.py

@@ -0,0 +1,69 @@
+"""Public types. They mirror the backend contract (GET /v1/flags) exactly."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Optional, Union
+
+FlagType = Literal["boolean", "string", "number", "json"]
+
+# bool | str | int | float | dict — None is the geofenced-off value for
+# non-boolean flags.
+FlagValue = Union[bool, str, int, float, dict, None]
+
+
+@dataclass(frozen=True)
+class Coordinates:
+    latitude: float
+    longitude: float
+
+
+@dataclass(frozen=True)
+class Geofence:
+    latitude: float
+    longitude: float
+    radius_meters: float
+
+    @staticmethod
+    def from_json(data: dict) -> "Geofence":
+        return Geofence(
+            latitude=float(data["latitude"]),
+            longitude=float(data["longitude"]),
+            radius_meters=float(data["radiusMeters"]),
+        )
+
+
+@dataclass(frozen=True)
+class Flag:
+    key: str
+    type: FlagType
+    value: FlagValue
+    geofence: Optional[Geofence] = None
+
+    @staticmethod
+    def from_json(data: dict) -> "Flag":
+        geofence = data.get("geofence")
+        return Flag(
+            key=data["key"],
+            type=data["type"],
+            value=data.get("value"),
+            geofence=Geofence.from_json(geofence) if geofence else None,
+        )
+
+    def with_value(self, value: Any) -> "Flag":
+        return Flag(key=self.key, type=self.type, value=value, geofence=self.geofence)
+
+
+class GreenFlagsError(Exception):
+    """Raised on network or API failures.
+
+    ``code`` mirrors the API error codes (e.g. ``INVALID_TOKEN``,
+    ``QUOTA_EXCEEDED``) plus the client-side ``NETWORK_ERROR`` and
+    ``PARSE_ERROR``. ``status`` is the HTTP status (0 for network failures).
+    """
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(f"{code} ({status}): {message}")
+        self.code = code
+        self.message = message
+        self.status = status

greenflags-0.1.0/tests/test_client.py

@@ -0,0 +1,175 @@
+import json
+import time
+
+import pytest
+
+from greenflags import Coordinates, GreenFlagsClient, GreenFlagsError
+
+
+def flags_server(flags):
+    body = json.dumps({"success": True, "data": {"flags": flags}})
+
+    def http_get(url, headers):
+        http_get.calls.append((url, headers))
+        return 200, body
+
+    http_get.calls = []
+    return http_get
+
+
+def test_refresh_and_reads():
+    http_get = flags_server(
+        [
+            {"key": "on", "type": "boolean", "value": True},
+            {"key": "banner", "type": "string", "value": "hello"},
+        ]
+    )
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev/", api_token="gf_test", http_get=http_get
+    )
+    client.refresh()
+
+    url, headers = http_get.calls[0]
+    assert url == "https://app.greenflags.dev/v1/flags"
+    assert headers["authorization"] == "Bearer gf_test"
+
+    assert client.is_enabled("on") is True
+    assert client.get_flag("banner") == "hello"
+    assert client.get_flag("missing", default=42) == 42
+    assert client.is_enabled("missing") is False
+    assert len(client.get_all_flags()) == 2
+
+
+def test_error_envelope_maps_to_exception():
+    def http_get(url, headers):
+        return 401, json.dumps(
+            {"success": False, "error": "INVALID_TOKEN", "message": "Invalid API token."}
+        )
+
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="bad", http_get=http_get
+    )
+    with pytest.raises(GreenFlagsError) as exc:
+        client.refresh()
+    assert exc.value.code == "INVALID_TOKEN"
+    assert exc.value.status == 401
+
+
+def test_network_error_and_parse_error():
+    def network_fail(url, headers):
+        raise ConnectionError("connection refused")
+
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=network_fail
+    )
+    with pytest.raises(GreenFlagsError) as exc:
+        client.refresh()
+    assert exc.value.code == "NETWORK_ERROR"
+    assert exc.value.status == 0
+
+    def bad_json(url, headers):
+        return 200, "<html>oops</html>"
+
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=bad_json
+    )
+    with pytest.raises(GreenFlagsError) as exc:
+        client.refresh()
+    assert exc.value.code == "PARSE_ERROR"
+
+
+def test_failed_refresh_keeps_previous_snapshot():
+    state = {"fail": False}
+
+    def http_get(url, headers):
+        if state["fail"]:
+            return 429, json.dumps(
+                {"success": False, "error": "QUOTA_EXCEEDED", "message": "Quota."}
+            )
+        return 200, json.dumps(
+            {"success": True, "data": {"flags": [{"key": "on", "type": "boolean", "value": True}]}}
+        )
+
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=http_get
+    )
+    client.refresh()
+    assert client.is_enabled("on") is True
+
+    state["fail"] = True
+    with pytest.raises(GreenFlagsError):
+        client.refresh()
+    assert client.is_enabled("on") is True  # previous snapshot survives
+
+
+def test_geofence_evaluation():
+    http_get = flags_server(
+        [
+            {
+                "key": "geo-bool",
+                "type": "boolean",
+                "value": True,
+                "geofence": {"latitude": 19.4326, "longitude": -99.1332, "radiusMeters": 1000},
+            },
+            {
+                "key": "geo-string",
+                "type": "string",
+                "value": "promo",
+                "geofence": {"latitude": 19.4326, "longitude": -99.1332, "radiusMeters": 1000},
+            },
+        ]
+    )
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=http_get
+    )
+    client.refresh()
+
+    # No coordinates: geofence ignored.
+    assert client.is_enabled("geo-bool") is True
+
+    # Inside the radius.
+    client.set_coordinates(Coordinates(latitude=19.4327, longitude=-99.1333))
+    assert client.is_enabled("geo-bool") is True
+    assert client.get_flag("geo-string") == "promo"
+
+    # Outside (Monterrey, ~700 km away).
+    client.set_coordinates(Coordinates(latitude=25.6866, longitude=-100.3161))
+    assert client.is_enabled("geo-bool") is False
+    assert client.get_flag("geo-string") is None
+
+    # Clearing restores un-geofenced evaluation.
+    client.set_coordinates(None)
+    assert client.is_enabled("geo-bool") is True
+
+
+def test_subscribe_and_unsubscribe():
+    http_get = flags_server([{"key": "on", "type": "boolean", "value": True}])
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=http_get
+    )
+    seen = []
+    unsubscribe = client.subscribe(lambda snapshot: seen.append(snapshot))
+
+    client.refresh()
+    assert len(seen) == 1
+    assert seen[0]["on"].value is True
+
+    unsubscribe()
+    client.refresh()
+    assert len(seen) == 1
+
+
+def test_polling_refreshes_and_stops():
+    http_get = flags_server([])
+    client = GreenFlagsClient(
+        url="https://app.greenflags.dev", api_token="gf", http_get=http_get
+    )
+
+    client.start_polling(0.02)
+    time.sleep(0.09)
+    client.stop_polling()
+    calls_at_stop = len(http_get.calls)
+    assert calls_at_stop >= 2
+
+    time.sleep(0.06)
+    assert len(http_get.calls) == calls_at_stop

greenflags-0.1.0/tests/test_geo.py

@@ -0,0 +1,35 @@
+from greenflags import Coordinates
+from greenflags.geo import haversine_meters
+
+
+def test_same_point_is_zero():
+    point = Coordinates(latitude=19.4326, longitude=-99.1332)
+    assert abs(haversine_meters(point, point)) < 1e-6
+
+
+def test_paris_london_within_one_percent():
+    paris = Coordinates(latitude=48.8566, longitude=2.3522)
+    london = Coordinates(latitude=51.5074, longitude=-0.1278)
+    expected = 343_550  # meters, known reference
+    distance = haversine_meters(paris, london)
+    assert abs(distance - expected) / expected < 0.01
+
+
+def test_antimeridian_is_small_not_half_earth():
+    a = Coordinates(latitude=0, longitude=179.9)
+    b = Coordinates(latitude=0, longitude=-179.9)
+    distance = haversine_meters(a, b)
+    assert 15_000 < distance < 30_000
+
+
+def test_near_pole_small_finite():
+    a = Coordinates(latitude=89.999, longitude=0)
+    b = Coordinates(latitude=89.999, longitude=180)
+    distance = haversine_meters(a, b)
+    assert distance < 300
+
+
+def test_exact_pole_zero():
+    a = Coordinates(latitude=90, longitude=0)
+    b = Coordinates(latitude=90, longitude=137)
+    assert abs(haversine_meters(a, b)) < 1e-6