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

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

@@ -0,0 +1,73 @@
+name: Build
+on: 
+  push:
+    branches:
+      - master
+      - main
+      - tmp-*
+    tags:
+      - v*
+  pull_request:
+
+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 sync --extra test --extra 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 sync --extra test --extra dev
+      - name: Build
+        run: uv 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')
+    environment: pypi
+    permissions:
+      contents: read
+      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.6.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.6.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.6.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.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.6.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.6.0/parse_errors/_jsonpath.py

@@ -0,0 +1,71 @@
+"""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}"
+            )
+        for group in ("name", "sq", "dq", "idx"):
+            if (name := m.group(group)) is not None:
+                break
+        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.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'