docfill 0.3.1

Library: fill Excel (.xlsx) templates with Jinja2 and optional row expansion from a context dict

docfill

Заполнение шаблонов Excel (.xlsx) через Jinja2 и опциональное размножение строки-шаблона по списку из JSON.

Установка

pip install -e .
pip install -e ".[dev]"   # опционально: pytest

Тесты без pytest (stdlib):

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 не обрабатывает (только обычный текст в ячейках).
• Опционально поддерживаются вертикальные объединения в развёрнутом блоке списка через метаданные контекста items_meta.vertical_merges (ключ items_meta исторически общий; правила применяются к тому списку, который только что развёрнут на листе — items, products, {% for x in items2 %}, и т.д.):

{
  "items": [
    {"name": "n1", "packages": 1},
    {"name": "n2", "packages": 1},
    {"name": "n3", "packages": 1}
  ],
  "items_meta": {
    "vertical_merges": [
      {"field": "packages", "start": 0, "span": 3}
    ]
  }
}

Где field — имя поля из шаблона: подойдут {{ item.field }}, {{ field }} (плоский контекст строки), {{ product.field }} при {% for product in products %}, и любой другой префикс {{ loopVar.field }} на строке с {% for %} (см. ограничение ниже). start — индекс строки в развёрнутом списке (0-based), span — число объединяемых строк. При отсутствии items_meta поведение остаётся прежним.

Опционально в items_meta можно задать list_key (строка): тогда vertical_merges применяются только к блоку с таким ключом списка в шаблоне ({% for … in list_key %}), что полезно при нескольких таблицах на листе и одном общем items_meta. Если list_key не указан, правила применяются к каждому развёрнутому repeat-блоку (и к авто-режиму по ключу items), для которого в контексте есть соответствующий список.

Многострочный шаблон между {% for %} и {% endfor %}: плейсхолдеры только на промежуточных строках не участвуют в определении колонок для merge; поддерживается сценарий с маркерами цикла на одной строке данных (как в примерах тестов).

Библиотека

Установка: pip install . из корня репозитория или pip install -e . для разработки. Пакет следует PEP 517 (python -m build при наличии build).

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. Загрузка с GitHub Actions идёт через trusted publishing (OIDC): в настройках проекта на PyPI добавьте publisher с вашим owner/repo, workflow publish.yml, окружение pypi. Отдельный API token для CI не нужен. Для ручной загрузки через twine можно создать API token.
2. Имя пакета docfill должно быть свободно на PyPI; при занятости смените name в pyproject.toml.
3. При желании добавьте в pyproject.toml в [project.urls] поля Repository и Issues (рядом с Homepage).
4. Версия в pyproject.toml должна совпадать с релизом: при каждом GitHub Release поднимайте version иначе PyPI отклонит повтор той же версии.
5. Сборка и проверка дистрибутивов вручную:

pip install -e ".[publish]"
python -m build
twine check dist/*

6. Загрузка вручную (тестовый индекс TestPyPI или основной PyPI):

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 при открытии.
• Горизонтальные объединения не поддерживаются (поддерживается только vertical merge через items_meta.vertical_merges, в т.ч. для списков с произвольным ключом в {% for %}).
• Rich text в ячейке не разбирается как шаблон.