Metadata-Version: 2.4
Name: station-python
Version: 1.0.0
Summary: Lightweight Python SDK for sending count and value stats to Station.
Project-URL: Homepage, https://station.guide
Project-URL: Issues, https://github.com/station-guide/station-python/issues
Project-URL: Repository, https://github.com/station-guide/station-python
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,metrics,monitoring,observability,station,stats
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: requests>=2.32.0
Description-Content-Type: text/markdown

# Station Python

Python SDK for sending simple app stats to [Station](https://station.guide).

## Install

```sh
pip install station-python
```

## Usage

```python
import station_python as station

station.set_api_key("your-api-key")
station.set_debug(True)

station.track_count("page_view")
station.track_count("signup", 3)
station.track_value("checkout_total", 24.95)

station.capture_count("background_job_started")
station.capture_value("api_latency_ms", 142)
```

Instead of calling `set_api_key`, you can set the `STATION_API_KEY` environment
variable before starting your app:

```sh
STATION_API_KEY=your-api-key python app.py
```

## API

### `set_api_key(api_key)`

Sets the Station API key used by subsequent events.

### `set_debug(enabled)`

Enables or disables debug logging. Debug mode is disabled by default.

### `track_count(stat_name, value=1)`

Sends a count event to Station. Use it for incrementing counters such as page
views, clicks, signups, or other discrete events.

### `track_value(stat_name, value)`

Sends a numeric value event to Station. Use it for measurements such as totals,
durations, scores, or other numeric observations.

### `capture_count(stat_name, value=1)`

Fire-and-forget version of `track_count`. It schedules the request and returns
immediately.

### `capture_value(stat_name, value)`

Fire-and-forget version of `track_value`. It schedules the request and returns
immediately.

Network errors do not interrupt your application flow. Enable debug mode if you
want failed event submissions logged during development or diagnostics. The
client reuses keep-alive connections, applies a short request timeout, retries
one transient network/server failure, and backs off after `429` rate limit
responses.

## Current Contract

The package posts to:

- `POST https://api.station.guide/v1/events/count`
- `POST https://api.station.guide/v1/events/value`

Request bodies use `apiKey`, `statName`, and `value`.

## Development

```sh
uv sync --dev
uv run pytest
```
