chore: Upload to GitHub

Author: lxmnk

.gitignore

@@ -0,0 +1,109 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+.idea/
+.vscode/
+
+static/

LICENSE.md

@@ -0,0 +1,55 @@
+Лицензия на программное обеспечение
+Дата 10 июня 2021г.
+
+Настоящая лицензия регламентирует использование следующего Программного
+обеспечения:
+* Библиотека Pybotx - сборник подпрограмм или объектов, используемых для
+  разработки ботов, обеспечивающий интеграцию с ПО «Система коммуникаций
+  Express».
+* Авторский программный модуль (АПМ) (Asyncbox) - программная платформа для
+  создания ботов для Системы коммуникаций Express.
+* Библиотека FSM – сборник подпрограмм или объектов, используемых для
+  разработки ботов, для представления и управления потоком выполнения команд
+  ботов.
+* Модуль Proxier – модуль ПО, позволяющий перенаправлять запросы на локально
+  развернутого бота.
+* ToDo Бот - индивидуальная разработка ООО «Анлимитед Продакшен» для
+  демонстрации процесса и результата разработки ботов на платформе.
+* Библиотека Pybotx Widgets – библиотека переиспользуемых компонентов для
+  взаимодействия с пользователями.
+
+Далее по тексту «Программное обеспечение» Правообладателем Программного
+обеспечения является ООО «Анлимитед Продакшен» (ИНН: 7707374451, ОГРН:
+5167746251240) Данная неисключительная лицензия разрешает лицам, получившим
+законным способом копию программного кода Программного обеспечения и
+сопутствующей документации, безвозмездно использовать Программное обеспечение
+без ограничений, включая неограниченное право на использование, копирование,
+доработку, адаптацию, публикацию, распространение, сублицензирование, при
+соблюдении следующих условий:
+
+Уведомление о правообладателе должны быть включены во все копии или значимые
+части Программных продуктов, в том числе созданных с использованием
+Программного обеспечения. Неисключительная лицензия ограничена «правом на
+использование», ни одно из положений настоящей лицензии не означает передачи
+кому бы то ни было исключительного права на Платформу, Библиотеки, Блоки и
+любые элементы Программного обеспечения. Запрещается вносить изменения в
+Программное обеспечение, переводить или создавать производные продукты,
+основанные на Программном обеспечении и его элементах с целью регистрации
+исключительных прав на программный код Программного обеспечения, а также
+интегрировать Программное обеспечение или его элементы в другие результаты
+интеллектуальной деятельности с последующей регистрацией исключительных прав на
+Программное обеспечение в составе результатов интеллектуальной деятельности.
+
+Неисключительная лицензия предоставляется на срок действия авторских прав на
+территории всего мира. ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК
+ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ
+ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И
+ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ
+ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО
+ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ
+СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ
+ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ. В ТОМ ЧИСЛЕ, НЕ ГАРАНТИРУЕТ (ВКЛЮЧАЯ, НО
+НЕ ОГРАНИЧИВАЯСЬ): ПРИГОДНОСТЬ ДЛЯ КОНКРЕТНЫХ ЦЕЛЕЙ, ТОЧНОСТЬ, ПОЛНОТУ,
+ПРОИЗВОДИТЕЛЬНОСТЬ, СИСТЕМНУЮ ИНТЕГРАЦИЮ, БЕСПЕРЕБОЙНОЕ ФУНКЦИОНИРОВАНИЕ,
+ОТСУТСТВИЕ ОШИБОК, ИСПРАВЛЕНИЕ НЕПОЛАДОК, ЗАКОННОСТЬ ИСПОЛЬЗОВАНИЯ НА ЛЮБЫХ
+ТЕРРИТОРИЯХ ЗА ПРЕДЕЛАМИ РОССИЙСКОЙ ФЕДЕРАЦИИ.

README.md

