jsonc-document 2026.10.15__py3-none-any.whl

jsonc_document/__init__.py

@@ -0,0 +1,27 @@
+"""Typed JSONC parsing with comments and original source spans."""
+
+from jsonc_document._lexer import tokenize
+from jsonc_document._model import (
+    Document,
+    ErrorKind,
+    JSONCDecodeError,
+    Node,
+    Token,
+    TokenKind,
+)
+from jsonc_document._parser import loads, parse
+from jsonc_document.types import Scalar, Value
+
+__all__ = [
+    "Document",
+    "ErrorKind",
+    "JSONCDecodeError",
+    "Node",
+    "Scalar",
+    "Token",
+    "TokenKind",
+    "Value",
+    "loads",
+    "parse",
+    "tokenize",
+]

jsonc_document/_lexer.py

@@ -0,0 +1,201 @@
+"""JSONC lexical grammar with original source spans."""
+
+import math
+import re
+from collections.abc import Iterator
+
+from jsonc_document._model import (
+    ErrorKind,
+    JSONCDecodeError,
+    Token,
+    TokenKind,
+)
+
+_CONTROL_BOUNDARY = 0x20
+_UNICODE_ESCAPE_DIGITS = 4
+_WHITE_SPACE = " \t\r\n"
+_NUMBER = re.compile(
+    pattern=r"-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?"
+)
+_LITERAL = re.compile(pattern=r"true|false|null")
+_ESCAPES = {
+    '"': '"',
+    "\\": "\\",
+    "/": "/",
+    "b": "\b",
+    "f": "\f",
+    "n": "\n",
+    "r": "\r",
+    "t": "\t",
+}
+
+
+def _error(*, source: str, position: int, message: str) -> JSONCDecodeError:
+    """Build a position-bearing lexical error."""
+    return JSONCDecodeError(
+        message=message,
+        source=source,
+        position=position,
+        reason=ErrorKind.SYNTAX,
+    )
+
+
+def _string(*, source: str, start: int) -> tuple[int, str]:
+    """Read a double-quoted string and decode JSON escape sequences."""
+    index = start + 1
+    characters: list[str] = []
+    while index < len(source):
+        char = source[index]
+        index += 1
+        if char == '"':
+            decoded = "".join(characters)
+            return index, decoded.encode(
+                encoding="utf-16", errors="surrogatepass"
+            ).decode(encoding="utf-16", errors="surrogatepass")
+        if ord(char) < _CONTROL_BOUNDARY:
+            raise _error(
+                source=source,
+                position=index - 1,
+                message="Unescaped control character in string",
+            )
+        if char != "\\":
+            characters.append(char)
+            continue
+        if index == len(source):
+            break
+        char = source[index]
+        index += 1
+        if char == "u":
+            digits = source[index : index + _UNICODE_ESCAPE_DIGITS]
+            if len(digits) != _UNICODE_ESCAPE_DIGITS or any(
+                digit not in "0123456789abcdefABCDEF" for digit in digits
+            ):
+                raise _error(
+                    source=source,
+                    position=index,
+                    message="Invalid Unicode escape",
+                )
+            characters.append(chr(int(digits, base=16)))
+            index += _UNICODE_ESCAPE_DIGITS
+        elif char in _ESCAPES:
+            characters.append(_ESCAPES[char])
+        else:
+            raise _error(
+                source=source,
+                position=index - 1,
+                message="Invalid string escape",
+            )
+    raise _error(source=source, position=start, message="Unterminated string")
+
+
+def _number_value(*, source: str, start: int, raw: str) -> int | float:
+    """Decode a number while rejecting finite overflow and underflow."""
+    if raw == "-0":
+        return -0.0
+    try:
+        if not any(char in raw for char in ".eE"):
+            return int(raw, base=10)
+        value = float(raw)
+    except ValueError as exc:
+        raise JSONCDecodeError(
+            source=source,
+            position=start,
+            reason=ErrorKind.INTEGER_DIGITS,
+            message="Integer exceeds the interpreter's supported digit limit",
+        ) from exc
+    significant = (
+        raw.lstrip("-").lower().split(sep="e")[0].replace(".", "").strip("0")
+    )
+    if math.isinf(value) or (value == 0 and bool(significant)):
+        raise JSONCDecodeError(
+            source=source,
+            position=start,
+            reason=ErrorKind.NUMBER_RANGE,
+            message="Finite numeric token is outside binary64 range",
+        )
+    return value
+
+
+def _block_comment_end(*, source: str, index: int) -> int:
+    """Find a block comment's terminator or report its original start."""
+    close = source.find("*/", index + 2)
+    if close == -1:
+        raise _error(
+            source=source, position=index, message="Unterminated block comment"
+        )
+    return close + 2
+
+
+def _whitespace_end(*, source: str, index: int) -> int:
+    """Find the end of consecutive JSON whitespace."""
+    index += 1
+    while index < len(source) and source[index] in _WHITE_SPACE:
+        index += 1
+    return index
+
+
+def _line_comment_end(*, source: str, index: int) -> int:
+    """Find a CR or LF terminating a line comment."""
+    index += 2
+    while index < len(source) and source[index] not in "\r\n":
+        index += 1
+    return index
+
+
+def tokenize(*, source: str) -> Iterator[Token]:
+    """
+    Yield every source token, including comments and whitespace.
+
+    Lexical validity is checked; use ``parse`` to validate the complete
+    document grammar.
+    """
+    index = 0
+    while index < len(source):
+        start = index
+        char = source[index]
+        value: str | int | float | bool | None = None
+        if char in _WHITE_SPACE:
+            kind = TokenKind.WHITESPACE
+            index = _whitespace_end(source=source, index=index)
+        elif source.startswith("//", index):
+            kind = TokenKind.COMMENT
+            index = _line_comment_end(source=source, index=index)
+        elif source.startswith("/*", index):
+            kind = TokenKind.COMMENT
+            index = _block_comment_end(source=source, index=index)
+        elif char in "{}[]:,":
+            kind = TokenKind.PUNCTUATION
+            index += 1
+        elif char == '"':
+            kind = TokenKind.STRING
+            index, value = _string(source=source, start=start)
+        elif char in "-0123456789":
+            kind = TokenKind.NUMBER
+            match = _NUMBER.match(string=source, pos=index)
+            if match is None:
+                raise _error(
+                    source=source, position=start, message="Invalid number"
+                )
+            index = match.end()
+            value = _number_value(
+                source=source, start=start, raw=match.group()
+            )
+        else:
+            kind = TokenKind.LITERAL
+            match = _LITERAL.match(string=source, pos=index)
+            if match is None:
+                raise _error(
+                    source=source,
+                    position=start,
+                    message="Unexpected character",
+                )
+            index = match.end()
+            literals = {"true": True, "false": False, "null": None}
+            value = literals[match.group()]
+        yield Token(
+            kind=kind,
+            text=source[start:index],
+            start=start,
+            end=index,
+            value=value,
+        )

