diff --git a/docs/code_snippets/input_flag_snippet1.py b/docs/code_snippets/input_flag_snippet1.py index 8138439..9ac88fe 100644 --- a/docs/code_snippets/input_flag_snippet1.py +++ b/docs/code_snippets/input_flag_snippet1.py @@ -1,4 +1,4 @@ -from argenta import InputFlag, ValidationStatus +from argenta.command.flag import InputFlag, ValidationStatus # Создание InputFlag с полным набором параметров output_flag = InputFlag( diff --git a/docs/code_snippets/input_flag_snippet2.py b/docs/code_snippets/input_flag_snippet2.py index e0f0a6b..4890d4e 100644 --- a/docs/code_snippets/input_flag_snippet2.py +++ b/docs/code_snippets/input_flag_snippet2.py @@ -1,4 +1,4 @@ -from argenta import InputFlag, ValidationStatus +from argenta.command.flag import InputFlag, ValidationStatus flag = InputFlag( name="verbose", diff --git a/docs/code_snippets/input_flag_snippet3.py b/docs/code_snippets/input_flag_snippet3.py index 853aecc..8c894c0 100644 --- a/docs/code_snippets/input_flag_snippet3.py +++ b/docs/code_snippets/input_flag_snippet3.py @@ -1,4 +1,4 @@ -from argenta import InputFlag, ValidationStatus +from argenta.command.flag import InputFlag, ValidationStatus flag_with_value = InputFlag( name="output", diff --git a/docs/code_snippets/input_flag_snippet4.py b/docs/code_snippets/input_flag_snippet4.py index 62d7ce0..00d61ca 100644 --- a/docs/code_snippets/input_flag_snippet4.py +++ b/docs/code_snippets/input_flag_snippet4.py @@ -1,4 +1,4 @@ -from argenta import InputFlag, ValidationStatus +from argenta.command.flag import InputFlag, ValidationStatus flag = InputFlag( name="config", diff --git a/docs/code_snippets/input_flag_snippet5.py b/docs/code_snippets/input_flag_snippet5.py index 4825d3f..f37650d 100644 --- a/docs/code_snippets/input_flag_snippet5.py +++ b/docs/code_snippets/input_flag_snippet5.py @@ -1,4 +1,4 @@ -from argenta import InputFlag, ValidationStatus +from argenta.command.flag import InputFlag, ValidationStatus flag1 = InputFlag( name="debug", diff --git a/docs/code_snippets/validation_status_comprehensive_snippet6.py b/docs/code_snippets/validation_status_comprehensive_snippet6.py new file mode 100644 index 0000000..de1f36b --- /dev/null +++ b/docs/code_snippets/validation_status_comprehensive_snippet6.py @@ -0,0 +1,40 @@ +from argenta.command.flag import Flag, InputFlag, ValidationStatus, PossibleValues +import re + +# Создаём различные типы флагов +verbose_flag = Flag("verbose", possible_values=PossibleValues.NEITHER) +output_flag = Flag("output", possible_values=PossibleValues.ALL) +level_flag = Flag("level", possible_values=["1", "2", "3"]) +pattern_flag = Flag("pattern", possible_values=re.compile(r'^[a-zA-Z]+$')) + +# Создаём входные флаги с различными статусами +input_flags = [ + # Валидные флаги + InputFlag("verbose", input_value=None, status=ValidationStatus.VALID), + InputFlag("output", input_value="result.txt", status=ValidationStatus.VALID), + InputFlag("level", input_value="2", status=ValidationStatus.VALID), + InputFlag("pattern", input_value="onlyletters", status=ValidationStatus.VALID), + + # Невалидные флаги + InputFlag("verbose", input_value="true", status=ValidationStatus.INVALID), + InputFlag("level", input_value="4", status=ValidationStatus.INVALID), + InputFlag("pattern", input_value="123", status=ValidationStatus.INVALID), + + # Неопределённые флаги + InputFlag("unknown", input_value="value", status=ValidationStatus.UNDEFINED), +] + +# Обрабатываем все флаги +valid_count = invalid_count = undefined_count = 0 + +for flag in input_flags: + if flag.status == ValidationStatus.VALID: + valid_count += 1 + elif flag.status == ValidationStatus.INVALID: + invalid_count += 1 + elif flag.status == ValidationStatus.UNDEFINED: + undefined_count += 1 + +print(f"Валидных флагов: {valid_count}") +print(f"Невалидных флагов: {invalid_count}") +print(f"Неопределённых флагов: {undefined_count}") diff --git a/docs/code_snippets/validation_status_input_flag_snippet4.py b/docs/code_snippets/validation_status_input_flag_snippet4.py new file mode 100644 index 0000000..5217d1e --- /dev/null +++ b/docs/code_snippets/validation_status_input_flag_snippet4.py @@ -0,0 +1,24 @@ +from argenta import InputFlag, ValidationStatus + +# Создание входных флагов с различными статусами +valid_flag = InputFlag( + "output", + input_value="/path/to/file.txt", + status=ValidationStatus.VALID +) + +invalid_flag = InputFlag( + "count", + input_value="not-a-number", + status=ValidationStatus.INVALID +) + +undefined_flag = InputFlag( + "experimental", + input_value="test", + status=ValidationStatus.UNDEFINED +) + +flags = [valid_flag, invalid_flag, undefined_flag] +for flag in flags: + print(f"{flag.string_entity}: {flag.status.value}") diff --git a/docs/code_snippets/validation_status_invalid_snippet2.py b/docs/code_snippets/validation_status_invalid_snippet2.py new file mode 100644 index 0000000..d2eb50e --- /dev/null +++ b/docs/code_snippets/validation_status_invalid_snippet2.py @@ -0,0 +1,15 @@ +from argenta.command.flag import Flag, InputFlag, ValidationStatus, PossibleValues + +# Создание флага без значения +help_flag = Flag("help", possible_values=PossibleValues.NEITHER) + +# Создание некорректного входного флага (передано значение, когда не должно быть) +invalid_input = InputFlag("help", input_value="please", status=ValidationStatus.INVALID) + +print(f"Флаг: {invalid_input.string_entity}") +print(f"Значение: {invalid_input.input_value}") +print(f"Статус: {invalid_input.status}") # Выведет: INVALID + +# Также невалидным будет флаг с недопустимым значением из списка +mode_flag = Flag("mode", possible_values=["fast", "slow"]) +invalid_mode = InputFlag("mode", input_value="medium", status=ValidationStatus.INVALID) diff --git a/docs/code_snippets/validation_status_processing_snippet5.py b/docs/code_snippets/validation_status_processing_snippet5.py new file mode 100644 index 0000000..e71a85b --- /dev/null +++ b/docs/code_snippets/validation_status_processing_snippet5.py @@ -0,0 +1,31 @@ +from argenta import InputFlag, ValidationStatus + +def process_input_flag(input_flag: InputFlag) -> None: + """Обрабатывает входной флаг в зависимости от его статуса валидации""" + + if input_flag.status == ValidationStatus.VALID: + print(f"✓ Обрабатываем валидный флаг: {input_flag.string_entity}") + # Выполняем основную логику + execute_flag_logic(input_flag) + + elif input_flag.status == ValidationStatus.INVALID: + print(f"✗ Ошибка валидации флага: {input_flag.string_entity}") + # Записываем ошибку и прекращаем выполнение + log_validation_error(input_flag) + + elif input_flag.status == ValidationStatus.UNDEFINED: + print(f"? Неопределённый статус флага: {input_flag.string_entity}") + # Пытаемся провести валидацию или пропускаем + attempt_revalidation(input_flag) + +def execute_flag_logic(flag: InputFlag) -> None: + """Выполняет логику для валидного флага""" + pass + +def log_validation_error(flag: InputFlag) -> None: + """Записывает ошибку валидации в лог""" + pass + +def attempt_revalidation(flag: InputFlag) -> None: + """Пытается повторно провести валидацию""" + pass diff --git a/docs/code_snippets/validation_status_undefined_snippet3.py b/docs/code_snippets/validation_status_undefined_snippet3.py new file mode 100644 index 0000000..a3734fe --- /dev/null +++ b/docs/code_snippets/validation_status_undefined_snippet3.py @@ -0,0 +1,11 @@ +from argenta import InputFlag, ValidationStatus + +# Создание входного флага без определения статуса +undefined_input = InputFlag("unknown-flag", input_value="some-value", status=ValidationStatus.UNDEFINED) + +print(f"Флаг: {undefined_input.string_entity}") +print(f"Значение: {undefined_input.input_value}") +print(f"Статус: {undefined_input.status.value}") # Выведет: UNDEFINED + +# Или флаг, для которого валидация ещё не проводилась +pending_input = InputFlag("pending", input_value=None, status=ValidationStatus.UNDEFINED) diff --git a/docs/code_snippets/validation_status_valid_snippet1.py b/docs/code_snippets/validation_status_valid_snippet1.py new file mode 100644 index 0000000..4c2659a --- /dev/null +++ b/docs/code_snippets/validation_status_valid_snippet1.py @@ -0,0 +1,11 @@ +from argenta.command.flag import Flag, InputFlag, ValidationStatus + +# Создание флага, который принимает только определённые значения +log_level_flag = Flag("log-level", possible_values=["debug", "info", "warning", "error"]) + +# Создание корректного входного флага +valid_input = InputFlag("log-level", input_value="debug", status=ValidationStatus.VALID) + +print(f"Флаг: {valid_input.string_entity}") +print(f"Значение: {valid_input.input_value}") +print(f"Статус: {valid_input.status}") # Выведет: VALID diff --git a/docs/root/api/command/input_flag.rst b/docs/root/api/command/input_flag.rst index bdd7e02..c465da3 100644 --- a/docs/root/api/command/input_flag.rst +++ b/docs/root/api/command/input_flag.rst @@ -9,7 +9,7 @@ InputFlag Документация по :ref:`Flag ` — сущность флага, регистрируемого для последующей обработки. - Документация по :ref:`ValidationStatus ` — статусы валидации флагов. + Документация по :ref:`ValidationStatus ` — статусы валидации флагов. ----- @@ -33,6 +33,9 @@ InputFlag * ``input_value`` : Значение введённого флага. Может быть ``None`` если флаг не принимает значения * ``status`` : Статус валидации флага из перечисления ``ValidationStatus`` +.. warning :: + Экземпляры класса не предназначены для их прямого создания, они содержаться в контейнере :ref:`Response ` + **Атрибуты:** .. py:attribute:: name diff --git a/docs/root/api/command/validation_status.rst b/docs/root/api/command/validation_status.rst index 0dda45f..878da57 100644 --- a/docs/root/api/command/validation_status.rst +++ b/docs/root/api/command/validation_status.rst @@ -1,6 +1,109 @@ .. _root_api_command_validation_status: ValidationStatus -**************** +================ + +Enum ``ValidationStatus`` представляет собой перечисление, определяющее состояние валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для отображения результата проверки введённых пользователем флагов и их значений. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag`` для информирования о том, прошёл ли флаг валидацию успешно. + +``ValidationStatus`` наследуется от стандартного класса ``Enum`` и содержит три основных значения: ``VALID`` для корректных флагов, ``INVALID`` для некорректных флагов и ``UNDEFINED`` для незарегистрированных флагов. + +.. note:: + + Статус валидации устанавливается автоматически при создании экземпляра ``InputFlag`` на основе проверки через соответствующий ``Flag``. + +.. seealso:: + + Документация по :ref:`InputFlag ` — сущности входного флага, использующей ``ValidationStatus`` + + Документация по :ref:`Flag ` — сущности флага с методом валидации + + Документация по :ref:`PossibleValues ` — типам допустимых значений флагов + +----- + +Значения enum +------------- + +VALID +~~~~~ + +.. code-block:: python + :linenos: + + ValidationStatus.VALID = 'VALID' + +Указывает, что флаг и его значение **прошли** валидацию успешно. + +Флаги с этим статусом полностью соответствуют правилам, заданным в параметре ``possible_values`` соответствующего ``Flag``. Такие флаги могут быть безопасно использованы в логике приложения без дополнительных проверок. + +**Условия получения статуса** ``VALID``: + +* Флаг с ``PossibleValues.NEITHER`` передан без значения +* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него +* Флаг со списком значений передан с одним из допустимых значений +* Флаг с регулярным выражением передан со значением, соответствующим паттерну + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/validation_status_valid_snippet1.py + :linenos: + :language: python + +----- + +INVALID +~~~~~~~ + +.. code-block:: python + :linenos: + + ValidationStatus.INVALID = 'INVALID' + +Указывает, что флаг или его значение **не прошли** валидацию. + +Флаги с этим статусом нарушают правила, установленные в ``possible_values`` соответствующего ``Flag``. Такие флаги должны быть обработаны как ошибочные, и их использование может привести к некорректной работе приложения. + +**Условия получения статуса** ``INVALID``: + +* Флаг с ``PossibleValues.NEITHER`` передан со значением +* Флаг со списком значений передан с недопустимым значением +* Флаг с регулярным выражением передан со значением, не соответствующим паттерну +* Флаг требует значение, но передан без него (для определённых типов валидации) + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/validation_status_invalid_snippet2.py + :linenos: + :language: python + +----- + +UNDEFINED +~~~~~~~~~ + +.. code-block:: python + :linenos: + + ValidationStatus.UNDEFINED = 'UNDEFINED' + +Указывает, что флаг был введён, но не зарегистрирован. + +**Условия получения статуса** ``UNDEFINED``: + +* Флаг был введён с любым значением, но не зарегистрирован + +----- + + +Практические примеры +-------------------- + +Комплексный пример валидации +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Пример демонстрирует использование всех статусов в реальном сценарии: + +.. literalinclude:: ../../../code_snippets/validation_status_comprehensive_snippet6.py + :linenos: + :language: python -case