prombed 0.1.0__tar.gz

prombed-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

prombed-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   Copyright 2026 Prombed Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

prombed-0.1.0/Makefile

@@ -0,0 +1,15 @@
+.PHONY: fix lint test build
+
+fix:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+lint:
+	uv run ruff format --check .
+	uv run ruff check .
+
+test:
+	uv run pytest -q
+
+build:
+	uv build

prombed-0.1.0/NOTICE

@@ -0,0 +1,8 @@
+Prombed
+Copyright 2026 Prombed Authors
+
+Prombed includes algorithms adapted from Prometheus, which is licensed under
+the Apache License 2.0. Adapted behavior includes rate extrapolation, classic
+histogram quantiles, scrape label mutation and staleness, and evaluator sample
+accounting. Corresponding source files retain Prometheus Authors copyright
+notices.

prombed-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+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.

prombed-0.1.0/README.md

@@ -0,0 +1,52 @@
+# 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.

prombed-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "prombed"
+version = "0.1.0"
+description = "A small, embeddable Prometheus subset for short-lived metric analysis."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<10.0",
+    "pytest-asyncio>=0.23,<2.0",
+    "ruff>=0.12,<1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prombed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

prombed-0.1.0/src/prombed/__init__.py

@@ -0,0 +1,50 @@
+from .errors import PrombedError as PrombedError
+from .errors import PrombedErrorCode as PrombedErrorCode
+from .exposition import parse_exposition as parse_exposition
+from .prombed import Fetch as Fetch
+from .prombed import Prombed as Prombed
+from .promql import PromQLEngine as PromQLEngine
+from .promql import parse_duration as parse_duration
+from .promql import parse_promql as parse_promql
+from .storage import AppendResult as AppendResult
+from .storage import InMemoryStorage as InMemoryStorage
+from .storage import StorageAppender as StorageAppender
+from .storage import StoredSeries as StoredSeries
+from .storage import label_key as label_key
+from .types import (
+    ExpositionSample as ExpositionSample,
+)
+from .types import (
+    LabelMatcher as LabelMatcher,
+)
+from .types import (
+    LabelMatcherOperator as LabelMatcherOperator,
+)
+from .types import (
+    LabelSet as LabelSet,
+)
+from .types import (
+    MetricMetadata as MetricMetadata,
+)
+from .types import (
+    MetricType as MetricType,
+)
+from .types import (
+    ParsedExposition as ParsedExposition,
+)
+from .types import (
+    Sample as Sample,
+)
+from .types import (
+    ScrapeResult as ScrapeResult,
+)
+from .types import (
+    ScrapeTarget as ScrapeTarget,
+)
+from .types import (
+    ScrapeTargetHealth as ScrapeTargetHealth,
+)
+from .types import (
+    ScrapeTargetStatus as ScrapeTargetStatus,
+)
+from .value import STALE_NAN_BITS as STALE_NAN_BITS

prombed-0.1.0/src/prombed/errors.py

@@ -0,0 +1,20 @@
+from typing import Literal
+
+PrombedErrorCode = Literal[
+    "invalid_exposition",
+    "invalid_query",
+    "unsupported_promql_feature",
+    "query_execution_error",
+    "out_of_order_sample",
+    "duplicate_sample",
+    "storage_capacity_exceeded",
+    "scrape_failed",
+]
+
+
+class PrombedError(Exception):
+    """A stable, machine-readable failure from Prombed."""
+
+    def __init__(self, code: PrombedErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code = code

prombed-0.1.0/src/prombed/exposition.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import math
+import re
+
+from .errors import PrombedError
+from .types import ExpositionSample, MetricMetadata, ParsedExposition
+
+_METRIC_NAME = re.compile(r"^[A-Za-z_:][A-Za-z0-9_:]*$")
+_LABEL_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_FLOAT = re.compile(r"^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$")
+_METRIC_TYPES: set[str] = {
+    "counter",
+    "gauge",
+    "histogram",
+    "summary",
+    "untyped",
+    "info",
+    "stateset",
+    "gaugehistogram",
+    "unknown",
+}
+
+
+def _invalid(line_number: int, message: str) -> None:
+    raise PrombedError(
+        "invalid_exposition",
+        f"invalid Prometheus exposition at line {line_number}: {message}",
+    )
+
+
+def _skip_whitespace(value: str, start: int) -> int:
+    index = start
+    while index < len(value) and value[index].isspace():
+        index += 1
+    return index
+
+
+def _parse_escaped_string(value: str, start: int, line_number: int) -> tuple[str, int]:
+    if start >= len(value) or value[start] != '"':
+        _invalid(line_number, "expected quoted label value")
+    output: list[str] = []
+    index = start + 1
+    while index < len(value):
+        char = value[index]
+        if char == '"':
+            return "".join(output), index + 1
+        if char != "\\":
+            output.append(char)
+            index += 1
+            continue
+        index += 1
+        if index >= len(value):
+            _invalid(line_number, "unterminated quoted label value")
+        escaped = value[index]
+        replacement = {"\\": "\\", '"': '"', "n": "\n"}.get(escaped)
+        if replacement is None:
+            _invalid(line_number, f"unsupported escape sequence \\{escaped}")
+        output.append(replacement)
+        index += 1
+    _invalid(line_number, "unterminated quoted label value")
+    raise AssertionError("unreachable")
+
+
+def _parse_labels(value: str, start: int, line_number: int) -> tuple[dict[str, str], int]:
+    labels: dict[str, str] = {}
+    index = start + 1
+    while True:
+        index = _skip_whitespace(value, index)
+        if index < len(value) and value[index] == "}":
+            return labels, index + 1
+        name_start = index
+        while index < len(value) and (value[index].isalnum() or value[index] == "_"):
+            index += 1
+        name = value[name_start:index]
+        if not _LABEL_NAME.fullmatch(name):
+            _invalid(line_number, f"invalid label name {name!r}")
+        if name in labels:
+            _invalid(line_number, f"duplicate label {name!r}")
+        index = _skip_whitespace(value, index)
+        if index >= len(value) or value[index] != "=":
+            _invalid(line_number, f"expected '=' after label {name!r}")
+        index = _skip_whitespace(value, index + 1)
+        parsed, index = _parse_escaped_string(value, index, line_number)
+        labels[name] = parsed
+        index = _skip_whitespace(value, index)
+        if index < len(value) and value[index] == ",":
+            index += 1
+            continue
+        if index < len(value) and value[index] == "}":
+            return labels, index + 1
+        _invalid(line_number, "expected ',' or '}' after label value")
+
+
+def _parse_float(token: str, line_number: int) -> float:
+    if token == "NaN":
+        return math.nan
+    if token in {"+Inf", "Inf"}:
+        return math.inf
+    if token == "-Inf":
+        return -math.inf
+    if not _FLOAT.fullmatch(token):
+        _invalid(line_number, f"invalid sample value {token!r}")
+    return float(token)
+
+
+def _parse_sample_line(line: str, line_number: int) -> ExpositionSample:
+    index = 0
+    while index < len(line) and not line[index].isspace() and line[index] != "{":
+        index += 1
+    name = line[:index]
+    if not _METRIC_NAME.fullmatch(name):
+        _invalid(line_number, f"invalid metric name {name!r}")
+    labels: dict[str, str] = {}
+    if index < len(line) and line[index] == "{":
+        labels, index = _parse_labels(line, index, line_number)
+    index = _skip_whitespace(line, index)
+    value_start = index
+    while index < len(line) and not line[index].isspace():
+        index += 1
+    sample_value = _parse_float(line[value_start:index], line_number)
+    index = _skip_whitespace(line, index)
+    timestamp: int | None = None
+    if index < len(line) and line[index] != "#":
+        timestamp_start = index
+        while index < len(line) and not line[index].isspace():
+            index += 1
+        token = line[timestamp_start:index]
+        if not re.fullmatch(r"-?\d+", token):
+            _invalid(line_number, f"invalid sample timestamp {token!r}")
+        timestamp = int(token)
+        if abs(timestamp) > 2**53 - 1:
+            _invalid(line_number, f"sample timestamp is outside the safe integer range: {token}")
+        index = _skip_whitespace(line, index)
+    if index < len(line) and line[index] != "#":
+        _invalid(line_number, f"unexpected trailing content {line[index:]!r}")
+    return ExpositionSample(name, labels, sample_value, timestamp)
+
+
+def _unescape_help(value: str, line_number: int) -> str:
+    output: list[str] = []
+    index = 0
+    while index < len(value):
+        char = value[index]
+        if char != "\\":
+            output.append(char)
+            index += 1
+            continue
+        index += 1
+        if index >= len(value):
+            _invalid(line_number, "unsupported HELP escape sequence \\")
+        escaped = value[index]
+        if escaped == "\\":
+            output.append("\\")
+        elif escaped == "n":
+            output.append("\n")
+        else:
+            _invalid(line_number, f"unsupported HELP escape sequence \\{escaped}")
+        index += 1
+    return "".join(output)
+
+
+def parse_exposition(value: str) -> ParsedExposition:
+    """Parse Prometheus text format 0.0.4 and its classic OpenMetrics subset."""
+
+    samples: list[ExpositionSample] = []
+    metadata: dict[str, MetricMetadata] = {}
+    descriptor_pattern = re.compile(r"^#\s*(HELP|TYPE|UNIT)\s+([^\s]+)\s+(.+)$")
+    for line_number, raw in enumerate(value.splitlines(), 1):
+        line = raw.strip()
+        if not line or line == "# EOF":
+            continue
+        if not line.startswith("#"):
+            samples.append(_parse_sample_line(line, line_number))
+            continue
+        match = descriptor_pattern.fullmatch(line)
+        if match is None:
+            continue
+        kind, name, raw_value = match.groups()
+        if not _METRIC_NAME.fullmatch(name):
+            _invalid(line_number, f"invalid metadata metric name {name!r}")
+        entry = metadata.setdefault(name, MetricMetadata())
+        if kind == "TYPE":
+            metric_type = raw_value.lower()
+            if metric_type not in _METRIC_TYPES:
+                _invalid(line_number, f"unsupported metric type {raw_value!r}")
+            entry.type = metric_type  # type: ignore[assignment]
+        elif kind == "HELP":
+            entry.help = _unescape_help(raw_value, line_number)
+        else:
+            entry.unit = raw_value
+    return ParsedExposition(samples, metadata)