Metadata-Version: 2.4
Name: docxlint
Version: 0.1.0
Summary: Validate Jinja2 template syntax inside .docx files (docxtpl compatible)
Author-email: Huy <dichvu@techcoop.vn>
License: MIT
Project-URL: Homepage, https://github.com/techcoop-vn/docx-jinja2-validator
Project-URL: Issues, https://github.com/techcoop-vn/docx-jinja2-validator/issues
Keywords: docx,jinja2,docxtpl,template,validation,word
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Text Processing :: Markup :: XML
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# docx-jinja2-validator

Validate [Jinja2](https://jinja.palletsprojects.com/) template syntax inside `.docx` files — built for use with [docxtpl](https://docxtpl.readthedocs.io/).

## Install

```bash
pip install docxlint
```

## Usage

```bash
# single file
docxlint template.docx

# entire folder
docxlint ./templates/

# recursive (includes subfolders)
docxlint ./templates/ --recursive

# verbose (show all block tags)
docxlint ./templates/ --verbose
```

Or via Python module:

```bash
python -m docxlint template.docx
```

## What it checks

| # | Check | Example error caught |
|---|-------|----------------------|
| 1 | Valid ZIP / DOCX structure | Corrupt file |
| 2 | XML well-formedness | `word/document.xml` broken |
| 3 | `{{ }}` balance | Missing `}` in variable |
| 4 | `{% %}` balance | Missing `%}` in block tag |
| 5 | Split tags | Word splits `{{var}}` across XML runs |
| 6 | Common typos | `{{{`, `}}}`, `{ %`, `% }`, `end for` |
| 7 | Block pairing | `{% for %}` without `{% endfor %}` |
| 8 | Table row tags | `{%tr for %}` without `{%tr endfor %}` |
| 9 | Variable inventory | Lists all `{{ ... }}` found |

## Example output

```
Validating: template.docx  (42 KB)
────────────────────────────────────────────────────────────

1. DOCX structure
  ✓ Valid ZIP with 17 entries
  ✓ word/document.xml present

2. XML well-formedness
  ✓ word/document.xml

3. Jinja2 syntax
  ✓ word/document.xml: 6 variables, 4 block tags

4. Block tag pairing
  ✓ All for/if blocks properly closed

5. Table row tags {%tr %}
  ✓ word/document.xml: 1 table row loop(s) matched

6. Variable inventory
  → Found 6 unique variable expression(s):
    {{ objects.customer_id.name }}
    {{ objects.total_overdue_amount }}
    ...

Result
  ✓ PASSED
```

## Exit codes

| Code | Meaning |
|------|---------|
| `0`  | All files passed |
| `1`  | One or more files have issues |

Useful for CI/CD pipelines:

```bash
docxlint ./templates/ && echo "Templates OK" || echo "Fix templates!"
```

## Use as a library

```python
from docxlint import validate_one
from pathlib import Path

result = validate_one(Path("template.docx"), verbose=False)
print(result.passed)   # True / False
print(result.issues)   # number of failed checks
```

## License

MIT
