parse-errors 0.0.0a1__tar.gz → 0.5.0__tar.gz

parse_errors-0.5.0/.github/workflows/build.yml

@@ -0,0 +1,75 @@
+name: Build
+on: 
+  push:
+    branches:
+      - master
+      - main
+      - tmp-*
+    tags:
+      - v*
+  pull_request:
+
+env:
+  UV_SYSTEM_PYTHON: 1
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        os: [macOS-latest, ubuntu-latest, windows-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set Up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - uses: astral-sh/setup-uv@v3
+      - name: Install
+        run: |
+          uv pip install -e .[test,dev]
+      - name: Test
+        run: |
+          git config --global user.name "Unit Test"
+          git config --global user.email "example@example.com"
+          make test
+      - name: Lint
+        run: |
+          make lint
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - uses: astral-sh/setup-uv@v3
+      - name: Install
+        run: uv pip install build
+      - name: Build
+        run: python -m build
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

parse_errors-0.5.0/.gitignore

@@ -0,0 +1,113 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv*
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# Visual Studio Code
+.vscode/
+
+# Vim swapfiles
+*.sw[op]
+
+# Setuptools-scm
+_version.py

parse_errors-0.5.0/.vars.ini

@@ -0,0 +1,10 @@
+[vars]
+pypi_name = parse-errors
+short_desc = re-raise parse errors with filename and line number
+url = https://github.com/advice-animal/parse-errors/
+author = Tim Hatch
+author_email = tim@timhatch.com
+package = parse_errors
+year = 2026
+author_website = https://timhatch.com/
+

parse_errors-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Hatch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parse_errors-0.5.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include *.md LICENSE
+recursive-include parse_errors *.txt

parse_errors-0.5.0/Makefile

@@ -0,0 +1,37 @@
+ifeq ($(OS),Windows_NT)
+    ACTIVATE:=.venv/Scripts/activate
+else
+    ACTIVATE:=.venv/bin/activate
+endif
+
+UV:=$(shell uv --version)
+ifdef UV
+	VENV:=uv venv
+	PIP:=uv pip
+else
+	VENV:=python -m venv
+	PIP:=python -m pip
+endif
+
+.venv:
+	$(VENV) .venv
+
+.PHONY: setup
+setup: .venv
+	source $(ACTIVATE) && $(PIP) install -Ue .[dev,test]
+
+.PHONY: test
+test:
+	python -m coverage run -m pytest $(TESTOPTS)
+	python -m coverage report
+
+.PHONY: format
+format:
+	ruff format
+	ruff check --fix
+
+.PHONY: lint
+lint:
+	ruff check
+	python -m checkdeps --allow-names parse_errors parse_errors
+	mypy --strict --install-types --non-interactive parse_errors

parse_errors-0.5.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: parse-errors
+Version: 0.5.0
+Summary: re-raise parse errors with filename and line number
+Home-page: https://github.com/advice-animal/parse-errors/
+Author: Tim Hatch
+Author-email: tim@timhatch.com
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: json-source-map
+Requires-Dist: pyyaml
+Requires-Dist: tree-sitter
+Requires-Dist: tree-sitter-toml
+Provides-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: tox==4.50.0; extra == "dev"
+Requires-Dist: tox-uv==1.33.4; extra == "dev"
+Requires-Dist: types-pyyaml; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage>=6; extra == "test"
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: msgspec; extra == "test"
+Dynamic: license-file
+
+# parse-errors
+
+
+# Version Compat
+
+This library is compatile 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/README.md

@@ -0,0 +1,18 @@
+# parse-errors
+
+
+# Version Compat
+
+This library is compatile 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/__init__.py

@@ -0,0 +1,13 @@
+"""re-raise parse errors with filename and line number."""
+
+from .context import ParseContext, ParseError
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    __version__ = "dev"
+
+__all__ = [
+    "ParseContext",
+    "ParseError",
+]

parse_errors-0.5.0/parse_errors/_jsonpath.py

@@ -0,0 +1,70 @@
+"""Convert JSONPath expressions to JSON Pointer (RFC 6901)."""
+
+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
+    r"|\[(?P<idx>\d+)\]"  # [0]
+    r"|\[\'(?P<sq>[^\']*)\'\]"  # ['key']
+    r'|\["(?P<dq>[^"]*)"\]'  # ["key"]
+)
+
+# Pattern to extract JSONPath from msgspec-style error messages: "... - at `$.foo.bar`"
+_AT_PATH = re.compile(r" - at `(\$[^`]*)`")
+
+
+def jsonpath_to_pointer(jsonpath: str) -> str:
+    """Convert a JSONPath string like ``$.foo[0].bar`` to a JSON Pointer like ``/foo/0/bar``.
+
+    Only supports simple dot-notation and bracket-index forms as produced by
+    msgspec.  Does not support filter expressions or wildcards.
+
+    Args:
+        jsonpath: A JSONPath string starting with ``$``.
+
+    Returns:
+        A JSON Pointer string (RFC 6901), e.g. ``/foo/0/bar``.
+    """
+    if jsonpath == "$":
+        return ""
+    if not jsonpath.startswith("$"):
+        raise ValueError(f"JSONPath must start with '$', got: {jsonpath!r}")
+
+    tail = jsonpath[1:]  # strip leading $
+    parts: list[str] = []
+
+    pos = 0
+    while pos < len(tail):
+        m = _STEP.match(tail, pos)
+        if m is None:
+            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")
+        parts.append(_escape(name))
+        pos = m.end()
+
+    return "/" + "/".join(parts) if parts else ""
+
+
+def extract_jsonpath(message: str) -> str | None:
+    """Extract a JSONPath expression from an error message.
+
+    Looks for the pattern ``- at `$.path``` as used by msgspec.
+
+    Args:
+        message: The exception message string.
+
+    Returns:
+        The JSONPath string if found, otherwise ``None``.
+    """
+    m = _AT_PATH.search(message)
+    return m.group(1) if m else None
+
+
+def _escape(segment: str) -> str:
+    return segment.replace("~", "~0").replace("/", "~1")

