docxtpl-lint 1.1.0__tar.gz

docxtpl_lint-1.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,31 @@
+name: Bug report / false positive
+description: docxtpl-lint reported something wrong, missed a problem, or crashed
+labels: [bug]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options: [False positive, Missed problem, Crash, Other]
+    validations: { required: true }
+  - type: textarea
+    id: output
+    attributes:
+      label: docxtpl-lint output
+      description: Paste the command and its output (`--no-color`).
+      render: text
+    validations: { required: true }
+  - type: textarea
+    id: docxtpl
+    attributes:
+      label: What docxtpl does with this template
+      description: Does `DocxTemplate(...).render(context)` raise, or is the output wrong? Paste the error if any.
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      placeholder: docxtpl-lint 0.1.0, docxtpl 0.20.2, Python 3.12
+    validations: { required: true }
+  - type: markdown
+    attributes:
+      value: Please attach a **minimal .docx** that reproduces the problem (remove confidential content). Without one we usually cannot confirm the behaviour.

docxtpl_lint-1.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

docxtpl_lint-1.1.0/.github/ISSUE_TEMPLATE/rule_request.yml

@@ -0,0 +1,20 @@
+name: Rule request
+description: Propose a new deterministic check
+labels: [rule-request]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Template mistake
+      description: What do people write in the .docx, and what goes wrong?
+    validations: { required: true }
+  - type: textarea
+    id: behaviour
+    attributes:
+      label: What docxtpl does
+      description: Error message, or how the rendered output is wrong. Link upstream issues if any.
+    validations: { required: true }
+  - type: textarea
+    id: detect
+    attributes:
+      label: How it could be detected without false positives

docxtpl_lint-1.1.0/.github/pull_request_template.md

@@ -0,0 +1,3 @@
+- [ ] `pytest` and `ruff check . && ruff format --check .` pass
+- [ ] New/changed docxtpl rule has a case in `tests/rule_cases.py` (rendered with real docxtpl)
+- [ ] `CHANGELOG.md` updated (Unreleased)

docxtpl_lint-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 3 * * 1"  # weekly: catch docxtpl upstream changes
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check . && ruff format --check .
+      - run: pytest -q
+  docxtpl-upstream:
+    # Ground truth against the newest docxtpl release and upstream master.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    strategy:
+      matrix:
+        docxtpl: ["docxtpl", "git+https://github.com/elapouya/python-docx-template.git"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" && pip install --upgrade "${{ matrix.docxtpl }}"
+      - run: pytest -q tests/test_docxtpl_behaviour.py
+  benchmark:
+    # 0 false positives on python-docx-template's own test templates (benchmark/expected.json).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install -e .[render]
+      - run: git clone --depth 1 https://github.com/elapouya/python-docx-template /tmp/docxtpl
+      - run: python scripts/benchmark.py /tmp/docxtpl/tests/templates --json benchmark-result.json
+      - run: cat benchmark-result.json >> "$GITHUB_STEP_SUMMARY"
+        if: always()
+  playground:
+    # The wheel must keep working inside Pyodide (browser playground).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+      - run: pip install build && python -m build --wheel && pip install dist/*.whl && bash scripts/build_site.sh
+      - run: npm install --no-save pyodide@314.0.7 && node scripts/pyodide_smoke.mjs _site
+  action:
+    # Dogfood the composite action on the bundled examples (path with a space included).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: mkdir -p "tmp dir" && cp examples/clean.docx "tmp dir/clean copy.docx"
+      - uses: ./
+        with:
+          files: |
+            examples/clean.docx
+            tmp dir/*.docx
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install build twine && python -m build && twine check dist/*

docxtpl_lint-1.1.0/.github/workflows/pages.yml

@@ -0,0 +1,39 @@
+name: Playground (GitHub Pages)
+# Deploys site/ + the current wheel to GitHub Pages.
+# Needs: Settings → Pages → Source: "GitHub Actions". Runs on pushes to main
+# that touch the package or the site, or by hand. (A `release` trigger runs on the
+# tag ref, which the github-pages environment rejects by default.)
+on:
+  push:
+    branches: [main]
+    paths: ["src/**", "site/**", "scripts/build_site.sh", "examples/**", "pyproject.toml"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build --wheel && pip install dist/*.whl && bash scripts/build_site.sh
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

docxtpl_lint-1.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+# PyPI Trusted Publishing (OIDC, no token stored in GitHub).
+# Prepared but deliberately manual: it only runs when started from the Actions
+# tab ("Run workflow") with the tag to publish. One-time setup on pypi.org:
+#   Publishing → Add a pending publisher → owner yq6666-66, repo docxtpl-lint,
+#   workflow publish-pypi.yml, environment pypi.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to publish, e.g. v0.2.0
+        required: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.tag }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install build twine && python -m build && twine check dist/*
+      - name: Version must match tag
+        run: |
+          v=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$v" = "${{ inputs.tag }}"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/docxtpl-lint/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2

docxtpl_lint-1.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+_site/
+node_modules/
+package*.json

docxtpl_lint-1.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: docxtpl-lint
+  name: docxtpl-lint
+  description: Lint docxtpl / Jinja2 Word templates
+  entry: docxtpl-lint
+  language: python
+  files: \.docx$
+  exclude: (^|/)~\$

docxtpl_lint-1.1.0/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.1.0] - 2026-10-16
+
+Found by an adversarial run (86 cases designed by DeepSeek, disputes settled by rendering with docxtpl) and a
+self-evaluation from a fresh install (docs/eval/).
+
+### Added
+- DTL210: `{%p %}` block opened and closed in the same paragraph (docxtpl raises).
+- `--explain RULE`.
+- `fix` suggests the missing `}` of a `{{ … }` tag.
+- `scripts/adversarial.py` + `benchmark/adversarial_adjudicated.json`: the 86 cases run in the test-suite.
+- `scripts/realworld.py`: invoice / Chinese contract / broken / 3000-paragraph templates used by the self-evaluation.
+
+### Fixed
+- `}}` or `%}` inside a string literal no longer ends the tag (false DTL103).
+- A tag missing its closing brace no longer swallows the following paragraphs (it was only a DTL002 warning and
+  hid later errors); it is reported as DTL001 and scanning continues at the next tag.
+- Unclosed `{% raw %}` is reported (DTL101).
+- DTL209: comments are not counted as lost text; text in other cells of a `{%tr %}` row and in other paragraphs of a
+  `{%tc %}` cell is now checked; no DTL209 next to DTL201/202/203 or a same-paragraph `{%p %}` pair.
+- `--data` / `--schema` JSON with a UTF-8 BOM (Windows Notepad) is accepted.
+- `infer` / `verify` / `diff` / `fix` exit with code 2 and a one-line message on unreadable input instead of a traceback.
+- Playground: the 1.0.0 page failed to load (escaped newlines in the embedded Python); the Pyodide smoke test now runs
+  the page's own code. A hint appears if loading takes over 30 s.
+- `fix` diff headers: no `a//tmp/...` double slash.
+
+### Changed
+- `infer` writes `x-docxtpl-templates` only when several templates are merged.
+- Clearer `--data` help text.
+
+## [1.0.0] - 2026-10-16
+
+### Added
+- `docxtpl-lint infer`: data contract of one or more templates as JSON Schema (2020-12) plus sample data; lists from
+  `for` loops, numbers from `round`/`int`/`float`/`abs`, arithmetic and numeric comparisons, objects from `.items()`,
+  optional fields from `is defined`/`default`; merged schemas list the templates using each field
+  (`x-docxtpl-templates`).
+- `docxtpl-lint verify` (optional extra `[render]`): render with the real docxtpl and sentinel data; DTL401 = rendered
+  value silently missing from the output, DTL402 = render fails.
+- `docxtpl-lint diff old.docx new.docx [--fail-on-breaking]`: data contract changes between template versions,
+  with rename hints.
+- `--schema schema.json`: DTL304 (variable not declared), DTL305 (loop over a non-iterable type).
+- `docxtpl-lint fix`: fix suggestions as unified diffs of the paragraph text for DTL202, DTL203, DTL204, DTL102 (stray tag
+  or misspelt opening tag), DTL103 (unknown tag) and DTL301 (with `--data`); conservative matching (≤ 2 edits, no ties).
+- DTL209: text next to a `{%p %}`/`{%tr %}`/`{%tc %}` tag is silently dropped by docxtpl (found with `verify`).
+- Playground: fix suggestions, inferred JSON Schema and sample data.
+- Benchmark runs `verify` on docxtpl's 40 templates (37 render with inferred data, 0 false DTL401).
+
+### Changed
+- Pages deploy runs on pushes to `main` (the `release` trigger ran on the tag ref, which the `github-pages` environment
+  rejects).
+- Development status: Production/Stable.
+
+## [0.2.0] - 2026-10-16
+
+### Added
+- Browser playground (Pyodide, runs fully client-side), deployed to GitHub Pages by `pages.yml`.
+- `[tool.docxtpl-lint]` configuration in `pyproject.toml` (`--config`, `--no-config`); unknown keys are errors.
+- `--context N`: show neighbouring paragraphs next to each issue (default 1 on a terminal, 0 otherwise).
+- DTL208: `cellbg`/`colspan`/`vm`/`hm` tag outside a table cell.
+- `docs/rules.md` with one anchor per rule; `help_url` in JSON output and `helpUri` in SARIF.
+- Benchmark against docxtpl's own 40 test templates (`scripts/benchmark.py`, CI job); stale allow-list entries fail it.
+- Manual-only PyPI Trusted Publishing workflow (`publish-pypi.yml`).
+
+### Fixed
+- False positives on docxtpl cell tags (`{% cellbg %}`, `{% colspan %}`, `{% vm %}`, `{% hm %}`) and on Word smart quotes inside tags: 7 → 0 on the benchmark.
+
+### Changed
+- GitHub Actions updated to Node 24 versions (`checkout@v7`, `setup-python@v7`, ...); the composite action uses `setup-python@v7`.
+- New dependency on Python < 3.11: `tomli`.
+
+## [0.1.0] - 2026-10-16
+
+### Added
+- First release.
+- Locations down to the table cell (`T1 R2 C2 > T2 R2 C1`, nested tables) for body, headers, footers and footnotes.
+- Tag and block rules: DTL001 (tag never closed), DTL002 (tag spans paragraphs, warning), DTL101 (unclosed block),
+  DTL102 (stray end/else), DTL103 (other Jinja2 syntax errors, using docxtpl's default environment).
+- docxtpl tag rules: DTL201 (`%`/`}` in prefixed tags, #644), DTL202 (space before prefix), DTL203 (tr/tc outside
+  a table), DTL204 (prefix mismatch, #603), DTL205 (tr block spans tables), DTL206 (tr open/close in the same row),
+  DTL207 (tc block spans rows).
+- Data rules with `--data` (repeatable): DTL301 (missing path, nested and loop-aware, respects `is defined` /
+  `| default`), DTL302 (unused key, with `--report-unused-data`), DTL303 (loop over a non-iterable).
+- `--format text|json|github|sarif`, `--lang en|zh`, `--select`, `--ignore`, `--warnings-as-errors`, `--list-vars`,
+  `--list-rules`, `--allow-cross-paragraph`; exit codes 0/1/2.
+- File-level suppression comment `{# docxtpl-lint: disable=… #}`.
+- GitHub Action, pre-commit hook, and test cases checked against real docxtpl 0.20.2 rendering.
+
+[Unreleased]: https://github.com/yq6666-66/docxtpl-lint/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/yq6666-66/docxtpl-lint/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/yq6666-66/docxtpl-lint/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/yq6666-66/docxtpl-lint/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/yq6666-66/docxtpl-lint/releases/tag/v0.1.0

docxtpl_lint-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to docxtpl-lint
+
+Thanks for your interest in improving docxtpl-lint. This document covers the
+practical steps for setting up, testing, and submitting changes.
+
+## Development setup
+
+```bash
+python -m venv .venv
+. .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Checks before submitting
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Run linting and formatting checks:
+
+```bash
+ruff check . && ruff format --check .
+```
+
+Both must pass. Please keep changes focused; unrelated refactors make review
+harder.
+
+## Project layout
+
+- `src/docxtpl_lint/messages.py` — rule definitions: `id`, `severity`,
+  `summary`, and the `en`/`zh` messages.
+- `src/docxtpl_lint/core.py` — rule implementations.
+
+## Adding a rule
+
+Rules must be deterministic. Prefer missing a report over emitting a false
+positive. Automatic fixes are out of scope — do not add them.
+
+When adding a docxtpl-related rule:
+
+1. Define the rule in `src/docxtpl_lint/messages.py` and implement it in
+   `src/docxtpl_lint/core.py`.
+2. Add a **bad** case to `tests/rule_cases.py`, and a **good** case whenever
+   one is meaningful.
+3. `tests/test_docxtpl_behaviour.py` renders the cases with the real `docxtpl`
+   package to prove the problem actually exists (either it `raises`, or it
+   fails `silent`). Make sure your case is covered there.
+
+## Fixtures and demo assets
+
+- Example `.docx` files are generated by `tests/make_fixtures.py`.
+- README screenshots are generated by `scripts/make_demo.py` (requires
+  `rich`).
+
+Regenerate these when your change affects them, and commit the results.
+
+## Reporting bugs
+
+Open an issue with a minimal `.docx` that reproduces the problem and the
+`docxtpl` version you are using. Without a reproduction we usually cannot
+confirm the behaviour.
+
+## Commits and changelog
+
+- Write commit messages in the imperative mood (e.g. "Add rule for ...").
+- Add an entry to the `Unreleased` section of `CHANGELOG.md`.
+
+## Pull requests
+
+Keep each PR scoped to one change. Describe what the rule or fix does, and
+reference the issue it addresses. Ensure `pytest` and `ruff` pass locally
+before requesting review.

docxtpl_lint-1.1.0/LICENSE

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