feat: impl docs (#4)

The entire public api is covered with documentation in two languages - Russian and English.

the library now supports the latest three versions of python - 3.12, 3.13 and 3.14

minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None.

tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.

docs/code_snippets/quickstart/calculator_app.py

@@ -0,0 +1,68 @@
+import operator
+import re
+
+from argenta import App, Orchestrator, Response, Router
+from argenta.app import DynamicDividingLine
+from argenta.command import Command, Flag, Flags
+from argenta.response.status import ResponseStatus
+
+router = Router("Calculator")
+
+operations = {
+    'mul': operator.mul,
+    'sub': operator.sub,
+    'add': operator.add
+}
+
+@router.command(
+    Command(
+        "calc",
+        description="Calculator with two numbers",
+        flags=Flags(
+            [
+                Flag("a", possible_values=re.compile(r"^\d{,5}$")),  # First number
+                Flag("b", possible_values=re.compile(r"^\d{,5}$")),  # Second number
+                Flag("operation", possible_values=["add", "sub", "mul"]),  # Operation: add, sub, mul
+            ]
+        ),
+    )
+)
+def calc_handler(response: Response):
+    # Get flag values
+    a_flag = response.input_flags.get_flag_by_name("a")
+    b_flag = response.input_flags.get_flag_by_name("b")
+    op_flag = response.input_flags.get_flag_by_name("op")
+
+    # Check that all flags are provided
+    if response.status != ResponseStatus.ALL_FLAGS_VALID or not all([a_flag, b_flag, op_flag]):
+        print("Error: must specify --a, --b and --op")
+        return
+
+    a = float(a_flag.input_value)
+    b = float(b_flag.input_value)
+    operation = op_flag.input_value
+
+    try:
+        result = operations[operation](a, b)
+    except ZeroDivisionError:
+        print("Can't divide by zero")
+    else:
+        print(f"Result: {result}")
+
+
+app = App(
+    initial_message="Calculator",
+    repeat_command_groups_printing=False,
+    prompt=">> ",
+    dividing_line=DynamicDividingLine("~"),
+)
+orchestrator = Orchestrator()
+
+
+def main():
+    app.include_router(router)
+    orchestrator.start_polling(app)
+
+
+if __name__ == "__main__":
+    main()

docs/code_snippets/quickstart/main.py

@@ -0,0 +1,16 @@
+# main.py
+from .routers import router
+
+from argenta import App, Orchestrator
+
+app: App = App()
+orchestrator: Orchestrator = Orchestrator()
+
+
+def main() -> None:
+    app.include_router(router)
+    orchestrator.start_polling(app)
+
+
+if __name__ == "__main__":
+    main()

docs/code_snippets/quickstart/routers.py

@@ -0,0 +1,9 @@
+# routers.py
+from argenta import Command, Response, Router
+
+router = Router(title="Quickstart Example")
+
+
+@router.command(Command("hello", description="Say hello"))
+def handler(response: Response):
+    print("Hello, world!")

docs/code_snippets/quickstart/simple_app.py

@@ -0,0 +1,37 @@
+from argenta import App, Command, Orchestrator, Router, Response
+from argenta.command import Flag
+
+# 1. Create app and orchestrator instances
+app = App(
+    prompt=">> ",
+    initial_message="Simple App",
+    farewell_message="Goodbye!",
+    repeat_command_groups_printing=False
+)
+orchestrator = Orchestrator()
+
+# 2. Create router for grouping commands
+main_router = Router(title="Main commands")
+
+
+# 3. Define command and its handler
+@main_router.command(Command(
+    "hello", 
+    description="Prints greeting message", 
+    flags=Flag("name")
+))
+def hello_handler(response: Response):
+    """This handler will be called for 'hello' command."""
+    name = response.input_flags.get_flag_by_name("name")
+    if name:
+        print(f"Hello, {name.input_value}!")
+    else:
+        print("Hello, world!")
+
+
+# 4. Include router to application
+app.include_router(main_router)
+
+# 5. Start application
+if __name__ == "__main__":
+    orchestrator.start_polling(app)

docs/code_snippets/quickstart/task_manager/handlers.py

@@ -0,0 +1,54 @@
+from typing import cast
+
+from argenta import Command, Response, Router
+from argenta.command.flag import Flag, Flags, ValidationStatus
+from argenta.di import FromDishka
+
+from .repository import Priority, Task, TaskRepository
+
+router = Router(title="Task Manager")
+
+
+@router.command(Command(
+        "add-task",
+        description="Add a new task",
+        flags=Flags([
+                Flag("description"),
+                Flag("priority", possible_values=["low", "medium", "high"]),
+            ]),
+    ))
+def add_task(response: Response, repo: FromDishka[TaskRepository]):
+    description_flag = response.input_flags.get_flag_by_name("description")
+    
+    if not description_flag or not description_flag.status == ValidationStatus.VALID:
+        print("Error: --description flag is required.")
+        return
+        
+    task_description = description_flag.input_value or ""
+
+    priority_flag = response.input_flags.get_flag_by_name("priority")
+    
+    if priority_flag and priority_flag.status == ValidationStatus.VALID:
+        priority_value = priority_flag.input_value
+    else:
+        priority_value = "medium"
+
+    priority = cast(Priority, priority_value)
+
+    task = Task(description=task_description, priority=priority)
+    repo.add_task(task)
+    
+    print(f"Added task: '{task.description}' with priority '{task.priority}'")
+
+
+@router.command(Command("list-tasks", description="List all tasks"))
+def list_tasks(response: Response, repo: FromDishka[TaskRepository]):
+    tasks = repo.get_all_tasks()
+    
+    if not tasks:
+        print("No tasks found.")
+        return
+
+    print("Tasks:")
+    for i, task in enumerate(tasks, 1):
+        print(f"  {i}. {task.description} (Priority: {task.priority})")

docs/code_snippets/quickstart/task_manager/main.py

@@ -0,0 +1,18 @@
+from argenta import App, Orchestrator
+
+from .handlers import router
+from .provider import TaskProvider
+
+# 1. Create app and orchestrator instances
+app = App(
+    initial_message="Task Manager",
+    prompt="Enter a command: ",
+)
+orchestrator = Orchestrator(custom_providers=[TaskProvider()])
+
+# 2. Include router with our commands
+app.include_router(router)
+
+# 3. Start polling via orchestrator
+if __name__ == "__main__":
+    orchestrator.start_polling(app)

docs/code_snippets/quickstart/task_manager/provider.py

@@ -0,0 +1,9 @@
+from dishka import Provider, Scope, provide
+
+from .repository import TaskRepository
+
+
+class TaskProvider(Provider):
+    @provide(scope=Scope.APP)
+    def get_repository(self) -> TaskRepository:
+        return TaskRepository()

docs/code_snippets/quickstart/task_manager/repository.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from typing import Literal
+
+Priority = Literal["low", "medium", "high"]
+
+
+@dataclass
+class Task:
+    description: str
+    priority: Priority = "medium"
+
+
+class TaskRepository:
+    def __init__(self):
+        self._tasks: list[Task] = []
+
+    def add_task(self, task: Task):
+        self._tasks.append(task)
+
+    def get_all_tasks(self) -> list[Task]:
+        return self._tasks