tg-tree-wizard 1.0.0__tar.gz

tg_tree_wizard-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Артем Самарин
+
+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.

tg_tree_wizard-1.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: tg-tree-wizard
+Version: 1.0.0
+Summary: Лёгкий движок древовидных inline-опросников (wizard) для aiogram 3
+Author: Артем Самарин
+License: MIT License
+        
+        Copyright (c) 2026 Артем Самарин
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/ваш-ник/tg-tree-wizard
+Project-URL: Repository, https://github.com/ваш-ник/tg-tree-wizard
+Project-URL: Issues, https://github.com/ваш-ник/tg-tree-wizard/issues
+Keywords: aiogram,telegram,telegram-bot,inline-keyboard,fsm,wizard
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiogram>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# tg-tree-wizard
+
+Лёгкий движок древовидных inline-опросников для aiogram 3.
+Дерево описывается данными (`Node`/`Option`), а не отдельным хендлером на
+каждый уровень; "назад" и переходы обрабатываются двумя общими хендлерами
+независимо от глубины дерева.
+
+## Сколько кода экономит
+
+Замер на дереве из 6 уровней (язык → формат → цель → индивидуально/группа →
+возраст → уровень владения), с 2-7 вариантами ответа на каждом —
+навигационная часть кода, без учёта бизнес-логики финального шага
+(сохранение заявки и т.п. — она одинакова в обоих случаях):
+
+| | Строк кода |
+|---|---|
+| Вручную (клавиатура + парсинг callback_data + кнопка "назад" на каждый уровень) | ~169 |
+| `tg-tree-wizard` (`linear_wizard` + подключение роутера) | ~26 |
+
+Разница держится линейно — не растёт и не убывает в зависимости от того,
+сколько таких деревьев в проекте: каждое новое дерево стоит фиксированные
+~26 строк вместо ~169, потому что логика навигации, "назад" и защита от
+превышения лимита `callback_data` уже написаны и покрыты тестами один раз,
+внутри самой библиотеки.
+
+## Структура пакета
+
+```
+tg_tree_wizard/
+├── pyproject.toml              # метаданные пакета, как его ставить
+├── src/tg_tree_wizard/
+│   ├── __init__.py             # публичный API (что видно снаружи через import)
+│   ├── core.py                 # чистая логика дерева, БЕЗ aiogram
+│   └── aiogram_adapter.py      # клавиатуры + хендлеры aiogram поверх core.py
+├── tests/
+│   └── test_core.py            # тесты ядра, без сети и без Telegram
+└── examples/
+    ├── simulate_flow.py        # прогон через настоящий aiogram Dispatcher, без сети
+    └── language_school_bot.py  # реальный бот — запускается с настоящим токеном
+```
+
+Почему `core.py` отдельно от `aiogram_adapter.py`: это приём, который
+делает библиотеку тестируемой. Ядро ничего не знает про Telegram — значит,
+его логику (переходы, "назад", ошибки) можно проверить обычным `pytest` за
+доли секунды, без сети и без живого бота. Адаптер — тонкий слой, который
+только рендерит клавиатуры и дёргает ядро.
+
+## Установка
+
+```bash
+cd tg_tree_wizard
+pip install -e .          # editable-режим: правите код — сразу видно в проекте
+```
+
+`-e` (editable) значит, что пакет ставится "по ссылке" на исходники, а не
+копируется — удобно, пока сами дорабатываете библиотеку.
+
+## Тесты ядра (без Telegram)
+
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+## Прогон через настоящий aiogram, но без сети
+
+```bash
+python examples/simulate_flow.py
+```
+
+Использует настоящий `Dispatcher` и `MemoryStorage`, подменяет только
+реальный HTTP-запрос к `api.telegram.org` — так что проверяется всё,
+кроме собственно доставки сообщений.
+
+## Запуск с реальным ботом
+
+```bash
+export BOT_TOKEN=ваш_настоящий_токен
+python examples/language_school_bot.py
+```
+
+Дальше пишите `/survey` в бота и проходите дерево — это уже 100% реальная
+проверка через живой Telegram.
+
+## Как описать своё дерево
+
+**Короткий способ (рекомендуется для большинства случаев)** — `linear_wizard`.
+Подходит, когда вопросы идут по порядку и лишь изредка нужно свернуть в
+сторону:
+
+```python
+from tg_tree_wizard import linear_wizard, TreeWizard
+
+TREE, ROOT = linear_wizard([
+    ("lang", "Выберите язык:", ["Английский", "Немецкий"]),       # label == value
+    ("delivery", "Формат:", [("Очно", "offline"), ("Онлайн", "online")]),
+    ("topping", "Начинка:", [
+        ("Пепперони", "pepperoni", "spicy"),   # явный переход = ветвление
+        ("Маргарита", "margherita"),           # без 3-го элемента = следующий шаг по порядку
+    ]),
+    ("spicy", "Поострее?", ["Да", "Нет"]),
+])
+
+wizard = TreeWizard(TREE, root=ROOT, on_finish=my_finish_callback)
+dp.include_router(wizard.router)
+```
+
+Правила для варианта ответа:
+- `"Текст"` — метка и значение совпадают, переход на следующий шаг по списку;
+- `("Текст", "значение")` — то же самое, но значение отдельно от текста кнопки;
+- `("Текст", "значение", "id_узла")` — явный переход, для ветвления или
+  для перехода не на следующий, а на произвольный узел (в т.ч. в обход
+  промежуточных шагов).
+
+Последний шаг в списке — финальный по умолчанию (после него опрос
+завершается), если явно не переопределить переход у его вариантов.
+
+Полный способ — `Node`/`Option` напрямую. Нужен, когда переходов в
+дерево больше, чем шагов, и связь "шаг → следующий по умолчанию" не
+работает (сложные ветвящиеся графы, несколько независимых корней и т.п.):
+
+```python
+from tg_tree_wizard import Node, Option, TreeWizard
+
+TREE = {
+    "start": Node(
+        text="Первый вопрос:",
+        options=(
+            Option("Вариант A", "a", "next_node_id"),
+            Option("Вариант B", "b", None),  # None = опрос завершается
+        ),
+    ),
+    "next_node_id": Node(...),
+}
+
+wizard = TreeWizard(TREE, root="start", on_finish=my_finish_callback)
+```
+
+`TreeWizard(...)` сам вызывает `validate_tree` при создании — если где-то
+опечатались в id узла, бот упадёт при старте с понятной ошибкой.