jsonc_document/_model.py

@@ -0,0 +1,142 @@
+"""Public document, token, and syntax tree models."""
+
+import dataclasses
+import enum
+import json
+from collections.abc import Callable
+from typing import override
+
+from jsonc_document.types import Scalar, Value
+
+
+class TokenKind(enum.Enum):
+    """The lexical categories retained in a document."""
+
+    PUNCTUATION = enum.auto()
+    STRING = enum.auto()
+    LITERAL = enum.auto()
+    NUMBER = enum.auto()
+    COMMENT = enum.auto()
+    WHITESPACE = enum.auto()
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Token:
+    """A token's original spelling and half-open Unicode source span."""
+
+    kind: TokenKind
+    text: str
+    start: int
+    end: int
+    value: Scalar
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Node:
+    """
+    A value and its syntax tree, retaining object keys in source order.
+
+    ``children`` contains array elements or object member values.
+    ``keys`` is empty for arrays and scalars. Collection delimiters are
+    included in the node's half-open source span.
+    """
+
+    value: Value
+    start: int
+    end: int
+    children: tuple["Node", ...]
+    keys: tuple[Token, ...]
+    commas: tuple[Token, ...]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Document:
+    """
+    A parsed JSONC source snapshot with every lexical token retained.
+
+    Mutating a returned Python collection does not rewrite source text.
+    Source editing is outside the document API.
+    """
+
+    source: str
+    root: Node
+    tokens: tuple[Token, ...]
+
+    @property
+    def value(self) -> Value:
+        """Return the decoded Python value."""
+        return self.root.value
+
+    @property
+    def comments(self) -> tuple[Token, ...]:
+        """Return line and block comments in source order."""
+        return tuple(
+            token for token in self.tokens if token.kind == TokenKind.COMMENT
+        )
+
+    def to_source(self) -> str:
+        """Return the original source, preserving all spelling and spacing."""
+        return self.source
+
+
+class ErrorKind(enum.Enum):
+    """Structured error categories for applications adapting
+    diagnostics.
+    """
+
+    SYNTAX = enum.auto()
+    DUPLICATE_KEY = enum.auto()
+    NUMBER_RANGE = enum.auto()
+    INTEGER_DIGITS = enum.auto()
+    DEPTH = enum.auto()
+
+
+class JSONCDecodeError(json.JSONDecodeError):
+    """
+    A syntax or data-policy error with original source coordinates.
+
+    ``pos`` is a zero-based character offset. ``lineno`` and ``colno``
+    are one-based and recognize CR, LF, and CRLF.
+    """
+
+    reason: ErrorKind
+    lineno: int
+    colno: int
+    args: tuple[object, ...]
+
+    def __init__(
+        self, *, message: str, source: str, position: int, reason: ErrorKind
+    ) -> None:
+        """Record a structured failure at its original source location."""
+        self.reason = reason
+        super().__init__(msg=message, doc=source, pos=position)
+        prefix = source[:position].replace("\r\n", "\n")
+        for ending in ("\r",):
+            prefix = prefix.replace(ending, "\n")
+        self.lineno = prefix.count("\n") + 1
+        self.colno = len(prefix.rsplit(sep="\n", maxsplit=1)[-1]) + 1
+        formatted = (
+            f"{message}: line {self.lineno} column {self.colno} "
+            f"(char {position})"
+        )
+        self.args = (formatted,)
+
+    @override
+    def __reduce__(
+        self,
+    ) -> tuple[
+        Callable[..., "JSONCDecodeError"], tuple[str, str, int, ErrorKind]
+    ]:
+        """Retain source coordinates and reason when copying or
+        serializing.
+        """
+        return _restore_error, (self.msg, self.doc, self.pos, self.reason)
+
+
+def _restore_error(
+    message: str, source: str, position: int, reason: ErrorKind
+) -> JSONCDecodeError:
+    """Restore a serialized exception through its keyword argument API."""
+    return JSONCDecodeError(
+        message=message, source=source, position=position, reason=reason
+    )

jsonc_document/_parser.py

@@ -0,0 +1,264 @@
+"""An iterative JSONC parser, independent of Python's recursion limit."""
+
+import dataclasses
+import enum
+
+from jsonc_document._lexer import tokenize
+from jsonc_document._model import (
+    Document,
+    ErrorKind,
+    JSONCDecodeError,
+    Node,
+    Token,
+    TokenKind,
+)
+from jsonc_document.types import Value
+
+_MAX_DEPTH = 512
+
+
+class _State(enum.Enum):
+    """The next grammar production expected inside a collection."""
+
+    KEY = enum.auto()
+    COLON = enum.auto()
+    VALUE = enum.auto()
+    ARRAY_VALUE = enum.auto()
+    SEPARATOR = enum.auto()
+
+
+@dataclasses.dataclass
+class _Frame:
+    """A collection currently being assembled."""
+
+    opening: Token
+    children: list[Node]
+    keys: list[Token]
+    commas: list[Token]
+    values: dict[str, Value]
+    pending_name: str
+    seen_keys: set[str]
+    pending_key: Token | None
+    state: _State
+
+    def expect(self, *, state: _State) -> None:
+        """Record the next production expected by this frame."""
+        self.state = state
+
+
+@dataclasses.dataclass
+class _Parser:
+    """Consume syntax tokens while retaining their original positions."""
+
+    source: str
+    tokens: tuple[Token, ...]
+    frames: list[_Frame]
+    root: Node | None
+
+    def error(
+        self, *, token: Token, message: str, reason: ErrorKind
+    ) -> JSONCDecodeError:
+        """Create an error at the offending syntax token."""
+        return JSONCDecodeError(
+            message=message,
+            source=self.source,
+            position=token.start,
+            reason=reason,
+        )
+
+    def accept(self, *, node: Node) -> None:
+        """Attach a completed node to its parent or the document root."""
+        if not bool(self.frames):
+            self.root = node
+            return
+        frame = self.frames[-1]
+        frame.children.append(node)
+        if frame.pending_key is not None:
+            frame.keys.append(frame.pending_key)
+            frame.values[frame.pending_name] = node.value
+            frame.pending_key = None
+        frame.expect(state=_State.SEPARATOR)
+
+    def close(self, *, token: Token) -> None:
+        """Finish the current collection and attach its complete tree."""
+        frame = self.frames.pop()
+        value: Value
+        if frame.opening.text == "[":
+            value = [child.value for child in frame.children]
+        else:
+            value = frame.values
+        self.accept(
+            node=Node(
+                value=value,
+                start=frame.opening.start,
+                end=token.end,
+                children=tuple(frame.children),
+                keys=tuple(frame.keys),
+                commas=tuple(frame.commas),
+            )
+        )
+
+    def advance(self, *, token: Token) -> bool:
+        """Consume collection punctuation and keys before reading a
+        value.
+        """
+        frame = self.frames[-1]
+        closing = "]" if frame.opening.text == "[" else "}"
+        if frame.state == _State.SEPARATOR:
+            if token.text == closing:
+                self.close(token=token)
+            elif token.text == ",":
+                frame.commas.append(token)
+                frame.expect(
+                    state=_State.ARRAY_VALUE if closing == "]" else _State.KEY
+                )
+            else:
+                raise self.error(
+                    token=token,
+                    message="Expected comma or closing delimiter",
+                    reason=ErrorKind.SYNTAX,
+                )
+            return True
+        if (
+            frame.state in {_State.KEY, _State.ARRAY_VALUE}
+            and token.text == closing
+        ):
+            if bool(frame.commas) and len(frame.commas) == len(frame.children):
+                raise self.error(
+                    token=token,
+                    message="Trailing commas are not allowed",
+                    reason=ErrorKind.SYNTAX,
+                )
+            self.close(token=token)
+            return True
+        if frame.state == _State.KEY:
+            self.read_key(token=token)
+            return True
+        if frame.state == _State.COLON:
+            if token.text != ":":
+                raise self.error(
+                    token=token,
+                    message="Expected colon",
+                    reason=ErrorKind.SYNTAX,
+                )
+            frame.expect(state=_State.VALUE)
+            return True
+        return False
+
+    def read_key(self, *, token: Token) -> None:
+        """Decode a member name and reject repeated keys."""
+        frame = self.frames[-1]
+        if token.kind != TokenKind.STRING or not isinstance(token.value, str):
+            raise self.error(
+                token=token,
+                message="Expected an object member name",
+                reason=ErrorKind.SYNTAX,
+            )
+        if token.value in frame.seen_keys:
+            raise self.error(
+                token=token,
+                message=f"Duplicate key {token.value!r}",
+                reason=ErrorKind.DUPLICATE_KEY,
+            )
+        frame.seen_keys.add(token.value)
+        frame.pending_key = token
+        frame.pending_name = token.value
+        frame.expect(state=_State.COLON)
+
+    def read_value(self, *, token: Token) -> None:
+        """Read a scalar or open another collection."""
+        if token.text in {"[", "{"}:
+            if len(self.frames) == _MAX_DEPTH:
+                raise self.error(
+                    token=token,
+                    message="Input exceeds the supported nesting depth",
+                    reason=ErrorKind.DEPTH,
+                )
+            self.frames.append(
+                _Frame(
+                    opening=token,
+                    children=[],
+                    keys=[],
+                    commas=[],
+                    values={},
+                    pending_name="",
+                    seen_keys=set(),
+                    pending_key=None,
+                    state=_State.ARRAY_VALUE
+                    if token.text == "["
+                    else _State.KEY,
+                )
+            )
+            return
+        value: Value = token.value
+        if token.kind not in {
+            TokenKind.NUMBER,
+            TokenKind.STRING,
+            TokenKind.LITERAL,
+        }:
+            raise self.error(
+                token=token,
+                message="Expected a JSONC value",
+                reason=ErrorKind.SYNTAX,
+            )
+        self.accept(
+            node=Node(
+                value=value,
+                start=token.start,
+                end=token.end,
+                children=(),
+                keys=(),
+                commas=(),
+            )
+        )
+
+    def parse(self) -> Node:
+        """Build a complete syntax tree or report the first invalid
+        token.
+        """
+        for token in self.tokens:
+            if self.root is not None and not bool(self.frames):
+                raise self.error(
+                    token=token,
+                    message="Unexpected data after the root value",
+                    reason=ErrorKind.SYNTAX,
+                )
+            if bool(self.frames) and self.advance(token=token):
+                continue
+            self.read_value(token=token)
+        if self.root is None:
+            message = (
+                "Unterminated collection"
+                if bool(self.frames)
+                else "Expected a JSONC value"
+            )
+            raise JSONCDecodeError(
+                message=message,
+                source=self.source,
+                position=len(self.source),
+                reason=ErrorKind.SYNTAX,
+            )
+        return self.root
+
+
+def parse(*, source: str) -> Document:
+    """
+    Parse a JSONC document, retaining tokens, comments, and source
+    spans.
+
+    Duplicate keys and finite numbers outside binary64 range are rejected.
+    Up to 512 nested collections are accepted. No source is executed.
+    """
+    tokens = tuple(tokenize(source=source))
+    syntax = tuple(
+        token
+        for token in tokens
+        if token.kind not in {TokenKind.COMMENT, TokenKind.WHITESPACE}
+    )
+    root = _Parser(source=source, tokens=syntax, frames=[], root=None).parse()
+    return Document(source=source, root=root, tokens=tokens)
+
+
+def loads(*, source: str) -> Value:
+    """Decode a JSONC string to ordinary Python values."""
+    return parse(source=source).value

jsonc_document/types.py

@@ -0,0 +1,7 @@
+"""Public recursive types for decoded JSONC values."""
+
+type Scalar = str | int | float | bool | None
+"""A decoded string, number, Boolean, or null value."""
+
+type Value = Scalar | list[Value] | dict[str, Value]
+"""A decoded scalar or recursively nested JSONC collection."""

jsonc_document-2026.10.15.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: jsonc-document
+Version: 2026.10.15
+Summary: Typed JSONC parsing with preserved comments, tokens, and source spans.
+Author-email: Adam Dangoor <adamdangoor@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://adamtheturtle.github.io/jsonc-document/
+Project-URL: Source, https://github.com/adamtheturtle/jsonc-document
+Keywords: comments,jsonc,parser
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Dynamic: license-file
+
+jsonc-document
+==============
+
+A typed JSONC parser that preserves comments, tokens, and source spans.
+It requires Python 3.12 or newer and has no runtime dependencies.
+
+Installation
+------------
+
+.. code-block:: console
+
+    pip install jsonc-document
+
+Usage
+-----
+
+.. code-block:: python
+
+    """Parse JSONC while preserving source comments."""
+
+    import jsonc_document
+
+    source = '// heading\n{"count": 2}'
+    document = jsonc_document.parse(source=source)
+    assert document.value == {"count": 2}
+    assert document.comments[0].text == "// heading"
+    assert document.to_source() == source
+
+Use ``loads(source=...)`` when only Python values are needed.
+See the `documentation <https://adamtheturtle.github.io/jsonc-document/>`_ for the full API and parsing policies.

