Registry / observability / promql-parser

promql-parser

library0.10.0pypypi✓ verified 87d ago

promql-parser is a Python binding that provides a fast and robust PromQL (Prometheus Query Language) parser. It leverages a Rust-based parser for efficient conversion of PromQL queries into an Abstract Syntax Tree (AST), enabling programmatic analysis and manipulation of Prometheus queries. The current version is 0.8.0, with releases typically following updates to the underlying Rust parser.

observability devops

pip install promql-parser

github ↗package ↗

INSTALL

IMPORT

SIG · PROMQL-PARSER

promql-parser

observabilitypythonv0.10.0

Install

1.9s avg

Import

—

Disk

20MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 1.83s

py 3.11

✓ —

✓ 1.75s

py 3.12

✓ —

✓ 1.75s

py 3.13

✓ —

✓ 2.25s

py 3.9

✕ build_error

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from promql_parser import parse

Parse a PromQL query string into its Abstract Syntax Tree (AST) representation. The returned AST is a Python object that mirrors the structure of the PromQL query, allowing for detailed inspection of metric names, labels, functions, and operators.

from promql_parser import parse query = 'rate(http_requests_total{code="200", job="prometheus"}[5m])' ast = parse(query) print(ast) # Example of accessing AST components (exact structure depends on query) # print(ast.expr.name) # For a VectorSelector, might access name # print(ast.expr.matchers.matchers[0].name) # Accessing a matcher's name

Debug

Known issues

breakingThe underlying Rust parser declares compatibility with a specific Prometheus PromQL version (e.g., v3.8 as of March 2026). Future changes to the PromQL syntax in newer Prometheus versions may lead to parsing errors or unexpected AST structures without a corresponding update to `promql-parser`.

fix

Monitor the `messense/py-promql-parser` and `GreptimeTeam/promql-parser` GitHub repositories for updates and release notes to ensure compatibility with the PromQL version you are using. Upgrade `promql-parser` promptly when new versions are released to maintain parsing accuracy for evolving PromQL syntax.

affects: All versions

gotchaThe output of the `parse` function is an Abstract Syntax Tree (AST), which is a complex nested object structure. Understanding the exact shape of the AST for different PromQL queries requires familiarity with PromQL grammar and the parser's internal representation.

fix

Inspect the `print(ast)` output for various query types to understand its structure. Refer to the `GreptimeTeam/promql-parser` documentation (Rust library) for details on the AST node types if deep programmatic manipulation is required, as the Python binding directly exposes this underlying structure.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'promql_parser'

The 'promql-parser' Python package has not been installed or is not accessible in the current Python environment.

fix

pip install promql-parser

Err: ParseError { ... }

The input string provided to the parser is not a valid PromQL query according to the library's grammar, resulting in a parsing failure.

fix

Correct the PromQL query string to adhere to the supported PromQL syntax. Example of correct usage: `promql_parser.parse('http_requests_total')`

ImportError: cannot import name 'parser' from 'promql_parser' (or similar for 'parse')

The user is attempting to import `parse` from a non-existent `parser` submodule or directly importing a non-existent `parser` module. The `parse` function is available directly under the top-level `promql_parser` module.

fix

Import the `parse` function directly from the top-level `promql_parser` module: `from promql_parser import parse`

AttributeError: 'SomeASTNode' object has no attribute 'some_non_existent_attribute'

After parsing a PromQL query into an Abstract Syntax Tree (AST), the user is attempting to access an attribute or field on an AST node object that does not exist for that specific node type or has a different name than expected.

fix

Consult the `promql-parser` library's documentation or inspect the AST object's structure (e.g., using `dir()` or `print(ast_node.__dict__)`) to identify the correct attributes for the specific AST node type.

Upgrade

Version history

0.10.0latest on PyPI · released Jun 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

36 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/messense/py-promql-parser ↗

packagehttps://pypi.org/project/promql-parser/ ↗