docs

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()
+    

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)
+    

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 <EMAIL@ADDRESS>\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 ""
+

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 <EMAIL@ADDRESS>\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:`этом разделе<root_redirect_stdout>`."
+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 ""
+

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 <EMAIL@ADDRESS>\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:`разделе "
+"документации <root_error_handling>`."
+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 ""
+

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 <EMAIL@ADDRESS>\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 ""
+

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 <EMAIL@ADDRESS>\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:`тут "
+"<root_api_orchestrator_arguments>`."
+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:`тут "
+"<root_api_orchestrator_argspace>`."
+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:`тут "
+"<root_dependency_injection>`."
+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 "
+"<root_api_orchestrator_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 ""
+

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 <EMAIL@ADDRESS>, 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 <EMAIL@ADDRESS>\n"
+"Language: en\n"
+"Language-Team: en <LL@li.org>\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:`тут "
+"<root_api_orchestrator_arguments_inputargument>`"
+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:`тут <root_dependency_injection>`."
+msgstr ""
+
+#: ../../root/api/orchestrator/argspace.rst:131
+msgid "**Запуск приложения:**"
+msgstr ""
+

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 <EMAIL@ADDRESS>\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:`тут "
+"<root_api_orchestrator_argspace>`."
+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 ""
+

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 <EMAIL@ADDRESS>\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 ""
+

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 <EMAIL@ADDRESS>\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:`соответствующем разделе <root_redirect_stdout>`"
+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 ""
+

docs/root/api/command/flags.rst

@@ -3,6 +3,7 @@
 Flags
 ======
 
+.. _root_api_command_flag:
 
 Flag
 =====

docs/root/api/command/index.rst

@@ -13,4 +13,4 @@ Command
 .. _input_command:
 
 InputCommand
-============
+~~~~~~~~~~~~

docs/root/api/orchestrator/argparser.rst

@@ -39,7 +39,7 @@ ArgParser
 
 -----
    
-Назначение и интеграция
+Лучшие практики
 ------------------------
 
 Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``,  подробнее :ref:`тут <root_dependency_injection>`.
@@ -50,3 +50,36 @@ ArgParser
 .. literalinclude:: ../../../code_snippets/argparser_snippet.py
    :language: python
    :linenos:
+   
+Обработка ошибок
+----------------
+
+.. seealso:: 
+   Про типы аргументов подробнее в :ref:`Arguments <root_api_orchestrator_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

docs/root/api/orchestrator/argspace.rst

@@ -1,4 +1,147 @@
 .. _root_api_orchestrator_argspace:
 
 ArgSpace
-==========
+==========
+
+Объект ``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:`тут <root_api_orchestrator_arguments_inputargument>`
+
+-----
+
+Примеры испольования
+--------------------
+
+``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий работы включает парсинг аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
+
+**Полный пример:**
+
+.. literalinclude:: ../../../code_snippets/argspace_snippet.py
+   :linenos:
+   
+Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, подробнее :ref:`тут <root_dependency_injection>`.
+
+.. 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

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:`тут <root_api_orchestrator_argspace>`.
+
+Представляет собой распаршенный аргумент командной строки после запуска приложения. Этот класс используется внутри объекта ``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
+
+   Возвращает техническое представление объекта в виде строки.