t8ot 0.3.0__py3-none-any.whl

t8ot/__init__.py

@@ -0,0 +1,36 @@
+from .app import Bot
+from .context import Context
+from .base import BaseCommand, BaseCallback, BaseMessage, BaseInline
+from .fsm import (
+    BaseFlow,
+    Step,
+    BaseStorage,
+    MemoryStorage,
+    SQLiteStorage,
+    RedisStorage,
+)
+from .middleware import BaseMiddleware
+from .guards import admin_only, private_only, group_only
+from .types import InlineKeyboard, ReplyKeyboard, remove_keyboard
+
+__all__ = [
+    "Bot",
+    "Context",
+    "BaseCommand",
+    "BaseCallback",
+    "BaseMessage",
+    "BaseInline",
+    "BaseMiddleware",
+    "admin_only",
+    "private_only",
+    "group_only",
+    "BaseFlow",
+    "Step",
+    "MemoryStorage",
+    "SQLiteStorage",
+    "RedisStorage",
+    "BaseStorage",
+    "InlineKeyboard",
+    "ReplyKeyboard",
+    "remove_keyboard",
+]

t8ot/app.py

@@ -0,0 +1,260 @@
+import sys
+import inspect
+import importlib.util
+from pathlib import Path
+from typing import Optional, Type, Dict, List, Callable, Awaitable
+from types import ModuleType
+import asyncio
+
+from telebot.async_telebot import AsyncTeleBot
+from telebot.types import Message, CallbackQuery, InlineQuery
+
+from .context import Context
+from .base import BaseCommand, BaseCallback, BaseMessage, BaseInline
+from .fsm import BaseStorage, MemoryStorage, BaseFlow
+from .middleware import BaseMiddleware
+
+
+class Bot:
+    def __init__(
+        self,
+        token: str,
+        parse_mode: Optional[str] = "HTML",
+        storage: Optional[BaseStorage] = None,
+    ):
+        self.bot = AsyncTeleBot(token=token, parse_mode=parse_mode)
+        self.storage: BaseStorage = storage or MemoryStorage()
+        self.flows: Dict[str, BaseFlow] = {}
+        self.middlewares: List[BaseMiddleware] = []
+
+        # Global message interceptor for active multi-step flows
+        @self.bot.message_handler(
+            func=lambda msg: self.storage.get_state(msg.from_user.id) is not None,
+            content_types=['text', 'contact', 'location']
+        )
+        async def flow_interceptor(message: Message):
+            ctx = Context(self, message)
+            await self._execute_with_middlewares(ctx, self._handle_flow_step)
+
+    def use(self, middleware: BaseMiddleware) -> None:
+        """Registers a global middleware into the execution pipeline."""
+        self.middlewares.append(middleware)
+
+    async def _execute_with_middlewares(
+        self,
+        ctx: Context,
+        handler: Callable[[Context], Awaitable[None]]
+    ) -> None:
+        """Executes pre-hooks, the target handler, and post-hooks."""
+        executed_middlewares: List[BaseMiddleware] = []
+        halted = False
+        exception: Optional[Exception] = None
+
+        try:
+            # 1. Run pre_process hooks sequentially
+            for mw in self.middlewares:
+                allowed = await mw.pre_process(ctx)
+                executed_middlewares.append(mw)
+                if not allowed:
+                    halted = True  # Request halted by middleware
+                    break
+
+            # 2. Execute target handler
+            if not halted:
+                await handler(ctx)
+
+        except Exception as e:
+            exception = e
+
+        # 3. Unwind post_process hooks in reverse order (success, halt or error)
+        for mw in reversed(executed_middlewares):
+            await mw.post_process(ctx, exception=exception)
+
+        if exception is not None:
+            raise exception
+
+    def _import_module_from_file(self, file_path: Path, root: Path) -> Optional[ModuleType]:
+        """Import a handler file under a name derived from its relative path.
+
+        The relative path keeps same-named files in sibling folders
+        (``admin/stats.py`` vs ``user/stats.py``) from clashing in
+        ``sys.modules``. Returns ``None`` when the file cannot be imported.
+        """
+        rel = file_path.relative_to(root).as_posix()
+        dotted = rel[:-3].replace("/", ".")
+        module_name = f"t8ot_dynamic_{dotted}_{abs(hash(str(file_path.resolve())))}"
+
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if not spec or not spec.loader:
+            print(f"[t8ot] Warning: Cannot load '{rel}'.")
+            return None
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            del sys.modules[module_name]  # Never cache a half-imported module
+            print(f"[t8ot] Warning: Failed to import '{rel}': {e!r}")
+            return None
+        return module
+
+    def load_handlers(self, directory: str):
+        """Recursively discover and register handler classes under ``directory``."""
+        root = Path(directory)
+        if not root.is_dir():
+            print(f"[t8ot] Warning: '{directory}' is not a directory.")
+            return
+
+        for py_file in sorted(root.rglob("*.py")):
+            rel = py_file.relative_to(root)
+            # Skip private/hidden modules: __init__.py, _helpers.py, .cache/x.py
+            if any(part.startswith(("_", ".")) for part in rel.parts):
+                continue
+
+            module = self._import_module_from_file(py_file, root)
+            if not module:
+                continue
+
+            for _, obj in inspect.getmembers(module, inspect.isclass):
+                if obj.__module__ != module.__name__:
+                    continue
+
+                if issubclass(obj, BaseCommand) and obj is not BaseCommand:
+                    self._register_command(obj)
+
+                elif issubclass(obj, BaseCallback) and obj is not BaseCallback:
+                    self._register_callback(obj)
+
+                elif issubclass(obj, BaseMessage) and obj is not BaseMessage:
+                    self._register_message(obj)
+
+                elif issubclass(obj, BaseInline) and obj is not BaseInline:
+                    self._register_inline(obj)
+
+                elif issubclass(obj, BaseFlow) and obj is not BaseFlow:
+                    self._register_flow(obj)
+
+    def _register_flow(self, cls: Type[BaseFlow]):
+        instance = cls()
+        flow_name = instance.name or cls.__name__.lower().replace("flow", "")
+        self.flows[flow_name] = instance
+        print(f"[t8ot] Registered flow: {flow_name}")
+
+    def _register_command(self, cls: Type[BaseCommand]):
+        instance = cls()
+        cmd_name = instance.name or cls.__name__.lower().replace("command", "")
+
+        @self.bot.message_handler(commands=[cmd_name])
+        async def handler(message: Message):
+            ctx = Context(self, message)
+            await self._execute_with_middlewares(ctx, instance.execute)
+
+        print(f"[t8ot] Registered command: /{cmd_name}")
+
+    def _register_callback(self, cls: Type[BaseCallback]):
+        instance = cls()
+        pattern = instance.pattern
+        filter_fn = (
+            lambda call: (call.data == pattern or (call.data and call.data.startswith(pattern)))
+        ) if pattern else (lambda call: True)
+
+        @self.bot.callback_query_handler(func=filter_fn)
+        async def handler(call: CallbackQuery):
+            ctx = Context(self, call)
+            await self._execute_with_middlewares(ctx, instance.execute)
+
+        print(f"[t8ot] Registered callback: {cls.__name__} (pattern={pattern})")
+
+    def _register_message(self, cls: Type[BaseMessage]):
+        instance = cls()
+        filter_fn = (lambda msg: msg.text == instance.text_filter) if instance.text_filter else (lambda msg: True)
+
+        @self.bot.message_handler(func=filter_fn, content_types=instance.content_types)
+        async def handler(message: Message):
+            # Ignore if user is currently in a flow
+            if self.storage.get_state(message.from_user.id) is not None:
+                return
+            ctx = Context(self, message)
+            await self._execute_with_middlewares(ctx, instance.execute)
+
+        print(f"[t8ot] Registered message handler: {cls.__name__}")
+
+    def _register_inline(self, cls: Type[BaseInline]):
+        instance = cls()
+
+        @self.bot.inline_handler(func=lambda query: True)
+        async def handler(inline_query: InlineQuery):
+            ctx = Context(self, inline_query)
+            await self._execute_with_middlewares(ctx, instance.execute)
+
+        print(f"[t8ot] Registered inline handler: {cls.__name__}")
+
+    async def start_flow(self, ctx: Context, flow_name: str):
+        flow = self.flows.get(flow_name)
+        if not flow or not flow.steps:
+            raise ValueError(f"Flow '{flow_name}' not found or has no steps.")
+
+        first_step = flow.steps[0]
+        self.storage.set_state(ctx.user.id, f"{flow_name}:0")
+        await ctx.reply(first_step.prompt)
+
+    async def cancel_user_flow(self, ctx: Context):
+        state = self.storage.get_state(ctx.user.id)
+        if state:
+            flow_name, _ = state.split(":")
+            flow = self.flows.get(flow_name)
+            self.storage.clear(ctx.user.id)
+            if flow:
+                await flow.on_cancel(ctx)
+            else:
+                await ctx.reply("Cancelled.")
+
+    async def _handle_flow_step(self, ctx: Context):
+        state = self.storage.get_state(ctx.user.id)
+        if not state:
+            return
+
+        flow_name, step_idx_str = state.split(":")
+        step_idx = int(step_idx_str)
+        flow = self.flows.get(flow_name)
+
+        if not flow:
+            self.storage.clear(ctx.user.id)
+            return
+
+        # Check for cancel keywords
+        if ctx.text and ctx.text.strip().lower() in [cmd.lower() for cmd in flow.cancel_commands]:
+            await self.cancel_user_flow(ctx)
+            return
+
+        current_step = flow.steps[step_idx]
+
+        # Validation
+        if current_step.validator:
+            is_valid = current_step.validator(ctx)
+            if inspect.iscoroutine(is_valid):
+                is_valid = await is_valid
+
+            if not is_valid:
+                await ctx.reply(current_step.error_message)
+                return
+
+        # Save step value
+        value = ctx.value
+        self.storage.update_data(ctx.user.id, **{current_step.name: value})
+
+        # Move to next step or complete
+        next_idx = step_idx + 1
+        if next_idx < len(flow.steps):
+            self.storage.set_state(ctx.user.id, f"{flow_name}:{next_idx}")
+            next_step = flow.steps[next_idx]
+            await ctx.reply(next_step.prompt)
+        else:
+            data = self.storage.get_data(ctx.user.id)
+            self.storage.clear(ctx.user.id)
+            await flow.on_finish(ctx, data)
+
+    def run(self):
+        print("[t8ot] Bot is polling...")
+        asyncio.run(self.bot.infinity_polling())

