relator 0.1.0__py3-none-any.whl

relator-0.1.0.dist-info/METADATA

@@ -0,0 +1,608 @@
+Metadata-Version: 2.4
+Name: relator
+Version: 0.1.0
+Summary: Simple markdown/html report templating with loops, tables, lists and media.
+Author: reporting maintainers
+License: MIT
+Project-URL: Homepage, https://example.com/reporting
+Project-URL: Repository, https://example.com/reporting
+Project-URL: Documentation, https://example.com/reporting/docs
+Keywords: report,template,markdown,html
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich
+Requires-Dist: pillow
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# relator
+
+`relator` — библиотека шаблонов для автогенерации отчётов в Markdown и HTML.
+
+Главная идея:
+
+1. Вы задаёте шаблон.
+2. По шагам добавляете данные через `template.data([name, value])`.
+3. Смотрите предпросмотр `template.print()`.
+4. Компилируете отчёт в файл `template.compile(...)`.
+
+---
+
+## Содержание
+
+1. [Установка](#установка)
+2. [Быстрый старт](#быстрый-старт)
+3. [Концепция шаблона](#концепция-шаблона)
+4. [Служебные плейсхолдеры](#служебные-плейсхолдеры)
+5. [Пошаговый API](#пошаговый-api)
+6. [Подробные примеры](#подробные-примеры)
+7. [Тяжёлые сценарии](#тяжёлые-сценарии)
+8. [Media: PIL и matplotlib](#media-pil-и-matplotlib)
+9. [CLI](#cli)
+10. [Ошибки и отладка](#ошибки-и-отладка)
+11. [FAQ](#faq)
+12. [Рекомендации по архитектуре](#рекомендации-по-архитектуре)
+13. [Кроссплатформенность](#кроссплатформенность)
+14. [Публикация и релиз](#публикация-и-релиз)
+
+---
+
+## Установка
+
+### Через pip из локального проекта
+
+```bash
+cd reporting
+python -m pip install -e .
+```
+
+### Через uv из локального проекта
+
+```bash
+cd reporting
+uv pip install -e .
+```
+
+### Через pip из PyPI
+
+```bash
+python -m pip install relator
+```
+
+### Через uv из PyPI
+
+```bash
+uv pip install relator
+```
+
+### Через pip из GitHub
+
+```bash
+python -m pip install "git+https://github.com/threenebula23/Reporting.git"
+```
+
+### Через uv из GitHub
+
+```bash
+uv pip install "git+https://github.com/threenebula23/Reporting.git"
+```
+
+---
+
+## Быстрый старт
+
+```python
+from reporting import Template
+
+template = Template("template.md")
+template.data(["name", [{"USER": "Ann", "SCORE": 10}, {"USER": "Bob", "SCORE": 20}]])
+template.data(["names", ["Ann", "Bob", "Chris"]])
+template.print()
+template.compile("report.md")
+```
+
+---
+
+## Концепция шаблона
+
+Шаблон — это обычный `.md` или `.html` файл.
+
+Внутри него используются:
+
+- блоки повторения `%%len=VAR ... %%`
+- плейсхолдеры `[[...]]`
+
+Пример:
+
+```text
+%%len=name
+Строка [[CELL.ONE]] из [[CELL.COUNT]]
+|[[name.KEYS]]|
+|[[name.DIVIDER]]|
+|[[name.VALUES]]|
+%%
+```
+
+---
+
+## Служебные плейсхолдеры
+
+Важно: **служебные названия всегда в верхнем регистре**.
+
+### CELL
+
+- `[[CELL.INDEX]]` — индекс 0..N-1
+- `[[CELL.ONE]]` — индекс 1..N
+- `[[CELL.COUNT]]` — длина текущего цикла
+
+### ITEM
+
+- `[[ITEM]]` — текущий элемент в теле `%%len=VAR%%`
+
+### TABLE
+
+- `[[TABLE.VAR]]` — таблица
+- `[[TABLE.VAR.NUMBERED]]` — таблица с колонкой `#`
+- `[[TABLE.VAR.INDEX0]]` — таблица с колонкой index0
+
+### LIST / ENUM
+
+- `[[LIST.VAR]]` — маркированный список
+- `[[ENUM.VAR]]` — нумерованный список
+
+### MEDIA
+
+- `[[MEDIA.VAR]]` — универсальная вставка по типу шаблона
+- `[[MEDIA.VAR.PATH]]` — путь до файла
+- `[[MEDIA.VAR.MD]]` — принудительный Markdown
+- `[[MEDIA.VAR.HTML]]` — принудительный HTML
+
+### Совместимость
+
+- `[[VAR.TABLE]]`
+- `[[VAR.TABLE.NUMBERED]]`
+
+---
+
+## Пошаговый API
+
+### 1) Создать объект
+
+```python
+from reporting import Template
+template = Template("template.md")
+```
+
+### 2) Добавить данные по одной переменной
+
+```python
+template.data(["name", [{"USER": "Ann", "SCORE": 10}]])
+template.data(["names", ["Ann", "Bob"]])
+```
+
+### 3) Посмотреть результат в консоли
+
+```python
+template.print(width=100)
+```
+
+### 4) Скомпилировать в файл
+
+```python
+template.compile("report.md")
+```
+
+### Функциональный шорткат
+
+```python
+from reporting import compile_template
+
+compile_template(
+    template_path="template.md",
+    context={"name": [{"A": 1}], "names": ["x", "y"]},
+    output_path="report.md",
+)
+```
+
+---
+
+## Подробные примеры
+
+### Пример A: таблица внутри цикла
+
+Шаблон:
+
+```text
+%%len=rows
+|[[rows.KEYS]]|
+|[[rows.DIVIDER]]|
+|[[rows.VALUES]]|
+%%
+```
+
+Данные:
+
+```python
+rows = [
+    {"CITY": "Paris", "POP": 2148},
+    {"CITY": "Berlin", "POP": 3769},
+]
+```
+
+### Пример B: таблица целиком
+
+Шаблон:
+
+```text
+[[TABLE.rows]]
+[[TABLE.rows.NUMBERED]]
+```
+
+### Пример C: списки
+
+Шаблон:
+
+```text
+[[LIST.names]]
+[[ENUM.names]]
+```
+
+Данные:
+
+```python
+names = ["Ann", "Bob", "Chris", "Dina"]
+```
+
+### Пример D: вложенный список
+
+Шаблон:
+
+```text
+%%len=names
+1. [[ITEM]]
+   - index: [[CELL.INDEX]]
+   - one: [[CELL.ONE]]
+%%
+```
+
+---
+
+## Тяжёлые сценарии
+
+Ниже сценарии ближе к реальному продакшену.
+
+### Сценарий 1: еженедельный отчёт команды
+
+Цель:
+
+- по командам показать KPI
+- дать агрегированную таблицу
+- вставить график
+
+Шаблон `weekly.md`:
+
+```text
+# Еженедельный отчёт
+
+## Команды
+
+%%len=teams
+### Команда [[ITEM]]
+Индекс: [[CELL.ONE]] / [[CELL.COUNT]]
+%%
+
+## KPI
+[[TABLE.kpi.NUMBERED]]
+
+## График
+[[MEDIA.kpi_chart]]
+```
+
+Код:
+
+```python
+from reporting import Template
+import matplotlib.pyplot as plt
+
+fig = plt.figure(figsize=(6, 3))
+ax = fig.add_subplot(111)
+ax.plot([1, 2, 3, 4], [95, 97, 96, 99], marker="o")
+ax.set_title("KPI динамика")
+
+template = Template("weekly.md", assets_dir="weekly_assets")
+template.data(["teams", ["Backend", "Frontend", "QA"]])
+template.data(["kpi", [
+    {"METRIC": "Coverage", "VALUE": "82%"},
+    {"METRIC": "Incidents", "VALUE": "2"},
+    {"METRIC": "Deploys", "VALUE": "14"},
+]])
+template.data(["kpi_chart", fig])
+template.print()
+template.compile("weekly_report.md")
+```
+
+### Сценарий 2: HTML-отчёт для менеджмента
+
+Шаблон `management.html`:
+
+```html
+<h1>Отчёт менеджмента</h1>
+<h2>Сводная таблица</h2>
+[[TABLE.metrics.HTML]]
+<h2>Визуализация</h2>
+[[MEDIA.chart]]
+```
+
+Код:
+
+```python
+from reporting import Template
+from PIL import Image
+
+logo = Image.new("RGB", (160, 60), "navy")
+
+template = Template("management.html", assets_dir="html_assets")
+template.data(["metrics", [
+    {"NAME": "Revenue", "VALUE": "1.2M"},
+    {"NAME": "Cost", "VALUE": "0.7M"},
+]])
+template.data(["chart", logo])
+template.compile("management_report.html")
+```
+
+### Сценарий 3: много отчётов в цикле по проектам
+
+```python
+from pathlib import Path
+from reporting import Template
+
+projects = {
+    "alpha": {"issues": 14, "coverage": "79%"},
+    "beta": {"issues": 4, "coverage": "88%"},
+    "gamma": {"issues": 0, "coverage": "93%"},
+}
+
+for project_name, data in projects.items():
+    t = Template("project_template.md", assets_dir=Path("assets") / project_name)
+    t.data(["project_name", project_name])
+    t.data(["metrics", [{"KEY": "issues", "VALUE": data["issues"]}, {"KEY": "coverage", "VALUE": data["coverage"]}]])
+    t.compile(Path("reports") / f"{project_name}.md")
+```
+
+### Сценарий 4: пакетная генерация + предпросмотр только при ошибках
+
+```python
+from reporting import Template, TemplateError
+
+def render_safe(template_path: str, out_path: str, context: dict):
+    t = Template(template_path)
+    for k, v in context.items():
+        t.data([k, v])
+    try:
+        t.compile(out_path)
+    except TemplateError:
+        t.print()
+        raise
+```
+
+---
+
+## Media: PIL и matplotlib
+
+### PIL.Image
+
+```python
+from PIL import Image
+from reporting import Template
+
+img = Image.new("RGB", (120, 40), "steelblue")
+t = Template("template.md", assets_dir="assets")
+t.data(["logo", img])
+t.compile("report.md")
+```
+
+### matplotlib.figure.Figure
+
+```python
+import matplotlib.pyplot as plt
+from reporting import Template
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+ax.bar(["A", "B", "C"], [3, 7, 5])
+
+t = Template("template.md")
+t.data(["chart", fig])
+t.compile("report.md")
+```
+
+### Управление вставкой
+
+```text
+[[MEDIA.chart]]       # авто (md/html)
+[[MEDIA.chart.PATH]]  # только путь
+[[MEDIA.chart.MD]]    # строго markdown
+[[MEDIA.chart.HTML]]  # строго html
+```
+
+---
+
+## CLI
+
+### Компиляция в файл
+
+```bash
+relator --template template.md --context context.json --output report.md
+```
+
+### Только печать
+
+```bash
+relator --template template.md --context context.json --print
+```
+
+### Пример context.json
+
+```json
+{
+  "name": [
+    {"USER": "Ann", "SCORE": 10},
+    {"USER": "Bob", "SCORE": 20}
+  ],
+  "names": ["Ann", "Bob", "Chris"]
+}
+```
+
+---
+
+## Ошибки и отладка
+
+### `TemplateError: Unknown placeholder root ...`
+
+Причина:
+
+- в шаблоне используется переменная, которую не добавили через `data`.
+
+Решение:
+
+- проверить имя переменной и регистр.
+
+### `CELL.* is available only inside %%len=VAR%%`
+
+Причина:
+
+- `CELL` использован вне цикла.
+
+Решение:
+
+- перенести плейсхолдер в тело `%%len=...%%`.
+
+### `VAR.VALUES requires %%len=VAR%% context`
+
+Причина:
+
+- `[[VAR.VALUES]]` использован вне своего цикла.
+
+Решение:
+
+- использовать `[[TABLE.VAR]]` или обернуть в `%%len=VAR%%`.
+
+---
+
+## FAQ
+
+### Можно ли использовать lowercase имена переменных?
+
+Да. Например `name`, `rows`, `items`.
+
+### Почему служебные плейсхолдеры uppercase?
+
+Чтобы отделять пользовательские данные от системных токенов.
+
+### Можно ли использовать библиотеку без Rich?
+
+Да, но метод `print()` требует `rich`.
+
+### Можно ли рендерить только в строку без файла?
+
+Да, через `template.render()`.
+
+### Поддерживается ли Windows?
+
+Да, библиотека использует `pathlib` и UTF-8.
+
+---
+
+## Рекомендации по архитектуре
+
+1. Храните шаблоны в `templates/`.
+2. Храните generated отчёты в `reports/`.
+3. Для медиа используйте отдельную папку `assets/`.
+4. Не смешивайте бизнес-логику и шаблонную логику.
+5. Добавьте golden-тесты для ключевых шаблонов.
+
+Пример структуры:
+
+```text
+project/
+  templates/
+    weekly.md
+    management.html
+  reports/
+  assets/
+  scripts/
+    build_reports.py
+```
+
+---
+
+## Кроссплатформенность
+
+- операции с путями через `pathlib.Path`
+- чтение/запись через UTF-8
+- CI-матрица: Linux, macOS, Windows
+- тестовая матрица Python: 3.9–3.13
+
+---
+
+## Публикация и релиз
+
+### Локальная сборка
+
+```bash
+cd reporting
+python -m pip install --upgrade build
+python -m build
+```
+
+### Публикация в TestPyPI
+
+```bash
+python -m pip install --upgrade twine
+python -m twine upload --repository testpypi dist/*
+```
+
+### Публикация в PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+### Проверка установки (smoke test)
+
+```bash
+python -m pip install "git+https://github.com/threenebula23/Reporting.git"
+python -c "from reporting import Template; print(Template)"
+```
+
+---
+
+## Минимальный чеклист перед релизом
+
+- [ ] Все тесты зелёные
+- [ ] README актуален
+- [ ] Версия обновлена
+- [ ] CHANGELOG заполнен
+- [ ] Пакет собирается (`sdist` + `wheel`)
+- [ ] Проверена установка через `pip`
+- [ ] Проверена установка через `uv`
+
+---
+
+## Лицензия
+
+MIT.
+

relator-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+relator-0.1.0.dist-info/licenses/LICENSE,sha256=b9T0kEVk60_9TWL3dlEZfRoRKfGQX_VSIZz3Wuw8S3k,1078
+reporting/__init__.py,sha256=pbXkLtap_5V-oI2_-HOzMYqSFg2HKW51B1FaZbYtmt4,190
+reporting/builtins.py,sha256=eyUu7D5JHvIf4918TNbwt5l7MHFxUzODHTlbOquxGUU,7832
+reporting/cli.py,sha256=lbXraIAYiPZJVFymN76w9r28lwqVnMDPr83RN_Qjhxs,1532
+reporting/engine.py,sha256=UrHPEey97MbS3pQ4WvH1PExGmnRI-S-rLKdqZTF7B_s,5242
+reporting/errors.py,sha256=dW4QcYHqblpD9Wdgx89RH1_kTHcq5hsovUtQrn_xvcw,298
+reporting/media.py,sha256=6A_US84mCcYiovU-PEGL7nyoX6-TLCetWQ5FHlq9sBw,3155
+reporting/parser.py,sha256=3S6POZs__-QvhXF9dk6KXjfpnMmmJ9413o-3aJ3aQQg,2057
+reporting/resolver.py,sha256=JZxczHi2Tpg0HdmuU1DviP_1PEB0X9zsr3RviVwV0N4,1796
+reporting/template.py,sha256=XMheByNSGKCSJQAgknlPdpXAq553a-mW5u6zOeIvB7k,3750
+relator-0.1.0.dist-info/METADATA,sha256=lzEP4t_Yu2OhSNf_3KF2t3ccVXjy6-93PJKaatj9xgQ,13844
+relator-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+relator-0.1.0.dist-info/entry_points.txt,sha256=j7vxAyLr2h-8GtDunCChkcxewhNw4tAqfnfpS687EcM,47
+relator-0.1.0.dist-info/top_level.txt,sha256=4KHGYNPUQIGgNtRdbExkO0ueGRwX45dWfTannK_mf1c,10
+relator-0.1.0.dist-info/RECORD,,

relator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

relator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+relator = reporting.cli:main

relator-0.1.0.dist-info/licenses/LICENSE

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

relator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reporting

reporting/__init__.py

@@ -0,0 +1,7 @@
+"""Public exports for reporting package."""
+
+from .errors import TemplateError
+from .template import Template, compile_template
+
+__all__ = ["Template", "TemplateError", "compile_template"]
+