jsonc_document-2026.10.15.dist-info/RECORD

@@ -0,0 +1,11 @@
+jsonc_document/__init__.py,sha256=DQhCgABvaLCAjJcaX3ZvHE2iNGDJc2uB6I74W0gu_Yg,514
+jsonc_document/_lexer.py,sha256=8rPMMLj3yfnzw2bzi5b7iCJet9FZF73awZfvRKTUevo,6411
+jsonc_document/_model.py,sha256=vIGk2B95mgEi3hnkaXAe4evakQ-J0z7st6dDVbqUnrY,3888
+jsonc_document/_parser.py,sha256=Q1wrrAqgeKlOJPXpZ22VUEBNFdPxbby9TxGHz07hiOc,8321
+jsonc_document/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jsonc_document/types.py,sha256=6AniLLgjI4U-4UEtXDyt1UoFd6hLGEkUzetHIqh42Xw,275
+jsonc_document-2026.10.15.dist-info/licenses/LICENSE,sha256=cnfgEzv8YMudbgPysNfgAdqeOo4zf0y2C3Ctw4RgEE4,1069
+jsonc_document-2026.10.15.dist-info/METADATA,sha256=jB_US4O61NSDzKBx7W_-mfWjGK9wq3uWHGuD3-3Lna4,1584
+jsonc_document-2026.10.15.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jsonc_document-2026.10.15.dist-info/top_level.txt,sha256=s1329lphqq1OrAM94ils1Sd5LRf6a72s9ZgjhFaiNSQ,15
+jsonc_document-2026.10.15.dist-info/RECORD,,

jsonc_document-2026.10.15.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jsonc_document-2026.10.15.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Dangoor
+
+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.

jsonc_document-2026.10.15.dist-info/top_level.txt

@@ -0,0 +1 @@
+jsonc_document