@@ -0,0 +1,124 @@
+# pybotx-fsm
+
+Конечный автомат (Finite state machine) для ботов на базе библиотеки
+[pybotx](https://github.com/ExpressApp/pybotx).
+
+
+## Возможности
+
+* Лёгкое создание графа состояний и их переключений.
+* Передача данных в следующее состояние при явном вызове перехода.
+
+
+## Подготовка к установке
+
+Для работы библиотеки необходим Redis, который уже встроен в последние версии
+[коробки](https://github.com/ExpressApp/async-box).
+
+
+## Установка
+
+Добавьте эту строку в зависимости проекта в `pyproject.toml`:
+
+```toml
+botx-fsm = { git = "https://github.com/ExpressApp/pybotx-fsm", rev = "0.1.4" }
+```
+
+## Работа с графом состояний
+
+1. Добавьте экземпляр автомата в мидлваре для того, чтобы бот мог использовать его:
+
+```python
+# bot.py
+
+bot.add_middleware(
+    FSMMiddleware,
+    storage=redis_storage,
+    fsm_instances=your_fsm_instance,
+)
+```
+
+2. Создайте `enum` для возможных состояний автомата:
+
+```python
+from enum import Enum, auto
+from botx_fsm import FSM
+
+
+class ProcessStates(Enum):
+    state1 = auto()
+    state2 = auto()
+
+fsm = FSM(ProcessStates)
+```
+
+3. Создайте обработчик конкретного состояния:
+
+```python
+from botx_fsm import FlowError
+
+
+@fsm.on(ProcessStates.state1, on_success=ProcessStates.state2)
+async def process_state(message: Message, bot: Bot) -> None:
+    if message.body == "to_state2":
+        await bot.answer_message("going to state2", message)
+        return  # No exceptions, going to `on_success` argument state
+
+    await bot.answer_message("wrong text, try again", message)
+    raise FlowError  # State haven't changed
+```
+
+4. Передайте управление обработчику состояний из любого обработчика сообщений:
+
+```python
+# bot.py
+@collector.handler(command="/start-process")
+async def start_process_fsm(message: Message, bot: Bot) -> None:
+    await bot.answer_message("started process", message)
+    await fsm.change_state(message, ProcessStates.state1)
+```
+
+**Примечание:** В `example/bot` находятся примеры нескольких процессов,
+созданных через pybotx-fsm.
+
+
+## Продвинутая работа с библиотекой
+
+1. В `FlowError` можно передать состояние из enum-а, тогда бот автоматически
+   перейдёт в него. Также можно выбросить `FlowError(clear=True)`, чтобы выйти
+   из машины состояний (управление будет передано обработчикам сообщений).
+
+2. Помимо аргумента `on_success` для `@fsm.on` можно использовать `on_failure`.
+   Тогда выбрасывание `FlowError` без аргументов будет переводить в это
+   состояние.
+
+   Также есть состояние `unset`, которое позволяет выйти из
+   выполнения конечного автомата:
+
+```python
+from botx_fsm import unset
+
+
+@fsm.on(ProcessStates.state2, on_success=unset, on_failure=ProcessStates.state1)
+async def process_state(message: Message, bot: Bot) -> None:
+    ...
+```
+
+3. Чтобы передать данные в следующее состояние, необходимо явно вызвать процесс
+   перехода и распаковать данные в следующем состоянии.
+
+```python
+from botx_fsm import StateExtractor
+
+
+@collector.hidden(command="/start-process", name="start-process")
+async def start_process(message: Message, bot: Bot) -> None:
+    await fsm.change_state(message, ProcessStates.state1, foo="bar")
+
+
+@fsm.on(ProcessStates.state2, on_success=unset)
+async def get_additional_data(
+    message: Message, bot: Bot, foo: str = Depends(StateExtractor.foo)
+) -> None:
+    ...
+```

botx_fsm/__init__.py

@@ -0,0 +1,10 @@
+from botx_fsm.di_extractors import StateExtractor
+from botx_fsm.exceptions import FlowError
+from botx_fsm.fsm import FSM
+from botx_fsm.markers import unset
+from botx_fsm.middleware import FSMMiddleware
+from botx_fsm.models import Key
+
+__all__ = (  # noqa: WPS410
+    "FlowError", "FSM", "unset", "FSMMiddleware", "Key", 'StateExtractor'
+)

botx_fsm/di_extractors.py

@@ -0,0 +1,21 @@
+from typing import Callable
+
+from botx import Message, Bot
+
+
+def _extractor(key: str) -> Callable[[Message], Bot]:
+    def decorator(message: Message):
+        try:
+            return getattr(message.state, key)
+        except AttributeError:
+            return getattr(message.bot.state, key)
+
+    return decorator
+
+
+class _StateExtractor:
+    def __getattribute__(self, item: str) -> Callable[[Message], Bot]:
+        return _extractor(item)
+
+
+StateExtractor = _StateExtractor()

botx_fsm/exceptions.py

@@ -0,0 +1,31 @@
+from enum import Enum
+from typing import Union
+
+from botx_fsm.markers import FSMStateMarker, undefined
+from botx_fsm.typing import EnumT
+
+
+class FlowError(Exception):
+    def __init__(
+        self,
+        new_state: Union[EnumT, FSMStateMarker] = undefined,
+        *,
+        clear: bool = False,
+    ) -> None:
+        if not isinstance(new_state, Enum) and new_state is not undefined:
+            raise RuntimeError("new state should be enum member")
+
+        self.new_state = new_state
+        self.clear = clear
+
+    def new_state_defined(self) -> bool:
+        return self.new_state is not undefined and not self.clear
+
+    def __repr__(self) -> str:
+        new_state_str = str(self.new_state)
+        if self.new_state is undefined:
+            new_state_str = "<will not change>"
+        if self.clear:
+            new_state_str = "<will be cleared>"
+
+        return f"FlowError(new_state: {new_state_str})"