update docs

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(

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",

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",

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",

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",

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}")

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}")

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)

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

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)

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

docs/root/api/command/input_flag.rst

@@ -9,7 +9,7 @@ InputFlag
 
    Документация по :ref:`Flag <root_api_command_flag>` — сущность флага, регистрируемого для последующей обработки.
 
-   Документация по :ref:`ValidationStatus <root_api_validation_status>` — статусы валидации флагов.
+   Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — статусы валидации флагов.
 
 -----
 
@@ -33,6 +33,9 @@ InputFlag
 * ``input_value`` : Значение введённого флага. Может быть ``None`` если флаг не принимает значения
 * ``status`` : Статус валидации флага из перечисления ``ValidationStatus``
 
+.. warning ::
+   Экземпляры класса не предназначены для их прямого создания, они содержаться в контейнере :ref:`Response <root_api_response>`
+
 **Атрибуты:**
 
 .. py:attribute:: name

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 <root_api_command_input_flag>` — сущности входного флага, использующей ``ValidationStatus``
+   
+   Документация по :ref:`Flag <root_api_command_flag>` — сущности флага с методом валидации
+   
+   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — типам допустимых значений флагов
+
+-----
+
+Значения 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