diff --git a/README.md b/README.md index ea8c8d1..9120eba 100644 --- a/README.md +++ b/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 `_, 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. diff --git a/README.ru.md b/README.ru.md index 3e5fb35..a16fe30 100644 --- a/README.ru.md +++ b/README.ru.md @@ -35,7 +35,7 @@ Argenta готова к требованиям создания масштаби - **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение. - **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код интуитивно понятным и позволяет сосредоточиться на том, "что" вы хотите сделать, а не "как". -- **Нативный DI**: Благодаря интеграции с `dishka `_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование, позволяет избежать мутабельных глобалов и многое другое. +- **Нативный DI**: Благодаря интеграции с [dishka](https://dishka.readthedocs.io/en/stable/), вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование, позволяет избежать мутабельных глобалов и многое другое. - **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов. - **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода, ссоздавать кастомные обработчики нестандартного поведения и т.д. diff --git a/docs/root/api/app/index.rst b/docs/root/api/app/index.rst index 638ee66..1fa883d 100644 --- a/docs/root/api/app/index.rst +++ b/docs/root/api/app/index.rst @@ -83,7 +83,7 @@ App ``App`` позволяет настраивать реакцию на различные события, такие как ошибки ввода или неизвестные команды. .. hint:: - Подробнее о исключениях и их обработке в соответствующем :ref:`разделе документации `. + Подробнее об исключениях и их обработке в соответствующем :ref:`разделе документации `. ----- @@ -148,7 +148,7 @@ PredefinedMessages ``PredefinedMessages`` — это контейнер, содержащий набор готовых к использованию сообщений. Они отформатированы с использованием синтаксиса ``rich`` и предназначены для вывода стандартной информации, такой как подсказки по использованию. -Реккомендуется использовать их при старте приложения. +Рекомендуется использовать их при старте приложения. .. code-block:: python :linenos: diff --git a/docs/root/api/command/index.rst b/docs/root/api/command/index.rst index 0f44996..f3afcdf 100644 --- a/docs/root/api/command/index.rst +++ b/docs/root/api/command/index.rst @@ -51,7 +51,7 @@ Command :linenos: .. seealso :: - Подробнее про флаги: :ref:`Flags ` и :ref:`Флаги вводимых команд `. + Подробнее про флаги: :ref:`Flags ` и :ref:`Флаги команд `. ----- diff --git a/docs/root/api/response.rst b/docs/root/api/response.rst index fd2ac27..3979c15 100644 --- a/docs/root/api/response.rst +++ b/docs/root/api/response.rst @@ -32,7 +32,7 @@ Response * ``status``: Общий статус валидации флагов из перечисления ``ResponseStatus``. * ``input_flags``: Коллекция введённых флагов (``InputFlags``). По умолчанию — пустая. -.. warning :: +.. warning:: Экземпляры этого класса не предназначены для прямого создания. Они автоматически формируются системой и передаются в обработчик команды в качестве первого обязательного аргумента. **Атрибуты:** diff --git a/docs/root/dependency_injection.rst b/docs/root/dependency_injection.rst index 3cd1416..ae200d8 100644 --- a/docs/root/dependency_injection.rst +++ b/docs/root/dependency_injection.rst @@ -55,7 +55,7 @@ Встроенные провайдеры ----------------------- -``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект ``ArgSpace``, который содержит аргументы командной строки, переданные при запуске приложения. +``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект :ref:`ArgSpace `, который содержит аргументы командной строки, переданные при запуске приложения. **Пример использования:** diff --git a/docs/root/flags.rst b/docs/root/flags.rst index de9d04f..db2efb9 100644 --- a/docs/root/flags.rst +++ b/docs/root/flags.rst @@ -73,12 +73,9 @@ Флаги против аргументов ----------------------- -В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия. +В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением. -Определение и назначение -~~~~~~~~~~~~~~~~~~~~~~~~ - -**Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы. +**Аргументы** — это параметры, передаваемые при запуске приложения. Они определяют глобальную конфигурацию на протяжении всей его работы (например, адрес базы данных, уровень логирования). .. seealso:: API и более подробное описание в разделах :ref:`ArgParser ` и :ref:`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`` — для команды тестирования - -Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами. diff --git a/docs/root/overriding_formatting.rst b/docs/root/overriding_formatting.rst index 04377a6..1d279af 100644 --- a/docs/root/overriding_formatting.rst +++ b/docs/root/overriding_formatting.rst @@ -12,7 +12,7 @@ При создании экземпляра ``App`` можно использовать параметр ``override_system_messages: bool`` (по умолчанию ``False``), который позволяет отключать стандартное форматирование. -Если установить его в ``True``, стилизация текста и ASCII-арт будут отключены, а системные сообщения — выводиться в «сыром» виде. +Если установить его в ``True``, стилизация текста и ASCII-графика будут отключены, а системные сообщения — выводиться в «сыром» виде. ----- diff --git a/docs/root/quickstart.rst b/docs/root/quickstart.rst index eade7c1..92eef94 100644 --- a/docs/root/quickstart.rst +++ b/docs/root/quickstart.rst @@ -5,8 +5,8 @@ В этом руководстве мы рассмотрим два примера создания CLI-приложения с помощью Argenta: -* **Простой пример**: Минимальное приложение, быстрое знакомство с основными компонентами. -* **Более сложный пример**: Полнофункциональное приложение «Менеджер задач» с внедрением зависимостей и бизнес-логикой. +* **Простой пример**: минимальное приложение для быстрого знакомства с основными компонентами. +* **Более сложный пример**: полнофункциональное приложение «Менеджер задач» с внедрением зависимостей и бизнес-логикой. Простой пример --------------- diff --git a/docs/root/redirect_stdout.rst b/docs/root/redirect_stdout.rst index 23c7d5b..555bb56 100644 --- a/docs/root/redirect_stdout.rst +++ b/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 -Как вы можете заметить разделительная линия ровно той же длины, что и самая длинная строка в выводе. +Как вы можете заметить, разделительная линия ровно той же длины, что и самая длинная строка в выводе. То же приложение с статической линией: diff --git a/docs/root/testing.rst b/docs/root/testing.rst index 22e7b29..f5a5be6 100644 --- a/docs/root/testing.rst +++ b/docs/root/testing.rst @@ -48,7 +48,9 @@ E2E-тестирование цикла Полный запуск цикла ``start_polling`` можно покрывать через подпроцесс с передачей строк в ``stdin``. Это тяжелее и обычно не требуется. Если всё же необходимо — пример ниже. .. danger:: - Обязательно передавайте строковый триггер команды выхода последним элементом в списке, который передаёте в контекстном менеджере при патче ``input`` как аргумент ``side_effects``, иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться. + **Важно:** Обязательно передавайте строковый триггер команды выхода последним элементом в списке ``side_effects`` при патче ``input``. + + Иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться. **Пример использования:** diff --git a/imgs/argenta_banner.png b/imgs/argenta_banner.png deleted file mode 100644 index 297aded..0000000 Binary files a/imgs/argenta_banner.png and /dev/null differ diff --git a/imgs/argenta_logo.png b/imgs/argenta_logo.png deleted file mode 100644 index c99e421..0000000 Binary files a/imgs/argenta_logo.png and /dev/null differ diff --git a/imgs/argenta_logo_strip.png b/imgs/argenta_logo_strip.png deleted file mode 100644 index ce2f6b2..0000000 Binary files a/imgs/argenta_logo_strip.png and /dev/null differ diff --git a/imgs/argenta_logo_strip.svg b/imgs/argenta_logo_strip.svg deleted file mode 100644 index 19a1a0a..0000000 --- a/imgs/argenta_logo_strip.svg +++ /dev/null @@ -1,46 +0,0 @@ - - - - - - - - - - diff --git a/imgs/mock_app_preview1.png b/imgs/mock_app_preview1.png deleted file mode 100644 index 1be0ae7..0000000 Binary files a/imgs/mock_app_preview1.png and /dev/null differ diff --git a/imgs/mock_app_preview2.png b/imgs/mock_app_preview2.png deleted file mode 100644 index c74ec2b..0000000 Binary files a/imgs/mock_app_preview2.png and /dev/null differ diff --git a/imgs/mock_app_preview3.png b/imgs/mock_app_preview3.png deleted file mode 100644 index c8a9fc3..0000000 Binary files a/imgs/mock_app_preview3.png and /dev/null differ diff --git a/imgs/mock_app_preview4.png b/imgs/mock_app_preview4.png deleted file mode 100644 index 15ffda1..0000000 Binary files a/imgs/mock_app_preview4.png and /dev/null differ diff --git a/imgs/mock_app_preview6.png b/imgs/mock_app_preview6.png deleted file mode 100644 index 2a00c4b..0000000 Binary files a/imgs/mock_app_preview6.png and /dev/null differ diff --git a/src/argenta/command/flag/models.py b/src/argenta/command/flag/models.py index ba4227c..f4816fd 100644 --- a/src/argenta/command/flag/models.py +++ b/src/argenta/command/flag/models.py @@ -50,7 +50,10 @@ class Flag: if isinstance(self.possible_values, Pattern): return isinstance(input_flag_value, str) and bool(self.possible_values.match(input_flag_value)) - return input_flag_value in self.possible_values + if isinstance(self.possible_values, list): + return input_flag_value in self.possible_values + + return False @property def string_entity(self) -> str: diff --git a/src/argenta/command/models.py b/src/argenta/command/models.py index b0b684a..19f7adc 100644 --- a/src/argenta/command/models.py +++ b/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: """ diff --git a/src/argenta/orchestrator/argparser/entity.py b/src/argenta/orchestrator/argparser/entity.py index d67861a..f7c79cb 100644 --- a/src/argenta/orchestrator/argparser/entity.py +++ b/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: