Metadata-Version: 2.5
Name: prombed
Version: 0.1.0
Summary: A small, embeddable Prometheus subset for short-lived metric analysis.
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == 'dev'
Requires-Dist: pytest<10.0,>=8.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# Prombed Python

The Python implementation provides zero-runtime-dependency Prometheus text exposition parsing,
bounded in-memory storage, static-target scraping, and PromQL queries. It requires Python 3.10+.

## Development

```bash
cd <repo_root>/python
uv sync --extra dev
uv run pytest -q
uv run ruff format .
uv run ruff check .
```

## API

```python
from prombed import Prombed, ScrapeTarget

metrics = Prombed(
    targets=[
        ScrapeTarget(
            "http://example:8080/metrics",
            labels={"service": "example"},
            metric_names=("example_requests_total", "example_duration_seconds"),
        )
    ],
    retention_ms=10 * 60_000,
    scrape_interval_ms=5_000,
)

await metrics.start()
success_rate = metrics.query(
    'sum(rate(example_requests_total{status="success"}[1m])) '
    "/ sum(rate(example_requests_total[1m]))"
)
latency = metrics.query(
    "histogram_quantile(0.95, sum by (le) (rate(example_duration_seconds_bucket[1m])))"
)
metrics.stop()
```

- `await scrape_once()` scrapes configured targets immediately.
- `await start()` performs an initial scrape and starts periodic collection; `stop()` stops it.
- `ingest()` accepts a snapshot when the caller owns the sampling lifecycle.
- `targets()` returns target health and the latest scrape error.
- `query()` and `query_range()` return Prometheus HTTP API-style dictionaries.

Storage, queries, and external requests have explicit capacity and timeout limits. See the
[PromQL compatibility contract](../docs/promql-compatibility.md) for supported behavior and
deliberate omissions.