parse_errors-0.5.0/parse_errors/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
+
+__commit_id__ = commit_id = 'g9fcc0e192'

parse_errors-0.5.0/parse_errors/context.py

@@ -0,0 +1,83 @@
+"""Context manager for better parse error messages."""
+
+from __future__ import annotations
+
+import os
+import contextlib
+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
+
+__all__ = ["ParseError", "ParseContext"]
+
+
+class ParseError(Exception):
+    """A parse or validation error augmented with filename and line number."""
+
+    def __init__(
+        self, message: str, filename: str | os.PathLike[str], line: int, column: int = 0
+    ):
+        self.filename = str(filename)
+        self.line = line
+        self.column = column
+        super().__init__(message)
+
+
+@contextlib.contextmanager
+def ParseContext(
+    filename: str | os.PathLike[str],
+    *,
+    data: str | bytes | None = None,
+    format: str | None = None,
+) -> Iterator[None]:
+    """Context manager that re-raises parse/validation errors with location info.
+
+    Catches exceptions whose message contains a JSONPath (e.g. as emitted by
+    msgspec) and re-raises a :class:`ParseError` with the filename and
+    1-based line number derived from the file's source map.
+
+    Args:
+        filename: Path to the file being parsed.
+        data: The file contents as a string or bytes (UTF-8).  If provided, the
+              file is not read from disk.  Regardless of type, reported
+              locations (line, column) are always in characters, not bytes.
+        format: One of ``"json"``, ``"yaml"``, or ``"toml"``.  If omitted the
+                format is inferred from the file extension.
+    """
+    try:
+        yield
+    except Exception as exc:
+        message = str(exc)
+        # 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.
+        jsonpath = extract_jsonpath(message)
+        if jsonpath is None:
+            raise
+
+        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
+
+        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
+
+        loc = entry.value_start
+        # Lines are 0-based in source maps; convert to 1-based for humans.
+        raise ParseError(
+            f"{path}:{loc.line + 1}:{loc.column + 1}: {message}",
+            filename=path,
+            line=loc.line + 1,
+            column=loc.column + 1,
+        ) from exc

