PDF Invoice / Check Generator (CLI)

Консольное приложение на Python, которое генерирует PDF‑счета и чеки из CSV/JSON‑данных и HTML‑шаблонов.
Проект сделан в рамках обучения в Zerocoder как пример реального кейса для портфолио и фриланс‑услуги по автоматизации документооборота.

---

Возможности

• Чтение данных из папки data:
  • CSV‑файлы с позициями и invoice_id;
  • JSON‑файлы: как плоские списки, так и объекты с вложенным items.
• Чтение HTML‑шаблонов из папки templates.
• Меню в терминале:
  • выбор файла данных;
  • выбор HTML‑шаблона;
  • выбор нужного invoice_id из списка.
• Формирование контекста:
  • шапка счёта (клиент, дата и т.п.);
  • список товаров (items) и итоговая сумма (total).
• Рендеринг шаблона:
  • одиночные плейсхолдеры {{ key }};
  • блоки списков {{#items}} ... {{/items}} с поддержкой {{ loop.index }}.
• Генерация PDF:
  • используется системный weasyprint (CLI);
  • CSS‑стили для кириллицы, таблиц и переносов длинных строк.
• Сохранение PDF в папку output и автоматическое открытие готового файла.

---

Технологии

• Язык: Python 3.10+
• Библиотеки Python:
  • pandas (опционально, для удобного чтения CSV);
  • стандартная библиотека (pathlib, csv, json, subprocess, tempfile, logging и др.).
• Внешний инструмент:
  • weasyprint — установлен как системный CLI‑инструмент (через пакетный менеджер ОС). [file:1]
• Форматы данных: CSV, JSON
• Интерфейс: CLI (интерфейс командной строки)

---

Структура проекта

project-root/ ├─ pdf_generator.py # основной скрипт ├─ README.md ├─ requirements.txt ├─ data/ # файлы с данными (CSV/JSON) │ ├─ invoices.csv │ └─ invoices.json ├─ templates/ # HTML-шаблоны и стили │ ├─ invoice_template.html │ ├─ style.css # базовые стили для PDF │ ├─ config.json # (pro) конфиг клиента: реквизиты, валюта, НДС, тексты │ └─ fonts/ # (опционально) шрифты для кириллицы │ ├─ DejaVuSans.ttf │ └─ DejaVuSans-Bold.ttf └─ output/ # сюда сохраняются сгенерированные PDF

text

---

Примеры данных

CSV: несколько позиций в одном счёте

invoice_id,customer_name,date,product,price,quantity INV-001,"Иванов Иван",2024-01-15,"Футболка Zerocoder",1990,2 INV-001,"Иванов Иван",2024-01-15,"Стикеры Vibe-coder",350,5 INV-001,"Иванов Иван",2024-01-15,"Онлайн-курс по нейросетям",4990,1

text

Ключевое поле для группировки — invoice_id (поддерживаются и алиасы: invoice, invoice_number, bill_id, order_id, id).

JSON: плоский список позиций

[ { "invoice_id": "INV-001", "customer_name": "Иванов Иван", "date": "2024-01-15", "product": "Футболка Zerocoder", "price": 1990, "quantity": 2 }, { "invoice_id": "INV-001", "customer_name": "Иванов Иван", "date": "2024-01-15", "product": "Стикеры Vibe-coder", "price": 350, "quantity": 5 } ]

text

JSON: инвойс с вложенным items

{ "invoices": [ { "invoice_id": "INV-002", "customer_name": "Петров Пётр", "date": "2024-01-20", "items": [ { "product": "Курс по Python", "price": 5900, "quantity": 1 }, { "product": "Доступ в сообщество", "price": 990, "quantity": 1 } ] } ] }

text

Скрипт автоматически определяет, работать как с набором строк, так и с объектом invoice с вложенным массивом items.

---

HTML‑шаблон (invoice_template.html)

<title>{{ i18n_invoice_title }}</title>

{{ i18n_invoice_title }}

text

{{#logo_enabled}} {{/logo_enabled}}

<h2>{{ company_name }}</h2>
<p>ИНН: {{ company_inn }}</p>
<p>{{ company_address }}</p>

{{ i18n_date_label }}: {{ date }}

{{ i18n_customer_label }}: {{ customer_name }}

{{ i18n_items_title }}

{{#items}} {{/items}}

{{ i18n_col_index }}	{{ i18n_col_product }}	{{ i18n_col_price }}	{{ i18n_col_qty }}	{{ i18n_col_total }}
{{ loop.index }}	{{ product }}	{{ price }} {{ currency }}	{{ quantity }}	{{ line_total }} {{ currency }}

{{#taxes_enabled}}

{{ taxes_label }}: {{ tax_amount }} {{ currency }}

{{/taxes_enabled}}

{{#discount_enabled}}

Скидка ({{ discount_percent }}%): −{{ discount_amount }} {{ currency }}

{{/discount_enabled}}

{{#shipping_enabled}}

Доставка: {{ shipping_amount }} {{ currency }}

{{/shipping_enabled}}

{{ i18n_grand_total }}: {{ grand_total }} {{ currency }}

{{ i18n_positions_count }}: {{ items_count }}

{{ i18n_thanks }}

{{ i18n_contacts }}

``` Все тексты и реквизиты приходят из config.json, а суммы/налоги считаются в коде.

Установка и запуск

1. Клонировать репозиторий text git clone https://github.com/USER/REPO.git cd REPO
2. Создать и активировать виртуальное окружение text python -m venv venv

Ubuntu / macOS:

source venv/bin/activate

Windows:

venv\Scripts\activate

3. Установить Python‑зависимости text pip install -r requirements.txt
4. Установить системный weasyprint (CLI) Ubuntu ≥ 20.04:

text sudo apt update sudo apt install -y weasyprint
libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b
libgdk-pixbuf2.0-0 libcairo2 libglib2.0-0 libffi-dev libjpeg-dev libopenjp2-7-dev Проверить:

text weasyprint --version Windows: по официальной инструкции WeasyPrint (Python + MSYS2 + Pango), чтобы команда weasyprint была доступна в PATH. [file:1]

5. Запустить скрипт text python pdf_generator.py Дальше в консоли:

Выбрать файл данных (invoices.csv или invoices.json) из data/.

Выбрать HTML‑шаблон из templates/.

Выбрать invoice_id из списка.

Скрипт создаст PDF в output/ и попытается открыть его (Ubuntu — через xdg-open, Windows — через os.startfile).

Как это использовать бизнесу Быстро выпускать:

счета и акты;

чеки и накладные;

сертификаты для выпускников;

регулярные PDF‑отчёты.

Данные можно выгружать из CRM/таблиц в CSV/JSON, шаблоны — верстать в HTML.

Генератор убирает ручной копипаст, ускоряет документооборот и снижает количество ошибок.

Roadmap (pro‑фичи) Проект задуман как основа под «pro»‑версию генератора документов. Планируемые улучшения:

1. Пакетная генерация и фильтры Режим «сгенерировать все счета за период» или «по конкретному клиенту».

Фильтрация по дате, статусу, клиенту на уровне CLI перед генерацией PDF.

2. Мультистраничные PDF со шапкой/футером Поддержка длинных таблиц на несколько страниц.

Повторяющийся заголовок таблицы (thead) на каждой странице.

Единый футер с нумерацией страниц с помощью CSS paged media (WeasyPrint). [file:1]

3. Расширенный конфиг клиента Поддержка нескольких наборов настроек (несколько компаний/брендов).

Разные валюты и форматы дат.

Локализация шаблонов (RU/EN) через i18n‑блоки в config.json.

4. CLI‑флаги и интеграция в пайплайны CLI‑аргументы: --data, --template, --invoice-id, --all, --output-dir.

Интеграция в cron/CI: автоматическая генерация документов по расписанию или по событию (например, после выгрузки отчёта).

5. Лёгкий API‑слой Небольшой сервис на FastAPI/Flask поверх текущей логики:

принимает JSON с данными инвойса;

отдаёт готовый PDF.

Первый шаг к SaaS‑сервису генерации документов для бизнеса.

Автор Проект разработан как учебный кейс вайб‑кодинга: код генерировался и улучшался с помощью нейросетей, а человек выступает в роли архитектора и режиссёра процесса. Репозиторий можно использовать как портфолио и как основу для коммерческих внедрений генерации PDF‑документов.