| Name | scribe-templates JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Rapid DOCX generation from Jinja2 templates – YAML + pydantic + Typer. |
| upload_time | 2025-07-30 15:22:27 |
| maintainer | None |
| docs_url | None |
| author | Alex |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# scribe
> Rapid DOCX generation from Jinja2 templates – YAML + pydantic + Typer
`scribe` turns structured data (YAML / JSON / CSV / Excel) into polished Microsoft Word documents using **docxtpl** templates.
It targets bulk workflows (tens - hundreds of files) yet remains friendly for single-document scripting.
---
## Installation
```bash
pip install scribe # from PyPI (coming soon)
# or from source
pip install -e .
```
Python 3.10 + and LibreOffice/Microsoft Word (to open the results) are
required. On first use it will create `outputs/` directory next to the project root.
## Quick Start
```bash
# see registered templates
$ scribe list-templates
• annual_report templates/annual_report.docx
# scan disk for unregistered templates
$ scribe list-templates --all
# generate one file
$ scribe generate annual_report data/report.yaml
# bulk render from CSV (one row per document)
$ scribe generate annual_report data/bulk.csv --delimiter ';'
```
### Global flags:
| flag | default | description |
| ---------------------------- | ------- | --------------------------------- |
| `--log-level` | INFO | DEBUG / INFO / WARNING / ERROR |
| `--log-json / --no-log-json` | - | one-line JSON logs (for CI / k8s) |
### Discover and register new templates
```bash
$ scribe discover-templates
✓ 3 template(s) written to config/discovered_templates.yaml
# merge the snippet into config/app.yaml
```
## Public API (import and use in your own scripts)
```python
from pathlib import Path
from decimal import Decimal
from scribe import (
DataLoader,
TemplateFinder,
get_settings,
make_context,
generate_docx,
)
# 1) pick a template
tpl_cfg = TemplateFinder().discover()[0] # annual_report
# 2) load data
raw = DataLoader.load(Path("data/report.yaml")) # dict or list[dict]
# 3) validate via side-car schema (if any)
ctx = make_context(tpl_cfg.path, raw) # BaseDocContext or subclass
# 4) render
out_path = generate_docx(ctx, tpl_cfg, Path("outputs"))
print("wrote", out_path)
```
## Configuration
| source | precedence |
| ------ | ---------- |
| **CLI kwargs** | highest |
| `SCRIBE_*` environment variables | |
| `.env` file in CWD | |
| `config/app.yaml` | base |
### Environment variables
| name | example | purpose |
| ---- | ------- | ------- |
| `SCRIBE_OUTPUT_DIR` | `/tmp/reports` | override default outputs dir |
| `SCRIBE_TEMPLATES_DIR` | `/srv/docx:/opt/private` (path-sep list) | additional template search roots |
| `SCRIBE_LOG_JSON` | `1` | enable JSON logs in any context |
## Template validation (optional)
Add a file next to your template:
```yaml
# templates/annual_report.schema.yaml
client_name: str
report_date: date
summary: str
revenue: Decimal
details: List[scribe.models.custom:Detail]
```
`make_context` will generate a Pydantic model on the fly and coerce/validate incoming data before rendering.
## Rich text/conditional styling
`config/app.yaml`
```yaml
templates:
- name: annual_report
path: templates/annual_report.docx
output_naming: "{client_name}_{report_date:%Y%m%d}.docx"
options:
richtext:
status:
- when: { equals: "APPROVED" }
style: { bold: true, color: "008000" }
- when: { equals: "REJECTED" }
style: { bold: true, color: "CC0000" }
```
In your DOCX reference {{ richtext_status }} to get coloured text; the plain {{ status }} remains unchanged.
## Development & tests
```bash
# Linting & type-checking
ruff check scribe
mypy scribe
# Test suite
pytest -q --cov=scribe
```
### Commit conventions
- Black-formatted, fully-typed code
- NumPy-style docstrings
- CI matrix: Python 3.10 & 3.11
Feel free to open issues or PRs – contributions welcome!
Raw data
{
"_id": null,
"home_page": null,
"name": "scribe-templates",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Alex",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/98/15/31f65d5a4c85aa81adc4edf68aafd0cfe07973c7bff45c7085288c4c1dee/scribe_templates-0.3.1.tar.gz",
"platform": null,
"description": "# scribe\n\n> Rapid DOCX generation from Jinja2 templates \u2013 YAML + pydantic + Typer\n\n`scribe` turns structured data (YAML / JSON / CSV / Excel) into polished Microsoft Word documents using **docxtpl** templates. \nIt targets bulk workflows (tens - hundreds of files) yet remains friendly for single-document scripting.\n\n---\n\n## Installation\n\n```bash\npip install scribe # from PyPI (coming soon)\n# or from source\npip install -e .\n```\nPython 3.10 + and LibreOffice/Microsoft Word (to open the results) are\nrequired. On first use it will create `outputs/` directory next to the project root.\n\n## Quick Start\n\n```bash\n# see registered templates\n$ scribe list-templates\n\u2022 annual_report templates/annual_report.docx\n\n# scan disk for unregistered templates\n$ scribe list-templates --all\n\n# generate one file\n$ scribe generate annual_report data/report.yaml\n\n# bulk render from CSV (one row per document)\n$ scribe generate annual_report data/bulk.csv --delimiter ';'\n```\n\n### Global flags: \n\n| flag | default | description |\n| ---------------------------- | ------- | --------------------------------- |\n| `--log-level` | INFO | DEBUG / INFO / WARNING / ERROR |\n| `--log-json / --no-log-json` | - | one-line JSON logs (for CI / k8s) |\n\n\n### Discover and register new templates\n\n```bash\n$ scribe discover-templates\n\u2713 3 template(s) written to config/discovered_templates.yaml\n# merge the snippet into config/app.yaml\n```\n\n## Public API (import and use in your own scripts)\n\n```python\nfrom pathlib import Path\nfrom decimal import Decimal\n\nfrom scribe import (\n DataLoader,\n TemplateFinder,\n get_settings,\n make_context,\n generate_docx,\n)\n\n# 1) pick a template\ntpl_cfg = TemplateFinder().discover()[0] # annual_report\n\n# 2) load data\nraw = DataLoader.load(Path(\"data/report.yaml\")) # dict or list[dict]\n\n# 3) validate via side-car schema (if any)\nctx = make_context(tpl_cfg.path, raw) # BaseDocContext or subclass\n\n# 4) render\nout_path = generate_docx(ctx, tpl_cfg, Path(\"outputs\"))\nprint(\"wrote\", out_path)\n```\n\n## Configuration\n\n| source | precedence |\n| ------ | ---------- |\n| **CLI kwargs** | highest |\n| `SCRIBE_*` environment variables | |\n| `.env` file in CWD | |\n| `config/app.yaml` | base |\n\n### Environment variables\n| name | example | purpose |\n| ---- | ------- | ------- |\n| `SCRIBE_OUTPUT_DIR` | `/tmp/reports` | override default outputs dir |\n| `SCRIBE_TEMPLATES_DIR` | `/srv/docx:/opt/private` (path-sep list) | additional template search roots |\n| `SCRIBE_LOG_JSON` | `1` | enable JSON logs in any context |\n\n\n## Template validation (optional)\n\nAdd a file next to your template:\n\n```yaml\n# templates/annual_report.schema.yaml\nclient_name: str\nreport_date: date\nsummary: str\nrevenue: Decimal\ndetails: List[scribe.models.custom:Detail]\n```\n\n`make_context` will generate a Pydantic model on the fly and coerce/validate incoming data before rendering.\n\n## Rich text/conditional styling\n\n`config/app.yaml`\n```yaml\ntemplates:\n - name: annual_report\n path: templates/annual_report.docx\n output_naming: \"{client_name}_{report_date:%Y%m%d}.docx\"\n options:\n richtext:\n status:\n - when: { equals: \"APPROVED\" }\n style: { bold: true, color: \"008000\" }\n - when: { equals: \"REJECTED\" }\n style: { bold: true, color: \"CC0000\" }\n```\nIn your DOCX reference {{ richtext_status }} to get coloured text; the plain {{ status }} remains unchanged.\n\n## Development & tests\n\n```bash\n# Linting & type-checking\nruff check scribe\nmypy scribe\n\n# Test suite\npytest -q --cov=scribe\n```\n\n### Commit conventions\n- Black-formatted, fully-typed code\n- NumPy-style docstrings\n- CI matrix: Python 3.10 & 3.11\n\nFeel free to open issues or PRs \u2013 contributions welcome!\n",
"bugtrack_url": null,
"license": null,
"summary": "Rapid DOCX generation from Jinja2 templates \u2013 YAML + pydantic + Typer.",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "47235f1e28aa7bef037e4f2ece323f3d6539163b90c854da43f2693bf5a1b696",
"md5": "db3adddd0d799d5f385eb9eb0616841d",
"sha256": "0986b9aa6a8bbf0296bf3391122a951d329ec29090cc771017b42c37c905da7c"
},
"downloads": -1,
"filename": "scribe_templates-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db3adddd0d799d5f385eb9eb0616841d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 37561,
"upload_time": "2025-07-30T15:22:26",
"upload_time_iso_8601": "2025-07-30T15:22:26.046789Z",
"url": "https://files.pythonhosted.org/packages/47/23/5f1e28aa7bef037e4f2ece323f3d6539163b90c854da43f2693bf5a1b696/scribe_templates-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "981531f65d5a4c85aa81adc4edf68aafd0cfe07973c7bff45c7085288c4c1dee",
"md5": "f58b99478802c30c71201c527517c216",
"sha256": "c792c331e4fb1dca96e83f7712df9657cafdce877115e079dd60a8e312d5846a"
},
"downloads": -1,
"filename": "scribe_templates-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "f58b99478802c30c71201c527517c216",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 29793,
"upload_time": "2025-07-30T15:22:27",
"upload_time_iso_8601": "2025-07-30T15:22:27.463727Z",
"url": "https://files.pythonhosted.org/packages/98/15/31f65d5a4c85aa81adc4edf68aafd0cfe07973c7bff45c7085288c4c1dee/scribe_templates-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 15:22:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "scribe-templates"
}