tg_tree_wizard-1.0.0/README.md

@@ -0,0 +1,140 @@
+# tg-tree-wizard
+
+Лёгкий движок древовидных inline-опросников для aiogram 3.
+Дерево описывается данными (`Node`/`Option`), а не отдельным хендлером на
+каждый уровень; "назад" и переходы обрабатываются двумя общими хендлерами
+независимо от глубины дерева.
+
+## Сколько кода экономит
+
+Замер на дереве из 6 уровней (язык → формат → цель → индивидуально/группа →
+возраст → уровень владения), с 2-7 вариантами ответа на каждом —
+навигационная часть кода, без учёта бизнес-логики финального шага
+(сохранение заявки и т.п. — она одинакова в обоих случаях):
+
+| | Строк кода |
+|---|---|
+| Вручную (клавиатура + парсинг callback_data + кнопка "назад" на каждый уровень) | ~169 |
+| `tg-tree-wizard` (`linear_wizard` + подключение роутера) | ~26 |
+
+Разница держится линейно — не растёт и не убывает в зависимости от того,
+сколько таких деревьев в проекте: каждое новое дерево стоит фиксированные
+~26 строк вместо ~169, потому что логика навигации, "назад" и защита от
+превышения лимита `callback_data` уже написаны и покрыты тестами один раз,
+внутри самой библиотеки.
+
+## Структура пакета
+
+```
+tg_tree_wizard/
+├── pyproject.toml              # метаданные пакета, как его ставить
+├── src/tg_tree_wizard/
+│   ├── __init__.py             # публичный API (что видно снаружи через import)
+│   ├── core.py                 # чистая логика дерева, БЕЗ aiogram
+│   └── aiogram_adapter.py      # клавиатуры + хендлеры aiogram поверх core.py
+├── tests/
+│   └── test_core.py            # тесты ядра, без сети и без Telegram
+└── examples/
+    ├── simulate_flow.py        # прогон через настоящий aiogram Dispatcher, без сети
+    └── language_school_bot.py  # реальный бот — запускается с настоящим токеном
+```
+
+Почему `core.py` отдельно от `aiogram_adapter.py`: это приём, который
+делает библиотеку тестируемой. Ядро ничего не знает про Telegram — значит,
+его логику (переходы, "назад", ошибки) можно проверить обычным `pytest` за
+доли секунды, без сети и без живого бота. Адаптер — тонкий слой, который
+только рендерит клавиатуры и дёргает ядро.
+
+## Установка
+
+```bash
+cd tg_tree_wizard
+pip install -e .          # editable-режим: правите код — сразу видно в проекте
+```
+
+`-e` (editable) значит, что пакет ставится "по ссылке" на исходники, а не
+копируется — удобно, пока сами дорабатываете библиотеку.
+
+## Тесты ядра (без Telegram)
+
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+## Прогон через настоящий aiogram, но без сети
+
+```bash
+python examples/simulate_flow.py
+```
+
+Использует настоящий `Dispatcher` и `MemoryStorage`, подменяет только
+реальный HTTP-запрос к `api.telegram.org` — так что проверяется всё,
+кроме собственно доставки сообщений.
+
+## Запуск с реальным ботом
+
+```bash
+export BOT_TOKEN=ваш_настоящий_токен
+python examples/language_school_bot.py
+```
+
+Дальше пишите `/survey` в бота и проходите дерево — это уже 100% реальная
+проверка через живой Telegram.
+
+## Как описать своё дерево
+
+**Короткий способ (рекомендуется для большинства случаев)** — `linear_wizard`.
+Подходит, когда вопросы идут по порядку и лишь изредка нужно свернуть в
+сторону:
+
+```python
+from tg_tree_wizard import linear_wizard, TreeWizard
+
+TREE, ROOT = linear_wizard([
+    ("lang", "Выберите язык:", ["Английский", "Немецкий"]),       # label == value
+    ("delivery", "Формат:", [("Очно", "offline"), ("Онлайн", "online")]),
+    ("topping", "Начинка:", [
+        ("Пепперони", "pepperoni", "spicy"),   # явный переход = ветвление
+        ("Маргарита", "margherita"),           # без 3-го элемента = следующий шаг по порядку
+    ]),
+    ("spicy", "Поострее?", ["Да", "Нет"]),
+])
+
+wizard = TreeWizard(TREE, root=ROOT, on_finish=my_finish_callback)
+dp.include_router(wizard.router)
+```
+
+Правила для варианта ответа:
+- `"Текст"` — метка и значение совпадают, переход на следующий шаг по списку;
+- `("Текст", "значение")` — то же самое, но значение отдельно от текста кнопки;
+- `("Текст", "значение", "id_узла")` — явный переход, для ветвления или
+  для перехода не на следующий, а на произвольный узел (в т.ч. в обход
+  промежуточных шагов).
+
+Последний шаг в списке — финальный по умолчанию (после него опрос
+завершается), если явно не переопределить переход у его вариантов.
+
+Полный способ — `Node`/`Option` напрямую. Нужен, когда переходов в
+дерево больше, чем шагов, и связь "шаг → следующий по умолчанию" не
+работает (сложные ветвящиеся графы, несколько независимых корней и т.п.):
+
+```python
+from tg_tree_wizard import Node, Option, TreeWizard
+
+TREE = {
+    "start": Node(
+        text="Первый вопрос:",
+        options=(
+            Option("Вариант A", "a", "next_node_id"),
+            Option("Вариант B", "b", None),  # None = опрос завершается
+        ),
+    ),
+    "next_node_id": Node(...),
+}
+
+wizard = TreeWizard(TREE, root="start", on_finish=my_finish_callback)
+```
+
+`TreeWizard(...)` сам вызывает `validate_tree` при создании — если где-то
+опечатались в id узла, бот упадёт при старте с понятной ошибкой.

tg_tree_wizard-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tg-tree-wizard"
+version = "1.0.0"
+description = "Лёгкий движок древовидных inline-опросников (wizard) для aiogram 3"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Артем Самарин" },
+]
+keywords = ["aiogram", "telegram", "telegram-bot", "inline-keyboard", "fsm", "wizard"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: AsyncIO",
+    "Topic :: Communications :: Chat",
+]
+dependencies = [
+    "aiogram>=3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/ваш-ник/tg-tree-wizard"
+Repository = "https://github.com/ваш-ник/tg-tree-wizard"
+Issues = "https://github.com/ваш-ник/tg-tree-wizard/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tg_tree_wizard = ["py.typed"]

tg_tree_wizard-1.0.0/setup.cfg

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

tg_tree_wizard-1.0.0/src/tg_tree_wizard/__init__.py

@@ -0,0 +1,15 @@
+from .core import Node, Option, WizardState, TreeError, StaleChoiceError, linear_wizard
+from .aiogram_adapter import TreeWizard, WizardStates, pack_buttons, check_callback_data_limits
+
+__all__ = [
+    "Node",
+    "Option",
+    "WizardState",
+    "TreeError",
+    "StaleChoiceError",
+    "linear_wizard",
+    "TreeWizard",
+    "WizardStates",
+    "pack_buttons",
+    "check_callback_data_limits",
+]

tg_tree_wizard-1.0.0/src/tg_tree_wizard/aiogram_adapter.py

@@ -0,0 +1,182 @@
+"""
+Тонкий адаптер над core.py: рендер клавиатур, хендлеры aiogram,
+хранение WizardState в FSMContext. Логики дерева здесь нет —
+она уже проверена в core.py, тут только Telegram I/O.
+"""
+
+from aiogram import Router, F
+from aiogram.filters import StateFilter
+from aiogram.fsm.context import FSMContext
+from aiogram.fsm.state import State, StatesGroup
+from aiogram.types import CallbackQuery, InlineKeyboardButton, InlineKeyboardMarkup, Message
+
+from .core import Node, WizardState, choose, go_back, validate_tree, StaleChoiceError, TreeError
+
+
+class WizardStates(StatesGroup):
+    active = State()  # один State на весь опрос, независимо от глубины дерева
+
+
+# Официальный лимит Telegram Bot API на длину callback_data.
+TELEGRAM_CALLBACK_DATA_LIMIT_BYTES = 64
+
+
+def check_callback_data_limits(tree: dict[str, Node], callback_prefix: str) -> None:
+    """
+    Проверяет, что callback_data ни для одного узла/варианта не превысит
+    лимит Telegram в 64 байта, и что id узлов не содержат ':' (используется
+    как разделитель в callback_data и сломает парсинг).
+
+    В отличие от исходного бота, где в callback_data кодировался весь
+    пройденный путь (и лимит рос вместе с глубиной дерева), здесь в
+    callback_data передаётся только текущий узел + индекс варианта — путь
+    хранится в FSMContext. Поэтому лимит практически не зависит от глубины
+    дерева, но всё ещё зависит от длины id узлов и callback_prefix.
+    """
+    if ":" in callback_prefix:
+        raise TreeError(f"callback_prefix {callback_prefix!r} не может содержать ':'")
+
+    back_data = f"{callback_prefix}_back"
+    back_len = len(back_data.encode("utf-8"))
+    if back_len > TELEGRAM_CALLBACK_DATA_LIMIT_BYTES:
+        raise TreeError(
+            f"callback_data кнопки 'Назад' ({back_data!r}) занимает {back_len} байт, "
+            f"это больше лимита Telegram в {TELEGRAM_CALLBACK_DATA_LIMIT_BYTES}. "
+            f"Сократите callback_prefix."
+        )
+
+    for node_id, node in tree.items():
+        if ":" in node_id:
+            raise TreeError(
+                f"id узла {node_id!r} содержит ':' — это разделитель в callback_data, "
+                f"переименуйте узел."
+            )
+
+        max_index = len(node.options) - 1
+        candidate = f"{callback_prefix}:{node_id}:{max_index}"
+        length = len(candidate.encode("utf-8"))
+        if length > TELEGRAM_CALLBACK_DATA_LIMIT_BYTES:
+            raise TreeError(
+                f"callback_data для узла {node_id!r} займёт {length} байт "
+                f"({candidate!r}), это больше лимита Telegram в "
+                f"{TELEGRAM_CALLBACK_DATA_LIMIT_BYTES}. Сократите id узла "
+                f"или callback_prefix."
+            )
+
+
+def pack_buttons(
+    buttons: list[InlineKeyboardButton],
+    max_row_length: int = 30,
+) -> list[list[InlineKeyboardButton]]:
+    """Авто-раскладка кнопок по рядам с учётом длины текста."""
+    rows: list[list[InlineKeyboardButton]] = []
+    current_row: list[InlineKeyboardButton] = []
+    current_length = 0
+
+    for button in buttons:
+        button_length = len(button.text) + 5
+        if current_row and current_length + button_length > max_row_length:
+            rows.append(current_row)
+            current_row = [button]
+            current_length = button_length
+        else:
+            current_row.append(button)
+            current_length += button_length
+
+    if current_row:
+        rows.append(current_row)
+    return rows
+
+
+class TreeWizard:
+    """
+    Собирает Router для дерева. Использование:
+
+        wizard = TreeWizard(TREE, root="lang", callback_prefix="wz")
+        dp.include_router(wizard.router)
+
+        @dp.message(Command("survey"))
+        async def cmd_survey(message: Message, state: FSMContext):
+            await wizard.start(message, state)
+    """
+
+    def __init__(
+        self,
+        tree: dict[str, Node],
+        root: str,
+        callback_prefix: str = "wz",
+        max_row_length: int = 30,
+        on_finish=None,  # async def on_finish(message_or_call, state, answers): ...
+    ):
+        validate_tree(tree, root)  # падаем при старте бота, а не в рантайме
+        check_callback_data_limits(tree, callback_prefix)
+        self.tree = tree
+        self.root = root
+        self.prefix = callback_prefix
+        self.max_row_length = max_row_length
+        self.on_finish = on_finish
+        self.router = Router()
+        self._register_handlers()
+
+    def _build_keyboard(self, node_id: str, node: Node) -> InlineKeyboardMarkup:
+        buttons = [
+            InlineKeyboardButton(
+                text=opt.label, callback_data=f"{self.prefix}:{node_id}:{i}"
+            )
+            for i, opt in enumerate(node.options)
+        ]
+        rows = pack_buttons(buttons, self.max_row_length)
+        if node_id != self.root:
+            rows.append(
+                [InlineKeyboardButton(text="⬅️ Назад", callback_data=f"{self.prefix}_back")]
+            )
+        return InlineKeyboardMarkup(inline_keyboard=rows)
+
+    async def _render(self, target, node_id: str):
+        node = self.tree[node_id]
+        kb = self._build_keyboard(node_id, node)
+        if isinstance(target, CallbackQuery):
+            await target.message.edit_text(node.text, reply_markup=kb)
+        else:
+            await target.answer(node.text, reply_markup=kb)
+
+    async def start(self, message: Message, state: FSMContext):
+        wz = WizardState.start(self.root)
+        await state.set_state(WizardStates.active)
+        await state.update_data(**wz.to_dict())
+        await self._render(message, self.root)
+
+    def _register_handlers(self):
+        @self.router.callback_query(
+            StateFilter(WizardStates.active), F.data.startswith(f"{self.prefix}:")
+        )
+        async def handle_choice(call: CallbackQuery, state: FSMContext):
+            _, node_id, idx_str = call.data.split(":")
+            data = await state.get_data()
+            wz = WizardState.from_dict(data)
+
+            try:
+                new_wz, opt, is_final = choose(self.tree, wz, node_id, int(idx_str))
+            except StaleChoiceError:
+                await call.answer("Это меню устарело, начните заново.", show_alert=True)
+                return
+
+            await state.update_data(**new_wz.to_dict())
+
+            if is_final:
+                if self.on_finish:
+                    await self.on_finish(call, state, new_wz.answers)
+                await state.clear()
+            else:
+                await self._render(call, opt.next_node)
+            await call.answer()
+
+        @self.router.callback_query(
+            StateFilter(WizardStates.active), F.data == f"{self.prefix}_back"
+        )
+        async def handle_back(call: CallbackQuery, state: FSMContext):
+            data = await state.get_data()
+            wz = go_back(WizardState.from_dict(data))
+            await state.update_data(**wz.to_dict())
+            await self._render(call, wz.current_node)
+            await call.answer()

tg_tree_wizard-1.0.0/src/tg_tree_wizard/core.py

@@ -0,0 +1,186 @@
+"""
+Ядро дерева-опросника. Никаких импортов aiogram здесь нет и не должно быть —
+это чистая логика, которую можно тестировать без Telegram и без сети.
+"""
+
+from dataclasses import dataclass, field, replace
+
+
+class TreeError(Exception):
+    """Ошибка в описании дерева (обнаруживается один раз, при старте бота)."""
+
+
+class StaleChoiceError(Exception):
+    """Пользователь нажал на кнопку из уже неактуального (старого) сообщения."""
+
+
+@dataclass(frozen=True)
+class Option:
+    label: str
+    value: str
+    next_node: str | None = None  # None = после выбора опрос завершается
+
+
+@dataclass(frozen=True)
+class Node:
+    text: str
+    options: tuple[Option, ...] = field(default_factory=tuple)
+
+
+def validate_tree(tree: dict[str, Node], root: str) -> None:
+    """
+    Проверяет дерево один раз при старте бота, а не в рантайме на живом
+    пользователе. Ловит: отсутствующий root, ссылки на несуществующие
+    узлы, узлы без вариантов ответа (тупик).
+    """
+    if root not in tree:
+        raise TreeError(f"Корневой узел {root!r} отсутствует в дереве")
+
+    for node_id, node in tree.items():
+        if not node.options:
+            raise TreeError(f"Узел {node_id!r} не содержит вариантов ответа")
+        for opt in node.options:
+            if opt.next_node is not None and opt.next_node not in tree:
+                raise TreeError(
+                    f"Узел {node_id!r}: вариант {opt.label!r} ссылается "
+                    f"на несуществующий узел {opt.next_node!r}"
+                )
+
+
+@dataclass(frozen=True)
+class Answer:
+    node: str
+    label: str
+    value: str
+
+
+@dataclass(frozen=True)
+class WizardState:
+    """
+    Всё состояние одного прохождения опроса. Неизменяемое (frozen) —
+    каждая операция возвращает НОВЫЙ WizardState, старый не трогается.
+    Это то, что вы будете класть целиком в FSMContext.data.
+    """
+    stack: tuple[str, ...]
+    answers: tuple[Answer, ...] = field(default_factory=tuple)
+
+    @classmethod
+    def start(cls, root: str) -> "WizardState":
+        return cls(stack=(root,), answers=())
+
+    @property
+    def current_node(self) -> str:
+        return self.stack[-1]
+
+    def to_dict(self) -> dict:
+        """Для сохранения в FSMContext.data (там нужны сериализуемые типы)."""
+        return {
+            "stack": list(self.stack),
+            "answers": [a.__dict__ for a in self.answers],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "WizardState":
+        return cls(
+            stack=tuple(data["stack"]),
+            answers=tuple(Answer(**a) for a in data["answers"]),
+        )
+
+
+def choose(
+    tree: dict[str, Node],
+    state: WizardState,
+    node_id: str,
+    option_index: int,
+) -> tuple[WizardState, Option, bool]:
+    """
+    Обрабатывает выбор пользователя.
+    Возвращает (новое_состояние, выбранная_опция, завершён_ли_опрос).
+    """
+    if state.current_node != node_id:
+        # Пользователь нажал кнопку из уже неактуального сообщения
+        # (например, после /start заново или параллельного диалога).
+        raise StaleChoiceError(
+            f"Ожидался узел {state.current_node!r}, получен {node_id!r}"
+        )
+
+    node = tree[node_id]
+    if not (0 <= option_index < len(node.options)):
+        raise TreeError(f"Индекс {option_index} вне диапазона для узла {node_id!r}")
+
+    opt = node.options[option_index]
+    new_answers = state.answers + (Answer(node_id, opt.label, opt.value),)
+
+    if opt.next_node is None:
+        return replace(state, answers=new_answers), opt, True
+
+    new_stack = state.stack + (opt.next_node,)
+    return replace(state, stack=new_stack, answers=new_answers), opt, False
+
+
+def go_back(state: WizardState) -> WizardState:
+    """Отменяет последний шаг. Если мы уже в корне — ничего не делает."""
+    if len(state.stack) <= 1:
+        return state
+    return WizardState(stack=state.stack[:-1], answers=state.answers[:-1])
+
+
+# Один вариант ответа в коротком синтаксисе linear_wizard:
+#   "Текст кнопки"                       -> label == value, переход на следующий шаг
+#   ("Текст кнопки", "значение")         -> явное значение, переход на следующий шаг
+#   ("Текст кнопки", "значение", "узел") -> явное значение + явный переход (ветвление)
+ShortOption = str | tuple[str, str] | tuple[str, str, str]
+
+# Один шаг: (id_узла, текст_вопроса, список_вариантов)
+Step = tuple[str, str, list[ShortOption]]
+
+
+def linear_wizard(steps: list[Step]) -> tuple[dict[str, Node], str]:
+    """
+    Короткий способ описать дерево для типового случая — линейной цепочки
+    вопросов, где почти все варианты ведут на следующий шаг по порядку.
+    Возвращает (tree, root_id), готовые для validate_tree()/TreeWizard().
+
+    Последний шаг по умолчанию — финальный (next_node=None у всех его
+    вариантов, если не переопределено явно).
+
+    Точечное ветвление — там, где часть вариантов уходит не на следующий
+    шаг, а куда-то ещё (или сразу в финал, минуя промежуточные шаги) —
+    делается явным третьим элементом кортежа с id нужного узла.
+
+    Пример:
+        TREE, ROOT = linear_wizard([
+            ("size", "Выберите размер:", ["Маленькая", "Средняя", "Большая"]),
+            ("topping", "Начинка:", [
+                ("Пепперони", "pepperoni", "spicy"),  # ветка в сторону
+                "Маргарита",                          # обычный переход дальше
+            ]),
+            ("spicy", "Поострее?", ["Да", "Нет"]),
+            ("confirm", "Подтвердить заказ?", ["Да"]),
+        ])
+    """
+    if not steps:
+        raise TreeError("Нужен хотя бы один шаг")
+
+    node_ids = [step[0] for step in steps]
+    tree: dict[str, Node] = {}
+
+    for i, (node_id, text, options) in enumerate(steps):
+        default_next = node_ids[i + 1] if i + 1 < len(node_ids) else None
+        built_options = []
+
+        for opt in options:
+            if isinstance(opt, str):
+                label, value, next_node = opt, opt, default_next
+            elif len(opt) == 2:
+                label, value = opt
+                next_node = default_next
+            elif len(opt) == 3:
+                label, value, next_node = opt
+            else:
+                raise TreeError(f"Некорректный вариант ответа: {opt!r}")
+            built_options.append(Option(label, value, next_node))
+
+        tree[node_id] = Node(text=text, options=tuple(built_options))
+
+    return tree, node_ids[0]

tg_tree_wizard-1.0.0/src/tg_tree_wizard.egg-info/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: tg-tree-wizard
+Version: 1.0.0
+Summary: Лёгкий движок древовидных inline-опросников (wizard) для aiogram 3
+Author: Артем Самарин
+License: MIT License
+        
+        Copyright (c) 2026 Артем Самарин
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/ваш-ник/tg-tree-wizard
+Project-URL: Repository, https://github.com/ваш-ник/tg-tree-wizard
+Project-URL: Issues, https://github.com/ваш-ник/tg-tree-wizard/issues
+Keywords: aiogram,telegram,telegram-bot,inline-keyboard,fsm,wizard
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiogram>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# tg-tree-wizard
+
+Лёгкий движок древовидных inline-опросников для aiogram 3.
+Дерево описывается данными (`Node`/`Option`), а не отдельным хендлером на
+каждый уровень; "назад" и переходы обрабатываются двумя общими хендлерами
+независимо от глубины дерева.
+
+## Сколько кода экономит
+
+Замер на дереве из 6 уровней (язык → формат → цель → индивидуально/группа →
+возраст → уровень владения), с 2-7 вариантами ответа на каждом —
+навигационная часть кода, без учёта бизнес-логики финального шага
+(сохранение заявки и т.п. — она одинакова в обоих случаях):
+
+| | Строк кода |
+|---|---|
+| Вручную (клавиатура + парсинг callback_data + кнопка "назад" на каждый уровень) | ~169 |
+| `tg-tree-wizard` (`linear_wizard` + подключение роутера) | ~26 |
+
+Разница держится линейно — не растёт и не убывает в зависимости от того,
+сколько таких деревьев в проекте: каждое новое дерево стоит фиксированные
+~26 строк вместо ~169, потому что логика навигации, "назад" и защита от
+превышения лимита `callback_data` уже написаны и покрыты тестами один раз,
+внутри самой библиотеки.
+
+## Структура пакета
+
+```
+tg_tree_wizard/
+├── pyproject.toml              # метаданные пакета, как его ставить
+├── src/tg_tree_wizard/
+│   ├── __init__.py             # публичный API (что видно снаружи через import)
+│   ├── core.py                 # чистая логика дерева, БЕЗ aiogram
+│   └── aiogram_adapter.py      # клавиатуры + хендлеры aiogram поверх core.py
+├── tests/
+│   └── test_core.py            # тесты ядра, без сети и без Telegram
+└── examples/
+    ├── simulate_flow.py        # прогон через настоящий aiogram Dispatcher, без сети
+    └── language_school_bot.py  # реальный бот — запускается с настоящим токеном
+```
+
+Почему `core.py` отдельно от `aiogram_adapter.py`: это приём, который
+делает библиотеку тестируемой. Ядро ничего не знает про Telegram — значит,
+его логику (переходы, "назад", ошибки) можно проверить обычным `pytest` за
+доли секунды, без сети и без живого бота. Адаптер — тонкий слой, который
+только рендерит клавиатуры и дёргает ядро.
+
+## Установка
+
+```bash
+cd tg_tree_wizard
+pip install -e .          # editable-режим: правите код — сразу видно в проекте
+```
+
+`-e` (editable) значит, что пакет ставится "по ссылке" на исходники, а не
+копируется — удобно, пока сами дорабатываете библиотеку.
+
+## Тесты ядра (без Telegram)
+
+```bash
+pip install pytest
+pytest tests/ -v
+```
+
+## Прогон через настоящий aiogram, но без сети
+
+```bash
+python examples/simulate_flow.py
+```
+
+Использует настоящий `Dispatcher` и `MemoryStorage`, подменяет только
+реальный HTTP-запрос к `api.telegram.org` — так что проверяется всё,
+кроме собственно доставки сообщений.
+
+## Запуск с реальным ботом
+
+```bash
+export BOT_TOKEN=ваш_настоящий_токен
+python examples/language_school_bot.py
+```
+
+Дальше пишите `/survey` в бота и проходите дерево — это уже 100% реальная
+проверка через живой Telegram.
+
+## Как описать своё дерево
+
+**Короткий способ (рекомендуется для большинства случаев)** — `linear_wizard`.
+Подходит, когда вопросы идут по порядку и лишь изредка нужно свернуть в
+сторону:
+
+```python
+from tg_tree_wizard import linear_wizard, TreeWizard
+
+TREE, ROOT = linear_wizard([
+    ("lang", "Выберите язык:", ["Английский", "Немецкий"]),       # label == value
+    ("delivery", "Формат:", [("Очно", "offline"), ("Онлайн", "online")]),
+    ("topping", "Начинка:", [
+        ("Пепперони", "pepperoni", "spicy"),   # явный переход = ветвление
+        ("Маргарита", "margherita"),           # без 3-го элемента = следующий шаг по порядку
+    ]),
+    ("spicy", "Поострее?", ["Да", "Нет"]),
+])
+
+wizard = TreeWizard(TREE, root=ROOT, on_finish=my_finish_callback)
+dp.include_router(wizard.router)
+```
+
+Правила для варианта ответа:
+- `"Текст"` — метка и значение совпадают, переход на следующий шаг по списку;
+- `("Текст", "значение")` — то же самое, но значение отдельно от текста кнопки;
+- `("Текст", "значение", "id_узла")` — явный переход, для ветвления или
+  для перехода не на следующий, а на произвольный узел (в т.ч. в обход
+  промежуточных шагов).
+
+Последний шаг в списке — финальный по умолчанию (после него опрос
+завершается), если явно не переопределить переход у его вариантов.
+
+Полный способ — `Node`/`Option` напрямую. Нужен, когда переходов в
+дерево больше, чем шагов, и связь "шаг → следующий по умолчанию" не
+работает (сложные ветвящиеся графы, несколько независимых корней и т.п.):
+
+```python
+from tg_tree_wizard import Node, Option, TreeWizard
+
+TREE = {
+    "start": Node(
+        text="Первый вопрос:",
+        options=(
+            Option("Вариант A", "a", "next_node_id"),
+            Option("Вариант B", "b", None),  # None = опрос завершается
+        ),
+    ),
+    "next_node_id": Node(...),
+}
+
+wizard = TreeWizard(TREE, root="start", on_finish=my_finish_callback)
+```
+
+`TreeWizard(...)` сам вызывает `validate_tree` при создании — если где-то
+опечатались в id узла, бот упадёт при старте с понятной ошибкой.

tg_tree_wizard-1.0.0/src/tg_tree_wizard.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/tg_tree_wizard/__init__.py
+src/tg_tree_wizard/aiogram_adapter.py
+src/tg_tree_wizard/core.py
+src/tg_tree_wizard/py.typed
+src/tg_tree_wizard.egg-info/PKG-INFO
+src/tg_tree_wizard.egg-info/SOURCES.txt
+src/tg_tree_wizard.egg-info/dependency_links.txt
+src/tg_tree_wizard.egg-info/requires.txt
+src/tg_tree_wizard.egg-info/top_level.txt
+tests/test_adapter.py
+tests/test_core.py

tg_tree_wizard-1.0.0/src/tg_tree_wizard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tg_tree_wizard-1.0.0/src/tg_tree_wizard.egg-info/requires.txt

@@ -0,0 +1,4 @@
+aiogram>=3.0
+
+[dev]
+pytest>=8.0

tg_tree_wizard-1.0.0/src/tg_tree_wizard.egg-info/top_level.txt

@@ -0,0 +1 @@
+tg_tree_wizard

tg_tree_wizard-1.0.0/tests/test_adapter.py

@@ -0,0 +1,72 @@
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+import pytest
+from tg_tree_wizard.core import Node, Option, TreeError
+from tg_tree_wizard.aiogram_adapter import (
+    TreeWizard,
+    check_callback_data_limits,
+    TELEGRAM_CALLBACK_DATA_LIMIT_BYTES,
+)
+
+
+def make_node(n_options: int = 2) -> Node:
+    return Node(
+        text="x",
+        options=tuple(Option(f"opt{i}", f"v{i}", None) for i in range(n_options)),
+    )
+
+
+def test_normal_tree_passes_callback_limit_check():
+    tree = {"lang": make_node(), "delivery": make_node()}
+    check_callback_data_limits(tree, callback_prefix="wz")  # не должно кинуть
+
+
+def test_long_node_id_exceeds_limit_and_is_caught():
+    long_id = "a" * 60  # заведомо длинный id узла
+    tree = {long_id: make_node()}
+    with pytest.raises(TreeError):
+        check_callback_data_limits(tree, callback_prefix="wz")
+
+
+def test_colon_in_node_id_is_rejected():
+    tree = {"bad:id": make_node()}
+    with pytest.raises(TreeError):
+        check_callback_data_limits(tree, callback_prefix="wz")
+
+
+def test_treewizard_raises_at_construction_not_at_runtime():
+    """
+    Ключевое свойство: ошибка ловится при СОЗДАНИИ TreeWizard (то есть при
+    старте бота), а не когда до этого узла случайно дойдёт живой пользователь.
+    """
+    long_id = "b" * 60
+    tree = {long_id: make_node()}
+    with pytest.raises(TreeError):
+        TreeWizard(tree, root=long_id)
+
+
+def test_realistic_short_ids_stay_well_under_limit():
+    """
+    Проверка на здравый смысл: обычные короткие id узлов (как в примерах
+    из README) даже близко не подходят к лимиту, независимо от того,
+    сколько шагов в дереве — потому что путь не кодируется в callback_data.
+    """
+    tree = {
+        "lang": make_node(7),        # 7 вариантов языков, как в исходном боте
+        "delivery": make_node(2),
+        "goal": make_node(7),
+        "group": make_node(2),
+        "age": make_node(4),
+        "level": make_node(7),
+    }
+    check_callback_data_limits(tree, callback_prefix="wz")
+
+    max_len = 0
+    for node_id, node in tree.items():
+        candidate = f"wz:{node_id}:{len(node.options) - 1}"
+        max_len = max(max_len, len(candidate.encode("utf-8")))
+
+    assert max_len < TELEGRAM_CALLBACK_DATA_LIMIT_BYTES
+    print(f"Максимальная длина callback_data в этом дереве: {max_len} байт из {TELEGRAM_CALLBACK_DATA_LIMIT_BYTES}")

tg_tree_wizard-1.0.0/tests/test_core.py

@@ -0,0 +1,147 @@
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+import pytest
+from tg_tree_wizard.core import (
+    linear_wizard,
+    Node, Option, WizardState, TreeError, StaleChoiceError,
+    validate_tree, choose, go_back,
+)
+
+
+# Небольшое тестовое дерево: язык -> формат -> финал
+TREE = {
+    "lang": Node(
+        text="Выберите язык:",
+        options=(
+            Option("Английский", "en", "delivery"),
+            Option("Немецкий", "de", "delivery"),
+        ),
+    ),
+    "delivery": Node(
+        text="Выберите формат:",
+        options=(
+            Option("Очно", "offline", None),
+            Option("Онлайн", "online", None),
+        ),
+    ),
+}
+
+
+def test_valid_tree_passes_validation():
+    validate_tree(TREE, root="lang")  # не должно кинуть исключение
+
+
+def test_tree_with_missing_root_fails():
+    with pytest.raises(TreeError):
+        validate_tree(TREE, root="does_not_exist")
+
+
+def test_tree_with_broken_reference_fails():
+    broken = {
+        "lang": Node(text="x", options=(Option("a", "a", "nowhere"),)),
+    }
+    with pytest.raises(TreeError):
+        validate_tree(broken, root="lang")
+
+
+def test_happy_path_reaches_final_and_records_answers():
+    state = WizardState.start("lang")
+    assert state.current_node == "lang"
+
+    state, opt, is_final = choose(TREE, state, "lang", 0)  # выбрали "Английский"
+    assert opt.value == "en"
+    assert is_final is False
+    assert state.current_node == "delivery"
+
+    state, opt, is_final = choose(TREE, state, "delivery", 1)  # "Онлайн"
+    assert opt.value == "online"
+    assert is_final is True
+
+    assert [a.value for a in state.answers] == ["en", "online"]
+
+
+def test_back_restores_previous_node_and_drops_last_answer():
+    state = WizardState.start("lang")
+    state, _, _ = choose(TREE, state, "lang", 0)
+    assert state.current_node == "delivery"
+
+    state = go_back(state)
+    assert state.current_node == "lang"
+    assert state.answers == ()  # ответ про язык тоже откатился
+
+
+def test_back_at_root_is_noop():
+    state = WizardState.start("lang")
+    state2 = go_back(state)
+    assert state2 == state
+
+
+def test_stale_choice_from_old_message_is_rejected():
+    """
+    Пользователь дошёл до 'delivery', но нажал кнопку со старого
+    сообщения 'lang' (например, открыл старый чат). Это должно
+    падать с понятной ошибкой, а не молча ломать состояние.
+    """
+    state = WizardState.start("lang")
+    state, _, _ = choose(TREE, state, "lang", 0)  # теперь мы на delivery
+
+    with pytest.raises(StaleChoiceError):
+        choose(TREE, state, "lang", 1)  # а жмём на устаревшую кнопку lang
+
+
+def test_state_roundtrips_through_dict_like_fsmcontext_would_store_it():
+    """Ровно то, что будет происходить в FSMContext.data на реальном боте."""
+    state = WizardState.start("lang")
+    state, _, _ = choose(TREE, state, "lang", 0)
+
+    as_dict = state.to_dict()
+    restored = WizardState.from_dict(as_dict)
+
+    assert restored == state
+
+
+def test_linear_wizard_plain_strings_chain_to_next_step():
+    tree, root = linear_wizard([
+        ("a", "Шаг A", ["X", "Y"]),
+        ("b", "Шаг B", ["Z"]),
+    ])
+    assert root == "a"
+    validate_tree(tree, root)
+
+    state = WizardState.start(root)
+    state, opt, is_final = choose(tree, state, "a", 0)
+    assert opt.label == opt.value == "X"
+    assert is_final is False
+    assert state.current_node == "b"
+
+    state, opt, is_final = choose(tree, state, "b", 0)
+    assert is_final is True  # последний шаг - финальный по умолчанию
+
+
+def test_linear_wizard_explicit_next_node_enables_branching():
+    tree, root = linear_wizard([
+        ("topping", "Начинка", [
+            ("Пепперони", "pepperoni", "spicy"),
+            ("Маргарита", "margherita", "confirm"),
+        ]),
+        ("spicy", "Острота", ["Да", "Нет"]),
+        ("confirm", "Финал", ["OK"]),
+    ])
+    validate_tree(tree, root)
+
+    state = WizardState.start(root)
+    state, _, is_final = choose(tree, state, "topping", 0)
+    assert state.current_node == "spicy"
+    assert is_final is False
+
+    state2 = WizardState.start(root)
+    state2, _, is_final2 = choose(tree, state2, "topping", 1)
+    assert state2.current_node == "confirm"
+    assert is_final2 is False
+
+
+def test_linear_wizard_rejects_empty_steps():
+    with pytest.raises(TreeError):
+        linear_wizard([])