t8ot/base/__init__.py

@@ -0,0 +1,6 @@
+from .command import BaseCommand
+from .callback import BaseCallback
+from .message import BaseMessage
+from .inline import BaseInline
+
+__all__ = ["BaseCommand", "BaseCallback", "BaseMessage", "BaseInline"]

t8ot/base/callback.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+from ..context import Context
+
+
+class BaseCallback(ABC):
+    """Base class for inline button callback handlers."""
+
+    pattern: Optional[str] = None
+
+    @abstractmethod
+    async def execute(self, ctx: Context) -> None:
+        pass

t8ot/base/command.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+from ..context import Context
+
+
+class BaseCommand(ABC):
+    """Base class for slash command handlers (e.g., /start)."""
+
+    name: str = ""
+    description: Optional[str] = None
+
+    @abstractmethod
+    async def execute(self, ctx: Context) -> None:
+        pass

t8ot/base/inline.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+from ..context import Context
+
+
+class BaseInline(ABC):
+    """Base class for inline queries (@bot)."""
+
+    pattern: Optional[str] = None
+
+    @abstractmethod
+    async def execute(self, ctx: Context) -> None:
+        pass

t8ot/base/message.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Optional, List
+from ..context import Context
+
+
+class BaseMessage(ABC):
+    """Base class for standard text or media message handlers."""
+
+    content_types: List[str] = ["text"]
+    text_filter: Optional[str] = None
+
+    @abstractmethod
+    async def execute(self, ctx: Context) -> None:
+        pass

