promql-parser

What it is and what it does

promql-parser is a Python binding to a Rust-based PromQL parser that converts Prometheus query expressions into an inspectable AST. It lets you parse queries like `rate(http_requests_total{job="api"}[5m])` into structured objects (VectorSelector, MatrixSelector, Call, AggregateExpr, BinaryExpr) that you can examine, walk depth-first, or transform into new expressions. The package also includes duration helpers to parse and format time intervals.

Typical workflows involve parsing a PromQL string, inspecting its structure to extract metric names or matchers, walking the tree to collect information, or transforming nodes to rewrite queries. The AST can be converted back to PromQL string form. No runtime dependencies are required beyond Python itself.

Use it for:

• Extract metric names and label matchers from Prometheus queries for validation or analysis.
• Rewrite or transform PromQL expressions programmatically (e.g., rename metrics, adjust time ranges).
• Build tooling that inspects or validates Prometheus query syntax before execution.
• Walk query trees to collect metadata or enforce query patterns in monitoring systems.
• Parse duration strings from PromQL into Python timedelta objects.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses Prometheus query language (PromQL) expressions into a Python-accessible abstract syntax tree that can be inspected, walked, transformed, and formatted back to PromQL.

Yes, if you need to parse or manipulate PromQL queries in Python. The package is actively maintained, has no known vulnerabilities, supports Python >=3.8, and requires no runtime dependencies. Medium install friction (prebuilt wheels for common platforms) is a minor trade-off for a specialized tool with a clear use case.

Install

promql-parser on PyPI

pip install promql-parser

uv add promql-parser

poetry add promql-parser

Installing promql-parser

Before you install

Medium install friction due to compiled wheels; prebuilt binaries available for Python 3.10–3.11 on common platforms. Active maintenance with latest release 67 days ago.

Quickstart

pip install promql-parser

import promql_parser

ast = promql_parser.parse('prometheus_http_requests_total{code="200", job="prometheus"}')
print(ast.prettify())

Requires Python >=3.8; prebuilt wheels available for Python 3.10–3.11 on Linux, macOS, and Windows.

Verify before relying

• Whether the Rust implementation is vendored or requires a separate build toolchain for platforms without prebuilt wheels.
• Whether PyPy support (listed in classifiers) is fully tested or aspirational.
• License details: license_spdx and license_raw are both null despite MIT being mentioned in the description.

Package facts

Evidence: promql_parser-0.10.0-cp310-cp310-macosx_10_12_x86_64.whl; promql_parser-0.10.0-cp310-cp310-macosx_11_0_arm64.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_17_armv7l.manylinux2014_armv7l.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; promql_parser-0.10.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl; promql_parser-0.10.0-cp310-cp310-musllinux_1_2_aarch64.whl; promql_parser-0.10.0-cp310-cp310-musllinux_1_2_armv7l.whl; promql_parser-0.10.0-cp310-cp310-musllinux_1_2_i686.whl; promql_parser-0.10.0-cp310-cp310-musllinux_1_2_x86_64.whl; promql_parser-0.10.0-cp310-cp310-win32.whl; promql_parser-0.10.0-cp310-cp310-win_amd64.whl; promql_parser-0.10.0-cp311-cp311-macosx_10_12_x86_64.whl; promql_parser-0.10.0-cp311-cp311-macosx_11_0_arm64.whl; promql_parser-0.10.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; promql_parser-0.10.0-cp311-cp311-manylinux_2_17_armv7l.manylinux2014_armv7l.whl; promql_parser-0.10.0-cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl; promql_parser-0.10.0-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl

Tags

More Monitoring packages