Update documentation and code snippets

README.md

@@ -35,7 +35,7 @@ Argenta is ready for the demands of building scalable, robust and maintainable C
 
 -   **Interactive Sessions**: Unlike traditional CLI tools, ``Argenta`` creates cyclic sessions, allowing users to execute commands sequentially without restarting the application.
 -   **Declarative Syntax**: Commands and their handlers are declared using simple decorators, making the code intuitive and allowing you to focus on "what" you want to do, not "how".
--   **Native DI**: Thanks to integration with `dishka <https://dishka.readthedocs.io/en/stable/>`_, you can easily inject dependencies directly into command handlers, simplifying testing, avoiding mutable globals, and much more.
+-   **Native DI**: Thanks to integration with [dishka](https://dishka.readthedocs.io/en/stable/), you can easily inject dependencies directly into command handlers, simplifying testing, avoiding mutable globals, and much more.
 -   **Automatic Validation and Parsing**: The library handles command-line flags and arguments processing, including parsing, validation, and type conversion.
 -   **Flexible Configuration**: You can easily customize system messages, output formatting, create custom handlers for non-standard behavior, and more.
 

README.ru.md

@@ -35,7 +35,7 @@ Argenta готова к требованиям создания масштаби
 
 -   **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение.
 -   **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код интуитивно понятным и позволяет сосредоточиться на том, "что" вы хотите сделать, а не "как".
--   **Нативный DI**: Благодаря интеграции с `dishka <https://dishka.readthedocs.io/en/stable/>`_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование, позволяет избежать мутабельных глобалов и многое другое.
+-   **Нативный DI**: Благодаря интеграции с [dishka](https://dishka.readthedocs.io/en/stable/), вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование, позволяет избежать мутабельных глобалов и многое другое.
 -   **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов.
 -   **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода, ссоздавать кастомные обработчики нестандартного поведения и т.д.
 

docs/root/api/app/index.rst

@@ -83,7 +83,7 @@ App
 ``App`` позволяет настраивать реакцию на различные события, такие как ошибки ввода или неизвестные команды.
 
 .. hint::
-   Подробнее о исключениях и их обработке в соответствующем :ref:`разделе документации <root_error_handling>`.
+   Подробнее об исключениях и их обработке в соответствующем :ref:`разделе документации <root_error_handling>`.
    
 -----
 
@@ -148,7 +148,7 @@ PredefinedMessages
 
 ``PredefinedMessages`` — это контейнер, содержащий набор готовых к использованию сообщений. Они отформатированы с использованием синтаксиса ``rich`` и предназначены для вывода стандартной информации, такой как подсказки по использованию.
 
-Реккомендуется использовать их при старте приложения.
+Рекомендуется использовать их при старте приложения.
 
 .. code-block:: python
    :linenos:

docs/root/api/command/index.rst

@@ -51,7 +51,7 @@ Command
    :linenos:
    
 .. seealso ::
-   Подробнее про флаги: :ref:`Flags <root_api_command_flags>` и :ref:`Флаги вводимых команд <root_flags>`.
+   Подробнее про флаги: :ref:`Flags <root_api_command_flags>` и :ref:`Флаги команд <root_flags>`.
 
 -----
 

docs/root/dependency_injection.rst

@@ -55,7 +55,7 @@
 Встроенные провайдеры
 -----------------------
 
-``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект ``ArgSpace``, который содержит аргументы командной строки, переданные при запуске приложения.
+``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект :ref:`ArgSpace <root_api_orchestrator_argspace>`, который содержит аргументы командной строки, переданные при запуске приложения.
 
 **Пример использования:**
 

docs/root/flags.rst

@@ -73,12 +73,9 @@
 Флаги против аргументов
 -----------------------
 
-В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия.
+В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением.
 
-Определение и назначение
+**Аргументы** — это параметры, передаваемые при запуске приложения. Они определяют глобальную конфигурацию на протяжении всей его работы (например, адрес базы данных, уровень логирования).
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-**Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы.
 
 .. seealso:: API и более подробное описание в разделах :ref:`ArgParser <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.
 
@@ -91,34 +88,28 @@
 Ключевые различия
 ~~~~~~~~~~~~~~~~~
 
-**Время жизни и область действия**
+**Время жизни**
-  Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
+  Аргументы передаются один раз при запуске и действуют на весь период работы приложения. Флаги локальны и существуют только в рамках выполнения команды.
 
-**Частота изменения**
+**Изменяемость**
-  Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения.
+  Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять при каждом вводе команды.
 
-**Уровень конфигурации**
+**Назначение**
-  Аргументы управляют глобальной конфигурацией приложения и его окружением. Флаги управляют поведением отдельных команд и операций пользователя.
+  Аргументы управляют глобальной конфигурацией приложения. Флаги управляют поведением отдельных команд.
-
-**Использование**
-  Аргументы задают начальное состояние системы: что подключить, как работать. Флаги управляют тактикой выполнения команд: как её выполнить, с какими изменениями.
 
 -----
   
-Практические примеры в Argenta
+Практические примеры
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
-При запуске приложения Argenta передаются аргументы:
+Аргументы при запуске приложения:
 
 - Адрес подключения к базе данных
 - Режим работы (production, development, testing)
 - Уровень логирования
-- Путь к конфигурационным файлам
 
-В интерактивной сессии для каждой команды указываются флаги:
+Флаги в интерактивной сессии:
 
-- ``deploy --verbose --dry-run`` — для текущей команды развёртывания
+- ``deploy --verbose --dry-run`` — для команды развёртывания
 - ``backup --compress --encrypted`` — для команды резервного копирования
 - ``test --parallel --coverage`` — для команды тестирования
-
-Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами.

docs/root/overriding_formatting.rst

@@ -12,7 +12,7 @@
 
 При создании экземпляра ``App`` можно использовать параметр ``override_system_messages: bool`` (по умолчанию ``False``), который позволяет отключать стандартное форматирование.
 
-Если установить его в ``True``, стилизация текста и ASCII-арт будут отключены, а системные сообщения — выводиться в «сыром» виде.
+Если установить его в ``True``, стилизация текста и ASCII-графика будут отключены, а системные сообщения — выводиться в «сыром» виде.
 
 -----
 

docs/root/quickstart.rst

@@ -5,8 +5,8 @@
 
 В этом руководстве мы рассмотрим два примера создания CLI-приложения с помощью Argenta:
 
-*   **Простой пример**: Минимальное приложение, быстрое знакомство с основными компонентами.
+*   **Простой пример**: минимальное приложение для быстрого знакомства с основными компонентами.
-*   **Более сложный пример**: Полнофункциональное приложение «Менеджер задач» с внедрением зависимостей и бизнес-логикой.
+*   **Более сложный пример**: полнофункциональное приложение «Менеджер задач» с внедрением зависимостей и бизнес-логикой.
 
 Простой пример
 ---------------

docs/root/redirect_stdout.rst

@@ -17,7 +17,7 @@
 .. image:: https://i.ibb.co/yn9rWnNC/2025-11-07-180751.png
   :alt: Example of an application with a dynamic dividing line
 
-Как вы можете заметить разделительная линия ровно той же длины, что и самая длинная строка в выводе.
+Как вы можете заметить, разделительная линия ровно той же длины, что и самая длинная строка в выводе.
 
 То же приложение с статической линией:
 

docs/root/testing.rst

@@ -48,7 +48,9 @@ E2E-тестирование цикла
 Полный запуск цикла ``start_polling`` можно покрывать через подпроцесс с передачей строк в ``stdin``. Это тяжелее и обычно не требуется. Если всё же необходимо — пример ниже.
 
 .. danger::
-    Обязательно передавайте строковый триггер команды выхода последним элементом в списке, который передаёте в контекстном менеджере при патче ``input`` как аргумент ``side_effects``, иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться.
+    **Важно:** Обязательно передавайте строковый триггер команды выхода последним элементом в списке ``side_effects`` при патче ``input``.
+    
+    Иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться.
 
 **Пример использования:**
 

imgs/argenta_logo_strip.svg

@@ -1,46 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
- "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
-<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
- width="809.000000pt" height="809.000000pt" viewBox="0 0 809.000000 809.000000"
- preserveAspectRatio="xMidYMid meet">
-
-<g transform="translate(0.000000,809.000000) scale(0.100000,-0.100000)"
-fill="#000000" stroke="none">
-<path d="M3845 7600 c-683 -38 -1333 -259 -1875 -639 -702 -492 -1223 -1251
--1434 -2089 -83 -330 -111 -602 -103 -980 6 -273 19 -393 67 -632 167 -829
-642 -1593 1321 -2122 512 -399 1133 -656 1794 -745 165 -22 666 -25 825 -5
-779 99 1451 397 2020 898 687 603 1095 1401 1201 2344 17 147 17 571 0 715
--59 518 -204 977 -442 1402 -180 322 -355 552 -629 823 -518 515 -1164 850
--1887 979 -254 45 -594 66 -858 51z m655 -234 c545 -76 1005 -248 1445 -541
-195 -130 336 -245 506 -415 457 -456 758 -987 909 -1605 134 -547 132 -1119
--5 -1665 -149 -593 -445 -1112 -885 -1550 -624 -623 -1414 -966 -2315 -1006
--412 -18 -935 73 -1339 232 -656 259 -1228 720 -1610 1299 -298 450 -461 890
--538 1451 -28 210 -31 620 -4 819 103 786 437 1477 975 2016 149 149 266 249
-417 357 315 225 692 405 1059 506 211 58 342 81 675 120 87 10 601 -3 710 -18z"/>
-<path d="M3691 6759 c-231 -17 -522 -67 -660 -114 -227 -77 -354 -211 -381
--400 -14 -105 -13 -628 2 -643 9 -9 158 -12 611 -12 598 0 628 -2 649 -34 14
--21 8 -66 -12 -86 -20 -20 -33 -20 -908 -20 -857 0 -892 -1 -967 -20 -294 -75
--500 -321 -599 -715 -49 -195 -61 -309 -60 -585 0 -221 3 -272 23 -385 44
--251 116 -418 232 -540 78 -82 143 -123 254 -162 78 -27 85 -27 351 -31 l272
--4 16 23 c14 20 16 58 16 259 0 334 20 446 107 613 80 153 268 310 447 374
-128 45 138 46 881 52 683 7 713 8 786 28 201 56 353 177 437 348 80 162 86
-240 74 905 -11 608 -10 600 -84 743 -80 153 -240 271 -453 332 -252 73 -653
-101 -1034 74z m-383 -466 c126 -78 147 -245 44 -355 -144 -154 -396 -54 -395
-157 0 97 62 187 154 222 54 20 143 10 197 -24z"/>
-<path d="M5451 5491 c-20 -20 -21 -30 -21 -283 0 -276 -7 -351 -42 -458 -81
--251 -281 -454 -523 -534 -149 -48 -151 -48 -890 -56 -678 -6 -703 -7 -780
--28 -139 -38 -219 -84 -315 -181 -61 -61 -95 -105 -117 -151 -65 -134 -64
--129 -75 -780 -12 -665 -10 -694 47 -817 122 -265 419 -429 895 -494 127 -18
-592 -18 730 -1 377 48 646 169 785 355 57 75 67 94 96 182 20 64 23 94 27 325
-4 238 3 257 -15 278 l-18 23 -551 -1 c-399 0 -559 3 -577 11 -51 23 -56 102
--8 126 9 4 439 10 956 13 1044 7 981 2 1125 75 178 89 305 255 386 502 84 257
-111 618 73 973 -39 364 -167 655 -351 801 -63 50 -121 80 -213 110 -64 20 -93
-23 -337 27 -260 4 -267 3 -287 -17z m-2104 -1698 c78 -52 531 -413 561 -447
-17 -19 33 -48 37 -65 15 -71 3 -84 -323 -356 -275 -229 -310 -255 -342 -255
--78 1 -112 75 -61 134 9 10 86 75 171 144 247 201 355 294 358 311 1 9 -15 28
--38 44 -127 89 -503 393 -512 413 -23 50 20 103 82 104 15 0 45 -12 67 -27z
-m1388 -1244 c59 -15 129 -77 151 -134 36 -96 0 -204 -88 -262 -36 -24 -51 -28
--118 -28 -67 0 -82 4 -118 28 -153 101 -124 338 48 392 57 17 71 18 125 4z"/>
-</g>
-</svg>

src/argenta/command/flag/models.py

@@ -50,8 +50,11 @@ class Flag:
         if isinstance(self.possible_values, Pattern):
             return isinstance(input_flag_value, str) and bool(self.possible_values.match(input_flag_value))
 
+        if isinstance(self.possible_values, list):
             return input_flag_value in self.possible_values
             
+        return False
+
     @property
     def string_entity(self) -> str:
         """

src/argenta/command/models.py

@@ -39,7 +39,7 @@ class Command:
         self.registered_flags: Flags = flags if isinstance(flags, Flags) else Flags([flags])
         self.trigger: str = trigger
         self.description: str = description
-        self.aliases: list[str] = aliases
+        self.aliases: list[str] | list[Never] = aliases
 
     def validate_input_flag(self, flag: InputFlag) -> ValidationStatus:
         """

src/argenta/orchestrator/argparser/entity.py

@@ -48,7 +48,7 @@ class ArgSpace:
 
         return cls(parsed_arguments)
         
-    def _setup_getters(self):
+    def _setup_getters(self) -> None:
         if not self.all_arguments:
             return
         for input_arg in self.all_arguments: