dialog-engine 0.1.0__tar.gz

dialog_engine-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+.venv/
+*.whl

dialog_engine-0.1.0/LICENSE

@@ -0,0 +1,62 @@
+Dialog Engine — Source-Available License (v1)
+
+Copyright (c) 2026 Danila Shubin, Saveliy Khvostov. All rights reserved.
+
+TERMS AND CONDITIONS
+
+1. Definitions. "Software" means the dialog-engine package, its source code,
+   object code (if any), and documentation distributed with it.
+
+2. Grant of use. Subject to this License, you are granted a worldwide,
+   royalty-free, non-exclusive license to:
+   (a) install and run the Software;
+   (b) import, call, and link to the Software as a library in your own
+       programs;
+   (c) copy and redistribute unmodified copies of the Software (including
+       through package indexes such as PyPI), provided that you retain this
+       License and copyright notices.
+
+3. Modification and derivatives PROHIBITED. You may not modify, adapt,
+   translate, merge, or otherwise create derivative works of the Software.
+   You may not distribute the Software, or any part of it, if you have changed
+   its source files. You may not publicly fork or publish a variant of this
+   project that includes altered library source code.
+
+   Bug reports and feature suggestions are welcome through the channels
+   indicated in the project repository; they do not constitute permission to
+   modify and redistribute.
+
+4. No reverse engineering for circumvention. You may not circumvent the
+   restrictions in section 3 by decompiling or disassembling the Software except
+   to the extent that applicable law expressly permits and cannot be waived.
+
+5. Attribution. Redistributions of the Software must reproduce this License
+   and the copyright notice above.
+
+6. No trademark. This License does not grant permission to use trade names,
+   trademarks, or service marks of the copyright holders, except as required
+   for reasonable and customary use in describing the origin of the Software.
+
+7. Disclaimer of warranty. 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.
+
+8. Termination. If you violate this License, your rights under it terminate
+   automatically.
+
+---
+
+Note on "open source": This license is NOT an Open Source Initiative (OSI)
+approved license, because it does not grant the freedom to modify and share
+modified versions — a requirement of the Open Source Definition. It is a
+source-available license: the source is visible for transparency and
+auditing, but changing and redistributing changed source is not permitted.
+
+For comparison, Creative Commons offers "NoDerivatives" variants (e.g. CC BY-ND),
+but Creative Commons discourages using CC licenses for software; a dedicated
+software license (such as this text) is a common approach when you want
+use-without-modification terms.