parse_errors-0.5.0/parse_errors/json_source_map/__init__.py

@@ -0,0 +1,25 @@
+"""Thin wrapper around the json-source-map package that returns our own types."""
+
+from __future__ import annotations
+
+import json_source_map as _ext
+
+from ..source_map import Entry, Location, TSourceMap
+
+
+def calculate(source: str) -> TSourceMap:
+    """Calculate the source map for a JSON document."""
+    return {
+        pointer: Entry(
+            value_start=_loc(e.value_start),
+            value_end=_loc(e.value_end),
+            key_start=_loc(e.key_start) if e.key_start is not None else None,
+            key_end=_loc(e.key_end) if e.key_end is not None else None,
+        )
+        for pointer, e in _ext.calculate(source).items()
+    }
+
+
+def _loc(ext: _ext.Location) -> Location:
+    """Translate to our internal structure."""
+    return Location(line=ext.line, column=ext.column, position=ext.position)

parse_errors-0.5.0/parse_errors/json_source_map/__main__.py

@@ -0,0 +1,7 @@
+if __name__ == "__main__":  # pragma: no cover
+    import sys
+    from . import calculate
+
+    source = open(sys.argv[1]).read()
+    for pointer, entry in calculate(source).items():
+        print(f"{pointer!r:40s} {entry}")

parse_errors-0.5.0/parse_errors/source_map.py

@@ -0,0 +1,77 @@
+"""Source map types and utilities for parse_errors."""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+from typing import Dict, Optional
+
+
+# These are identical to the ones in json-source-map, but I feel icky exporting
+# some other project's types because they may change.
+
+
+@dataclasses.dataclass
+class Location:
+    line: int  # 0-based line number
+    column: int  # 0-based character offset within the line (not bytes)
+    position: int  # 0-based character offset from start of document (not bytes)
+
+
+@dataclasses.dataclass
+class Entry:
+    value_start: Location
+    value_end: Location
+    key_start: Optional[Location] = None
+    key_end: Optional[Location] = None
+
+
+TSourceMap = Dict[str, Entry]
+
+
+def detect_format(path: Path) -> str | None:
+    """Detect the format of a file based on its extension."""
+    suffix = path.suffix.lower()
+    return {
+        ".json": "json",
+        ".toml": "toml",
+        ".yaml": "yaml",
+        ".yml": "yaml",
+    }.get(suffix)
+
+
+def build_source_map(source: str | bytes, fmt: str) -> TSourceMap:
+    """Build a source map for the given source in the given format."""
+    if fmt == "toml":
+        from . import toml_source_map
+
+        return toml_source_map.calculate(source)
+    elif fmt in ("yaml", "yml"):
+        from . import yaml_source_map
+
+        return yaml_source_map.calculate(
+            source.decode("utf-8") if isinstance(source, bytes) else source
+        )
+    elif fmt == "json":
+        from . import json_source_map
+
+        return json_source_map.calculate(
+            source.decode("utf-8") if isinstance(source, bytes) else source
+        )
+    else:
+        raise ValueError(f"Unknown format: {fmt!r}")
+
+
+def closest_entry(source_map: TSourceMap, pointer: str) -> Entry | None:
+    """Return the source map entry for ``pointer``, falling back to the longest prefix."""
+    if pointer in source_map:
+        return source_map[pointer]
+
+    # Walk up the pointer path until we find a match.
+    parts = pointer.split("/")  # e.g. ['', 'foo', 'bar']
+    for length in range(len(parts) - 1, 0, -1):
+        candidate = "/".join(parts[:length])
+        if candidate in source_map:
+            return source_map[candidate]
+
+    return None