docfill 0.1.0__tar.gz

docfill-0.1.0/LICENSE

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

docfill-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: docfill
+Version: 0.1.0
+Summary: Library: fill Excel (.xlsx) templates with Jinja2 and optional row expansion from a context dict
+Author: docfill contributors
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/docfill/
+Keywords: excel,xlsx,openpyxl,jinja2,template,report
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build>=1.0.0; extra == "publish"
+Requires-Dist: twine>=5.0.0; extra == "publish"
+Dynamic: license-file
+
+# docfill
+
+Заполнение шаблонов Excel (`.xlsx`) через **Jinja2** и опциональное размножение **строки-шаблона** по списку из JSON.
+
+## Установка
+
+```bash
+pip install -e .
+pip install -e ".[dev]"   # опционально: pytest
+```
+
+Тесты без pytest (stdlib):
+
+```bash
+set PYTHONPATH=src
+python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+## Шаблон и контекст
+
+- **Все листы** книги обрабатываются подряд **одним** контекстом; лист без размеченной строки под список и без блоков `{% for %}` получает только глобальный Jinja (если в контексте есть непустой `items`, авторазвёртывание на таком листе **пропускается**, чтобы не падать на пустых листах).
+- **Несколько таблиц на листе:** для каждой пары `{% for var in listKey %}` … `{% endfor %}` в контексте должен быть список `listKey` (например `items`, `items2`). Блоки обрабатываются **снизу вверх**, чтобы вставка строк не сдвигала нижележащие шаблоны. Сдвиг формул под верхней таблицей **не затрагивает** строки нижней (до начала её блока `for`).
+- Если на листе **нет** тегов `{% for %}`, но в контексте есть непустой список по ключу **`items`**, строка-шаблон ищется автоматически: сначала строка с `{{ item.`, иначе строка с **наибольшим** числом ячеек с `{{` (при равенстве — нижняя). Если максимум **1** ячейка и таких строк **несколько** (например шапка «Customer» / «Date» в разных строках), авторазвёртывание **не делается** — только глобальный Jinja; таблицу пометьте `{% for %}` или `{{ item.... }}` на строке данных.
+- Для каждого элемента списка контекст строки = глобальный контекст без этого списка + поля элемента (плоское объединение) + `item` (тот же объект). Работают и `{{ name }}`, и `{{ item.name }}`.
+- Поддерживается шаблон с маркерами цикла в Excel: в строке-шаблоне можно использовать `{% for item in items %}...`, а в следующей строке `{% endfor %}`. Эти служебные маркеры удаляются в результате. В ячейках строки данных доступен объект **`loop`** (как в Jinja): `loop.index`, `loop.index0`, `loop.first` / `loop.last`, `loop.length`, `loop.revindex` / `loop.revindex0`, `loop.previtem` / `loop.nextitem`.
+- Формулы ниже блока цикла (например строка `Итого`) автоматически сдвигаются по относительным ссылкам на число добавленных строк.
+- Значения вида `2`, `10`, `3.5` после Jinja записываются как **числа**, а не текст — иначе `SUM` и другие формулы дают 0.
+- После размножения строк выполняется второй проход по листу: подставляются глобальные плейсхолдеры вне строки-шаблона (например `{{ customer_name }}` в шапке).
+- Формулы в строке-шаблоне копируются со сдвигом относительных ссылок (`openpyxl` `Translator`), как при протягивании в Excel. **Накопительный итог** в колонке (running total): в шаблоне первая строка данных, например строка 2, задайте `=SUM($E$2:E2)` или локально `=СУММ($E$2:E2)` — начало диапазона с **двумя** долларами у строки (`$E$2`). Вариант `=SUM($E2:E2)` после копирования вниз даст `=SUM($E3:E3)` и посчитает только текущую строку; это не ошибка листа или docfill, а формула шаблона.
+- Ячейки-**формулы** Jinja не обрабатывает (только обычный текст в ячейках).
+
+## Библиотека
+
+Установка: `pip install .` из корня репозитория или `pip install -e .` для разработки. Пакет следует [PEP 517](https://peps.python.org/pep-0517/) (`python -m build` при наличии `build`).
+
+```python
+from docfill import fill_workbook
+
+ctx = {"title": "Отчёт", "items": [{"name": "A", "qty": 1}]}
+fill_workbook("template.xlsx", "out.xlsx", ctx)
+```
+
+Контекст всегда передаётся **словарём** (или иным `Mapping`). Прочитать JSON из файла — на стороне вызывающего кода, например `json.loads(Path("context.json").read_text(encoding="utf-8"))`.
+
+## Публикация на PyPI
+
+1. Зарегистрируйте аккаунт на [pypi.org](https://pypi.org). Загрузка **с GitHub Actions** идёт через [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): в настройках проекта на PyPI добавьте publisher с вашим `owner/repo`, workflow **`publish.yml`**, окружение **`pypi`**. Отдельный API token для CI не нужен. Для ручной загрузки через `twine` можно создать [API token](https://pypi.org/manage/account/token/).
+2. Имя пакета **`docfill`** должно быть свободно на PyPI; при занятости смените `name` в `pyproject.toml`.
+3. При желании добавьте в `pyproject.toml` в `[project.urls]` поля **Repository** и **Issues** (рядом с `Homepage`).
+4. **Версия** в `pyproject.toml` должна совпадать с релизом: при каждом GitHub Release поднимайте `version` иначе PyPI отклонит повтор той же версии.
+5. Сборка и проверка дистрибутивов вручную:
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+```
+
+6. Загрузка вручную (тестовый индекс [TestPyPI](https://test.pypi.org) или основной PyPI):
+
+```bash
+twine upload dist/*
+```
+
+Для TestPyPI: `twine upload --repository testpypi dist/*` и установка проверки: `pip install -i https://test.pypi.org/simple/ docfill`.
+
+Лицензия: **MIT** (файл `LICENSE`). Версию перед релизом поднимайте в `pyproject.toml` и синхронно в запасном значении в `docfill/__init__.py` (`PackageNotFoundError`).
+
+## Ограничения
+
+- Нет пересчёта формул при сохранении — результат пересчитает Excel при открытии.
+- Объединённые ячейки в строке-шаблона не поддерживаются.
+- Rich text в ячейке не разбирается как шаблон.

docfill-0.1.0/README.md

@@ -0,0 +1,73 @@
+# docfill
+
+Заполнение шаблонов Excel (`.xlsx`) через **Jinja2** и опциональное размножение **строки-шаблона** по списку из JSON.
+
+## Установка
+
+```bash
+pip install -e .
+pip install -e ".[dev]"   # опционально: pytest
+```
+
+Тесты без pytest (stdlib):
+
+```bash
+set PYTHONPATH=src
+python -m unittest discover -s tests -p "test_*.py" -v
+```
+
+## Шаблон и контекст
+
+- **Все листы** книги обрабатываются подряд **одним** контекстом; лист без размеченной строки под список и без блоков `{% for %}` получает только глобальный Jinja (если в контексте есть непустой `items`, авторазвёртывание на таком листе **пропускается**, чтобы не падать на пустых листах).
+- **Несколько таблиц на листе:** для каждой пары `{% for var in listKey %}` … `{% endfor %}` в контексте должен быть список `listKey` (например `items`, `items2`). Блоки обрабатываются **снизу вверх**, чтобы вставка строк не сдвигала нижележащие шаблоны. Сдвиг формул под верхней таблицей **не затрагивает** строки нижней (до начала её блока `for`).
+- Если на листе **нет** тегов `{% for %}`, но в контексте есть непустой список по ключу **`items`**, строка-шаблон ищется автоматически: сначала строка с `{{ item.`, иначе строка с **наибольшим** числом ячеек с `{{` (при равенстве — нижняя). Если максимум **1** ячейка и таких строк **несколько** (например шапка «Customer» / «Date» в разных строках), авторазвёртывание **не делается** — только глобальный Jinja; таблицу пометьте `{% for %}` или `{{ item.... }}` на строке данных.
+- Для каждого элемента списка контекст строки = глобальный контекст без этого списка + поля элемента (плоское объединение) + `item` (тот же объект). Работают и `{{ name }}`, и `{{ item.name }}`.
+- Поддерживается шаблон с маркерами цикла в Excel: в строке-шаблоне можно использовать `{% for item in items %}...`, а в следующей строке `{% endfor %}`. Эти служебные маркеры удаляются в результате. В ячейках строки данных доступен объект **`loop`** (как в Jinja): `loop.index`, `loop.index0`, `loop.first` / `loop.last`, `loop.length`, `loop.revindex` / `loop.revindex0`, `loop.previtem` / `loop.nextitem`.
+- Формулы ниже блока цикла (например строка `Итого`) автоматически сдвигаются по относительным ссылкам на число добавленных строк.
+- Значения вида `2`, `10`, `3.5` после Jinja записываются как **числа**, а не текст — иначе `SUM` и другие формулы дают 0.
+- После размножения строк выполняется второй проход по листу: подставляются глобальные плейсхолдеры вне строки-шаблона (например `{{ customer_name }}` в шапке).
+- Формулы в строке-шаблоне копируются со сдвигом относительных ссылок (`openpyxl` `Translator`), как при протягивании в Excel. **Накопительный итог** в колонке (running total): в шаблоне первая строка данных, например строка 2, задайте `=SUM($E$2:E2)` или локально `=СУММ($E$2:E2)` — начало диапазона с **двумя** долларами у строки (`$E$2`). Вариант `=SUM($E2:E2)` после копирования вниз даст `=SUM($E3:E3)` и посчитает только текущую строку; это не ошибка листа или docfill, а формула шаблона.
+- Ячейки-**формулы** Jinja не обрабатывает (только обычный текст в ячейках).
+
+## Библиотека
+
+Установка: `pip install .` из корня репозитория или `pip install -e .` для разработки. Пакет следует [PEP 517](https://peps.python.org/pep-0517/) (`python -m build` при наличии `build`).
+
+```python
+from docfill import fill_workbook
+
+ctx = {"title": "Отчёт", "items": [{"name": "A", "qty": 1}]}
+fill_workbook("template.xlsx", "out.xlsx", ctx)
+```
+
+Контекст всегда передаётся **словарём** (или иным `Mapping`). Прочитать JSON из файла — на стороне вызывающего кода, например `json.loads(Path("context.json").read_text(encoding="utf-8"))`.
+
+## Публикация на PyPI
+
+1. Зарегистрируйте аккаунт на [pypi.org](https://pypi.org). Загрузка **с GitHub Actions** идёт через [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC): в настройках проекта на PyPI добавьте publisher с вашим `owner/repo`, workflow **`publish.yml`**, окружение **`pypi`**. Отдельный API token для CI не нужен. Для ручной загрузки через `twine` можно создать [API token](https://pypi.org/manage/account/token/).
+2. Имя пакета **`docfill`** должно быть свободно на PyPI; при занятости смените `name` в `pyproject.toml`.
+3. При желании добавьте в `pyproject.toml` в `[project.urls]` поля **Repository** и **Issues** (рядом с `Homepage`).
+4. **Версия** в `pyproject.toml` должна совпадать с релизом: при каждом GitHub Release поднимайте `version` иначе PyPI отклонит повтор той же версии.
+5. Сборка и проверка дистрибутивов вручную:
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+```
+
+6. Загрузка вручную (тестовый индекс [TestPyPI](https://test.pypi.org) или основной PyPI):
+
+```bash
+twine upload dist/*
+```
+
+Для TestPyPI: `twine upload --repository testpypi dist/*` и установка проверки: `pip install -i https://test.pypi.org/simple/ docfill`.
+
+Лицензия: **MIT** (файл `LICENSE`). Версию перед релизом поднимайте в `pyproject.toml` и синхронно в запасном значении в `docfill/__init__.py` (`PackageNotFoundError`).
+
+## Ограничения
+
+- Нет пересчёта формул при сохранении — результат пересчитает Excel при открытии.
+- Объединённые ячейки в строке-шаблона не поддерживаются.
+- Rich text в ячейке не разбирается как шаблон.

docfill-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docfill"
+version = "0.1.0"
+description = "Library: fill Excel (.xlsx) templates with Jinja2 and optional row expansion from a context dict"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "docfill contributors" }]
+keywords = ["excel", "xlsx", "openpyxl", "jinja2", "template", "report"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openpyxl>=3.1.0",
+    "jinja2>=3.1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+publish = ["build>=1.0.0", "twine>=5.0.0"]
+
+[project.urls]
+Homepage = "https://pypi.org/project/docfill/"
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+docfill = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

docfill-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docfill-0.1.0/src/docfill/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .pipeline import fill_workbook
+
+try:
+    __version__ = version("docfill")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = ["fill_workbook", "__version__"]

docfill-0.1.0/src/docfill/constants.py

@@ -0,0 +1 @@
+ITEMS_LIST_KEY = "items"

docfill-0.1.0/src/docfill/formulas.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from openpyxl.cell import Cell
+from openpyxl.formula.translate import Translator
+
+
+def is_formula_cell(cell: Cell) -> bool:
+    return cell.data_type == "f" and isinstance(cell.value, str)
+
+
+def translate_formula(formula: str, origin_coord: str, dest_coord: str) -> str:
+    if not formula.startswith("="):
+        formula = "=" + formula
+    return Translator(formula, origin_coord).translate_formula(dest_coord)

docfill-0.1.0/src/docfill/jinja_render.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from jinja2 import Environment, StrictUndefined, TemplateSyntaxError, UndefinedError
+
+
+def build_environment() -> Environment:
+    return Environment(
+        autoescape=False,
+        undefined=StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def template_markers_in_text(s: str) -> bool:
+    return "{{" in s or "{%" in s
+
+
+def render_cell_text(
+    env: Environment,
+    template_str: str,
+    context: Mapping[str, Any],
+    cell_coord: str,
+) -> str:
+    if not template_markers_in_text(template_str):
+        return template_str
+    try:
+        return env.from_string(template_str).render(**context)
+    except UndefinedError as e:
+        raise ValueError(f"{cell_coord}: undefined template variable: {e}") from e
+    except TemplateSyntaxError as e:
+        raise ValueError(f"{cell_coord}: Jinja syntax error: {e}") from e

docfill-0.1.0/src/docfill/pipeline.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from jinja2 import Environment
+from openpyxl import load_workbook
+from openpyxl.worksheet.worksheet import Worksheet
+
+from . import jinja_render, row_block
+from .constants import ITEMS_LIST_KEY
+from .row_block import RepeatBlock
+
+
+def _formula_shift_stop_row(
+    blocks_sorted_asc: list[RepeatBlock],
+    block: RepeatBlock,
+) -> int | None:
+    for b in blocks_sorted_asc:
+        if b.template_row > block.template_row:
+            return b.template_row
+    return None
+
+
+def _expand_repeat_blocks(
+    ws: Worksheet,
+    context: Mapping[str, Any],
+    env: Environment,
+    sheet_title: str,
+    blocks: list[RepeatBlock],
+) -> None:
+    blocks_asc = sorted(blocks, key=lambda b: b.template_row)
+    for block in reversed(blocks_asc):
+        raw = context.get(block.list_key)
+        if raw is None:
+            raise ValueError(
+                f"Sheet {sheet_title!r}, row {block.template_row}: template uses list "
+                f"{block.list_key!r}, but context has no such key."
+            )
+        if not isinstance(raw, list):
+            raise TypeError(
+                f"Sheet {sheet_title!r}, context key {block.list_key!r} must be a list, "
+                f"got {type(raw).__name__}"
+            )
+        row_block.expand_template_rows(
+            ws,
+            block.template_row,
+            list(raw),
+            context,
+            block.list_key,
+            env,
+            formula_shift_stop_row_exclusive=_formula_shift_stop_row(blocks_asc, block),
+        )
+
+
+def _expand_auto_items_template(
+    ws: Worksheet,
+    context: Mapping[str, Any],
+    env: Environment,
+    items: list[Any],
+) -> None:
+    try:
+        template_row = row_block.find_template_row(ws)
+    except ValueError:
+        return
+    row_block.expand_template_rows(
+        ws,
+        template_row,
+        list(items),
+        context,
+        ITEMS_LIST_KEY,
+        env,
+    )
+
+
+def _fill_worksheet(ws: Worksheet, context: Mapping[str, Any], env: Environment) -> None:
+    blocks = row_block.find_repeat_blocks(ws)
+    items = context.get(ITEMS_LIST_KEY)
+
+    if blocks:
+        _expand_repeat_blocks(ws, context, env, ws.title, blocks)
+    elif isinstance(items, list) and len(items) > 0:
+        _expand_auto_items_template(ws, context, env, items)
+
+    row_block.render_worksheet_global(ws, context, env)
+
+
+def fill_workbook(
+    template_path: str | Path,
+    output_path: str | Path,
+    context: Mapping[str, Any],
+) -> None:
+    wb = load_workbook(filename=template_path, data_only=False)
+    env = jinja_render.build_environment()
+    for ws in wb.worksheets:
+        _fill_worksheet(ws, context, env)
+    wb.save(output_path)