t8ot/cli/__init__.py

@@ -0,0 +1,3 @@
+from .main import build_parser, cli
+
+__all__ = ["cli", "build_parser"]

t8ot/cli/main.py

@@ -0,0 +1,235 @@
+import argparse
+import re
+from pathlib import Path
+from typing import Callable, List, Optional
+
+NAME_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+GITIGNORE = """\
+.env
+__pycache__/
+*.pyc
+*.db
+"""
+
+ENV_EXAMPLE = """\
+BOT_TOKEN=your_token_here
+"""
+
+MAIN_PY = '''\
+import os
+
+from t8ot import Bot
+
+BOT_TOKEN = os.getenv("BOT_TOKEN", "123456:YOUR_TOKEN_HERE")
+
+bot = Bot(token=BOT_TOKEN)
+
+# Auto-discovery walks each tree recursively, so you can nest handlers freely.
+bot.load_handlers("commands")
+bot.load_handlers("callbacks")
+bot.load_handlers("flows")
+
+if __name__ == "__main__":
+    bot.run()
+'''
+
+START_COMMAND = '''\
+from t8ot import Context, InlineKeyboard
+from t8ot.base import BaseCommand
+
+
+class StartCommand(BaseCommand):
+    name = "start"
+    description = "Welcome message"
+
+    async def execute(self, ctx: Context) -> None:
+        keyboard = (
+            InlineKeyboard()
+            .button("Website", url="https://telegram.org")
+            .button("Settings", callback_data="settings:open")
+            .build()
+        )
+        await ctx.reply("Welcome to your t8ot bot!", reply_markup=keyboard)
+'''
+
+COMMAND_TEMPLATE = '''\
+from t8ot import Context
+from t8ot.base import BaseCommand
+
+
+class {cls}Command(BaseCommand):
+    """Handles /{name}."""
+
+    name = "{name}"
+    description = "TODO: describe /{name}"
+
+    async def execute(self, ctx: Context) -> None:
+        await ctx.reply("TODO: handle /{name}")
+'''
+
+CALLBACK_TEMPLATE = '''\
+from t8ot import Context
+from t8ot.base import BaseCallback
+
+
+class {cls}Callback(BaseCallback):
+    """Handles callback data starting with "{pattern}"."""
+
+    pattern = "{pattern}"
+
+    async def execute(self, ctx: Context) -> None:
+        await ctx.answer("TODO: handle {pattern}")
+'''
+
+FLOW_TEMPLATE = '''\
+from t8ot import Context
+from t8ot.fsm import BaseFlow, Step
+
+
+def is_number(ctx: Context) -> bool:
+    """Example validator: rejects anything that is not a plain number."""
+    return bool(ctx.text and ctx.text.strip().lstrip("-").isdigit())
+
+
+class {cls}Flow(BaseFlow):
+    """Two-step {name} flow."""
+
+    name = "{name}"
+
+    def define_steps(self):
+        return [
+            Step(
+                name="amount",
+                prompt="How much? (send /cancel to stop)",
+                validator=is_number,
+                error_message="That is not a number. Try again:",
+            ),
+            Step(
+                name="reason",
+                prompt="Why?",
+            ),
+        ]
+
+    async def on_finish(self, ctx: Context, data: dict):
+        await ctx.reply(f"Done! Collected: {data}")
+'''
+
+
+def _class_name(name: str) -> str:
+    """Turns ``user-profile`` / ``user_profile`` into ``UserProfile``."""
+    return "".join(part.capitalize() for part in re.split(r"[-_]", name))
+
+
+def _render(template: str, **pairs: str) -> str:
+    """Fills ``{token}`` placeholders without touching generated-code braces."""
+    for key, value in pairs.items():
+        template = template.replace("{" + key + "}", value)
+    return template
+
+
+def _write(path: Path, content: str) -> bool:
+    """Writes ``content`` to ``path``, never overwriting an existing file."""
+    if path.exists():
+        print(f"[t8ot] Skipped (already exists): {path}")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    print(f"[t8ot] Created {path}")
+    return True
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    """Scaffolds a runnable bot project in ``<project_name>/``."""
+    root = Path(args.project_name)
+
+    _write(root / ".env.example", ENV_EXAMPLE)
+    _write(root / ".gitignore", GITIGNORE)
+    _write(root / "main.py", MAIN_PY)
+    _write(root / "commands" / "start.py", START_COMMAND)
+    for folder in ("commands", "callbacks", "flows"):
+        (root / folder).mkdir(parents=True, exist_ok=True)
+
+    print(f"[t8ot] Project ready: {root.resolve()}")
+    print("[t8ot] Next: cp .env.example .env  ->  add handlers  ->  python main.py")
+
+
+def cmd_make_command(args: argparse.Namespace) -> None:
+    _write(
+        Path(args.dir) / f"{args.name}.py",
+        _render(COMMAND_TEMPLATE, name=args.name, cls=_class_name(args.name)),
+    )
+
+
+def cmd_make_callback(args: argparse.Namespace) -> None:
+    pattern = args.pattern or f"{args.name}:"
+    _write(
+        Path(args.dir) / f"{args.name}.py",
+        _render(CALLBACK_TEMPLATE, pattern=pattern, cls=_class_name(args.name)),
+    )
+
+
+def cmd_make_flow(args: argparse.Namespace) -> None:
+    _write(
+        Path(args.dir) / f"{args.name}.py",
+        _render(FLOW_TEMPLATE, name=args.name, cls=_class_name(args.name)),
+    )
+
+
+def _add_make(
+    subparsers,
+    command: str,
+    handler: Callable[[argparse.Namespace], None],
+    help_text: str,
+    default_dir: str,
+    with_pattern: bool = False,
+) -> None:
+    """Registers one ``make:*`` subcommand sharing the name/--dir options."""
+    parser = subparsers.add_parser(command, help=help_text)
+    parser.add_argument("name", help="Handler name (e.g. user_profile)")
+    parser.add_argument("--dir", default=default_dir, help="Target directory")
+    if with_pattern:
+        parser.add_argument(
+            "--pattern", default=None, help="Callback data prefix (default '<name>:')"
+        )
+    parser.set_defaults(func=handler)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="t8ot", description="t8ot CLI tool for Telegram bot scaffolding"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser(
+        "init", help="Create a new bot project scaffold"
+    )
+    init_parser.add_argument("project_name", help="Directory to create")
+    init_parser.set_defaults(func=cmd_init)
+
+    _add_make(subparsers, "make:command", cmd_make_command, "Generate a command handler", "commands")
+    _add_make(
+        subparsers, "make:callback", cmd_make_callback, "Generate a callback handler", "callbacks", True
+    )
+    _add_make(subparsers, "make:flow", cmd_make_flow, "Generate a multi-step flow", "flows")
+    return parser
+
+
+def cli(argv: Optional[List[str]] = None) -> int:
+    """Entry point for the ``t8ot`` console script."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    name = getattr(args, "name", None)
+    if name and not NAME_PATTERN.match(name):
+        parser.error(
+            f"invalid name '{name}': start with a letter, then use letters, "
+            "digits, '-' or '_'"
+        )
+
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli())