codex-bot 0.1.0__py3-none-any.whl

codex_bot/cli/commands.py

@@ -0,0 +1,215 @@
+"""
+CLI commands for codex-bot feature scaffolding.
+
+Used as the ``codex-bot`` entry point (see pyproject.toml).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Path to the library's built-in templates
+_TEMPLATES_DIR = Path(__file__).parent.parent / "templates" / "feature"
+
+
+def _load_template(name: str, templates_dir: Path) -> str:
+    """Loads a template from a ``.py.tpl`` file.
+
+    Args:
+        name: Template name without extension.
+        templates_dir: Directory containing templates.
+
+    Returns:
+        Content of the template file.
+
+    Raises:
+        FileNotFoundError: If the template is not found.
+    """
+    path = templates_dir / f"{name}.py.tpl"
+    if not path.exists():
+        raise FileNotFoundError(f"Template not found: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def _get_template(base_name: str, suffix: str, templates_dir: Path) -> str:
+    """Loads a specific template, otherwise takes the base one.
+
+    Args:
+        base_name: Base template name.
+        suffix: Suffix for a specific template (e.g., ``"_redis"``).
+        templates_dir: Directory containing templates.
+
+    Returns:
+        Template content.
+    """
+    try:
+        return _load_template(f"{base_name}{suffix}", templates_dir)
+    except FileNotFoundError:
+        return _load_template(base_name, templates_dir)
+
+
+def create_feature(
+    name: str,
+    feature_type: str,
+    base_dir: Path | None = None,
+    templates_dir: Path | None = None,
+) -> None:
+    """Creates the structure of a new feature based on templates.
+
+    Generates a ``features/{feature_type}/{name}/`` directory with files:
+    ``feature_setting.py``, ``handlers/handlers.py``, ``logic/orchestrator.py``,
+    ``ui/ui.py``, ``contracts/contract.py``, ``resources/``, and ``tests/``.
+
+    Args:
+        name: Feature name in ``snake_case``.
+        feature_type: Feature type — ``"telegram"`` or ``"redis"``.
+        base_dir: Project root directory. ``None`` → current directory.
+        templates_dir: Templates directory. ``None`` → built-in templates.
+
+    Raises:
+        SystemExit: If the feature already exists or a template is not found.
+
+    Example:
+        ```bash
+        codex-bot create-feature booking
+        codex-bot create-feature payment_notify --type redis
+        ```
+    """
+    base_dir = base_dir or Path.cwd()
+    templates_dir = templates_dir or _TEMPLATES_DIR
+
+    feature_base = base_dir / "features" / feature_type / name
+
+    if feature_base.exists():
+        print(f"❌ Error: Feature '{name}' already exists in features/{feature_type}/")
+        return
+
+    # Name conversions
+    class_name = "".join(word.capitalize() for word in name.split("_"))
+    feature_key = name.lower()
+    container_key = f"redis_{feature_key}" if feature_type == "redis" else feature_key
+
+    # Check for paired feature
+    other_type = "redis" if feature_type == "telegram" else "telegram"
+    has_pair = (base_dir / "features" / other_type / name).exists()
+
+    # Create directories
+    dirs = [
+        feature_base,
+        feature_base / "handlers",
+        feature_base / "logic",
+        feature_base / "ui",
+        feature_base / "resources",
+        feature_base / "contracts",
+        feature_base / "tests",
+    ]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "__init__.py").write_text("", encoding="utf-8")
+
+    suffix = "_redis" if feature_type == "redis" else ""
+
+    try:
+        templates: dict[str, str] = {
+            "feature.py": _get_template("feature", suffix, templates_dir),
+            "handlers.py": _get_template("handlers", suffix, templates_dir),
+            "orchestrator.py": _get_template("orchestrator", suffix, templates_dir),
+            "ui.py": _get_template("ui", "", templates_dir),
+            "contract.py": _get_template("contract", "", templates_dir),
+            "texts.py": _get_template("texts", "", templates_dir),
+            "keyboards.py": _get_template("keyboards", "", templates_dir),
+            "callbacks.py": _get_template("callbacks", "", templates_dir),
+            "formatters.py": _get_template("formatters", "", templates_dir),
+            "dto.py": _get_template("dto", "", templates_dir),
+        }
+    except FileNotFoundError as e:
+        print(f"❌ Error: Template file not found. {e}")
+        return
+
+    format_vars = {
+        "class_name": class_name,
+        "feature_key": feature_key,
+        "container_key": container_key,
+        "feature_type": feature_type,
+    }
+
+    files: dict[Path, str] = {
+        feature_base / "feature_setting.py": templates["feature.py"],
+        feature_base / "handlers" / "handlers.py": templates["handlers.py"],
+        feature_base / "logic" / "orchestrator.py": templates["orchestrator.py"],
+        feature_base / "ui" / "ui.py": templates["ui.py"],
+        feature_base / "contracts" / "contract.py": templates["contract.py"],
+        feature_base / "resources" / "texts.py": templates["texts.py"],
+        feature_base / "resources" / "keyboards.py": templates["keyboards.py"],
+        feature_base / "resources" / "callbacks.py": templates["callbacks.py"],
+        feature_base / "resources" / "formatters.py": templates["formatters.py"],
+        feature_base / "resources" / "dto.py": templates["dto.py"],
+    }
+
+    for file_path, template in files.items():
+        content = template.format(**format_vars)
+        file_path.write_text(content, encoding="utf-8")
+
+    # Export router from handlers/__init__.py
+    router_attr = "redis_router" if feature_type == "redis" else "router"
+    init_content = f"from .handlers import {router_attr}\n"
+    (feature_base / "handlers" / "__init__.py").write_text(init_content, encoding="utf-8")
+
+    print(f"\n✅ Feature '{name}' ({feature_type}) successfully created!")
+
+    if has_pair:
+        print(f"🔗 Paired feature found in '{other_type}'!")
+        if feature_type == "telegram":
+            print("💡 Tip: Configure inheritance in resources/callbacks.py to handle buttons from Redis notifications.")
+
+    setting_list = "INSTALLED_FEATURES" if feature_type == "telegram" else "INSTALLED_REDIS_FEATURES"
+    print(f"👉 Add 'features.{feature_type}.{name}' to {setting_list}")
+
+
+def main() -> None:
+    """CLI entry point for ``codex-bot``.
+
+    Subcommands:
+        create-feature: Create a new feature.
+
+    Example:
+        ```bash
+        codex-bot create-feature booking
+        codex-bot create-feature payment_notify --type redis
+        ```
+    """
+    parser = argparse.ArgumentParser(
+        description="codex-bot: Aiogram Bot Management Framework",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    create_parser = subparsers.add_parser("create-feature", help="Create a new feature")
+    create_parser.add_argument("name", help="Feature name in snake_case")
+    create_parser.add_argument(
+        "--type",
+        choices=["telegram", "redis"],
+        default="telegram",
+        help="Feature type (default: telegram)",
+    )
+
+    if len(sys.argv) == 1:
+        parser.print_help()
+        sys.exit(0)
+
+    args = parser.parse_args()
+
+    if args.command == "create-feature":
+        if not args.name:
+            create_parser.print_help()
+        else:
+            create_feature(args.name, args.type)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

codex_bot/director/__init__.py

@@ -0,0 +1,13 @@
+"""
+codex_bot.director — Cross-feature transition coordinator.
+"""
+
+from codex_bot.director.director import Director
+from codex_bot.director.protocols import ContainerProtocol, OrchestratorProtocol, SceneConfig
+
+__all__ = [
+    "Director",
+    "OrchestratorProtocol",
+    "ContainerProtocol",
+    "SceneConfig",
+]

codex_bot/director/director.py

@@ -0,0 +1,107 @@
+"""
+Director — Coordinator of cross-feature transitions.
+
+The Director knows how to transition from one feature to another: change the FSM state,
+get the required orchestrator from the container, and call its handle_entry().
+Orchestrators are stateless — the Director passes itself as context with each call.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aiogram.fsm.context import FSMContext
+
+from ..base.view_dto import UnifiedViewDTO
+from .protocols import ContainerProtocol, OrchestratorProtocol
+
+log = logging.getLogger(__name__)
+
+
+class Director:
+    """Coordinator of transitions between features (scenes).
+
+    Instantiated in the handler for each incoming request.
+    Stores the request context (user_id, chat_id, state) and passes itself
+    to orchestrators as an argument — no mutable state in the orchestrator.
+
+    Args:
+        container: Project's DI container with a ``features`` attribute.
+        state: FSM context of the current user.
+        user_id: Telegram ID of the user.
+        chat_id: Target chat ID.
+        trigger_id: ID of the trigger message (e.g., /start) for subsequent deletion.
+
+    Example:
+        ```python
+        director = Director(
+            container=container,
+            state=state,
+            user_id=callback.from_user.id,
+            chat_id=callback.message.chat.id,
+        )
+        view = await director.set_scene(feature="booking", payload=None)
+        await sender.send(view)
+        ```
+    """
+
+    def __init__(
+        self,
+        container: ContainerProtocol,
+        state: FSMContext | None = None,
+        user_id: int | None = None,
+        chat_id: int | None = None,
+        trigger_id: int | None = None,
+    ) -> None:
+        self.container = container
+        self.state = state
+        self.user_id = user_id
+        self.chat_id = chat_id
+        self.trigger_id = trigger_id
+
+    async def set_scene(self, feature: str, payload: Any = None) -> Any:
+        """Cross-feature transition: changes FSM state and calls the feature orchestrator.
+
+        Algorithm:
+        1. Retrieves the orchestrator by key from ``container.features``.
+        2. Sets the FSM state if the orchestrator has declared it.
+        3. Passes itself to ``handle_entry(director=self, payload=payload)``.
+        4. Enriches the result with ``chat_id`` and ``session_key`` as a fallback.
+
+        Args:
+            feature: Orchestrator key in ``container.features`` (e.g., ``"booking"``).
+            payload: Data to pass to ``handle_entry()``.
+
+        Returns:
+            UnifiedViewDTO or any orchestrator result. None if the feature is not found.
+        """
+        orchestrator = self.container.features.get(feature)
+
+        if orchestrator is None:
+            log.error(f"Director | unknown_feature='{feature}' user_id={self.user_id}")
+            return None
+
+        # 1. FSM state change
+        if self.state and hasattr(orchestrator, "expected_state") and orchestrator.expected_state:
+            await self.state.set_state(orchestrator.expected_state)
+
+        # 2. Call handle_entry (pass self as context) or render
+        if isinstance(orchestrator, OrchestratorProtocol):
+            view = await orchestrator.handle_entry(director=self, payload=payload)
+        elif hasattr(orchestrator, "render"):
+            view = await orchestrator.render(payload, self)
+        else:
+            log.warning(f"Director | orchestrator='{feature}' has no handle_entry or render")
+            return None
+
+        # 3. Fallback enrichment of UnifiedViewDTO with session data
+        if isinstance(view, UnifiedViewDTO):
+            view = view.model_copy(
+                update={
+                    "chat_id": view.chat_id or self.chat_id,
+                    "session_key": view.session_key or self.user_id,
+                }
+            )
+
+        return view

