diff --git a/docs/code_snippets/argspace_snippet.py b/docs/code_snippets/argspace_snippet.py new file mode 100644 index 0000000..8d40f73 --- /dev/null +++ b/docs/code_snippets/argspace_snippet.py @@ -0,0 +1,46 @@ +from argenta import Orchestrator, App +from argenta.orchestrator.argparser import ArgParser, ValueArgument + + +# Определение аргументов приложения +arguments = [ + ValueArgument( + "host", + help="Server host", + default="localhost" + ), + ValueArgument( + "port", + help="Server port", + default="8080" + ), +] + +# Создание и запуск парсера +argparser = ArgParser( + processed_args=arguments, + name="WebServer", + description="Simple web server" +) + +app = App() +orchestrator = Orchestrator(argparser) + + +def main(): + # Получение аргументов только после инициализации Orchestrator + argspace = argparser.parsed_argspace + + # Получение конкретных аргументов + host = argspace.get_by_name("host") + port = argspace.get_by_name("port") + + print("Server configuration:") + print(f" Host: {host.value}") + print(f" Port: {port.value}") + + orchestrator.start_polling(app) + +if __name__ == "__main__": + main() + \ No newline at end of file diff --git a/docs/code_snippets/argspace_snippet2.py b/docs/code_snippets/argspace_snippet2.py new file mode 100644 index 0000000..dabe4b2 --- /dev/null +++ b/docs/code_snippets/argspace_snippet2.py @@ -0,0 +1,11 @@ +from argenta import Router, Response +from argenta.di import FromDishka +from argenta.orchestrator.argparser import ArgSpace + + +router = Router() + +@router.command('get_args') +async def get_args(response: Response, argspace: FromDishka[ArgSpace]): + print(argspace.all_arguments) + \ No newline at end of file diff --git a/docs/locales/en/LC_MESSAGES/root/api/app/autocompleter.po b/docs/locales/en/LC_MESSAGES/root/api/app/autocompleter.po index 11d5bac..56614dd 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/app/autocompleter.po +++ b/docs/locales/en/LC_MESSAGES/root/api/app/autocompleter.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,6 +20,101 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../root/api/app/autocompleter.rst:4 -msgid "Autocompleter" +msgid "AutoCompleter" msgstr "" +#: ../../root/api/app/autocompleter.rst:6 +msgid "" +"Объект ``AutoCompleter`` является компонентом ``Argenta``, отвечающим за " +"интерактивное автодополнение команд. Его основная задача — улучшить опыт " +"взаимодействия пользователя с командной строкой, предоставляя подсказки и" +" автоматически завершая ввод на основе ранее введенных команд. Это " +"значительно ускоряет работу и снижает вероятность опечаток." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:8 +msgid "" +"``AutoCompleter`` использует ``pyreadline3`` для имплементации ``readline" +" GNU`` на ``Windows`` для управления историей команд и реализации логики " +"автодополнения." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:13 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/app/autocompleter.rst:20 +msgid "Создает и настраивает экземпляр ``AutoCompleter``." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:22 +msgid "" +"``history_filename``: Имя файла для сохранения и загрузки истории команд." +" Если указано, история будет персистентной между сессиями приложения. " +"Если **None**, история будет храниться только в памяти текущей сессии." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:23 +msgid "" +"``autocomplete_button``: Название клавиши, которая активирует " +"автодополнение. По умолчанию используется клавиша **\"tab\"**." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:28 +msgid "Назначение и возможности" +msgstr "" + +#: ../../root/api/app/autocompleter.rst:30 +msgid "``AutoCompleter`` обладает следующими возможностями:" +msgstr "" + +#: ../../root/api/app/autocompleter.rst:32 +msgid "" +"**Автодополнение по истории**: Основная логика автодополнения основана на" +" истории команд, которые пользователь вводил ранее. Когда пользователь " +"начинает вводить команду и нажимает клавишу автодополнения (по умолчанию " +"**Tab**), система ищет в истории все команды, начинающиеся с введенного " +"текста." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:34 +msgid "" +"**Завершение по общему префиксу**: Если найдено несколько команд с общим " +"префиксом, автодокомплитер подставит только общую часть. Например, если в" +" истории есть команды ``show_users`` и ``show_profile``, при вводе " +"``sho`` и нажатии **Tab** будет подставлено ``show_``." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:36 +msgid "" +"**Персистентная история**: При указании параметра ``history_filename`` в " +"конструкторе, вся история команд сохраняется в файл при выходе из " +"приложения и загружается при следующем запуске. Это делает автодополнение" +" со временем все более \"умным\" и персонализированным." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:38 +msgid "" +"**Очистка истории**: При сохранении истории ``AutoCompleter`` " +"автоматически удаляет дубликаты и команды, которые больше не " +"зарегистрированы в приложении, поддерживая актуальность и чистоту файла " +"истории." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:40 +msgid "" +"**Настройка клавиши активации**: Вы можете изменить клавишу, отвечающую " +"за автодополнение, через параметр ``autocomplete_button``." +msgstr "" + +#: ../../root/api/app/autocompleter.rst:45 +msgid "Пример использования" +msgstr "" + +#: ../../root/api/app/autocompleter.rst:47 +msgid "``AutoCompleter`` передается как аргумент при инициализации `App`." +msgstr "" + +#~ msgid "Autocompleter" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/app/dividing_lines.po b/docs/locales/en/LC_MESSAGES/root/api/app/dividing_lines.po index 31f9ae8..55c93b5 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/app/dividing_lines.po +++ b/docs/locales/en/LC_MESSAGES/root/api/app/dividing_lines.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,6 +20,140 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../root/api/app/dividing_lines.rst:4 -msgid "DividingLines" +msgid "Dividing Lines" msgstr "" +#: ../../root/api/app/dividing_lines.rst:6 +msgid "" +"Разделительные линии в ``Argenta`` играют важную роль в визуальном " +"оформлении консольного интерфейса. Они используются для структурирования " +"вывода, отделения блоков информации друг от друга (например, вывода " +"команды от следующего приглашения к вводу). Библиотека предлагает два " +"подхода к управлению разделительными линиями: статический и динамический," +" каждый из которых имеет свои преимущества и сценарии использования." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:12 +msgid "Класс ``StaticDividingLine``" +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:14 +msgid "" +"``StaticDividingLine`` — это класс, который создает разделительную линию " +"**фиксированной** длины. Длина и символ-заполнитель задаются при " +"инициализации объекта. Этот тип линии полезен, когда вам нужен " +"предсказуемый и унифицированный внешний вид интерфейса, независимо от " +"содержимого вывода." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:22 +msgid "Создает экземпляр статической разделительной линии." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:24 +msgid "" +"``unit_part``: Символ, который будет использоваться для построения линии." +" Учитывается только первый символ строки. По умолчанию: ``-``." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:25 +msgid "" +"``length``: Целое число, определяющее фиксированную длину линии в " +"символах. Является keyword-only аргументом. По умолчанию: ``25``." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:30 +msgid "Класс ``DynamicDividingLine``" +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:32 +msgid "" +"``DynamicDividingLine`` представляет собой более \"умный\" подход. Этот " +"класс создает линию, длина которой **динамически** подстраивается под " +"самую длинную строку, выведенную в консоль, в рамках выполнения одной " +"команды. Это достигается за счет механизма перехвата `stdout`. В " +"результате разделительные линии всегда идеально обрамляют выводимый " +"контент, что выглядит очень аккуратно." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:39 +msgid "Создает экземпляр динамической разделительной линии." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:41 +msgid "" +"``unit_part``: Символ, который будет использоваться для построения линии." +" По умолчанию: ``-``." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:43 +msgid "" +"Длина для этой линии не задается при инициализации, так как она " +"вычисляется автоматически во время выполнения." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:46 +msgid "" +"Обязательно почитайте про нюансы использования динамических линий и " +"перехвата ``stdout`` в :ref:`этом разделе`." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:51 +msgid "Назначение и использование" +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:53 +msgid "" +"Выбор между статической и динамической линией зависит от ваших " +"потребностей в конкретном приложении или даже для конкретного " +"``Router``-а." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:55 +msgid "**StaticDividingLine** идеально подходит, если:" +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:57 +msgid "Вам нужен строгий, консистентный дизайн." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:58 +msgid "" +"Вы используете роутеры с отключенным перехватом ``stdout`` " +"(``disable_redirect_stdout=True``), так как в этом случае динамическое " +"вычисление длины невозможно." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:60 +msgid "" +"**DynamicDividingLine** (используется по умолчанию) является " +"предпочтительным выбором, если:" +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:62 +msgid "Вы хотите, чтобы интерфейс выглядел аккуратно и адаптивно." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:63 +msgid "" +"Вывод ваших команд имеет разную длину, и вы хотите, чтобы рамки всегда " +"соответствовали контенту." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:64 +msgid "В ваших хэндлерах нет ожидающих ``io`` операций." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:66 +msgid "" +"Тип разделительной линии для всего приложения задается при инициализации " +"``App`` через параметр ``dividing_line``." +msgstr "" + +#: ../../root/api/app/dividing_lines.rst:71 +msgid "Пример конфигурации" +msgstr "" + +#~ msgid "DividingLines" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/app/index.po b/docs/locales/en/LC_MESSAGES/root/api/app/index.po index bb3db40..5866465 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/app/index.po +++ b/docs/locales/en/LC_MESSAGES/root/api/app/index.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,7 +19,227 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/api/app/index.rst:2 +#: ../../root/api/app/index.rst:4 msgid "App" msgstr "" +#: ../../root/api/app/index.rst:6 +msgid "" +"Объект ``App`` является центральной сущностью библиотеки ``Argenta``. Он " +"выступает в роли ядра вашего консольного приложения, отвечая за его " +"конфигурацию, управление жизненным циклом, обработку команд и " +"взаимодействие с пользователем. ``App`` координирует работу всех " +"остальных компонентов, таких как роутеры, обработчики команд и системные " +"сообщения." +msgstr "" + +#: ../../root/api/app/index.rst:11 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/app/index.rst:38 +msgid "Создает и настраивает экземпляр приложения ``Argenta``." +msgstr "" + +#: ../../root/api/app/index.rst:40 +msgid "" +"``prompt``: Строка-приглашение, которая отображается перед вводом каждой" +" команды. По умолчанию: **\"What do you want to do?\\\\n\\\\n\"**." +msgstr "" + +#: ../../root/api/app/index.rst:41 +msgid "" +"``initial_message``: Приветственное сообщение, которое выводится при " +"запуске приложения." +msgstr "" + +#: ../../root/api/app/index.rst:42 +msgid "" +"``farewell_message``: Прощальное сообщение при завершении работы " +"приложения." +msgstr "" + +#: ../../root/api/app/index.rst:43 +msgid "" +"``exit_command``: Сущность команды, которая будет маркирована как команда" +" для выхода из приложения." +msgstr "" + +#: ../../root/api/app/index.rst:44 +msgid "" +"``system_router_title``: Заголовок для системного роутера, который " +"содержит команду выхода и другие системные команды." +msgstr "" + +#: ../../root/api/app/index.rst:45 +msgid "" +"``ignore_command_register``: Если **True** (по умолчанию), регистр " +"введенных команд будет игнорироваться при поиске обработчика." +msgstr "" + +#: ../../root/api/app/index.rst:46 +msgid "" +"``dividing_line``: Объект, управляющий стилем разделительной линии. Может" +" быть **StaticDividingLine** или **DynamicDividingLine**." +msgstr "" + +#: ../../root/api/app/index.rst:47 +msgid "" +"``repeat_command_groups``: Если **True** (по умолчанию), описание " +"доступных команд будет выводиться перед каждым вводом." +msgstr "" + +#: ../../root/api/app/index.rst:48 +msgid "" +"``override_system_messages``: Если **True** (по умолчанию), стандартное " +"форматирование системных сообщений (цвета, ASCII-арт) будет отключено." +msgstr "" + +#: ../../root/api/app/index.rst:49 +msgid "``autocompleter``: Объект, отвечающий за логику автодополнения команд." +msgstr "" + +#: ../../root/api/app/index.rst:50 +msgid "" +"``print_func``: Функция, используемая для вывода всех системных " +"сообщений. По умолчанию используется ``rich.console.Console().print``." +msgstr "" + +#: ../../root/api/app/index.rst:55 +msgid "Основные методы" +msgstr "" + +#: ../../root/api/app/index.rst:59 +msgid "" +"Регистрирует один ``Router`` в приложении. Все команды, определенные в " +"этом роутере, становятся доступными для вызова." +msgstr "" + +#: ../../root/api/app/index.rst +msgid "Parameters" +msgstr "" + +#: ../../root/api/app/index.rst:61 +msgid "Объект роутера, который нужно зарегистрировать." +msgstr "" + +#: ../../root/api/app/index.rst:65 +msgid "" +"Регистрирует несколько роутеров одновременно. Является удобной оберткой " +"над ``include_router``." +msgstr "" + +#: ../../root/api/app/index.rst:67 +msgid "Последовательность объектов ``Router`` для регистрации." +msgstr "" + +#: ../../root/api/app/index.rst:71 +msgid "" +"Добавляет дополнительное текстовое сообщение, которое будет выведено на " +"экран при запуске приложения, сразу после `initial_message`." +msgstr "" + +#: ../../root/api/app/index.rst:73 +msgid "Строка с сообщением." +msgstr "" + +#: ../../root/api/app/index.rst:78 +msgid "Методы установки обработчиков" +msgstr "" + +#: ../../root/api/app/index.rst:80 +msgid "" +"``App`` позволяет гибко настраивать реакцию на различные события, такие " +"как ошибки ввода или ввод неизвестной команды." +msgstr "" + +#: ../../root/api/app/index.rst:83 +msgid "" +"Подробнее о исключениях и их обработке в соответствующем :ref:`разделе " +"документации `." +msgstr "" + +#: ../../root/api/app/index.rst:89 +msgid "" +"Устанавливает пользовательский шаблон для форматирования строки, " +"описывающей доступную команду (триггер + описание)." +msgstr "" + +#: ../../root/api/app/index.rst:91 +msgid "``DescriptionMessageGenerator`` -> ``Callable[[str, str], str]``" +msgstr "" + +#: ../../root/api/app/index.rst:93 +msgid "" +"Где первый аргумент - это триггер команды, а второй - ее описание, " +"возвращает строку, которая является форматированной строкой." +msgstr "" + +#: ../../root/api/app/index.rst:99 +msgid "" +"Устанавливает обработчик, который вызывается при некорректном синтаксисе " +"флагов в введенной команде." +msgstr "" + +#: ../../root/api/app/index.rst:101 ../../root/api/app/index.rst:111 +msgid "``NonStandardBehaviorHandler[str]`` -> ``Callable[[str], None]``" +msgstr "" + +#: ../../root/api/app/index.rst:103 ../../root/api/app/index.rst:113 +msgid "" +"Где первый и единственный аргумент - это необработанная строка " +"пользовательского ввода." +msgstr "" + +#: ../../root/api/app/index.rst:109 +msgid "" +"Устанавливает обработчик для ситуации, когда пользователь вводит один и " +"тот же флаг несколько раз." +msgstr "" + +#: ../../root/api/app/index.rst:119 +msgid "" +"Устанавливает обработчик, который срабатывает, если введенная команда не " +"была найдена ни в одном из зарегистрированных роутеров." +msgstr "" + +#: ../../root/api/app/index.rst:121 +msgid "" +"``NonStandardBehaviorHandler[InputCommand]`` -> " +"``Callable[[InputCommand], None]``" +msgstr "" + +#: ../../root/api/app/index.rst:123 +msgid "" +"Где первый и единственный аргумент - это распаршенный в объект " +"InputCommand ввод пользователя." +msgstr "" + +#: ../../root/api/app/index.rst:129 +msgid "" +"Устанавливает обработчик для случая, когда пользователь отправляет пустую" +" строку вместо команды." +msgstr "" + +#: ../../root/api/app/index.rst:131 +msgid "``EmptyCommandHandler`` -> ``Callable[[], None]``" +msgstr "" + +#: ../../root/api/app/index.rst:133 +msgid "Не принимает и не возвращает ничего." +msgstr "" + +#: ../../root/api/app/index.rst:139 +msgid "" +"Позволяет переопределить стандартное поведение при вызове команды выхода." +" По умолчанию просто выводится ``farewell_message``." +msgstr "" + +#: ../../root/api/app/index.rst:141 +msgid "``NonStandardBehaviorHandler[Response]`` -> ``Callable[[Response], None]``" +msgstr "" + +#: ../../root/api/app/index.rst:143 +msgid "Где первый и единственный аргумент - это объект ответа, ``Response``." +msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/index.po b/docs/locales/en/LC_MESSAGES/root/api/index.po index 55ba8df..baeed85 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/index.po +++ b/docs/locales/en/LC_MESSAGES/root/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 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,7 +19,53 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/api/index.rst:2 -msgid "Публичный API" +#: ../../root/api/index.rst:5 +msgid "Публичное API" msgstr "" +#: ../../root/api/index.rst:8 +msgid "Описание раздела" +msgstr "" + +#: ../../root/api/index.rst:10 +msgid "" +"В данном разделе приводятся сведения о публичной части интерфейса " +"библиотеки:" +msgstr "" + +#: ../../root/api/index.rst:12 +msgid "" +"Классы и функции, предназначенные для прямой интеграции в сторонние " +"приложения." +msgstr "" + +#: ../../root/api/index.rst:13 +msgid "" +"Советы по совместимости, ограничения и поддерживаемые сценарии " +"использования." +msgstr "" + +#: ../../root/api/index.rst:14 +msgid "" +"Примеры типовой интеграции, подробные сигнатуры методов и описание " +"возвращаемых сущностей." +msgstr "" + +#: ../../root/api/index.rst:15 +msgid "" +"Гарантии стабильности API, поддержка и обратная совместимость между " +"версиями." +msgstr "" + +#: ../../root/api/index.rst:17 +msgid "" +"Интерфейсы, не указанные в этом разделе, считаются внутренними и не " +"подлежат использованию вне самой библиотеки. При разработке собственных " +"решений рекомендуем обращаться именно к описанным здесь компонентам — это" +" даст стабильность и гарантии на будущее развитие ваших продуктов с " +"использованием ``Argenta``." +msgstr "" + +#~ msgid "Публичный API" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argparser.po b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argparser.po index 62ef841..2baf285 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argparser.po +++ b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argparser.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -20,10 +20,129 @@ msgstr "" "Generated-By: Babel 2.17.0\n" #: ../../root/api/orchestrator/argparser.rst:4 -msgid "Argparser" +msgid "ArgParser" msgstr "" #: ../../root/api/orchestrator/argparser.rst:6 -msgid "nu" +msgid "" +"Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки " +"**аргументов командной строки**, которые передаются вашему приложению при" +" его запуске. Важно не путать их с флагами команд, которые пользователь " +"вводит в интерактивном режиме работы приложения. ``ArgParser`` позволяет " +"вашему приложению получать внешнюю конфигурацию в момент старта, " +"например, путь к файлу настроек, флаги для отладки или режим запуска." msgstr "" +#: ../../root/api/orchestrator/argparser.rst:11 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:21 +msgid "Создает экземпляр парсера аргументов командной строки." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:23 +msgid "" +"``processed_args``: Список аргументов, которые будут обрабатываться и " +"парситься при запуске приложения, подробнее :ref:`тут " +"`." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:24 +msgid "``name``: Имя приложения, которое будет отображаться в справке." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:25 +msgid "" +"``description``: Описание приложения, которое будет отображаться в " +"справке." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:26 +msgid "" +"``epilog``: Дополнительная информация, которая будет отображаться в конце" +" справки." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:29 +msgid "Основные методы и атрибуты" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:33 +msgid "" +"Экземпляр класса ``ArgSpace``, который содержит все обработанные " +"аргументы командной строки, подробнее :ref:`тут " +"`." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:36 +msgid "" +"До инициализации инстанса ``Orchestrator``, которому в конструктор был " +"передан соответствующий экземпляр ``ArgParser``, атрибут " +"``parsed_argspace`` будет равен пустому ``ArgSpace``." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:38 +msgid "" +"Парсинг и валидация аргументов командной строки происходит при " +"инициализации ``Orchestrator``, соответственно использование атрибута " +"``parsed_argspace`` **целесообразно только после инициализации** " +"``Orchestrator``." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:43 +msgid "Лучшие практики" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:45 +msgid "" +"Использование атрибута ``parsed_argspace`` рекомендуется только на этапе " +"настройки приложения, в хэндлерах лучшей практикой является получение " +"``ArgSpace`` через ``di``, подробнее :ref:`тут " +"`." +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:48 +msgid "Пример использования" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:55 +msgid "Обработка ошибок" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:58 +msgid "" +"Про типы аргументов подробнее в :ref:`Arguments " +"`" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:60 +msgid "" +"При работе с аргументами командной строки стандартный ``ArgumentParser`` " +"автоматически обрабатывает следующие ситуации:" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:62 +msgid "**Отсутствие обязательного аргумента:**" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:70 +msgid "**Недопустимое значение из списка choices:**" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:78 +msgid "**Использование устаревшего аргумента:**" +msgstr "" + +#: ../../root/api/orchestrator/argparser.rst:80 +msgid "" +"При использовании аргумента с ``is_deprecated=True`` выводится " +"предупреждение, но выполнение продолжается:" +msgstr "" + +#~ msgid "Argparser" +#~ msgstr "" + +#~ msgid "nu" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argspace.po b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argspace.po new file mode 100644 index 0000000..dfaa7ff --- /dev/null +++ b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/argspace.po @@ -0,0 +1,173 @@ +# 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-27 11:56+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" + +#: ../../root/api/orchestrator/argspace.rst:4 +msgid "ArgSpace" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:6 +msgid "" +"Объект ``ArgSpace`` является контейнером для хранения и управления " +"распаршенными аргументами командной строки в приложении ``Argenta``. Его " +"основная задача — предоставить удобный интерфейс для доступа к значениям " +"аргументов, переданных при запуске приложения." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:8 +msgid "" +"``ArgSpace`` автоматически создается после парсинга аргументов через " +"``ArgParser`` и содержит коллекцию объектов ``InputArgument``, " +"представляющих собой финальные значения всех переданных параметров " +"командной строки." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:13 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:20 +msgid "Создает новое пространство аргументов." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:22 +msgid "" +"``all_arguments`` : Список распаршенных аргументов в виде объектов " +"``InputArgument``. Каждый элемент содержит имя, значение и тип исходного " +"аргумента." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:24 +msgid "**Атрибуты:**" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:28 +msgid "" +"Список всех распаршенных аргументов типа ``InputArgument``. Содержит все " +"аргументы, переданные при запуске приложения, включая значения по " +"умолчанию для не указанных параметров." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:33 +msgid "Методы" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:36 +msgid "get_by_name" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:43 +msgid "Возвращает аргумент по его имени." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst +msgid "param name" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:45 +msgid "Имя искомого аргумента" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst +msgid "return" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:46 +msgid "" +"Объект ``InputArgument`` с указанным именем или ``None``, если аргумент " +"не найден" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:48 +msgid "" +"Метод выполняет линейный поиск по списку ``all_arguments`` и возвращает " +"аргумент с соответствующим именем. Если аргумент не найден, возвращается " +"``None``." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:50 +#: ../../root/api/orchestrator/argspace.rst:86 +msgid "**Пример использования:**" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:72 +msgid "get_by_type" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:79 +msgid "Получает все аргументы определенного типа." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst +msgid "param arg_type" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:81 +msgid "Тип аргумента (``BooleanArgument`` или ``ValueArgument``)" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:82 +msgid "" +"Список аргументов указанного типа или пустой список, если аргументы не " +"найдены" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:84 +msgid "" +"Метод фильтрует ``all_arguments`` по атрибуту ``founder_class`` каждого " +"``InputArgument`` и возвращает только те аргументы, которые были созданы " +"из указанного типа." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:109 +msgid "InputArgument" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:112 +msgid "" +"Документация по ``InputArgument`` находится :ref:`тут " +"`" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:117 +msgid "Примеры испольования" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:119 +msgid "" +"``ArgSpace`` используется для доступа к значениям аргументов после " +"запуска приложения. Типичный сценарий работы включает парсинг аргументов " +"через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:121 +msgid "**Полный пример:**" +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:126 +msgid "" +"Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, " +"подробнее :ref:`тут `." +msgstr "" + +#: ../../root/api/orchestrator/argspace.rst:131 +msgid "**Запуск приложения:**" +msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/arguments.po b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/arguments.po index 0c4266e..54d4403 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/arguments.po +++ b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/arguments.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -24,6 +24,211 @@ msgid "Arguments" msgstr "" #: ../../root/api/orchestrator/arguments.rst:6 -msgid "prikol" +msgid "" +"Модуль ``Arguments`` предоставляет набор классов для работы с аргументами" +" командной строки при запуске приложения ``Argenta``. Эти аргументы " +"позволяют настраивать поведение приложения на этапе его старта, передавая" +" различные параметры конфигурации через интерфейс командной строки." msgstr "" +#: ../../root/api/orchestrator/arguments.rst:8 +msgid "" +"Аргументы регистрируются в ``ArgParser`` и парсятся при запуске " +"приложения, становясь доступными через объект ``ArgSpace``." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:13 +msgid "ValueArgument" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:15 +msgid "" +"Класс для аргументов командной строки, требующих передачи значения. " +"Используется для параметров конфигурации, которым необходимо указать " +"конкретное значение при запуске приложения." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:30 +msgid "Создает аргумент командной строки, требующий значения." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param name" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:32 +#: ../../root/api/orchestrator/arguments.rst:100 +#: ../../root/api/orchestrator/arguments.rst:165 +msgid "Имя аргумента" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param prefix" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:33 +#: ../../root/api/orchestrator/arguments.rst:101 +msgid "Префикс аргумента, по умолчанию ``--``" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param help" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:34 +#: ../../root/api/orchestrator/arguments.rst:102 +msgid "Сообщение справки, отображаемое при ``--help``" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param possible_values" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:35 +msgid "" +"Список допустимых значений для аргумента. Передается в параметр " +"``choices`` ArgumentParser" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param default" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:36 +msgid "Значение по умолчанию, используемое если аргумент не передан при запуске" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param is_required" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:37 +msgid "" +"Обязатялен ли аргумент. Если ``True``, приложение не запустится без этого" +" аргумента" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param is_deprecated" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:38 +#: ../../root/api/orchestrator/arguments.rst:103 +msgid "Является ли аргумент устаревшим" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:40 +#: ../../root/api/orchestrator/arguments.rst:105 +msgid "**Пример использования:**" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:74 +#: ../../root/api/orchestrator/arguments.rst:134 +msgid "**Запуск приложения:**" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:84 +msgid "BooleanArgument" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:86 +msgid "" +"Класс для булевых аргументов командной строки, которые не требуют " +"передачи значения. Наличие или отсутствие аргумента при запуске " +"определяет состояние распаршенных аргументов(``True`` при наличии и " +"``False`` при отсутствии)." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:98 +msgid "Создает булевый аргумент командной строки без значения." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:147 +msgid "InputArgument" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:150 +msgid "" +"``InputArgument`` непосредственно связан и является наполнителем " +"контейнера ``ArgSpace``, подробнее про него :ref:`тут " +"`." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:152 +msgid "" +"Представляет собой распаршенный аргумент командной строки после запуска " +"приложения. Этот класс используется внутри объекта ``ArgSpace`` для " +"хранения значений аргументов, полученных при парсинге." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:163 +msgid "Создает экземпляр распарсенного входного аргумента." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param value" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:166 +msgid "" +"Значение аргумента. Для ``BooleanArgument`` всегда ``True`` если флаг " +"передан, для ``ValueArgument`` — строка со значением" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst +msgid "param founder_class" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:167 +msgid "" +"Класс-родитель, из которого был создан этот аргумент (``BooleanArgument``" +" или ``ValueArgument``)" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:169 +msgid "**Атрибуты:**" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:173 +msgid "" +"Имя аргумента в виде строки. Соответствует имени, указанному при создании" +" ``ValueArgument`` или ``BooleanArgument``." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:177 +msgid "Значение аргумента. Тип значения зависит от исходного класса аргумента:" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:179 +msgid "Для ``BooleanArgument``: ``True`` если флаг был передан при запуске" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:180 +msgid "" +"Для ``ValueArgument``: строка с переданным значением или значением по " +"умолчанию" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:184 +msgid "" +"Ссылка на класс, из которого был создан этот аргумент. Используется для " +"определения типа аргумента и фильтрации в методе ``get_by_type()``." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:186 +msgid "**Методы:**" +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:190 +msgid "" +"Возвращает строковое представление аргумента в формате " +"``InputArgument(name=value)``." +msgstr "" + +#: ../../root/api/orchestrator/arguments.rst:200 +msgid "Возвращает техническое представление объекта в виде строки." +msgstr "" + +#~ msgid "prikol" +#~ msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/index.po b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/index.po index c72d04a..76f7b0f 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/orchestrator/index.po +++ b/docs/locales/en/LC_MESSAGES/root/api/orchestrator/index.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -19,7 +19,121 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 2.17.0\n" -#: ../../root/api/orchestrator/index.rst:2 +#: ../../root/api/orchestrator/index.rst:4 msgid "Orchestrator" msgstr "" +#: ../../root/api/orchestrator/index.rst:6 +msgid "" +"Объект ``Orchestrator`` в ``Argenta`` представляет собой высокоуровневый " +"компонент, который стоит над ``App`` и отвечает за \"оркестрацию\" всего " +"приложения. Его главная задача — инициализация и конфигурация сложных " +"систем, таких как внедрение зависимостей (``di``), парсинг аргументов " +"командной строки при запуске, и запуск основного цикла приложения." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:8 +msgid "" +"В то время как ``App`` отвечает за интерактивную сессию (ввод команд, " +"роутинг), ``Orchestrator`` подготавливает окружение, в котором ``App`` " +"будет работать. Он является точкой входа для приложений." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:13 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:28 +msgid "Создает и конфигурирует экземпляр ``Orchestrator``." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:30 +msgid "" +"``arg_parser``: Экземпляр " +":class:`argenta.orchestrator.argparser.ArgParser`, который отвечает за " +"парсинг аргументов, переданных скрипту при запуске из командной строки " +"(не путать с командами, вводимыми в интерактивном режиме)." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:31 +msgid "" +"``custom_providers``: Список пользовательских провайдеров " +"``dishka.Provider``. Это основной механизм для добавления ваших " +"собственных сервисов (например, подключений к базе данных, клиентов API) " +"в контейнер внедрения зависимостей." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:32 +msgid "" +"``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` будет " +"автоматически инспектировать сигнатуры обработчиков команд и внедрять в " +"них требуемые зависимости из контейнера." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:37 +msgid "Основные методы" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:41 +msgid "" +"Это главный метод, который запускает все приложение. Он выполняет " +"следующие шаги:" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:43 +msgid "" +"**Настройка DI**: На основе системного провайдера (``SystemProvider``, " +"который предоставляет ``ArgParser``) и списка ``custom_providers`` " +"создается ``ioc`` - контейнер и настраивается внедрение зависимостей." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:45 +msgid "" +"**Запуск основного цикла**: Запускает бесконечный цикл ожидания и " +"обработки пользовательского ввода." +msgstr "" + +#: ../../root/api/orchestrator/index.rst +msgid "Parameters" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:47 +msgid "Экземпляр класса :class:`~argenta.app.models.App`, который будет запущен." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:52 +msgid "Назначение и использование" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:54 +msgid "" +"``Orchestrator`` абстрагирует от вас всю сложность, связанную с " +"настройкой внедрения зависимостей и парсингом стартовых аргументов. " +"Типичный сценарий использования ``Argenta`` выглядит следующим образом:" +msgstr "" + +#: ../../root/api/orchestrator/index.rst:56 +msgid "Создать экземпляр ``App`` и настроить его (добавить роутеры)." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:57 +msgid "" +"Создать экземпляр ``Orchestrator``, передав в него необходимые " +"DI-провайдеры и, возможно, парсер аргументов." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:58 +msgid "Вызвать ``orchestrator.start_polling(app)``, чтобы запустить приложение." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:60 +msgid "" +"Такой подход позволяет сохранить код чистым и разделяет ответственность: " +"``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за " +"подготовку и запуск окружения." +msgstr "" + +#: ../../root/api/orchestrator/index.rst:63 +msgid "Пример использования" +msgstr "" + diff --git a/docs/locales/en/LC_MESSAGES/root/api/router.po b/docs/locales/en/LC_MESSAGES/root/api/router.po index 6bf2423..352d998 100644 --- a/docs/locales/en/LC_MESSAGES/root/api/router.po +++ b/docs/locales/en/LC_MESSAGES/root/api/router.po @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Argenta \n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2025-10-15 16:09+0300\n" +"POT-Creation-Date: 2025-10-27 11:56+0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language: en\n" @@ -23,3 +23,138 @@ msgstr "" msgid "Router" msgstr "" +#: ../../root/api/router.rst:6 +msgid "" +"Объект ``Router`` является фундаментальным строительным блоком для " +"организации логики в приложении ``Argenta``. Его основная задача — " +"группировать связанные команды и их обработчики. Каждый роутер " +"представляет собой логический контейнер для определенного набора " +"функциональности." +msgstr "" + +#: ../../root/api/router.rst:8 +msgid "" +"Например, в приложении для управления пользователями один роутер может " +"отвечать за команды, связанные с аутентификацией (``login``, ``logout``)," +" а другой — за операции с профилем (``profile show``, ``profile edit``)." +msgstr "" + +#: ../../root/api/router.rst:13 +msgid "Инициализация" +msgstr "" + +#: ../../root/api/router.rst:21 +msgid "Создает новый экземпляр маршрутизатора." +msgstr "" + +#: ../../root/api/router.rst:23 +msgid "" +"``title`` : Необязательный заголовок для группы команд, которые " +"регистрируются в этом роутере. Этот заголовок будет отображаться в списке" +" доступных команд, помогая пользователю ориентироваться." +msgstr "" + +#: ../../root/api/router.rst:24 +msgid "" +"``disable_redirect_stdout`` : Если установлено в ``True``, отключает " +"механизм перехвата стандартного вывода (``stdout``) для всех команд этого" +" роутера. Это необходимо для команд, которые требуют интерактивного ввода" +" от пользователя (например, с помощью ``input()``). При отключении " +"перехвата вывода автоматически используется статическая разделительная " +"линия. Подробнее в :ref:`соответствующем разделе `" +msgstr "" + +#: ../../root/api/router.rst:29 +msgid "Регистрация команд" +msgstr "" + +#: ../../root/api/router.rst:31 +msgid "" +"Для регистрации новой команды и привязки к ней функции-обработчика " +"используется декоратор ``@command``." +msgstr "" + +#: ../../root/api/router.rst:35 +msgid "Декоратор для регистрации функции как обработчика для указанной команды." +msgstr "" + +#: ../../root/api/router.rst +msgid "Parameters" +msgstr "" + +#: ../../root/api/router.rst:37 +msgid "" +"Экземпляр класса ``argenta.command.Command``, описывающий триггер, флаги " +"и описание команды. Также может быть просто строкой, которая будет " +"являться триггером, в этом случае нет возможности настроить флаги, " +"описание и всё остальное." +msgstr "" + +#: ../../root/api/router.rst:39 +msgid "**Пример использования:**" +msgstr "" + +#: ../../root/api/router.rst:48 +msgid "Системный роутер по умолчанию" +msgstr "" + +#: ../../root/api/router.rst:50 +msgid "" +"``Argenta`` поставляется со встроенным системным роутером, который " +"автоматически подключается к каждому приложению." +msgstr "" + +#: ../../root/api/router.rst:54 +msgid "" +"Предопределенный экземпляр ``Router``, который содержит базовые системные" +" команды. По умолчанию в него включена команда выхода из приложения " +"(обычно **exit**). Он имеет заголовок **\"System points:\"**, который " +"можно переопределить в инстансе приложения -> ``App``." +msgstr "" + +#: ../../root/api/router.rst:56 +msgid "" +"Вы можете добавлять свои команды в этот роутер, для этого импортируйте " +"``argenta.router.defaults.system_router`` и декорируйте его методом " +"необходимые хэндлеры." +msgstr "" + +#: ../../root/api/router.rst:61 +msgid "Возможные исключения" +msgstr "" + +#: ../../root/api/router.rst:63 +msgid "" +"При регистрации команд и флагов в ``Router`` могут возникнуть следующие " +"исключения, сигнализирующие о некорректной конфигурации:" +msgstr "" + +#: ../../root/api/router.rst:67 +msgid "" +"Выбрасывается, если триггер команды, передаваемый в ``Command``, содержит" +" пробелы. Триггеры команд должны быть одним словом." +msgstr "" + +#: ../../root/api/router.rst:69 +msgid "" +"**Неправильно:** ``Command(\"add user\")`` **Правильно:** ``Command" +"(\"add-user\")``" +msgstr "" + +#: ../../root/api/router.rst:74 +msgid "" +"Возникает, если при определении флагов для одной команды были " +"использованы дублирующиеся имена (как короткие, так и длинные). Каждое " +"имя флага в рамках одной команды должно быть уникальным." +msgstr "" + +#: ../../root/api/router.rst:76 +msgid "**Пример, вызывающий исключение:**" +msgstr "" + +#: ../../root/api/router.rst:88 +msgid "" +"Это исключение возникает, если какой-либо обработчик команды не ожидает " +"обязательный аргумент, которым является объект ответа(``Response``)." +msgstr "" + diff --git a/docs/root/api/command/flags.rst b/docs/root/api/command/flags.rst index e605b8d..c3319fc 100644 --- a/docs/root/api/command/flags.rst +++ b/docs/root/api/command/flags.rst @@ -3,6 +3,7 @@ Flags ====== +.. _root_api_command_flag: Flag ===== diff --git a/docs/root/api/command/index.rst b/docs/root/api/command/index.rst index 215542f..475b6d4 100644 --- a/docs/root/api/command/index.rst +++ b/docs/root/api/command/index.rst @@ -13,4 +13,4 @@ Command .. _input_command: InputCommand -============ +~~~~~~~~~~~~ diff --git a/docs/root/api/orchestrator/argparser.rst b/docs/root/api/orchestrator/argparser.rst index 91d434e..e3303c3 100644 --- a/docs/root/api/orchestrator/argparser.rst +++ b/docs/root/api/orchestrator/argparser.rst @@ -39,7 +39,7 @@ ArgParser ----- -Назначение и интеграция +Лучшие практики ------------------------ Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``, подробнее :ref:`тут `. @@ -50,3 +50,36 @@ ArgParser .. literalinclude:: ../../../code_snippets/argparser_snippet.py :language: python :linenos: + +Обработка ошибок +---------------- + +.. seealso:: + Про типы аргументов подробнее в :ref:`Arguments ` + +При работе с аргументами командной строки стандартный ``ArgumentParser`` автоматически обрабатывает следующие ситуации: + +**Отсутствие обязательного аргумента:** + +.. code-block:: bash + + $ python app.py + usage: MyApp [-h] --config CONFIG + MyApp: error: the following arguments are required: --config + +**Недопустимое значение из списка choices:** + +.. code-block:: bash + + $ python app.py --config app.yaml --log-level TRACE + usage: MyApp [-h] --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + MyApp: error: argument --log-level: invalid choice: 'TRACE' + +**Использование устаревшего аргумента:** + +При использовании аргумента с ``is_deprecated=True`` выводится предупреждение, но выполнение продолжается: + +.. code-block:: bash + + $ python app.py --old-param value + Warning: argument --old-param is deprecated diff --git a/docs/root/api/orchestrator/argspace.rst b/docs/root/api/orchestrator/argspace.rst index a2964ba..f134184 100644 --- a/docs/root/api/orchestrator/argspace.rst +++ b/docs/root/api/orchestrator/argspace.rst @@ -1,4 +1,147 @@ .. _root_api_orchestrator_argspace: ArgSpace -========== \ No newline at end of file +========== + +Объект ``ArgSpace`` является контейнером для хранения и управления распаршенными аргументами командной строки в приложении ``Argenta``. Его основная задача — предоставить удобный интерфейс для доступа к значениям аргументов, переданных при запуске приложения. + +``ArgSpace`` автоматически создается после парсинга аргументов через ``ArgParser`` и содержит коллекцию объектов ``InputArgument``, представляющих собой финальные значения всех переданных параметров командной строки. + +----- + +Инициализация +------------- + +.. code-block:: python + :linenos: + + __init__(self, all_arguments: list[InputArgument]) -> None + +Создает новое пространство аргументов. + +* ``all_arguments`` : Список распаршенных аргументов в виде объектов ``InputArgument``. Каждый элемент содержит имя, значение и тип исходного аргумента. + +**Атрибуты:** + +.. py:attribute:: all_arguments + + Список всех распаршенных аргументов типа ``InputArgument``. Содержит все аргументы, переданные при запуске приложения, включая значения по умолчанию для не указанных параметров. + +----- + +Методы +------ + +get_by_name +~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + get_by_name(self, name: str) -> InputArgument | None + +Возвращает аргумент по его имени. + +:param name: Имя искомого аргумента +:return: Объект ``InputArgument`` с указанным именем или ``None``, если аргумент не найден + +Метод выполняет линейный поиск по списку ``all_arguments`` и возвращает аргумент с соответствующим именем. Если аргумент не найден, возвращается ``None``. + +**Пример использования:** + +.. code-block:: python + :linenos: + + # Получение значения конкретного аргумента + config_arg = argspace.get_by_name("config") + if config_arg: + print(f"Config path: {config_arg.value}") + + verbose_arg = argspace.get_by_name("verbose") + if verbose_arg and verbose_arg.value: + print("Verbose mode enabled") + + # Обработка отсутствующего аргумента + unknown_arg = argspace.get_by_name("nonexistent") + if unknown_arg is None: + print("Argument not found") + +----- + +get_by_type +~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + get_by_type(self, arg_type: type[BaseArgument]) -> list[InputArgument] | list[Never] + +Получает все аргументы определенного типа. + +:param arg_type: Тип аргумента (``BooleanArgument`` или ``ValueArgument``) +:return: Список аргументов указанного типа или пустой список, если аргументы не найдены + +Метод фильтрует ``all_arguments`` по атрибуту ``founder_class`` каждого ``InputArgument`` и возвращает только те аргументы, которые были созданы из указанного типа. + +**Пример использования:** + +.. code-block:: python + :linenos: + + from argenta import BooleanArgument, ValueArgument + + # Получение всех булевых флагов + boolean_flags = argspace.get_by_type(BooleanArgument) + print(f"Active flags: {[arg.name for arg in boolean_flags if arg.value]}") + + # Получение всех аргументов со значениями + value_args = argspace.get_by_type(ValueArgument) + for arg in value_args: + print(f"{arg.name} = {arg.value}") + + # Подсчет количества аргументов каждого типа + print(f"Boolean arguments: {len(argspace.get_by_type(BooleanArgument))}") + print(f"Value arguments: {len(argspace.get_by_type(ValueArgument))}") + +----- + +InputArgument +------------- + +.. seealso :: + Документация по ``InputArgument`` находится :ref:`тут ` + +----- + +Примеры испольования +-------------------- + +``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий работы включает парсинг аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``. + +**Полный пример:** + +.. literalinclude:: ../../../code_snippets/argspace_snippet.py + :linenos: + +Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, подробнее :ref:`тут `. + +.. literalinclude:: ../../../code_snippets/argspace_snippet2.py + :linenos: + +**Запуск приложения:** + +.. code-block:: bash + + # С параметрами по умолчанию + python server.py + # Output: + # Server configuration: + # Host: localhost + # Port: 8080 + + # С кастомными параметрами + python server.py --host 0.0.0.0 --port 9000 + # Output: + # Server configuration: + # Host: 0.0.0.0 + # Port: 9000 diff --git a/docs/root/api/orchestrator/arguments.rst b/docs/root/api/orchestrator/arguments.rst index e6c288d..1a98887 100644 --- a/docs/root/api/orchestrator/arguments.rst +++ b/docs/root/api/orchestrator/arguments.rst @@ -1,6 +1,200 @@ .. _root_api_orchestrator_arguments: Arguments -**************** +========= -prikol +Модуль ``Arguments`` предоставляет набор классов для работы с аргументами командной строки при запуске приложения ``Argenta``. Эти аргументы позволяют настраивать поведение приложения на этапе его старта, передавая различные параметры конфигурации через интерфейс командной строки. + +Аргументы регистрируются в ``ArgParser`` и парсятся при запуске приложения, становясь доступными через объект ``ArgSpace``. + +----- + +ValueArgument +------------- + +Класс для аргументов командной строки, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать конкретное значение при запуске приложения. + +.. py:class:: ValueArgument(BaseArgument) + +.. code-block:: python + :linenos: + + __init__(self, name: str, *, + prefix: Literal["-", "--", "---"] = "--", + help: str = "Help message for the value argument", + possible_values: list[str] | None = None, + default: str | None = None, + is_required: bool = False, + is_deprecated: bool = False) -> None + +Создает аргумент командной строки, требующий значения. + +:param name: Имя аргумента +:param prefix: Префикс аргумента, по умолчанию ``--`` +:param help: Сообщение справки, отображаемое при ``--help`` +:param possible_values: Список допустимых значений для аргумента. Передается в параметр ``choices`` ArgumentParser +:param default: Значение по умолчанию, используемое если аргумент не передан при запуске +:param is_required: Обязатялен ли аргумент. Если ``True``, приложение не запустится без этого аргумента +:param is_deprecated: Является ли аргумент устаревшим + +**Пример использования:** + +.. code-block:: python + :linenos: + + from argenta import ArgParser, ValueArgument + + # Создание аргументов + config_arg = ValueArgument( + "config", + help="Path to configuration file", + default="config.yaml" + ) + + log_level_arg = ValueArgument( + "log-level", + help="Logging level", + possible_values=["DEBUG", "INFO", "WARNING", "ERROR"], + default="INFO" + ) + + host_arg = ValueArgument( + "host", + help="Server host address", + is_required=True + ) + + # Регистрация в ArgParser + parser = ArgParser( + processed_args=[config_arg, log_level_arg, host_arg], + name="MyApp", + description="My application with CLI arguments" + ) + +**Запуск приложения:** + +.. code-block:: bash + + python app.py --host 127.0.0.1 + python app.py --host 127.0.0.1 --config custom.yaml --log-level DEBUG + +----- + +BooleanArgument +--------------- + +Класс для булевых аргументов командной строки, которые не требуют передачи значения. Наличие или отсутствие аргумента при запуске определяет состояние распаршенных аргументов(``True`` при наличии и ``False`` при отсутствии). + +.. py:class:: BooleanArgument(BaseArgument) + +.. code-block:: python + :linenos: + + __init__(self, name: str, *, + prefix: Literal["-", "--", "---"] = "--", + help: str = "Help message for the boolean argument", + is_deprecated: bool = False) -> None + +Создает булевый аргумент командной строки без значения. + +:param name: Имя аргумента +:param prefix: Префикс аргумента, по умолчанию ``--`` +:param help: Сообщение справки, отображаемое при ``--help`` +:param is_deprecated: Является ли аргумент устаревшим + +**Пример использования:** + +.. code-block:: python + :linenos: + + from argenta import ArgParser, BooleanArgument + + # Создание булевых аргументов + verbose_arg = BooleanArgument( + "verbose", + help="Enable verbose output" + ) + + debug_arg = BooleanArgument( + "debug", + help="Enable debug mode" + ) + + no_cache_arg = BooleanArgument( + "no-cache", + help="Disable caching" + ) + + # Регистрация в ArgParser + parser = ArgParser( + processed_args=[verbose_arg, debug_arg, no_cache_arg], + name="MyApp" + ) + +**Запуск приложения:** + +.. code-block:: bash + + python app.py --verbose + python app.py --debug --no-cache + python app.py # без флагов + +----- + +.. _root_api_orchestrator_arguments_inputargument: + +InputArgument +------------- + +.. seealso:: + ``InputArgument`` непосредственно связан и является наполнителем контейнера ``ArgSpace``, подробнее про него :ref:`тут `. + +Представляет собой распаршенный аргумент командной строки после запуска приложения. Этот класс используется внутри объекта ``ArgSpace`` для хранения значений аргументов, полученных при парсинге. + +.. py:class:: InputArgument + +.. code-block:: python + :linenos: + + __init__(self, name: str, + value: str | Literal[True], + founder_class: type[BaseArgument]) -> None + +Создает экземпляр распарсенного входного аргумента. + +:param name: Имя аргумента +:param value: Значение аргумента. Для ``BooleanArgument`` всегда ``True`` если флаг передан, для ``ValueArgument`` — строка со значением +:param founder_class: Класс-родитель, из которого был создан этот аргумент (``BooleanArgument`` или ``ValueArgument``) + +**Атрибуты:** + +.. py:attribute:: name + + Имя аргумента в виде строки. Соответствует имени, указанному при создании ``ValueArgument`` или ``BooleanArgument``. + +.. py:attribute:: value + + Значение аргумента. Тип значения зависит от исходного класса аргумента: + + * Для ``BooleanArgument``: ``True`` если флаг был передан при запуске + * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию + +.. py:attribute:: founder_class + + Ссылка на класс, из которого был создан этот аргумент. Используется для определения типа аргумента и фильтрации в методе ``get_by_type()``. + +**Методы:** + +.. py:method:: __str__() -> str + + Возвращает строковое представление аргумента в формате ``InputArgument(name=value)``. + + .. code-block:: python + :linenos: + + arg = InputArgument("verbose", True, BooleanArgument) + print(str(arg)) # InputArgument(verbose=True) + +.. py:method:: __repr__() -> str + + Возвращает техническое представление объекта в виде строки. \ No newline at end of file