diff --git a/docs/Makefile b/docs/Makefile index 4a3a5ee..0c65a7c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,7 +13,7 @@ help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) live-ru: - sphinx-autobuild -b html . _build/html/ -D language=ru + sphinx-autobuild -b html . _build/html/ru -D language=ru serve-all: sphinx-build -b html . _build/html/ -D language=en diff --git a/docs/code_snippets/quickstart_example_main.py b/docs/code_snippets/quickstart_example_main.py new file mode 100644 index 0000000..4f27c1c --- /dev/null +++ b/docs/code_snippets/quickstart_example_main.py @@ -0,0 +1,14 @@ +# main.py +from argenta import App, Orchestrator +from routers import router + +app: App = App() +orchestrator: Orchestrator = Orchestrator() + +def main() -> None: + app.include_router(router) + orchestrator.start_polling(app) + +if __name__ == '__main__': + main() + \ No newline at end of file diff --git a/docs/code_snippets/quickstart_example_routers.py b/docs/code_snippets/quickstart_example_routers.py new file mode 100644 index 0000000..7e500eb --- /dev/null +++ b/docs/code_snippets/quickstart_example_routers.py @@ -0,0 +1,9 @@ +# routers.py +from argenta import Router, Response + +router = Router() + +@router.command("hello") +def handler(response: Response): + print("Hello, world!") + \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst index 2bfe226..08af6ad 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,3 +1,5 @@ +.. _contributing: + Вклад в проект *************************** diff --git a/docs/index.rst b/docs/index.rst index c4328d7..91adb29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Argenta Основная цель библиотеки дать возможность разработчикам сфокусироваться на реализации своих идей, предоставляя для этого удобные абстракциию. .. image:: https://github.com/koloideal/Argenta/blob/main/imgs/mock_app_preview4.png?raw=True + :alt: Пример приложения Argenta нужна для создания приложений, которым необходим свой скоуп, то есть: при запуске приложения юзер входит в абстрагированный скоуп, в котором у него есть доступ к созданной функциональности @@ -25,7 +26,9 @@ Argenta нужна для создания приложений, которым * **Приложение**. Объект управления жизненным циклом приложения, подключения созданных маршрутизаторов, конфигурирования различных вторичных утилит, таких как автокомплит, логирование и т.д. * **Оркестратор**. Объект *оркестрации*, который конфигурирует, запускает и управляет всеми остальными компонентами программы. * **Внедрение зависимостей**. ``Argenta`` нативно поддерживает ``dishka`` и предоставляет возможность инжектирования зависимостей в хэндлерах, резолвя тайпхинты, подробнее_. + .. _подробнее: https://dishka.readthedocs.io/en/stable/di_intro.html + * **Поддержка флагов**. Библиотека поддерживает определение флагов, введённых вместе с командой, ``Argenta`` сама парсит и валидирует их, отдавая понятные сущности. * **Поддержка аргументов**. Осуществленна поддержка аргументов командной строки, позволяя пользователю передавать различные параметры при запуске приложения. diff --git a/docs/locales/en/LC_MESSAGES/api/index.po b/docs/locales/en/LC_MESSAGES/api/index.po index 62eb706..4529f62 100644 --- a/docs/locales/en/LC_MESSAGES/api/index.po +++ b/docs/locales/en/LC_MESSAGES/api/index.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 11:06+0300\n" +"POT-Creation-Date: 2025-10-15 13:40+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,6 +20,9 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../api/index.rst:2 -msgid "Public API" +msgid "Публичный API" msgstr "" +#~ msgid "Public API" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/contributing.po b/docs/locales/en/LC_MESSAGES/contributing.po index 8ab1471..63b15f8 100644 --- a/docs/locales/en/LC_MESSAGES/contributing.po +++ b/docs/locales/en/LC_MESSAGES/contributing.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 11:06+0300\n" +"POT-Creation-Date: 2025-10-15 13:40+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,7 +20,7 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../contributing.rst:2 -msgid "Contributing" +msgid "Вклад в проект" msgstr "" #: ../../contributing.rst:4 @@ -33,3 +33,6 @@ msgstr "" msgid "Getting started" msgstr "" +#~ msgid "Contributing" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/index.po b/docs/locales/en/LC_MESSAGES/index.po index e042026..aec3378 100644 --- a/docs/locales/en/LC_MESSAGES/index.po +++ b/docs/locales/en/LC_MESSAGES/index.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 11:06+0300\n" +"POT-Creation-Date: 2025-10-15 14:19+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,23 +19,23 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../index.rst:11 +#: ../../index.rst:35 msgid "Контент:" msgstr "Content:" -#: ../../index.rst:20 +#: ../../index.rst:45 msgid "Для разработчиков:" msgstr "For developers:" -#: ../../index.rst:26 +#: ../../index.rst:51 msgid "GitHub" msgstr "" -#: ../../index.rst:26 +#: ../../index.rst:51 msgid "PyPI" msgstr "" -#: ../../index.rst:26 +#: ../../index.rst:51 msgid "Ссылки проекта:" msgstr "Project Links" @@ -44,8 +44,86 @@ msgid "Argenta" msgstr "" #: ../../index.rst:9 +#, fuzzy msgid "" -"Python библиотека для построения модульных CLI-приложений с простым и " -"приятным API." -msgstr "Python library for building modular CLI applications with simple and agreeable API." +"**Библиотека для построения модульных CLI-приложений с простым и приятным" +" API.**" +msgstr "" +"Python library for building modular CLI applications with simple and " +"agreeable API." + +#: ../../index.rst:11 +msgid "" +"У вас есть некая функциональность и вы хотите распространять её в виде " +"cli? Argenta поможет вам. Основная цель библиотеки дать возможность " +"разработчикам сфокусироваться на реализации своих идей, предоставляя для " +"этого удобные абстракциию." +msgstr "" + +#: ../../index.rst:14 +msgid "Пример приложения" +msgstr "" + +#: ../../index.rst:17 +msgid "" +"Argenta нужна для создания приложений, которым необходим свой скоуп, то " +"есть: при запуске приложения юзер входит в абстрагированный скоуп, в " +"котором у него есть доступ к созданной функциональности Один из основных " +"принципов библиотеки это цикличность, это значит, что после ввода юзером " +"команды он не выходит из скоупа, в этом основное отличие от таких " +"библиотек, как ``argparse``, ``click`` и ``typer``. Выход из скоупа " +"контролируется самим юзером." +msgstr "" + +#: ../../index.rst:22 +msgid "**Ключевые особенности:**" +msgstr "" + +#: ../../index.rst:24 +msgid "" +"**Обработчики**. Объекты представления приложения, непосредственные " +"обработчики введённых команд. Создание обработчиков максимально " +"декларативно" +msgstr "" + +#: ../../index.rst:25 +msgid "" +"**Маршрутизаторы**. Объекты маршрутизации, которые регистрируют " +"обработчиков, позволяя создавать кастомные настройки для групп " +"обработчиков, а также семантически их разделять." +msgstr "" + +#: ../../index.rst:26 +msgid "" +"**Приложение**. Объект управления жизненным циклом приложения, " +"подключения созданных маршрутизаторов, конфигурирования различных " +"вторичных утилит, таких как автокомплит, логирование и т.д." +msgstr "" + +#: ../../index.rst:27 +msgid "" +"**Оркестратор**. Объект *оркестрации*, который конфигурирует, запускает и" +" управляет всеми остальными компонентами программы." +msgstr "" + +#: ../../index.rst:28 +msgid "" +"**Внедрение зависимостей**. ``Argenta`` нативно поддерживает ``dishka`` и" +" предоставляет возможность инжектирования зависимостей в хэндлерах, " +"резолвя тайпхинты, подробнее_." +msgstr "" + +#: ../../index.rst:32 +msgid "" +"**Поддержка флагов**. Библиотека поддерживает определение флагов, " +"введённых вместе с командой, ``Argenta`` сама парсит и валидирует их, " +"отдавая понятные сущности." +msgstr "" + +#: ../../index.rst:33 +msgid "" +"**Поддержка аргументов**. Осуществленна поддержка аргументов командной " +"строки, позволяя пользователю передавать различные параметры при запуске " +"приложения." +msgstr "" diff --git a/docs/locales/en/LC_MESSAGES/quickstart.po b/docs/locales/en/LC_MESSAGES/quickstart.po index e1ebe38..1da81db 100644 --- a/docs/locales/en/LC_MESSAGES/quickstart.po +++ b/docs/locales/en/LC_MESSAGES/quickstart.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 11:06+0300\n" +"POT-Creation-Date: 2025-10-15 14:19+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,11 +19,37 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../quickstart.rst:2 -msgid "Quickstart" -msgstr "" - #: ../../quickstart.rst:4 -msgid "**Install Argenta**" +msgid "Быстрый старт" msgstr "" +#: ../../quickstart.rst:6 +msgid "**Установка** ``Argenta``" +msgstr "" + +#: ../../quickstart.rst:12 +msgid "" +"**Определение роутера и хэндлеров**, за регистрацию функции как " +"обработчика отвечает декоратор ``@router.command``, хэндлер всегда должен" +" принимать аргумент с типом ``Response``, подробнее в :ref:`разделе " +"`." +msgstr "" + +#: ../../quickstart.rst:17 +msgid "" +"**Определение приложения и оркестратора**, для запуска приложения " +"необходимо вызвать ``.include_router()`` у созданного приложения и " +"передать ему раннее созданный роутер, после этого необходимо вызвать " +"``.start_polling()`` у созданного оркестратора и передать ему созданное " +"приложение." +msgstr "" + +#~ msgid "Quickstart" +#~ msgstr "" + +#~ msgid "**Install Argenta**" +#~ msgstr "" + +#~ msgid "**Установка**" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/redirect_stdout.po b/docs/locales/en/LC_MESSAGES/redirect_stdout.po new file mode 100644 index 0000000..11a53b5 --- /dev/null +++ b/docs/locales/en/LC_MESSAGES/redirect_stdout.po @@ -0,0 +1,25 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, kolo +# This file is distributed under the same license as the Argenta package. +# FIRST AUTHOR , 2025. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Argenta \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-10-15 13:40+0300\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: en\n" +"Language-Team: en \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.17.0\n" + +#: ../../redirect_stdout.rst:2 +msgid "Перенаправление стандартного вывода" +msgstr "" + diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 4f5aa0d..aeabe96 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,8 +1,27 @@ +.. _quickstart: + Быстрый старт ******************** -1. **Установка** +1. **Установка** ``Argenta`` .. code-block:: shell pip install argenta + +2. **Определение роутера и хэндлеров**, за регистрацию функции как обработчика отвечает декоратор ``@router.command``, хэндлер всегда должен принимать аргумент с типом ``Response``, подробнее в :ref:`разделе `. + +.. literalinclude:: ./code_snippets/quickstart_example_routers.py + :language: python + +3. **Определение приложения и оркестратора**, для запуска приложения необходимо вызвать ``.include_router()`` у созданного приложения и передать ему раннее созданный роутер, после этого необходимо вызвать ``.start_polling()`` у созданного оркестратора и передать ему созданное приложение. + +.. literalinclude:: ./code_snippets/quickstart_example_main.py + :language: python + +4. **Запуск приложения**, запускаем приложение как обычный процесс. + + +.. image:: https://github.com/koloideal/Argenta/blob/docs/create_docs/imgs/mock_app_preview5.png?raw=true + :alt: Quickstart Example + \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index facd0b7..938e411 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx shibuya sphinx-intl +sphinx-autobuild diff --git a/imgs/mock_app_preview5.png b/imgs/mock_app_preview5.png new file mode 100644 index 0000000..768a085 Binary files /dev/null and b/imgs/mock_app_preview5.png differ diff --git a/mock/min_app/main.py b/mock/min_app/main.py new file mode 100644 index 0000000..a10ad26 --- /dev/null +++ b/mock/min_app/main.py @@ -0,0 +1,14 @@ +# main.py +from argenta import App, Orchestrator +from .routers import router + +app: App = App() +orchestrator: Orchestrator = Orchestrator() + +def main() -> None: + app.include_router(router) + orchestrator.start_polling(app) + +if __name__ == '__main__': + main() + \ No newline at end of file diff --git a/mock/min_app/routers.py b/mock/min_app/routers.py new file mode 100644 index 0000000..7e500eb --- /dev/null +++ b/mock/min_app/routers.py @@ -0,0 +1,9 @@ +# routers.py +from argenta import Router, Response + +router = Router() + +@router.command("hello") +def handler(response: Response): + print("Hello, world!") + \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 26f7563..d0f2615 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,5 +39,9 @@ dev = [ "mypy>=1.14.1", "pytest>=8.3.2", "ruff>=0.12.12", + "shibuya>=2025.9.25", + "sphinx>=8.2.3", + "sphinx-autobuild>=2025.8.25", + "sphinx-intl>=2.3.2", "wemake-python-styleguide>=0.17.0", ] diff --git a/src/argenta/__init__.py b/src/argenta/__init__.py index 94239fd..4535f4c 100644 --- a/src/argenta/__init__.py +++ b/src/argenta/__init__.py @@ -1,3 +1,5 @@ from argenta.app.models import App as App from argenta.orchestrator.entity import Orchestrator as Orchestrator from argenta.router.entity import Router as Router +from argenta.response.entity import Response as Response +from argenta.command.models import Command as Command diff --git a/src/argenta/command/__init__.py b/src/argenta/command/__init__.py index 67ecd1b..8ecc09f 100644 --- a/src/argenta/command/__init__.py +++ b/src/argenta/command/__init__.py @@ -1,6 +1,6 @@ -from argenta.command.flag import Flag as Flag -from argenta.command.flag import Flags as Flags -from argenta.command.flag import PossibleValues as PossibleValues +from argenta.command.flag import (Flag as Flag, + Flags as Flags, + PossibleValues as PossibleValues) from argenta.command.flag.defaults import PredefinedFlags as PredefinedFlags -from argenta.command.models import Command as Command -from argenta.command.models import InputCommand as InputCommand +from argenta.command.models import (Command as Command, + InputCommand as InputCommand)