codex_bot/director/protocols.py

@@ -0,0 +1,80 @@
+"""
+Protocols for Director — Dependency inversion without concrete classes.
+
+OrchestratorProtocol describes the minimum contract of a stateless orchestrator,
+ContainerProtocol — the minimum contract of the project's DI container.
+The library does not know about specific implementations — only about interfaces.
+"""
+
+from typing import Any, NamedTuple, Protocol, runtime_checkable
+
+from aiogram.fsm.state import State
+
+
+class SceneConfig(NamedTuple):
+    """Scene configuration: FSM state + entry-point service key.
+
+    Used in the project's SCENE_ROUTES to describe cross-feature transitions.
+
+    Attributes:
+        fsm_state: Aiogram State set when entering the scene.
+        entry_service: Orchestrator key in the container registry (e.g., ``"booking"``).
+
+    Example:
+        ```python
+        SCENE_ROUTES = {
+            "booking": SceneConfig(
+                fsm_state=BookingStates.main,
+                entry_service="booking",
+            ),
+        }
+        ```
+    """
+
+    fsm_state: State
+    entry_service: str
+
+
+@runtime_checkable
+class OrchestratorProtocol(Protocol):
+    """Minimum contract for a stateless feature orchestrator.
+
+    The Director works through this protocol without knowing about specific classes.
+    BaseBotOrchestrator implements it automatically.
+
+    The orchestrator must be stateless — it does not store user state.
+    Context is passed via the ``director`` argument on each call.
+    """
+
+    async def render(self, payload: Any, director: Any) -> Any:
+        """Renders content for the passed payload."""
+        ...
+
+    async def handle_entry(
+        self,
+        director: Any,
+        payload: Any = None,
+    ) -> Any:
+        """Entry point into the feature."""
+        ...
+
+
+@runtime_checkable
+class ContainerProtocol(Protocol):
+    """Minimum contract for the project's DI container.
+
+    The Director only requires the ``features`` attribute — a dictionary of orchestrators.
+    The specific BotContainer of the project must provide this attribute.
+
+    Attributes:
+        features: Dictionary of ``{feature_key: orchestrator}``.
+
+    Example:
+        ```python
+        class BotContainer:
+            def __init__(self):
+                self.features: dict[str, Any] = {}
+        ```
+    """
+
+    features: dict[str, OrchestratorProtocol]

codex_bot/engine/__init__.py

@@ -0,0 +1,13 @@
+"""
+codex_bot.engine — инфраструктурный движок (подкапотная магия).
+
+Содержит модули, которые нужны для сборки бота, но не используются
+разработчиком фичи в повседневной работе.
+
+Подмодули:
+    engine.middlewares   — системные middleware (Throttling, Security, Container, …)
+    engine.discovery     — FeatureDiscoveryService (авто-обнаружение фич)
+    engine.factory       — BotBuilder, compile_locales
+    engine.router_builder — collect_feature_routers, build_main_router
+    engine.http          — BaseApiClient, ApiClientError
+"""

codex_bot/engine/discovery/__init__.py

@@ -0,0 +1,7 @@
+"""
+codex_bot.engine.discovery — Feature discovery and registration.
+"""
+
+from codex_bot.engine.discovery.service import FeatureDiscoveryService
+
+__all__ = ["FeatureDiscoveryService"]