Parsing

The parsing module converts raw data (files, bytes, strings) into a polars.DataFrame. It is fully implemented and powers both the engine and the top-level hr.parse().

ParserEngine

from hermes.parsing import ParserEngine
 
engine = ParserEngine()

detect_format(source) -> str | None

Detect the format of the input. Detection uses the file extension first (.csv, .json, .jsonl/.ndjson, .parquet, .xml), then falls back to content sniffing for string/bytes input (XML for <, JSON for {/[).

engine.detect_format("data.csv")   # -> "csv"
engine.detect_format("<root>")     # -> "xml"
engine.detect_format('{"a": 1}')   # -> "json"

Returns None if the format cannot be determined.

parse(raw_data, format=None, **kwargs) -> pl.DataFrame

Parse raw data into a polars.DataFrame. If format is omitted, it is detected automatically. Raises ParseError for unsupported or undetectable formats.

df = engine.parse("data.csv")
df = engine.parse('{"a": 1}', format="json")
df = engine.parse(b"\x89PARQUET...", format="parquet")

Supported formats: csv, json, jsonl, parquet, xml.

Format Parsers

Individual parsers are dispatched by the engine — you rarely need them directly. Each implements parse(raw_data, **kwargs) -> pl.DataFrame:

Top-Level API

import hermes as hr
 
result = hr.parse("data.csv")     # Result; .data is the DataFrame
result = hr.parse(path, format="json")

hr.parse() returns a Result: .data holds the parsed polars.DataFrame and .statistics includes row/column counts. On failure the Result has status "failure" and errors populated.

The Dataset.load() method also routes through ParserEngine, so any supported file format works:

ds = hr.Dataset(name="gdp", data_ref="gdp.csv")
ds.load()  # reads the CSV into ds.data

Errors

from hermes.parsing import ParseError
from hermes.core.errors import ParseError  # same class