jsonc-document 2026.10.15__tar.gz

jsonc_document-2026.10.15/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+tests/conformance/** -text -whitespace
+.git_archival.txt export-subst

jsonc_document-2026.10.15/.github/dependabot.yml

@@ -0,0 +1,20 @@
+---
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    cooldown:
+      default-days: 7
+    directory: /
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+  - package-ecosystem: github-actions
+    cooldown:
+      default-days: 7
+    directory: /
+    schedule:
+      interval: daily
+
+  # Dependabot cannot read prek.toml yet:
+  # https://github.com/dependabot/dependabot-core/issues/14624

jsonc_document-2026.10.15/.github/workflows/autofix.yml

@@ -0,0 +1,40 @@
+---
+name: autofix.ci
+
+on:
+  pull_request: {}
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+
+      - name: Run fixers
+        uses: j178/prek-action@1382ad72dea72f9d53832f2bcb65b3e87a947204  # v3.0.1
+        with:
+          # Matches the ``prek`` pin in ``pyproject.toml``; keep them in
+          # sync. prek reimplements the ``pre-commit-hooks`` checks
+          # natively, so a version difference changes their verdicts and
+          # not merely their scheduling (issue 4013).
+          prek-version: 0.5.5
+          extra-args: >-
+            --all-files --hook-stage pre-commit --no-fail-fast --verbose
+        env:
+          UV_NO_CACHE: '1'
+          UV_PYTHON: 3.14
+
+      - uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a  # v1.3.4
+        if: always()

jsonc_document-2026.10.15/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  workflow_dispatch: {}
+
+permissions: {}
+
+concurrency:
+  group: ci-pr-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.12', '3.13', '3.14', '3.15']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        with:
+          enable-cache: true
+      - name: Test with complete branch coverage
+        run: uv run --python '${{ matrix.python }}' --group dev pytest --cov --cov-report=term-missing
+  completion-ci:
+    needs: [test]
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check every test job
+        env:
+          RESULT: ${{ needs.test.result }}
+        run: test "$RESULT" = success

jsonc_document-2026.10.15/.github/workflows/dependabot-merge.yml

@@ -0,0 +1,19 @@
+---
+
+name: Dependabot auto-merge
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    steps:
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr merge --auto --merge "$PR_URL"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GH_TOKEN: ${{secrets.GITHUB_TOKEN}}

jsonc_document-2026.10.15/.github/workflows/lint.yml

@@ -0,0 +1,50 @@
+---
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  schedule:
+    - cron: 0 1 * * *
+  workflow_dispatch: {}
+
+permissions: {}
+
+concurrency:
+  group: lint-pr-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+        group: [fast, typecheck, pylint, docs]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        with:
+          enable-cache: true
+      - uses: j178/prek-action@1382ad72dea72f9d53832f2bcb65b3e87a947204  # v3.0.1
+        with:
+          prek-version: 0.5.5
+          extra-args: --all-files --group ${{ matrix.group }} --verbose
+        env:
+          UV_PYTHON: ${{ matrix.python }}
+  completion-lint:
+    needs: [lint]
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check every lint job
+        env:
+          RESULT: ${{ needs.lint.result }}
+        run: test "$RESULT" = success

jsonc_document-2026.10.15/.github/workflows/publish-site.yml

@@ -0,0 +1,34 @@
+---
+name: Deploy documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+# We often have a long CI queue, so cancel superseded runs for a PR as soon
+# as a new commit is pushed. Non-PR runs (push on main) fall back to the
+# unique run ID so they never cancel each other.
+concurrency:
+  group: deploy-docs-pr-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ github.ref_name == 'main' && 'github-pages' || 'development' }}
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: sphinx-notes/pages@39eda6fbd411e7cee6e814ef84a69bd806346e92  # v3
+        with:
+          documentation_path: docs/source
+          pyproject_group: dev
+          python_version: '3.13'
+          sphinx_build_options: -W
+          publish: ${{ github.ref_name == 'main' }}
+          enablement: ${{ github.ref_name == 'main' }}

jsonc_document-2026.10.15/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+---
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+      - name: Validate release
+        run: |
+          uv run --group dev pytest --cov --cov-report=term-missing
+          uv build
+          uv run --group release check-wheel-contents dist/*.whl
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+  publish:
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to PyPI using trusted publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1

jsonc_document-2026.10.15/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.coverage*
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.pyrefly_cache/
+build/
+dist/
+docs/build/
+styles/*
+!styles/snapper/
+.DS_Store
+uv.lock

jsonc_document-2026.10.15/.python-version

@@ -0,0 +1 @@
+3.14

jsonc_document-2026.10.15/.vale.ini

@@ -0,0 +1,26 @@
+StylesPath = styles
+MinAlertLevel = error
+
+Packages = https://github.com/tbhb/vale-ai-tells/releases/download/v1.29.0/ai-tells.zip
+
+[*.{rst,md}]
+BasedOnStyles = ai-tells, snapper
+snapper.SemanticLineBreaks = error
+
+# These rules misclassify established technical, example, or release-note prose
+# in this repository. All other ai-tells rules remain enforced.
+ai-tells.AbsoluteAssertions = NO
+ai-tells.AnthropomorphicJustification = NO
+ai-tells.CataphoricForecasting = NO
+ai-tells.ColonUsage = NO
+ai-tells.ContrastiveFormulas = NO
+ai-tells.DoubleHyphen = NO
+ai-tells.EmphaticCopula = NO
+ai-tells.EmptyPadding = NO
+ai-tells.EmptyPaddingStacked = NO
+ai-tells.FormalRegister = NO
+ai-tells.FormalTransitions = NO
+ai-tells.OverusedVocabulary = NO
+ai-tells.SemicolonUsage = NO
+ai-tells.ShipOveruse = NO
+ai-tells.VerbTricolon = NO

jsonc_document-2026.10.15/CONTRIBUTING.rst

@@ -0,0 +1,27 @@
+Contributing
+============
+
+Use the pinned uv version from ``pyproject.toml`` and Python 3.14 for development.
+
+.. code-block:: console
+
+    uv sync --group dev
+    uv run prek install
+    uv run pytest --cov --cov-report=term-missing
+    uv run prek run --all-files --group fast
+    uv run prek run --all-files --group typecheck
+    uv run prek run --all-files --group pylint
+    uv run prek run --all-files --group docs
+
+Source and tests require complete statement and branch coverage.
+Public APIs require complete type information, checked by Mypy, Pyright, Pyrefly, and ty.
+Ruff, Pylint, documentation checks, dependency checks, and package metadata checks run through prek.
+CI tests Python 3.12 through 3.15 on Linux and Windows.
+Add regression tests through the public API when changing parser behavior.
+
+The vendored JSONC test corpus retains its upstream MIT license and source revision.
+Tests treat duplicate keys as a documented rejection policy.
+Do not add parsing exceptions or suppressions to make conformance tests pass.
+
+To release, assemble Towncrier notes, validate the exact commit, tag it with a calendar version, and publish a GitHub release.
+The release workflow tests, builds, checks, and publishes the wheel and source distribution using PyPI trusted publishing.

jsonc_document-2026.10.15/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/MANIFEST.in

@@ -0,0 +1,6 @@
+include *.py
+include *.toml
+recursive-include tests *.py *.json *.jsonc *.js *.txt *.md *.errorSpec *.editorconfig
+recursive-include docs *.rst *.md
+recursive-include styles/snapper *.yml
+include tests/conformance/LICENSE

jsonc_document-2026.10.15/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,30 @@
+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/conftest.py

@@ -0,0 +1 @@
+"""Repository-wide pytest configuration."""

jsonc_document-2026.10.15/docs/__init__.py

@@ -0,0 +1 @@
+"""Project documentation."""

jsonc_document-2026.10.15/docs/source/__init__.py

@@ -0,0 +1 @@
+"""Project documentation."""

jsonc_document-2026.10.15/docs/source/changelog/2026.10.15.md

@@ -0,0 +1,3 @@
+# 2026.10.15
+
+Initial release with typed JSONC documents, comments, tokens, and source spans.

jsonc_document-2026.10.15/docs/source/conf.py

@@ -0,0 +1,22 @@
+"""Sphinx documentation configuration."""
+
+project = "jsonc-document"
+author = "Adam Dangoor"
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
+    "sphinxcontrib.spelling",
+]
+html_theme = "furo"
+nitpicky = True
+spelling_word_list_filename = "../../spelling_private_dict.txt"
+linkcheck_retries = 5
+
+autodoc_type_aliases = {
+    "Value": "jsonc_document.types.Value",
+    "Scalar": "jsonc_document.types.Scalar",
+}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

jsonc_document-2026.10.15/docs/source/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../CONTRIBUTING.rst

jsonc_document-2026.10.15/docs/source/index.rst

@@ -0,0 +1,24 @@
+jsonc-document
+==============
+
+.. include:: ../../README.rst
+   :start-after: ==============
+
+API reference
+-------------
+
+.. automodule:: jsonc_document
+   :members:
+   :imported-members:
+   :undoc-members:
+   :exclude-members: Scalar, Value
+
+.. automodule:: jsonc_document.types
+   :members:
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   parsing
+   changelog/2026.10.15

jsonc_document-2026.10.15/docs/source/parsing.rst

@@ -0,0 +1,40 @@
+Parsing contract
+================
+
+JSONC adds ``//`` line comments and ``/* ... */`` block comments to JSON.
+Comments are allowed wherever JSON whitespace is allowed.
+Line comments end at CR or LF, including CRLF.
+U+2028 and U+2029 do not end a line comment and are allowed inside strings.
+Trailing commas, unquoted names, single-quoted strings, hexadecimal numbers, ``NaN``, and ``Infinity`` are rejected.
+Whitespace outside strings and comments is limited to space, tab, CR, and LF.
+
+Duplicate object keys are rejected, including equivalent escaped spellings.
+Finite numeric literals that overflow or underflow binary64 are rejected.
+Negative zero is preserved.
+UTF-16 surrogate pairs are combined; lone surrogates are retained for callers to apply their own Unicode policy.
+Integers are arbitrary precision within the interpreter's decimal digit limit.
+The nesting limit is 512 collections, enforced without recursive parsing.
+
+Use ``tokenize(source=...)`` to inspect every token, including whitespace.
+Token and node spans use half-open Unicode character offsets into the original source.
+``tokenize`` validates individual tokens; ``parse`` validates the complete grammar.
+
+``JSONCDecodeError`` provides ``reason``, ``msg``, ``doc``, ``pos``, ``lineno``, and ``colno``.
+Positions refer to the original input, with one-based lines and columns and zero-based offsets.
+CR, LF, and CRLF are recognized when reporting positions.
+
+The document is a source snapshot.
+``to_source()`` returns the original text; changing a returned Python collection does not edit that text.
+Source editing is outside this library's API.
+The implementation is independent of JSON5 and has no runtime dependencies.
+
+Related libraries
+-----------------
+
+`jsonc-parser <https://github.com/NickolaiBeloguzov/jsonc-parser>`_ strips comments before decoding.
+Its existing `comment retention request <https://github.com/NickolaiBeloguzov/jsonc-parser/issues/8>`_ describes the missing capability.
+`json-with-comments <https://github.com/n-takumasa/json-with-comments>`_ can add comments when writing, but discards them when loading.
+``jsonc-document`` instead exposes the original comment tokens and syntax spans for callers to apply their own attachment policies.
+
+The grammar follows the `JSONC draft specification <https://jsonc.org/>`_ with trailing commas disabled.
+The documented duplicate-key, numeric-range, and nesting policies further constrain accepted data.