parse-errors

What it is and what it does

parse-errors is a thin wrapper around config file parsing that intercepts exceptions and enriches them with precise source locations. When you parse JSON, TOML, or YAML inside a ParseContext, any exception that occurs gets analyzed for line and column information and re-raised as a ParseError with the filename, line, and column attached. If location information cannot be extracted, the original exception passes through unchanged.

The package depends on tree-sitter and tree-sitter-toml for syntax-aware parsing, pyyaml for YAML support, and json-source-map for JSON location tracking. It's designed for developers building tools that parse user-supplied config files and need to give users actionable error messages pointing to the exact spot in the file that caused the problem.

Use it for:

• CLI tools that load JSON, TOML, or YAML config files and need to report parse errors with precise line/column to users.
• Configuration validation frameworks that combine multiple decoders and want unified error reporting.
• Build systems or deployment tools that must pinpoint config syntax errors for quick user fixes.
• API servers that accept config uploads and need to reject invalid files with exact error locations.
• Development utilities that parse structured data and want better debugging output than bare exception messages.

Worth the install?

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

Wraps parse and validation errors from JSON, TOML, and YAML files to include filename, line number, and column in the exception, making it easier to report precise error locations to users.

Yes, if you parse config files (JSON, TOML, YAML) and want to give users precise error locations. Low install friction, permissive license, no known vulnerabilities, and active maintenance. The package is young (first release 2026-03-18) but solves a real UX problem. Install it if error reporting quality matters in your use case.

Install

parse-errors on PyPI

pip install parse-errors

uv add parse-errors

poetry add parse-errors

Installing parse-errors

Before you install

Low friction: pure Python wheel with four runtime dependencies (json-source-map, pyyaml, tree-sitter, tree-sitter-toml). Active maintenance as of 2026-05-01, though early in its release history (first release 2026-03-18).

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for any project type.

Quickstart

from parse_errors import ParseContext, ParseError

with ParseContext("config.toml", data=raw, format="toml"):
    data = tomllib.loads(raw.decode())
    config = msgspec.convert(data, Config)

Requires Python 3.10 or later.

Verify before relying

• Whether tree-sitter-toml binary wheels are available for all target platforms, or if compilation is required.
• Performance impact of tree-sitter parsing overhead on large config files.
• Exact behavior when format inference from filename extension fails or is ambiguous.

Package facts

Evidence: parse_errors-0.5.0-py3-none-any.whl

Tags

More Software Development packages