Update documentation and code snippets

docs/code_snippets/flags/snippet.py

@@ -1,17 +1,11 @@
 import re
+from argenta.command import Command, Flag, Flags
 
-from argenta import Command
-from argenta.command import Flag, Flags
-
-# Создание коллекции с флагами
 flags = Flags(
     [
-        Flag(
-            "host", possible_values=re.compile(r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")
-        ),
+        Flag("host", possible_values=re.compile(r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")),
         Flag("port", possible_values=re.compile(r"^\d{1,5}$")),
     ]
 )
 
-# Использование в команде
 cmd = Command("start", description="Start the server", flags=flags)

docs/code_snippets/flags/snippet2.py

@@ -1,11 +1,9 @@
 from argenta.command import Flag, Flags
 
-# Создание коллекции
 flags: Flags = Flags()
 
-# Динамическое добавление флагов
 flags.add_flag(Flag("config"))
 flags.add_flag(Flag("debug"))
 flags.add_flag(Flag("log-level", possible_values=["INFO", "DEBUG", "ERROR"]))
 
-print(len(flags.flags))  # 3
+print(len(flags))  # 3

docs/code_snippets/flags/snippet3.py

@@ -1,10 +1,8 @@
 from argenta.command import Flag, Flags
 from argenta.command.flag.defaults import PredefinedFlags
 
-# Начальная коллекция
 flags = Flags([PredefinedFlags.HOST])
 
-# Дополнительные флаги
 additional_flags = [
     PredefinedFlags.PORT,
     Flag("database"),
@@ -12,7 +10,6 @@ additional_flags = [
     Flag("verbose"),
 ]
 
-# Добавление списка флагов
 flags.add_flags(additional_flags)
 
-print(len(flags.flags))  # 5
+print(len(flags))  # 5

docs/code_snippets/flags/snippet4.py

@@ -1,14 +1,13 @@
 from argenta.command import Flag, Flags
 from argenta.command.flag.defaults import PredefinedFlags
 
+
 flags = Flags([PredefinedFlags.HOST, PredefinedFlags.PORT, Flag("verbose")])
 
-# Получение флага по имени
 host_flag = flags.get_flag_by_name("host")
 if host_flag:
     print(f"Found flag: {host_flag.name}")
 
-# Поиск несуществующего флага
 unknown_flag = flags.get_flag_by_name("nonexistent")
 if unknown_flag is None:
     print("Flag not found")

docs/code_snippets/flags/snippet5.py

@@ -1,12 +0,0 @@
-from argenta.command import Flag, Flags
-from argenta.command.flag.defaults import PredefinedFlags
-
-flags = Flags([PredefinedFlags.HOST, PredefinedFlags.PORT, Flag("verbose")])
-
-# Итерация по всем флагам
-for flag in flags:
-    print(f"Flag: {flag.name} (type: {type(flag).__name__})")
-
-# Использование в list comprehension
-flag_names = [flag.name for flag in flags]
-print(f"All flags: {flag_names}")

docs/code_snippets/flags/snippet6.py

@@ -1,12 +0,0 @@
-from argenta.command import Flag, Flags
-
-flags = Flags([Flag("first"), Flag("second"), Flag("third")])
-
-print(flags[0].name)
-# first
-
-print(flags[1].name)
-# second
-
-print(flags[2].name)
-# third

docs/code_snippets/input_flags/snippet1.py

@@ -1,22 +1,23 @@
 from argenta import Command, Response, Router
 from argenta.command import Flag, Flags
 
-router = Router(title="Example")
 
+router = Router(title="Example")
 
 @router.command(
     Command(
         "example",
         description="Example command with flags",
-        flags=Flags([Flag("name"), Flag("age")]),
+        flags=Flags([
+            Flag("name"), 
+            Flag("age")
+        ]),
     )
 )
 def example_handler(response: Response):
-    # response.input_flags содержит коллекцию InputFlags
     input_flags = response.input_flags
 
-    # Проверяем наличие флагов
     if input_flags:
-        print(f"Received {len(input_flags.flags)} flag(s)")
+        print(f"Received {len(input_flags)} flag(s)")
     else:
         print("No flags provided")

docs/code_snippets/input_flags/snippet10.py

@@ -1,5 +1,5 @@
 from argenta import Command, Response, Router
-from argenta.command import Flag, Flags
+from argenta.command import Flag, Flags, InputFlag
 from argenta.command.flag import ValidationStatus
 
 router = Router(title="Comprehensive Example")
@@ -21,12 +21,11 @@ router = Router(title="Comprehensive Example")
 def validate_handler(response: Response):
     input_flags = response.input_flags
 
-    # Итерируемся по всем флагам и проверяем их статусы
     print("Flag validation results:")
 
-    valid_flags = []
-    invalid_flags = []
-    undefined_flags = []
+    valid_flags: list[InputFlag] = []
+    invalid_flags: list[InputFlag] = []
+    undefined_flags: list[InputFlag] = []
 
     for flag in input_flags:
         if flag.status == ValidationStatus.VALID:
@@ -39,13 +38,11 @@ def validate_handler(response: Response):
             undefined_flags.append(flag)
             print(f"  ? {flag.string_entity}: {flag.input_value} (UNDEFINED)")
 
-    # Выводим сводку
     print("\nSummary:")
     print(f"  Valid flags: {len(valid_flags)}")
     print(f"  Invalid flags: {len(invalid_flags)}")
     print(f"  Undefined flags: {len(undefined_flags)}")
 
-    # Обрабатываем только валидные флаги
     if valid_flags:
         print("\nProcessing valid flags:")
         for flag in valid_flags:

docs/code_snippets/input_flags/snippet2.py

@@ -8,13 +8,16 @@ router = Router(title="Get Flag Example")
     Command(
         "config",
         description="Configure settings",
-        flags=Flags([Flag("host"), Flag("port"), Flag("debug")]),
+        flags=Flags([
+            Flag("host"), 
+            Flag("port"),
+            Flag("debug")
+        ]),
     )
 )
 def config_handler(response: Response):
     input_flags = response.input_flags
 
-    # Получаем флаг по имени
     host_flag = input_flags.get_flag_by_name("host")
     port_flag = input_flags.get_flag_by_name("port")
     debug_flag = input_flags.get_flag_by_name("debug")
@@ -28,7 +31,6 @@ def config_handler(response: Response):
     if debug_flag:
         print("Debug mode enabled")
 
-    # Если флаг не найден, get_flag_by_name вернёт None
     missing_flag = input_flags.get_flag_by_name("nonexistent")
     if missing_flag is None:
         print("Flag 'nonexistent' not found")

docs/code_snippets/input_flags/snippet5.py

@@ -1,26 +0,0 @@
-from argenta import Command, Response, Router
-from argenta.command import Flag, Flags
-
-router = Router(title="Iterate Example")
-
-
-@router.command(
-    Command(
-        "process",
-        description="Process with multiple flags",
-        flags=Flags([Flag("file"), Flag("format"), Flag("output")]),
-    )
-)
-def process_handler(response: Response):
-    input_flags = response.input_flags
-
-    # Итерируемся по всем введённым флагам
-    print("All flags:")
-    for flag in input_flags:
-        status_str = flag.status.name if flag.status else "None"
-        print(f"  {flag.string_entity}: {flag.input_value} (status: {status_str})")
-
-    # Также можно использовать enumerate для получения индексов
-    print("\nFlags with indices:")
-    for index, flag in enumerate(input_flags):
-        print(f"  [{index}] {flag.name}: {flag.input_value}")

docs/code_snippets/input_flags/snippet6.py

@@ -1,29 +0,0 @@
-from argenta import Command, Response, Router
-from argenta.command import Flag, Flags
-
-router = Router(title="Index Access Example")
-
-
-@router.command(
-    Command(
-        "example",
-        description="Example with indexed access",
-        flags=Flags([Flag("first"), Flag("second"), Flag("third")]),
-    )
-)
-def example_handler(response: Response):
-    input_flags = response.input_flags
-
-    # Получаем флаги по индексу
-    if len(input_flags.flags) > 0:
-        first_flag = input_flags[0]
-        print(f"First flag: {first_flag.name} = {first_flag.input_value}")
-
-    if len(input_flags.flags) > 1:
-        second_flag = input_flags[1]
-        print(f"Second flag: {second_flag.name} = {second_flag.input_value}")
-
-    # Можно использовать срез для получения нескольких флагов
-    if len(input_flags.flags) >= 2:
-        first_two = input_flags.flags[:2]
-        print(f"First two flags: {[f.name for f in first_two]}")

docs/code_snippets/response/data_sharing.py

@@ -2,44 +2,32 @@ from argenta import Router, Response, Command, DataBridge
 from argenta.command import Flag
 from argenta.di import FromDishka
 
-# 1. Создаём роутер
 router = Router(title="Authentication")
 
-
-# 2. Определяем сервис и обработчики
 def authenticate_user(username: str) -> str:
-    """Возвращает фиктивный токен для пользователя."""
     return f"token_for_{username}"
 
 
 @router.command(Command("login", flags=Flag("username")))
 def login_handler(response: Response, data_bridge: FromDishka[DataBridge]):
-    """Обработчик для команды 'login'. Сохраняет токен в хранилище."""
     username_flag = response.input_flags.get_flag_by_name("username")
     if not username_flag or not username_flag.input_value:
-        print(
-            "[red]Ошибка:[/red] необходимо указать имя пользователя с помощью флага --username."
-        )
+        print("Ошибка необходимо указать имя пользователя с помощью флага --username.")
         return
 
     username = username_flag.input_value
     token = authenticate_user(username)
 
-    # Сохраняем токен в общем хранилище сессии
     data_bridge.update({"auth_token": token})
-    print(f"[green]Успешный вход![/green] Пользователь '{username}' аутентифицирован.")
+    print(f"Успешный вход! Пользователь '{username}' аутентифицирован.")
 
 
 @router.command("get-profile")
-def get_profile_handler(response: Response, data_bridge: FromDishka[DataBridge]):
-    """Обработчик для команды 'get-profile'. Использует токен из хранилища."""
-    session_data = data_bridge.get_all()
-    token = session_data.get("auth_token")
+def get_profile_handler(response: Response, data_bridge: FromDishka[DataBridge])
+    token = data_bridge.get_by_key("auth_token")
 
     if not token:
-        print(
-            "[red]Ошибка:[/red] вы не аутентифицированы. Сначала выполните команду 'login'."
-        )
+        print("Ошибка: вы не аутентифицированы. Сначала выполните команду 'login'.")
         return
 
     print(f"Загрузка профиля с использованием токена: [yellow]{token}[/yellow]")
@@ -47,9 +35,8 @@ def get_profile_handler(response: Response, data_bridge: FromDishka[DataBridge])
 
 @router.command("logout")
 def logout_handler(response: Response, data_bridge: FromDishka[DataBridge]):
-    """Обработчик для команды 'logout'. Очищает токен."""
     try:
         data_bridge.delete_by_key("auth_token")
-        print("[green]Выход выполнен.[/green] Данные сессии очищены.")
+        print("Выход выполнен. Данные сессии очищены.")
     except KeyError:
         print("Вы и так не были аутентифицированы.")

docs/code_snippets/response/snippet1.py

@@ -6,10 +6,6 @@ router = Router(title="Example")
 
 @router.command(Command("greet", description="Greet the user"))
 def greet_handler(response: Response):
-    # response автоматически передаётся в обработчик
-    # response.status содержит статус валидации флагов
-    # response.input_flags содержит все введённые флаги
-
     if response.status == ResponseStatus.ALL_FLAGS_VALID:
         print("Hello! All flags are valid.")
     else:

docs/code_snippets/response/snippet6.py

@@ -1,5 +1,6 @@
 from argenta import Command, Response, Router
 from argenta.command import Flag, Flags
+from argenta.command.flag import ValidationStatus
 from argenta.response import ResponseStatus
 
 router = Router(title="Flags Example")
@@ -9,14 +10,15 @@ router = Router(title="Flags Example")
     Command(
         "process",
         description="Process with flags",
-        flags=Flags([Flag("format", possible_values=["json", "xml"]), Flag("verbose")]),
+        flags=Flags([
+            Flag("format", possible_values=["json", "xml"]), 
+            Flag("verbose")
+        ]),
     )
 )
 def process_handler(response: Response):
-    # Проверяем статус валидации флагов
-    print(f"Status: {response.status.value}")
+    print(f"Status: {response.status}")
 
-    # Работаем с флагами
     format_flag = response.input_flags.get_flag_by_name("format")
     verbose_flag = response.input_flags.get_flag_by_name("verbose")
 
@@ -27,11 +29,10 @@ def process_handler(response: Response):
     if verbose_flag:
         print("Verbose mode enabled")
 
-    # Проверяем валидность флагов
     if response.status == ResponseStatus.ALL_FLAGS_VALID:
         print("All flags are valid, proceeding...")
     elif response.status == ResponseStatus.INVALID_VALUE_FLAGS:
         print("Warning: Some flags have invalid values")
         for flag in response.input_flags:
-            if flag.status and flag.status.name == "INVALID":
+            if flag.status == ValidationStatus.INVALID:
                 print(f"  Invalid flag: {flag.string_entity} = {flag.input_value}")

docs/code_snippets/validation_status/comprehensive.py

@@ -1,39 +0,0 @@
-import re
-
-from argenta.command.flag import Flag, InputFlag, PossibleValues, ValidationStatus
-
-# Создаём различные типы флагов
-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.py

@@ -1,18 +0,0 @@
-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.py

@@ -1,15 +0,0 @@
-from argenta.command.flag import Flag, InputFlag, PossibleValues, ValidationStatus
-
-# Создание флага без значения
-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.py

@@ -1,35 +0,0 @@
-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.py

@@ -1,15 +0,0 @@
-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.py

@@ -1,13 +0,0 @@
-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