parse-errors 0.5.0__tar.gz → 0.6.0__tar.gz

{parse_errors-0.5.0 → parse_errors-0.6.0}/.github/workflows/build.yml

@@ -9,9 +9,6 @@ on:
       - v*
   pull_request:
 
-env:
-  UV_SYSTEM_PYTHON: 1
-
 jobs:
   test:
     runs-on: ${{ matrix.os }}
@@ -31,8 +28,7 @@ jobs:
           allow-prereleases: true
       - uses: astral-sh/setup-uv@v3
       - name: Install
-        run: |
-          uv pip install -e .[test,dev]
+        run: uv sync --extra test --extra dev
       - name: Test
         run: |
           git config --global user.name "Unit Test"
@@ -52,9 +48,9 @@ jobs:
           python-version: "3.14"
       - uses: astral-sh/setup-uv@v3
       - name: Install
-        run: uv pip install build
+        run: uv sync --extra test --extra dev
       - name: Build
-        run: python -m build
+        run: uv run python -m build
       - name: Upload
         uses: actions/upload-artifact@v4
         with:
@@ -65,7 +61,9 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
     permissions:
+      contents: read
       id-token: write
     steps:
       - uses: actions/download-artifact@v4

parse_errors-0.6.0/MANIFEST.in

@@ -0,0 +1 @@
+include *.md LICENSE

parse_errors-0.6.0/Makefile

@@ -0,0 +1,22 @@
+.venv:
+	uv sync --extra dev --extra test
+
+.PHONY: setup
+setup:
+	uv sync --extra dev --extra test
+
+.PHONY: test
+test:
+	uv run coverage run -m pytest $(TESTOPTS)
+	uv run coverage report
+
+.PHONY: format
+format:
+	uv run ruff format
+	uv run ruff check --fix
+
+.PHONY: lint
+lint:
+	uv run ruff check
+	uv run python -m checkdeps --allow-names parse_errors parse_errors
+	uv run mypy --strict --install-types --non-interactive parse_errors

parse_errors-0.6.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: parse-errors
+Version: 0.6.0
+Summary: re-raise parse errors with filename and line number
+Author-email: Tim Hatch <tim@timhatch.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/advice-animal/parse-errors/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml
+Requires-Dist: tree-sitter!=0.26.0
+Requires-Dist: tree-sitter-json
+Requires-Dist: tree-sitter-toml
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: checkdeps==0.9.0; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: ruff==0.15.6; extra == "dev"
+Requires-Dist: setuptools>=65; extra == "dev"
+Requires-Dist: ty==0.0.81; extra == "dev"
+Requires-Dist: types-pyyaml; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage>=7.14; extra == "test"
+Requires-Dist: msgspec; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: tomli; extra == "test"
+Dynamic: license-file
+
+# parse-errors
+
+`parse-errors` improves the errors you get when parsing config files (JSON,
+TOML, YAML).  Instead of a bare exception with a vague message, you get a
+`ParseError` that includes the filename, line number, and column — so you can
+point users straight to the problem.
+
+It understands msgspec validation errors and TOML syntax errors, mapping them
+back to the line of config they came from.  Even unrelated exceptions get the
+filename attached.
+
+## Usage
+
+Wrap your parse/validate call in `ParseContext`:
+
+```python
+import msgspec
+import tomllib
+from parse_errors import ParseContext
+
+class Config(msgspec.Struct):
+    host: str
+    port: int
+
+filename = "config.toml"
+
+with open(filename, "rb") as f:
+    raw = f.read()
+
+with ParseContext(filename, data=raw, format="toml"):
+    data = tomllib.loads(raw.decode())
+    config = msgspec.convert(data, Config)
+```
+
+`ParseContext` will intercept exceptions. If it can analyze them for precise
+locations, it will raise a `ParseError` exception with the original exception as
+the cause. If it can't find location information, the original exception is
+raised as-is. No exceptions are swallowed.
+
+As a concrete example, if the `msgspec.convert` raises because `port` is a
+string instead of an integer, you get something like:
+
+```
+parse_errors.ParseError: config.toml:3:8: Expected `int`, got `str` - at `$.port`
+```
+
+rather than the bare `msgspec.ValidationError` with no location.
+
+`ParseContext` also handles errors from TOML and other decoders that include
+positional information (`at line N, column M`) and re-raises them in the same
+`filename:line:col: message` format.
+
+## API
+
+```python
+from parse_errors import ParseContext, ParseError
+from parse_errors.source_map import SourceMap, build_source_map, locate_pointer
+```
+
+**`ParseContext(filename, *, data=None, format=None)`** — context manager.
+
+- `filename`: path to the file being parsed (used in error messages and to
+  infer the format from the extension when `format` is omitted).
+- `data`: the file contents as `str` or `bytes`.  If omitted, the file is read
+  from disk automatically when location info is needed.
+- `format`: `"json"`, `"toml"`, or `"yaml"`.  Inferred from `filename`'s
+  extension when not supplied.
+
+**`ParseError`** — the exception raised inside the context.  Has attributes
+`filename`, `line` (1-based), and `column` (1-based).
+
+**`locate_pointer(source, fmt, pointer)`** — returns the best source-map entry
+for one JSON Pointer without building a full map.  `fmt` is `"json"`,
+`"toml"`, or `"yaml"`; `source` is `str` or UTF-8 `bytes`; `pointer` uses RFC
+6901 escaping.  If the exact pointer is not present, the result matches
+`closest_entry(build_source_map(source, fmt), pointer)`: the nearest enclosing
+value when one exists, otherwise `None`.
+
+**`SourceMap(source, fmt)`** — caches the parsed document for repeated targeted
+lookups.  Use `SourceMap(...).locate(pointer)` when several errors in the same
+document need locations.  It still avoids constructing a full pointer-to-entry
+map.
+
+**`build_source_map(source, fmt)`** — builds the full pointer-to-location map.
+This is useful when callers need many arbitrary entries or need to inspect all
+locations.
+
+**Warning:** source-map helpers locate nodes in a document; they are not
+validating parsers.  JSON and TOML location support uses tree-sitter so it can
+return a location from a syntax tree even when a real decoder would reject the
+source.  Parse or validate the document with your normal parser first, then use
+these helpers only to map known error paths back to source locations.
+
+# Version Compat
+
+This library is compatible with Python 3.10+, but should be linted under the
+newest stable version.
+
+# Versioning
+
+This library follows [meanver](https://meanver.org/) which basically means
+[semver](https://semver.org/) along with a promise to rename when the major
+version changes.
+
+# License
+
+parse-errors is copyright [Tim Hatch](https://timhatch.com/), and licensed under
+the MIT license.  See the `LICENSE` file for details.

parse_errors-0.6.0/README.md

@@ -0,0 +1,108 @@
+# parse-errors
+
+`parse-errors` improves the errors you get when parsing config files (JSON,
+TOML, YAML).  Instead of a bare exception with a vague message, you get a
+`ParseError` that includes the filename, line number, and column — so you can
+point users straight to the problem.
+
+It understands msgspec validation errors and TOML syntax errors, mapping them
+back to the line of config they came from.  Even unrelated exceptions get the
+filename attached.
+
+## Usage
+
+Wrap your parse/validate call in `ParseContext`:
+
+```python
+import msgspec
+import tomllib
+from parse_errors import ParseContext
+
+class Config(msgspec.Struct):
+    host: str
+    port: int
+
+filename = "config.toml"
+
+with open(filename, "rb") as f:
+    raw = f.read()
+
+with ParseContext(filename, data=raw, format="toml"):
+    data = tomllib.loads(raw.decode())
+    config = msgspec.convert(data, Config)
+```
+
+`ParseContext` will intercept exceptions. If it can analyze them for precise
+locations, it will raise a `ParseError` exception with the original exception as
+the cause. If it can't find location information, the original exception is
+raised as-is. No exceptions are swallowed.
+
+As a concrete example, if the `msgspec.convert` raises because `port` is a
+string instead of an integer, you get something like:
+
+```
+parse_errors.ParseError: config.toml:3:8: Expected `int`, got `str` - at `$.port`
+```
+
+rather than the bare `msgspec.ValidationError` with no location.
+
+`ParseContext` also handles errors from TOML and other decoders that include
+positional information (`at line N, column M`) and re-raises them in the same
+`filename:line:col: message` format.
+
+## API
+
+```python
+from parse_errors import ParseContext, ParseError
+from parse_errors.source_map import SourceMap, build_source_map, locate_pointer
+```
+
+**`ParseContext(filename, *, data=None, format=None)`** — context manager.
+
+- `filename`: path to the file being parsed (used in error messages and to
+  infer the format from the extension when `format` is omitted).
+- `data`: the file contents as `str` or `bytes`.  If omitted, the file is read
+  from disk automatically when location info is needed.
+- `format`: `"json"`, `"toml"`, or `"yaml"`.  Inferred from `filename`'s
+  extension when not supplied.
+
+**`ParseError`** — the exception raised inside the context.  Has attributes
+`filename`, `line` (1-based), and `column` (1-based).
+
+**`locate_pointer(source, fmt, pointer)`** — returns the best source-map entry
+for one JSON Pointer without building a full map.  `fmt` is `"json"`,
+`"toml"`, or `"yaml"`; `source` is `str` or UTF-8 `bytes`; `pointer` uses RFC
+6901 escaping.  If the exact pointer is not present, the result matches
+`closest_entry(build_source_map(source, fmt), pointer)`: the nearest enclosing
+value when one exists, otherwise `None`.
+
+**`SourceMap(source, fmt)`** — caches the parsed document for repeated targeted
+lookups.  Use `SourceMap(...).locate(pointer)` when several errors in the same
+document need locations.  It still avoids constructing a full pointer-to-entry
+map.
+
+**`build_source_map(source, fmt)`** — builds the full pointer-to-location map.
+This is useful when callers need many arbitrary entries or need to inspect all
+locations.
+
+**Warning:** source-map helpers locate nodes in a document; they are not
+validating parsers.  JSON and TOML location support uses tree-sitter so it can
+return a location from a syntax tree even when a real decoder would reject the
+source.  Parse or validate the document with your normal parser first, then use
+these helpers only to map known error paths back to source locations.
+
+# Version Compat
+
+This library is compatible with Python 3.10+, but should be linted under the
+newest stable version.
+
+# Versioning
+
+This library follows [meanver](https://meanver.org/) which basically means
+[semver](https://semver.org/) along with a promise to rename when the major
+version changes.
+
+# License
+
+parse-errors is copyright [Tim Hatch](https://timhatch.com/), and licensed under
+the MIT license.  See the `LICENSE` file for details.

{parse_errors-0.5.0 → parse_errors-0.6.0}/parse_errors/_jsonpath.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import re
 
-
 # Matches a single step in a JSONPath: .key or [index] or ['key'] or ["key"]
 _STEP = re.compile(
     r"\.(?P<name>[^.\[]+)"  # .key
@@ -44,7 +43,9 @@ def jsonpath_to_pointer(jsonpath: str) -> str:
             raise ValueError(
                 f"Cannot parse JSONPath step at position {pos}: {tail[pos:]!r}"
             )
-        name = m.group("name") or m.group("sq") or m.group("dq") or m.group("idx")
+        for group in ("name", "sq", "dq", "idx"):
+            if (name := m.group(group)) is not None:
+                break
         parts.append(_escape(name))
         pos = m.end()
 

parse_errors-0.6.0/parse_errors/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
+
+__commit_id__ = commit_id = 'g81d17405e'

{parse_errors-0.5.0 → parse_errors-0.6.0}/parse_errors/context.py

@@ -2,13 +2,25 @@
 
 from __future__ import annotations
 
-import os
 import contextlib
+import os
+import re
 from pathlib import Path
 from typing import Iterator
 
-from .source_map import detect_format, build_source_map, closest_entry
 from ._jsonpath import extract_jsonpath, jsonpath_to_pointer
+from .source_map import detect_format, locate_pointer, Location
+
+POSITIONAL_RE = re.compile(r"at line (\d+), column (\d+)")
+
+
+def extract_positional_reference(msg: str) -> Location | None:
+    if m := POSITIONAL_RE.search(msg):
+        return Location(
+            line=int(m.group(1)) - 1, column=int(m.group(2)) - 1, position=0
+        )
+    return None
+
 
 __all__ = ["ParseError", "ParseContext"]
 
@@ -50,28 +62,47 @@ def ParseContext(
         yield
     except Exception as exc:
         message = str(exc)
+        path = Path(filename)
+
         # This is focused on msgspec-style exceptions, which use JSONPath for
-        # some reason.  If there are other formats we know can be raised,
-        # adjust this.
+        # some reason.
         jsonpath = extract_jsonpath(message)
         if jsonpath is None:
-            raise
+            # These are raised by toml decoding
+            loc = extract_positional_reference(message)
+            if loc is None:
+                raise ParseError(
+                    f"{filename}: {exc!r}", filename=filename, line=1
+                ) from exc
+
+            raise ParseError(
+                f"{path}:{loc.line + 1}:{loc.column + 1}: {message}",
+                filename=path,
+                line=loc.line + 1,
+                column=loc.column + 1,
+            ) from exc
 
         try:
             pointer = jsonpath_to_pointer(jsonpath)
-        except ValueError:  # pragma: no cover
-            raise exc
-
-        path = Path(filename)
-        fmt = format or detect_format(path)
-        assert fmt is not None
+        except ValueError:
+            raise ParseError(
+                f"{filename}: {exc!r}", filename=filename, line=1
+            ) from exc
+
+        fmt = format.lower() if format else detect_format(path)
+        if fmt == "yml":
+            fmt = "yaml"
+        if fmt not in ("json", "toml", "yaml"):
+            raise ParseError(
+                f"{filename}: {exc!r}", filename=filename, line=1
+            ) from exc
 
         source = data if data is not None else path.read_bytes()
-        source_map = build_source_map(source, fmt)
-
-        entry = closest_entry(source_map, pointer)
-        if entry is None:  # pragma: no cover
-            raise exc
+        entry = locate_pointer(source, fmt, pointer)
+        if entry is None:
+            raise ParseError(
+                f"{filename}: {exc!r}", filename=filename, line=1
+            ) from exc
 
         loc = entry.value_start
         # Lines are 0-based in source maps; convert to 1-based for humans.

parse_errors-0.6.0/parse_errors/json_source_map/__init__.py

@@ -0,0 +1,222 @@
+"""Calculate JSON source locations using tree-sitter, targeted or full.
+
+tree-sitter does the parse in C instead of a hand-written pure-Python
+character scanner, and locate() additionally never visits a subtree that
+isn't on the path to the one pointer asked for -- indexing directly into
+tree-sitter's parsed node tree.
+
+calculate() (the full map, used by anything that still wants build_source_map
++ closest_entry) is kept for comparison/completeness.
+"""
+
+from __future__ import annotations
+
+import json
+
+import tree_sitter as ts
+import tree_sitter_json
+
+from .._jsonpath import _escape
+from ..source_map import Entry, Location, TSourceMap
+
+_LANGUAGE = ts.Language(tree_sitter_json.language())
+
+_Parsed = tuple[ts.Node, list[bytes]]
+
+
+def calculate(source: str | bytes) -> TSourceMap:
+    """Calculate the full source map for a JSON document."""
+    src_bytes = source.encode("utf-8") if isinstance(source, str) else source
+    root = ts.Parser(_LANGUAGE).parse(src_bytes).root_node
+    lines = src_bytes.splitlines(True) + [b""]
+    byte_to_char = [_byte_to_char_offsets(line) for line in lines]
+    line_start_chars = [0]
+    for offsets in byte_to_char[:-1]:
+        line_start_chars.append(line_start_chars[-1] + offsets[-1])
+
+    result: TSourceMap = {}
+    top = root.named_children[0] if root.named_children else root
+    _walk_all(top, [], result, byte_to_char, line_start_chars)
+    return result
+
+
+def _parse(source: str | bytes) -> _Parsed | None:
+    """Parse *source* into the (node, lines) pair :func:`_locate_in` walks.
+
+    Split out from :func:`locate` so :class:`~parse_errors.source_map.SourceMap`
+    can parse once and reuse it across several ``locate()`` calls on the same
+    document, instead of reparsing per pointer.
+    """
+    src_bytes = source.encode("utf-8") if isinstance(source, str) else source
+    root = ts.Parser(_LANGUAGE).parse(src_bytes).root_node
+    lines = src_bytes.splitlines(True) + [b""]
+    top = root.named_children[0] if root.named_children else root
+    return top, lines
+
+
+def _locate_in(parsed: _Parsed | None, pointer: str) -> Entry | None:
+    if parsed is None:
+        return None
+    top, lines = parsed
+    segments = _pointer_segments(pointer)
+    return _walk_targeted(top, segments, 0, lines)
+
+
+def locate(source: str | bytes, pointer: str) -> Entry | None:
+    """Find *pointer*'s location, visiting only nodes on the path to it."""
+    return _locate_in(_parse(source), pointer)
+
+
+# --- shared helpers ---
+
+
+def _pointer_segments(pointer: str) -> list[str]:
+    if not pointer:
+        return []
+    return [p.replace("~1", "/").replace("~0", "~") for p in pointer.split("/")[1:]]
+
+
+def _to_pointer(segments: list[str]) -> str:
+    return "/" + "/".join(_escape(s) for s in segments) if segments else ""
+
+
+def _byte_to_char_offsets(line: bytes) -> list[int]:
+    offsets = [0] * (len(line) + 1)
+    char_count = 0
+    for i, b in enumerate(line):
+        if b < 0x80 or b >= 0xC0:
+            char_count += 1
+        offsets[i + 1] = char_count
+    return offsets
+
+
+# --- full map (calculate) ---
+
+
+def _walk_all(
+    node: ts.Node,
+    segments: list[str],
+    result: TSourceMap,
+    byte_to_char: list[list[int]],
+    line_start_chars: list[int],
+    key_node: ts.Node | None = None,
+) -> None:
+    pointer = _to_pointer(segments)
+    result[pointer] = Entry(
+        value_start=_loc_precomputed(node.start_point, byte_to_char, line_start_chars),
+        value_end=_loc_precomputed(node.end_point, byte_to_char, line_start_chars),
+        key_start=_loc_precomputed(key_node.start_point, byte_to_char, line_start_chars)
+        if key_node
+        else None,
+        key_end=_loc_precomputed(key_node.end_point, byte_to_char, line_start_chars)
+        if key_node
+        else None,
+    )
+    if node.type == "object":
+        for pair in node.named_children:
+            if pair.type != "pair":
+                continue  # pragma: no cover
+            k = pair.child_by_field_name("key")
+            v = pair.child_by_field_name("value")
+            assert k is not None and k.text is not None
+            assert v is not None
+            key_text = json.loads(k.text.decode("utf-8"))
+            _walk_all(
+                v,
+                segments + [key_text],
+                result,
+                byte_to_char,
+                line_start_chars,
+                key_node=k,
+            )
+    elif node.type == "array":
+        for i, child in enumerate(node.named_children):
+            _walk_all(
+                child, segments + [str(i)], result, byte_to_char, line_start_chars
+            )
+
+
+def _loc_precomputed(
+    point: ts.Point, byte_to_char: list[list[int]], line_start_chars: list[int]
+) -> Location:
+    char_column = byte_to_char[point.row][point.column]
+    return Location(
+        line=point.row,
+        column=char_column,
+        position=line_start_chars[point.row] + char_column,
+    )
+
+
+# --- targeted lookup ---
+
+
+def _walk_targeted(
+    node: ts.Node,
+    segments: list[str],
+    idx: int,
+    lines: list[bytes],
+    key_node: ts.Node | None = None,
+) -> Entry:
+    if idx == len(segments):
+        return Entry(
+            value_start=_loc(node.start_point, lines),
+            value_end=_loc(node.end_point, lines),
+            key_start=_loc(key_node.start_point, lines)
+            if key_node is not None
+            else None,
+            key_end=_loc(key_node.end_point, lines) if key_node is not None else None,
+        )
+
+    if node.type == "object":
+        target_key = segments[idx]
+        for pair in node.named_children:
+            if pair.type != "pair":
+                continue  # pragma: no cover
+            k = pair.child_by_field_name("key")
+            assert k is not None and k.text is not None
+            key_text = json.loads(k.text.decode("utf-8"))
+            if key_text == target_key:
+                v = pair.child_by_field_name("value")
+                assert v is not None
+                return _walk_targeted(v, segments, idx + 1, lines, key_node=k)
+        # target_key not present -- this object is the closest ancestor
+        return _ancestor(node, lines, key_node)
+
+    if node.type == "array":
+        try:
+            target_index = int(segments[idx])
+        except ValueError:
+            target_index = -1
+        children = node.named_children
+        if 0 <= target_index < len(children):
+            return _walk_targeted(children[target_index], segments, idx + 1, lines)
+        return _ancestor(node, lines, key_node)
+
+    # A scalar, but the pointer wants to go deeper -- no such path; this
+    # value is the closest ancestor.
+    return _ancestor(node, lines, key_node)
+
+
+def _ancestor(node: ts.Node, lines: list[bytes], key_node: ts.Node | None) -> Entry:
+    # A fallback entry still carries key_start/key_end when this node is
+    # itself the value of an enclosing key -- matching the entry it would
+    # have gotten in the full map, at the pointer for that key.
+    return Entry(
+        value_start=_loc(node.start_point, lines),
+        value_end=_loc(node.end_point, lines),
+        key_start=_loc(key_node.start_point, lines) if key_node is not None else None,
+        key_end=_loc(key_node.end_point, lines) if key_node is not None else None,
+    )
+
+
+def _loc(point: ts.Point, lines: list[bytes]) -> Location:
+    # Only called O(depth) times per locate() call (a handful), so decoding
+    # fresh each time -- rather than precomputing a whole-document table --
+    # is cheap; the table only paid for itself when amortized over every
+    # node in the document, which locate() deliberately never visits.
+    line = lines[point.row]
+    char_column = len(line[: point.column].decode("utf-8"))
+    position = (
+        sum(len(prior.decode("utf-8")) for prior in lines[: point.row]) + char_column
+    )
+    return Location(line=point.row, column=char_column, position=position)

{parse_errors-0.5.0/parse_errors/yaml_source_map → parse_errors-0.6.0/parse_errors/json_source_map}/__main__.py

@@ -1,5 +1,6 @@
 if __name__ == "__main__":  # pragma: no cover
     import sys
+
     from . import calculate
 
     source = open(sys.argv[1]).read()