dialog_engine-0.1.0/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: dialog-engine
+Version: 0.1.0
+Summary: JSON-driven step dialog engine with conditional steps and optional aiogram helpers
+Project-URL: Homepage, https://github.com/ShyDamn/dialog-engine
+Project-URL: Documentation, https://github.com/ShyDamn/dialog-engine#readme
+Project-URL: Repository, https://github.com/ShyDamn/dialog-engine
+Project-URL: Issues, https://github.com/ShyDamn/dialog-engine/issues
+Author-email: Danila Shubin <den03062003@gmail.com>, Saveliy Khvostov <khvostov40@gmail.com>
+License: Dialog Engine — Source-Available License (v1)
+        
+        Copyright (c) 2026 Danila Shubin, Saveliy Khvostov. All rights reserved.
+        
+        TERMS AND CONDITIONS
+        
+        1. Definitions. "Software" means the dialog-engine package, its source code,
+           object code (if any), and documentation distributed with it.
+        
+        2. Grant of use. Subject to this License, you are granted a worldwide,
+           royalty-free, non-exclusive license to:
+           (a) install and run the Software;
+           (b) import, call, and link to the Software as a library in your own
+               programs;
+           (c) copy and redistribute unmodified copies of the Software (including
+               through package indexes such as PyPI), provided that you retain this
+               License and copyright notices.
+        
+        3. Modification and derivatives PROHIBITED. You may not modify, adapt,
+           translate, merge, or otherwise create derivative works of the Software.
+           You may not distribute the Software, or any part of it, if you have changed
+           its source files. You may not publicly fork or publish a variant of this
+           project that includes altered library source code.
+        
+           Bug reports and feature suggestions are welcome through the channels
+           indicated in the project repository; they do not constitute permission to
+           modify and redistribute.
+        
+        4. No reverse engineering for circumvention. You may not circumvent the
+           restrictions in section 3 by decompiling or disassembling the Software except
+           to the extent that applicable law expressly permits and cannot be waived.
+        
+        5. Attribution. Redistributions of the Software must reproduce this License
+           and the copyright notice above.
+        
+        6. No trademark. This License does not grant permission to use trade names,
+           trademarks, or service marks of the copyright holders, except as required
+           for reasonable and customary use in describing the origin of the Software.
+        
+        7. Disclaimer of warranty. 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.
+        
+        8. Termination. If you violate this License, your rights under it terminate
+           automatically.
+        
+        ---
+        
+        Note on "open source": This license is NOT an Open Source Initiative (OSI)
+        approved license, because it does not grant the freedom to modify and share
+        modified versions — a requirement of the Open Source Definition. It is a
+        source-available license: the source is visible for transparency and
+        auditing, but changing and redistributing changed source is not permitted.
+        
+        For comparison, Creative Commons offers "NoDerivatives" variants (e.g. CC BY-ND),
+        but Creative Commons discourages using CC licenses for software; a dedicated
+        software license (such as this text) is a common approach when you want
+        use-without-modification terms.
+License-File: LICENSE
+Keywords: aiogram,dialog,json,steps,telegram,wizard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: aiogram
+Requires-Dist: aiogram<4,>=3.0; extra == 'aiogram'
+Provides-Extra: dev
+Requires-Dist: aiogram<4,>=3.0; extra == 'dev'
+Requires-Dist: pydantic<3,>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: validation
+Requires-Dist: pydantic<3,>=2.0; extra == 'validation'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# dialog-engine
+
+Библиотека для описания **пошаговых диалогов** (мастеров, анкет, визардов) в JSON или YAML. Вы задаёте список шагов и тип каждого шага; при необходимости шаги можно **показывать или пропускать** в зависимости от уже собранных данных (**контекста**). Ядро не привязано к Telegram — его можно использовать в веб-приложениях, CLI и т.д. Дополнительно есть интеграция с **aiogram 3** (готовые inline-клавиатуры под типичные сценарии).
+
+**Лицензия:** исходный код открыт для просмотра (**source-available**), но **изменение и распространение изменённой версии запрещены**; в своих проектах вы можете **устанавливать пакет и использовать его как библиотеку** без переписывания кода библиотеки. Это **не** «open source» в смысле [Open Source Initiative](https://opensource.org/osd): по определению OSD право на модификацию и производные работы обязательно. Подробности — в [LICENSE](LICENSE).
+
+**Требования:** Python 3.10+.
+
+---
+
+## Установка
+
+Минимальная установка (только ядро, без зависимостей):
+
+```bash
+pip install dialog-engine
+```
+
+Дополнительные возможности подключаются **extras** (установите только то, что нужно):
+
+| Extra | Назначение |
+|-------|------------|
+| `validation` | Строгая проверка структуры JSON через Pydantic |
+| `yaml` | Загрузка диалогов из YAML-файлов (PyYAML) |
+| `aiogram` | Хелперы для inline-клавиатур под aiogram 3 |
+
+Примеры:
+
+```bash
+pip install dialog-engine[validation]
+pip install dialog-engine[yaml,aiogram]
+pip install dialog-engine[validation,yaml,aiogram]
+```
+
+Разработка пакета из клонированного репозитория:
+
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Идея в двух словах
+
+1. В файле описывается массив **шагов** (`steps`). У каждого шага есть `id`, `type` и поле `text` (часто это ключ для i18n или просто текст вопроса).
+2. Во время работы приложение хранит **контекст** — обычный словарь (например ответы пользователя: `{"email": "...", "plan": "pro"}`). Ключи в условиях совпадают с ключами контекста.
+3. Движок **`DialogEngine`** умеет по контексту определить, какие шаги **видимы**, и вычислить **следующий/предыдущий** видимый шаг — без ручных `if` в коде для каждого сценария.
+
+---
+
+## Формат JSON
+
+Корень файла — либо объект с полем `steps`, либо сразу массив шагов:
+
+```json
+{
+  "steps": [
+    { "id": "name", "type": "text", "text": "question-name", "required": true },
+    { "id": "plan", "type": "choice", "text": "question-plan", "required": true,
+      "choices": { "free": "plan-free", "pro": "plan-pro" } }
+  ]
+}
+```
+
+### Поля шага
+
+| Поле | Обязательно | Описание |
+|------|-------------|----------|
+| `id` | да | Уникальный идентификатор шага; по нему удобно сохранять ответ в контексте (`context[id] = ...`). |
+| `type` | да | Логический тип шага. В ядре допустимы произвольные строки; типичные: `text`, `choice`, `photo` — интерпретация на стороне вашего UI. |
+| `text` | да | Текст вопроса или ключ локализации (библиотека его не переводит). |
+| `required` | нет, по умолчанию `true` | Обязательность шага (для вашей логики и extras aiogram — кнопка «Пропустить»). |
+| `choices` | для `choice` | Объект `"значение_ответа": "ключ_подписи"` — подписи снова передаются в `translate()` в aiogram-extra. |
+| `min`, `max` | для шагов с вложениями | Для типа `photo` в примерах это минимальное и максимальное число файлов; в объекте `DialogStep` они хранятся как `min_photos` / `max_photos`. |
+| `skip_when` | нет | Условие: если выполняется — шаг **не показывается** (пропускается при навигации). |
+| `show_when` | нет | Если задано — шаг показывается **только** когда условие выполняется. Если не задано и `skip_when` не срабатывает — шаг виден. |
+
+### Условия `skip_when` и `show_when`
+
+Задаются одним объектом или списком объектов (логика **И** — все перечисленные условия должны выполняться).
+
+Каждое условие:
+
+- `field` — имя поля в контексте (строка).
+- Ровно одно из:
+  - `equals` — значение в контексте должно быть равно этому значению;
+  - `in` — значение должно входить в список;
+  - `not_in` — значение **не** должно входить в список.
+
+Пример: не показывать шаг загрузки фото карты, если владелец карты — третье лицо (значение в контексте заранее записано, например после шага `choice`):
+
+```json
+{
+  "id": "bank_card_photo",
+  "type": "photo",
+  "text": "upload-card",
+  "required": false,
+  "min": 1,
+  "max": 1,
+  "skip_when": { "field": "card_owner", "equals": "third" }
+}
+```
+
+Если поля `field` в контексте нет, сравнение идёт с `None` (например `equals` с конкретной строкой не сработает).
+
+---
+
+## Python API: ядро
+
+### Загрузка
+
+```python
+from pathlib import Path
+from dialog_engine import DialogEngine
+
+engine = DialogEngine.from_file(Path("wizard.json"))
+# или из строки JSON:
+engine = DialogEngine.from_json_string('{"steps": [...]}')
+# или из списка dict (например после своего парсера):
+engine = DialogEngine.from_list([{...}, {...}])
+```
+
+### Объект шага `DialogStep`
+
+Поля соответствуют JSON; у фото-диапазона в коде имена `min_photos` / `max_photos`.
+
+### Навигация и прогресс
+
+Контекст — любой `Mapping` (часто обычный `dict` с ответами пользователя).
+
+```python
+ctx = {"card_owner": "self"}
+
+# Индексы шагов в конфиге — «сырые» (0 .. len-1). Видимость зависит от ctx.
+engine.get_step(0)                    # шаг по индексу или None
+engine.get_step_by_id("email")        # (index, DialogStep) или None
+
+engine.total()                        # число шагов в файле (все подряд)
+engine.effective_total(ctx)           # сколько шагов видно при данном контексте
+engine.effective_position(3, ctx)   # номер среди видимых (1-based) или None, если индекс скрыт
+
+engine.next_index(2, ctx)           # следующий видимый индекс после 2, или None — конец
+engine.previous_index(5, ctx)       # предыдущий видимый, или None
+engine.visible_indices(ctx)         # список сырых индексов видимых шагов по порядку
+engine.first_visible_index(ctx)
+engine.iter_visible_steps(ctx)      # итератор (index, DialogStep) только по видимым
+
+engine.is_last(4)                   # последний ли индекс в конфиге (без учёта скрытых)
+engine.is_last_visible(4, ctx)      # последний ли среди видимых
+```
+
+### Проверка видимости одного шага
+
+```python
+from dialog_engine import step_is_visible
+
+if step_is_visible(step, ctx):
+    ...
+```
+
+Полезно при фильтрации обязательных полей или при построении сводки только по актуальным шагам.
+
+---
+
+## Дополнения (extras)
+
+### Pydantic (`validation`)
+
+После `pip install dialog-engine[validation]` можно проверять структуру данных до загрузки в движок:
+
+```python
+from dialog_engine.pydantic_schema import validate_dialog_data
+import json
+
+with open("wizard.json", encoding="utf-8") as f:
+    data = json.load(f)
+validate_dialog_data(data)   # при ошибке — ValidationError
+```
+
+Имеет смысл в CI и в редакторах конфигов.
+
+### YAML (`yaml`)
+
+```python
+from dialog_engine.loaders import from_yaml_file
+
+engine = from_yaml_file("wizard.yaml")
+```
+
+Корень YAML — как в JSON: `steps: [...]` или список шагов.
+
+### aiogram 3 (`aiogram`)
+
+```python
+from dialog_engine.integrations.aiogram import (
+    KeyboardCallbacks,
+    build_step_keyboard,
+    build_photo_keyboard,
+)
+
+# translate — функция вида lambda key: str, возвращающая подпись кнопки/строки
+kb = build_step_keyboard(
+    step,
+    translate,
+    show_back=True,
+    current_value=context.get(step.id),
+    keep_button_text=...,  # опционально, готовая строка для «оставить»
+)
+
+kb = build_photo_keyboard(
+    translate,
+    show_done=True,
+    show_keep=False,
+    keep_button_text=None,
+    show_clear=True,
+    show_skip=True,
+)
+```
+
+По умолчанию `callback_data` совместимы с префиксами вроде `dialog_choice:field_id:key`, `dialog_skip`, `dialog_back` и т.д. Свои значения можно задать через **`KeyboardCallbacks`** (поля `skip`, `back`, `keep`, `photo_done`, `photo_clear`, `choice_prefix` и метод `choice_data(step_id, key)`).
+
+---
+
+## Командная строка
+
+После установки пакета:
+
+```bash
+dialog-engine-validate путь/к/диалог.json
+```
+
+Проверяется синтаксис JSON и возможность собрать `DialogEngine`.
+
+Строгая проверка схемы (нужен extra `validation`):
+
+```bash
+dialog-engine-validate --strict путь/к/диалог.json
+```
+
+То же через модуль:
+
+```bash
+python -m dialog_engine путь/к/диалог.json
+```
+
+Коды выхода: `0` — успех, иначе ошибка (в т.ч. отсутствие файла или `--strict` без Pydantic).
+
+---
+
+## Как встроить в приложение
+
+1. Загрузите диалог один раз (или при смене файла) через `DialogEngine.from_file`.
+2. В состоянии сессии храните **текущий индекс** шага (сырой индекс в массиве `steps`) и **контекст** (ответы).
+3. После каждого ответа обновляйте контекст, например `context[step.id] = value`.
+4. Для перехода вперёд используйте `next_index(current_index, context)`; если вернулось `None` — диалог закончен (или нужно перейти на экран подтверждения).
+5. Для «Назад» — `previous_index(current_index, context)`.
+6. Для индикатора «Шаг 2 из 5» используйте `effective_position` и `effective_total`, чтобы число шагов учитывало скрытые по `skip_when` / `show_when`.
+
+Типы `text` / `choice` / `photo` в JSON — соглашение; библиотека не отправляет сообщения и не качает файлы. Реализацию ввода-вывода делаете вы (Telegram, HTTP, TUI и т.д.).
+
+---
+
+## Авторы
+
+| | GitHub | Email |
+|---|--------|-------|
+| **Данила Шубин** | [@ShyDamn](https://github.com/ShyDamn) | [den03062003@gmail.com](mailto:den03062003@gmail.com) |
+| **Савелий Хвостов** | [@k0te1ch](https://github.com/k0te1ch) | [khvostov40@gmail.com](mailto:khvostov40@gmail.com) |
+
+Репозиторий: [github.com/ShyDamn/dialog-engine](https://github.com/ShyDamn/dialog-engine).
+
+---
+
+## Лицензия
+
+Текст лицензии — в файле [LICENSE](LICENSE) (англ.). Кратко:
+
+- можно **устанавливать**, **запускать** и **подключать** пакет в своих приложениях;
+- можно **распространять неизменённые** копии (в т.ч. через PyPI), с сохранением уведомления об авторских правах и текста лицензии;
+- **нельзя** изменять исходники библиотеки, создавать производные работы на их основе и распространять изменённые версии;
+- отчёты об ошибках и предложения по улучшению приветствуются через репозиторий, но это **не** разрешение на форк с правками.
+
+Для сравнения: лицензии Creative Commons с условием **NoDerivatives** (например [CC BY-ND](https://creativecommons.org/licenses/by-nd/4.0/)) близки по духу («не переделывать и не распространять переделки»), но CC **не рекомендует** применять свои лицензии к ПО; поэтому здесь используется отдельный текст, заточенный под программное обеспечение.

dialog_engine-0.1.0/PUBLISHING.md

@@ -0,0 +1,65 @@
+# Публикация и сопровождение (для автора репозитория)
+
+Этот файл не для пользователей библиотеки. Здесь — чеклист релиза на PyPI и сопутствующие задачи.
+
+## Перед первым релизом
+
+1. **Имя на PyPI** — убедиться, что имя дистрибутива (`dialog-engine` в `pyproject.toml`) свободно или зарезервировано: https://pypi.org/project/dialog-engine/
+2. **Метаданные** в `[project]` файла `pyproject.toml`:
+   - `authors` (Danila Shubin, Saveliy Khvostov), `license = { file = "LICENSE" }`, `readme`
+   - `project.urls` — репозиторий [github.com/ShyDamn/dialog-engine](https://github.com/ShyDamn/dialog-engine) (владелец: ShyDamn)
+3. **Версия** — синхронизировать `version` в `pyproject.toml` и при необходимости `__version__` в `src/dialog_engine/__init__.py`.
+
+## Сборка артефактов
+
+Из каталога `DialogEngine` (где лежит `pyproject.toml`):
+
+```bash
+pip install build
+python -m build --outdir dist .
+```
+
+В `dist/` появятся `.tar.gz` (sdist) и `.whl` (wheel).
+
+Проверка установки колёса в чистом окружении:
+
+```bash
+pip install dist/dialog_engine-*.whl
+python -c "import dialog_engine; print(dialog_engine.__version__)"
+```
+
+## TestPyPI (рекомендуется перед боем)
+
+```bash
+pip install twine
+twine upload --repository testpypi dist/*
+```
+
+Установка с тестового индекса:
+
+```bash
+pip install -i https://test.pypi.org/simple/ dialog-engine==<версия>
+```
+
+## PyPI (production)
+
+```bash
+twine upload dist/*
+```
+
+Потребуются учётные данные PyPI (API token или логин/пароль). Не коммитьте токены в репозиторий — используйте `~/.pypirc` или переменные окружения / секреты CI.
+
+## Релиз на GitHub
+
+1. Обновить версию и changelog (если ведёте).
+2. Создать тег `v0.x.y` и запушить.
+3. Прикрепить к релизу файлы из `dist/` или полагаться на автосборку workflow (если настроена).
+
+## CI
+
+В монорепозитории ArrowMediaBot workflow: `.github/workflows/dialog-engine-ci.yml` (пути `DialogEngine/**`). После выноса библиотеки в отдельный репозиторий перенесите workflow в корень и уберите `working-directory: DialogEngine`, либо оставьте структуру с подпапкой — по ситуации.
+
+## После релиза
+
+- Проверить страницу проекта на PyPI (описание, ссылки).
+- При необходимости обновить зависимость в приложениях: `dialog-engine = "^0.x.y"` вместо `path = ...`.