aiogram-cmds 0.1.0__py3-none-any.whl

aiogram_cmds/__init__.py

@@ -0,0 +1,69 @@
+"""
+aiogram_cmds - Command builder & scope manager for aiogram bots.
+
+This package provides both simple and full customizable modes for managing
+Telegram bot commands with i18n support, profiles, and multiple scope types.
+
+Simple Mode:
+    from aiogram_cmds import CommandScopeManager, load_settings, build_translator_from_i18n
+
+    settings = load_settings()
+    translator = build_translator_from_i18n(i18n)
+    manager = CommandScopeManager(bot, settings=settings, translator=translator)
+    await manager.setup_all()
+
+Full Customizable Mode:
+    from aiogram_cmds import CmdsConfig, CommandDef, ProfileDef, ScopeDef, MenuButtonDef
+
+    config = CmdsConfig(
+        commands={"start": CommandDef(i18n_key="start.desc")},
+        profiles={"guest": ProfileDef(include=["start"])},
+        scopes=[ScopeDef(scope="all_private_chats", profile="guest")],
+    )
+    manager = CommandScopeManager(bot, config=config, profile_resolver=my_resolver)
+
+Auto-Setup (Recommended):
+    from aiogram_cmds.auto_setup import setup_commands_auto
+
+    async def on_startup():
+        command_manager = await setup_commands_auto(bot)
+"""
+
+from .apply import apply_config
+from .auto_setup import setup_commands_auto
+from .builder import build_bot_commands
+from .customize import CmdsConfig, CommandDef, MenuButtonDef, ProfileDef, ScopeDef
+from .dynamic import set_user_profile
+from .manager import CommandScopeManager
+from .policy import CommandPolicy, Flags, ProfileResolver, default_policy
+from .settings import CmdsSettings, load_settings
+from .translator import Translator, build_translator_from_i18n, noop_translator
+
+__version__ = "0.1.0"
+__author__ = "aiogram_cmds contributors"
+__description__ = "Command builder & scope manager for aiogram bots"
+
+__all__ = [
+    # Simple / classic
+    "build_bot_commands",
+    "CommandScopeManager",
+    "Flags",
+    "CommandPolicy",
+    "default_policy",
+    "Translator",
+    "build_translator_from_i18n",
+    "noop_translator",
+    "CmdsSettings",
+    "load_settings",
+    # Full customizable
+    "CmdsConfig",
+    "CommandDef",
+    "ProfileDef",
+    "ScopeDef",
+    "MenuButtonDef",
+    "apply_config",
+    "set_user_profile",
+    "ProfileResolver",
+    # Auto-setup (convenience)
+    "setup_commands_auto",
+]

aiogram_cmds/apply.py

@@ -0,0 +1,88 @@
+"""
+Apply full configurations to Telegram bot.
+"""
+
+from collections.abc import Iterable
+
+from aiogram import Bot
+from aiogram.types import (
+    BotCommandScopeAllChatAdministrators,
+    BotCommandScopeAllGroupChats,
+    BotCommandScopeAllPrivateChats,
+    BotCommandScopeChat,
+    BotCommandScopeChatAdministrators,
+    BotCommandScopeChatMember,
+    BotCommandScopeDefault,
+    MenuButtonCommands,
+    MenuButtonDefault,
+)
+
+from .builders_configured import build_from_config
+from .customize import CmdsConfig, ScopeDef
+from .registry import CommandRegistry
+from .translator import Translator
+
+
+def _scope_obj(s: ScopeDef):
+    if s.scope == "default":
+        return BotCommandScopeDefault()
+    if s.scope == "all_private_chats":
+        return BotCommandScopeAllPrivateChats()
+    if s.scope == "all_group_chats":
+        return BotCommandScopeAllGroupChats()
+    if s.scope == "all_chat_admins":
+        return BotCommandScopeAllChatAdministrators()
+    if s.scope == "chat":
+        return BotCommandScopeChat(chat_id=s.chat_id)
+    if s.scope == "chat_admins":
+        return BotCommandScopeChatAdministrators(chat_id=s.chat_id)
+    if s.scope == "chat_member":
+        return BotCommandScopeChatMember(chat_id=s.chat_id, user_id=s.user_id)
+    raise ValueError(f"Unknown scope: {s.scope}")
+
+
+def _sorted_scopes(scopes: Iterable[ScopeDef]) -> list[ScopeDef]:
+    rank = {
+        "chat_member": 0,
+        "chat_admins": 1,
+        "chat": 2,
+        "all_chat_admins": 3,
+        "all_group_chats": 4,
+        "all_private_chats": 5,
+        "default": 6,
+    }
+    return sorted(scopes, key=lambda s: rank[s.scope])
+
+
+async def apply_config(
+    bot: Bot,
+    cfg: CmdsConfig,
+    *,
+    translator: Translator | None = None,
+) -> None:
+    """
+    Apply all configured scopes + menu button in order of specificity.
+    """
+    reg = CommandRegistry(cfg)
+    scopes = _sorted_scopes(cfg.scopes)
+    langs = cfg.languages or ["en"]
+
+    for s in scopes:
+        scope_obj = _scope_obj(s)
+        target_langs = s.languages or langs
+        names = list(reg.resolve_profile_commands(s.profile))
+        for lang in target_langs:
+            cmds = build_from_config(
+                reg,
+                names,
+                lang=lang,
+                translator=translator,
+                key_prefix=cfg.i18n_key_prefix,
+            )
+            await bot.set_my_commands(cmds, scope=scope_obj, language_code=lang)
+
+    # menu button (global default)
+    if cfg.menu_button.mode == "commands":
+        await bot.set_chat_menu_button(menu_button=MenuButtonCommands())
+    else:
+        await bot.set_chat_menu_button(menu_button=MenuButtonDefault())

aiogram_cmds/auto_setup.py

@@ -0,0 +1,161 @@
+"""
+Auto-setup utilities for aiogram_cmds.
+
+This module provides convenient functions to automatically set up command management
+with minimal configuration, making it easy to integrate into __main__.py.
+"""
+
+import logging
+
+from aiogram import Bot
+
+from .customize import CmdsConfig, CommandDef, MenuButtonDef, ProfileDef, ScopeDef
+from .manager import CommandScopeManager
+from .policy import Flags, ProfileResolver
+from .translator import build_translator_from_i18n
+
+logger = logging.getLogger(__name__)
+
+
+async def setup_commands_auto(
+    bot: Bot,
+    *,
+    languages: list[str] | None = None,
+    i18n_instance=None,
+    config: CmdsConfig | None = None,
+    profile_resolver: ProfileResolver | None = None,
+) -> CommandScopeManager:
+    """
+    Automatically set up command management with minimal configuration.
+
+    This function provides a simple way to set up commands in __main__.py
+    with sensible defaults and automatic i18n integration.
+
+    Args:
+        bot: Telegram Bot instance
+        languages: List of supported languages (default: ["en"])
+        i18n_instance: aiogram i18n instance (optional, will try to import from common locations)
+        config: Custom CmdsConfig (optional, will create default if not provided)
+        profile_resolver: Custom ProfileResolver (optional, will create default if not provided)
+
+    Returns:
+        CommandScopeManager instance ready to use
+
+    Example:
+        # In __main__.py
+        from aiogram_cmds.auto_setup import setup_commands_auto
+
+        async def on_startup(dp, app_context=None):
+            command_manager = await setup_commands_auto(bot)
+            # Commands are automatically set up!
+    """
+    # Default languages
+    if languages is None:
+        languages = ["en"]
+
+    # Try to get i18n instance if not provided
+    if i18n_instance is None:
+        i18n_instance = _try_import_i18n()
+
+    # Build translator
+    translator = build_translator_from_i18n(i18n_instance) if i18n_instance else None
+
+    # Create default config if not provided
+    if config is None:
+        config = create_default_config(languages)
+
+    # Create default profile resolver if not provided
+    if profile_resolver is None:
+        profile_resolver = create_default_profile_resolver()
+
+    # Create and setup command manager
+    manager = CommandScopeManager(
+        bot,
+        config=config,
+        translator=translator,
+        profile_resolver=profile_resolver,
+    )
+
+    # Setup all command scopes and menu button
+    await manager.setup_all()
+
+    logger.info(
+        f"✅ Command management set up with {len(config.commands)} commands and {len(config.profiles)} profiles"
+    )
+
+    return manager
+
+
+def _try_import_i18n():
+    """Try to import i18n from common locations."""
+    # Common aiogram i18n import patterns
+    import_patterns = [
+        "bot.core.i18n.i18n",
+        "bot.i18n.i18n",
+        "i18n.i18n",
+        "bot.core.i18n",
+        "bot.i18n",
+        "i18n",
+    ]
+
+    for pattern in import_patterns:
+        try:
+            module_parts = pattern.split(".")
+            module = __import__(pattern, fromlist=[module_parts[-1]])
+            # Try to get the i18n instance
+            if hasattr(module, "i18n"):
+                return module.i18n
+            elif hasattr(module, "gettext"):
+                return module
+        except ImportError:
+            continue
+
+    logger.debug(
+        "Could not find i18n instance, commands will use fallback descriptions"
+    )
+    return None
+
+
+def create_default_config(languages: list[str]) -> CmdsConfig:
+    """
+    Create a default configuration with basic commands.
+
+    This provides a sensible starting point for most bots.
+    """
+    return CmdsConfig(
+        languages=languages,
+        fallback_language=languages[0] if languages else "en",
+        i18n_key_prefix="cmd",
+        # Basic commands that most bots need
+        commands={
+            "start": CommandDef(i18n_key="start.desc"),
+            "help": CommandDef(i18n_key="help.desc"),
+            "cancel": CommandDef(i18n_key="cancel.desc"),
+        },
+        # Simple profile structure
+        profiles={
+            "guest": ProfileDef(include=["start", "help"]),
+            "user": ProfileDef(include=["start", "help", "cancel"]),
+        },
+        # Default scope for all private chats
+        scopes=[
+            ScopeDef(scope="all_private_chats", profile="guest"),
+        ],
+        # Menu button
+        menu_button=MenuButtonDef(mode="commands"),
+    )
+
+
+def create_default_profile_resolver() -> ProfileResolver:
+    """
+    Create a default profile resolver that maps user flags to profiles.
+
+    This provides a simple guest/user distinction based on registration status.
+    """
+
+    def default_resolver(flags: Flags) -> str:
+        if flags.is_during_registration or not flags.is_registered:
+            return "guest"
+        return "user"
+
+    return default_resolver

aiogram_cmds/builder.py

@@ -0,0 +1,77 @@
+"""
+Command building - construct BotCommand objects from names and i18n/inlined descriptions.
+
+- Validates command names per Telegram constraints.
+- Resolves descriptions via translator or falls back to Title Case.
+- Enforces Telegram length limits (name: 1..32, description: 1..256).
+"""
+
+import logging
+import re
+
+from aiogram.types import BotCommand
+
+from .translator import Translator
+
+logger = logging.getLogger(__name__)
+
+# Telegram /command rules (lowercase letters, digits, underscores; must start with a letter)
+_CMD_RE = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
+
+
+def validate_name(name: str) -> str:
+    """Coerce a human/provided name into a safe Telegram command name."""
+    n = (name or "").strip().lower().replace(" ", "_")
+    if not _CMD_RE.match(n):
+        logger.debug("Invalid command name '%s', coercing to safe form", name)
+        # drop leading non-letters
+        while n and not n[0].isalpha():
+            n = n[1:]
+        # remove invalid chars
+        n = re.sub(r"[^a-z0-9_]", "", n)
+        # clamp length
+        n = n[:32] if n else "cmd"
+        if not _CMD_RE.match(n):
+            n = "cmd"
+    return n
+
+
+def build_bot_commands(
+    command_names: list[str],
+    *,
+    lang: str,
+    translator: Translator | None = None,
+    key_prefix: str = "cmd",
+) -> list[BotCommand]:
+    """
+    Build BotCommand objects from command names using i18n descriptions.
+
+    i18n key pattern by default: {key_prefix}.{name}.desc
+    """
+    cmds: list[BotCommand] = []
+
+    for raw in command_names:
+        name = validate_name(raw)
+
+        # Try to get description from i18n
+        desc = None
+        if translator:
+            key = f"{key_prefix}.{name}.desc"
+            try:
+                desc = translator(key, locale=lang)
+            except Exception:  # pragma: no cover
+                logger.debug(
+                    "Translator failed for key %s (lang=%s)", key, lang, exc_info=True
+                )
+
+        # Fallback if missing translation
+        if not desc:
+            desc = name.replace("_", " ").title()
+            logger.debug(
+                "Missing i18n for %s.%s, fallback to '%s'", key_prefix, name, desc
+            )
+
+        cmds.append(BotCommand(command=name[:32], description=desc[:256]))
+
+    logger.debug("Built %d commands for language '%s'", len(cmds), lang)
+    return cmds

aiogram_cmds/builders_configured.py

@@ -0,0 +1,69 @@
+"""
+Command builders for config-driven mode.
+"""
+
+import logging
+
+from aiogram.types import BotCommand
+
+from .builder import validate_name
+from .registry import CommandRegistry
+from .translator import Translator
+
+logger = logging.getLogger(__name__)
+
+
+def build_from_config(
+    reg: CommandRegistry,
+    names: list[str],
+    *,
+    lang: str,
+    translator: Translator | None,
+    key_prefix: str,
+) -> list[BotCommand]:
+    """
+    Build commands using CmdsConfig registry:
+    - inline descriptions win
+    - else use command.i18n_key (relative to prefix unless dotted)
+    - else fallback to {prefix}.{name}.desc
+    - else Title Case fallback
+    """
+    items: list[BotCommand] = []
+    for raw in names:
+        name = validate_name(raw)
+        desc = None
+        c = reg.get_command(name)
+
+        # 1) inline descriptions
+        if c and c.descriptions:
+            desc = c.descriptions.get(lang)
+
+        # 2) specified i18n key
+        if not desc and c and c.i18n_key and translator:
+            i18n_key = c.i18n_key if "." in c.i18n_key else f"{key_prefix}.{c.i18n_key}"
+            try:
+                desc = translator(i18n_key, locale=lang)
+            except Exception:
+                logger.debug(
+                    "Translator failed for key %s (lang=%s)",
+                    i18n_key,
+                    lang,
+                    exc_info=True,
+                )
+
+        # 3) default i18n key {prefix}.{name}.desc
+        if not desc and translator:
+            key = f"{key_prefix}.{name}.desc"
+            try:
+                desc = translator(key, locale=lang)
+            except Exception:
+                logger.debug(
+                    "Translator failed for key %s (lang=%s)", key, lang, exc_info=True
+                )
+
+        # 4) fallback
+        if not desc:
+            desc = name.replace("_", " ").title()
+
+        items.append(BotCommand(command=name[:32], description=desc[:256]))
+    return items

aiogram_cmds/customize.py

@@ -0,0 +1,67 @@
+"""
+Full customizable configuration models for aiogram_cmds.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+ScopeType = Literal[
+    "default",
+    "all_private_chats",
+    "all_group_chats",
+    "all_chat_admins",
+    "chat",
+    "chat_admins",
+    "chat_member",
+]
+
+
+class CommandDef(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    # Either use i18n_key OR inline descriptions per language
+    i18n_key: str | None = None
+    descriptions: dict[str, str] = Field(default_factory=dict)
+    tags: list[str] = Field(default_factory=list)
+
+
+class ProfileDef(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    include: list[str] = Field(default_factory=list)
+    exclude: list[str] = Field(default_factory=list)
+
+
+class ScopeDef(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    scope: ScopeType
+    profile: str
+    chat_id: int | None = None
+    user_id: int | None = None
+    languages: list[str] = Field(default_factory=list)  # empty = use global languages
+
+
+class MenuButtonDef(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    mode: Literal["commands", "default"] = "commands"
+
+
+class CmdsConfig(BaseModel):
+    """
+    Full customizable configuration:
+    - languages, fallback language, i18n key prefix
+    - commands registry (with i18n_key or inline descriptions)
+    - profiles: named sets of commands (include/exclude)
+    - scopes: where to apply which profile
+    - menu button config
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    languages: list[str] = ["en"]
+    fallback_language: str = "en"
+    i18n_key_prefix: str = "cmd"
+    commands: dict[str, CommandDef] = Field(default_factory=dict)
+    profiles: dict[str, ProfileDef] = Field(default_factory=dict)
+    scopes: list[ScopeDef] = Field(default_factory=list)
+    menu_button: MenuButtonDef = Field(default_factory=MenuButtonDef)

aiogram_cmds/dynamic.py

@@ -0,0 +1,39 @@
+"""
+Dynamic command management for runtime profile changes.
+"""
+
+from aiogram import Bot
+from aiogram.types import BotCommandScopeChat, BotCommandScopeChatMember
+
+from .builders_configured import build_from_config
+from .customize import CmdsConfig
+from .registry import CommandRegistry
+from .translator import Translator
+
+
+async def set_user_profile(
+    bot: Bot,
+    cfg: CmdsConfig,
+    *,
+    translator: Translator | None,
+    user_id: int,
+    chat_id: int | None,
+    profile: str,
+    language: str,
+) -> None:
+    """
+    Dynamically apply a profile to a user (optionally in a specific chat).
+    """
+    reg = CommandRegistry(cfg)
+    names = list(reg.resolve_profile_commands(profile))
+    cmds = build_from_config(
+        reg, names, lang=language, translator=translator, key_prefix=cfg.i18n_key_prefix
+    )
+
+    scope = (
+        BotCommandScopeChat(chat_id=user_id)
+        if chat_id is None
+        else BotCommandScopeChatMember(chat_id=chat_id, user_id=user_id)
+    )
+
+    await bot.set_my_commands(cmds, scope=scope, language_code=language)

aiogram_cmds/manager.py

@@ -0,0 +1,148 @@
+"""
+High-level manager that supports:
+1) Simple mode (CmdsSettings + CommandPolicy -> list of command names)
+2) Full customizable mode (CmdsConfig + ProfileResolver -> profiles & scopes)
+
+Use whichever you provide. If both are provided, config mode is used for setup_all(),
+and update_user_commands() will prefer the profile resolver if present; otherwise falls
+back to policy-based names.
+"""
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from aiogram import Bot
+
+from .apply import apply_config
+from .dynamic import set_user_profile
+from .policy import CommandPolicy, Flags, ProfileResolver, default_policy
+from .setters import (
+    set_user_commands_by_flags,
+    setup_all_command_scopes,
+)
+from .settings import CmdsSettings
+from .translator import Translator
+
+if TYPE_CHECKING:
+    from .customize import CmdsConfig
+
+logger = logging.getLogger(__name__)
+
+
+class CommandScopeManager:
+    def __init__(
+        self,
+        bot: Bot,
+        *,
+        settings: CmdsSettings | None = None,
+        config: Optional["CmdsConfig"] = None,
+        translator: Translator | None = None,
+        policy: CommandPolicy | None = None,
+        profile_resolver: ProfileResolver | None = None,
+    ) -> None:
+        self.bot = bot
+        self.settings = settings or CmdsSettings()
+        self.config = config
+        self.translator = translator
+        self.policy = policy or default_policy
+        self.profile_resolver = profile_resolver
+
+    async def update_user_commands(
+        self,
+        user_id: int,
+        is_registered: bool,
+        has_vehicle: bool,
+        is_during_registration: bool = False,
+        user_language: str = "en",
+        chat_id: int | None = None,
+    ) -> None:
+        flags = Flags(
+            is_registered=is_registered,
+            has_vehicle=has_vehicle,
+            is_during_registration=is_during_registration,
+        )
+
+        try:
+            if self.config and self.profile_resolver:
+                profile = self.profile_resolver(flags)
+                await set_user_profile(
+                    self.bot,
+                    self.config,
+                    translator=self.translator,
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    profile=profile,
+                    language=user_language,
+                )
+            else:
+                # Classic mode: compute names via policy
+                await set_user_commands_by_flags(
+                    self.bot,
+                    user_id,
+                    is_registered=is_registered,
+                    has_vehicle=has_vehicle,
+                    is_during_registration=is_during_registration,
+                    user_language=user_language,
+                    policy=self.policy,
+                    translator=self.translator,
+                    key_prefix=self.settings.i18n_key_prefix,
+                )
+        except Exception as e:
+            logger.error(
+                "Failed to update user commands for user %d: %s",
+                user_id,
+                e,
+                exc_info=True,
+            )
+
+        # Human-friendly log
+        if is_during_registration:
+            status = "registration"
+        elif is_registered and has_vehicle:
+            status = "onboarded"
+        elif is_registered and not has_vehicle:
+            status = "registered_no_vehicle"
+        else:
+            status = "guest"
+
+        logger.info(
+            "Updated commands for user %s: %s (registered=%s, vehicle=%s, during_registration=%s)",
+            user_id,
+            status,
+            is_registered,
+            has_vehicle,
+            is_during_registration,
+        )
+
+    async def clear_user_commands(self, user_id: int) -> None:
+        from aiogram.types import BotCommandScopeChat
+
+        try:
+            await self.bot.delete_my_commands(
+                scope=BotCommandScopeChat(chat_id=user_id)
+            )
+            logger.info("Cleared commands for user %s", user_id)
+        except Exception as e:
+            logger.error(
+                "Failed to clear commands for user %d: %s", user_id, e, exc_info=True
+            )
+
+    async def setup_all(self) -> None:
+        """
+        Setup all command scopes + menu button.
+        - If a full CmdsConfig is provided: apply_config (full customizable mode)
+        - Else: setup_all_command_scopes (classic mode)
+        """
+        try:
+            if self.config:
+                await apply_config(self.bot, self.config, translator=self.translator)
+            else:
+                await setup_all_command_scopes(
+                    self.bot,
+                    languages=tuple(self.settings.languages),
+                    translator=self.translator,
+                    key_prefix=self.settings.i18n_key_prefix,
+                    menu_button=self.settings.menu_button,
+                )
+        except Exception as e:
+            logger.error("Failed to setup all commands: %s", e, exc_info=True)

aiogram_cmds/policy.py

@@ -0,0 +1,38 @@
+"""
+Policies & flags:
+- CommandPolicy: returns a list of command names from user Flags.
+- ProfileResolver: returns a profile name (for config-driven mode).
+"""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class Flags:
+    """User flags that determine which commands are available."""
+
+    is_registered: bool
+    has_vehicle: bool
+    is_during_registration: bool = False
+
+
+class CommandPolicy(Protocol):
+    """Protocol for command policy functions."""
+
+    def __call__(self, flags: Flags) -> list[str]: ...
+
+
+class ProfileResolver(Protocol):
+    """Resolve a profile name for a given user Flags (for CmdsConfig mode)."""
+
+    def __call__(self, flags: Flags) -> str: ...
+
+
+def default_policy(flags: Flags) -> list[str]:
+    """
+    Minimal, project-agnostic command policy.
+    """
+    if flags.is_during_registration or not flags.is_registered:
+        return ["start", "cancel"]
+    return ["start", "help", "cancel", "profile", "settings"]

aiogram_cmds/registry.py

@@ -0,0 +1,21 @@
+"""
+Command registry for managing profiles and commands in CmdsConfig.
+"""
+
+from .customize import CmdsConfig, CommandDef, ProfileDef
+
+
+class CommandRegistry:
+    def __init__(self, cfg: CmdsConfig):
+        self.cfg = cfg
+
+    def resolve_profile_commands(self, profile: str) -> list[str]:
+        p: ProfileDef | None = self.cfg.profiles.get(profile)
+        if not p:
+            return []
+        keep = [n for n in p.include if n in self.cfg.commands]
+        exclude = set(p.exclude)
+        return [n for n in keep if n not in exclude]
+
+    def get_command(self, name: str) -> CommandDef | None:
+        return self.cfg.commands.get(name)

aiogram_cmds/setters.py

@@ -0,0 +1,92 @@
+"""
+Simple (classic) setters for per-user and global scopes.
+"""
+
+import logging
+from collections.abc import Iterable
+
+from aiogram import Bot
+from aiogram.types import (
+    BotCommandScopeAllPrivateChats,
+    BotCommandScopeChat,
+    BotCommandScopeDefault,
+    MenuButtonCommands,
+    MenuButtonDefault,
+)
+
+from .builder import build_bot_commands
+from .policy import CommandPolicy, Flags, default_policy
+from .translator import Translator
+
+logger = logging.getLogger(__name__)
+
+
+async def set_user_commands_by_flags(
+    bot: Bot,
+    user_id: int,
+    *,
+    is_registered: bool,
+    has_vehicle: bool,
+    is_during_registration: bool = False,
+    user_language: str = "en",
+    policy: CommandPolicy = default_policy,
+    translator: Translator | None = None,
+    key_prefix: str = "cmd",
+) -> None:
+    names = policy(
+        Flags(
+            is_registered=is_registered,
+            has_vehicle=has_vehicle,
+            is_during_registration=is_during_registration,
+        )
+    )
+    commands = build_bot_commands(
+        names, lang=user_language, translator=translator, key_prefix=key_prefix
+    )
+    # Per-chat override (user's private chat)
+    await bot.set_my_commands(
+        commands=commands,
+        scope=BotCommandScopeChat(chat_id=user_id),
+        language_code=user_language,
+    )
+
+
+async def clear_user_commands(bot: Bot, user_id: int) -> None:
+    # Delete per-chat override (falls back to broader scopes)
+    await bot.delete_my_commands(scope=BotCommandScopeChat(chat_id=user_id))
+
+
+async def setup_all_command_scopes(
+    bot: Bot,
+    *,
+    languages: tuple[str, ...],
+    translator: Translator | None = None,
+    key_prefix: str = "cmd",
+    menu_button: str = "commands",
+    default_commands: Iterable[str] | None = None,
+) -> None:
+    """
+    Configure default/global command sets and the menu button for classic mode.
+    """
+    base_names = list(default_commands or ["start", "help"])
+
+    # default scope without language as a fallback
+    fallback_cmds = build_bot_commands(
+        base_names, lang=languages[0], translator=translator, key_prefix=key_prefix
+    )
+    await bot.set_my_commands(fallback_cmds, scope=BotCommandScopeDefault())
+
+    # language-specific sets for private chats (most common case)
+    for lang in languages:
+        cmds = build_bot_commands(
+            base_names, lang=lang, translator=translator, key_prefix=key_prefix
+        )
+        await bot.set_my_commands(
+            cmds, scope=BotCommandScopeAllPrivateChats(), language_code=lang
+        )
+
+    # Menu button setup
+    if menu_button == "commands":
+        await bot.set_chat_menu_button(menu_button=MenuButtonCommands())
+    else:
+        await bot.set_chat_menu_button(menu_button=MenuButtonDefault())

aiogram_cmds/settings.py

@@ -0,0 +1,54 @@
+"""
+Standalone settings for aiogram_cmds package.
+
+This module provides settings dataclass and configuration loading
+from pyproject.toml, making the library configurable without hardcoded values.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import tomllib
+from pydantic import BaseModel, ConfigDict, field_validator
+
+
+class CmdsSettings(BaseModel):
+    """Configuration settings for command management."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+    languages: tuple[str, ...] = ("en",)
+    fallback_language: str = "en"
+    i18n_key_prefix: str = "cmd"
+    profile: str = "default"
+    menu_button: str = "commands"  # "commands" | "default"
+
+    @field_validator("languages", mode="before")
+    @classmethod
+    def _ensure_nonempty(cls, v):
+        if v is None:
+            return ("en",)
+        if isinstance(v, str):
+            return (v,)
+        if isinstance(v, (list, tuple)):
+            return tuple(v) if v else ("en",)
+        return ("en",)
+
+
+def load_settings(pyproject_path: Path | None = None) -> CmdsSettings:
+    """
+    Load settings from [tool.aiogram_cmds] in pyproject.toml (if present).
+    """
+    p = pyproject_path or Path("pyproject.toml")
+    if not p.exists():
+        return CmdsSettings()
+    try:
+        data = tomllib.loads(p.read_text(encoding="utf-8"))
+        cfg = (data.get("tool") or {}).get("aiogram_cmds") or {}
+        return CmdsSettings.model_validate(cfg)
+    except Exception as ex:  # pragma: no cover
+        logging.getLogger(__name__).warning(
+            "aiogram_cmds: failed to load settings: %s", ex
+        )
+        return CmdsSettings()

aiogram_cmds/translator.py

@@ -0,0 +1,33 @@
+"""
+Translator protocol and adapters for i18n integration.
+"""
+
+from typing import Protocol
+
+
+class Translator(Protocol):
+    """Protocol for translation functions."""
+
+    def __call__(self, key: str, *, locale: str) -> str | None: ...
+
+
+def build_translator_from_i18n(i18n_obj) -> Translator:
+    """
+    Build translator adapter from an aiogram i18n instance exposing gettext(key, locale=?).
+    """
+
+    def _t(key: str, *, locale: str) -> str | None:
+        try:
+            value = i18n_obj.gettext(key, locale=locale)
+            if not value or value == key:
+                return None
+            return value
+        except Exception:
+            return None
+
+    return _t
+
+
+def noop_translator(key: str, *, locale: str) -> str | None:
+    """No-op translator that always returns None."""
+    return None

aiogram_cmds/version.py

@@ -0,0 +1,3 @@
+"""Version information for aiogram-cmds."""
+
+__version__ = "0.1.0"

aiogram_cmds-0.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: aiogram-cmds
+Version: 0.1.0
+Summary: Command management library for aiogram v3
+Project-URL: Homepage, https://github.com/ArmanAvanesyan/aiogram-cmds
+Project-URL: Repository, https://github.com/ArmanAvanesyan/aiogram-cmds
+Project-URL: Issues, https://github.com/ArmanAvanesyan/aiogram-cmds/issues
+Author: aiogram-cmds contributors
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiogram>=3.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: bandit>=1.7.0; extra == 'dev'
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.0.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=4.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# aiogram-cmds
+
+[![CI](https://github.com/ArmanAvanesyan/aiogram-cmds/workflows/CI/badge.svg)](https://github.com/ArmanAvanesyan/aiogram-cmds/actions)
+[![PyPI](https://img.shields.io/pypi/v/aiogram-cmds.svg)](https://pypi.org/project/aiogram-cmds/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiogram-cmds.svg)](https://pypi.org/project/aiogram-cmds/)
+[![License](https://img.shields.io/pypi/l/aiogram-cmds.svg)](https://pypi.org/project/aiogram-cmds/)
+
+**Command management library for aiogram v3** - Manage Telegram bot commands with i18n support, user profiles, and dynamic scopes.
+
+## ✨ Features
+
+* **Simple & Advanced Modes**: Start simple, scale to complex configurations
+* **i18n Integration**: Built-in support for aiogram i18n with fallback handling
+* **User Profiles**: Dynamic command sets based on user status (guest, registered, etc.)
+* **Multiple Scopes**: Support for all Telegram command scopes (private, group, admin, etc.)
+* **Auto-Setup**: One-call setup with sensible defaults
+* **Type-Safe**: Full type hints and strict type checking
+* **Production Ready**: Comprehensive testing, CI/CD, and documentation
+
+## 📦 Installation
+
+```bash
+# Basic installation
+pip install aiogram-cmds
+
+# With Redis support (for multi-worker deployments)
+pip install aiogram-cmds[redis]
+```
+
+## ⚡ Quick Start
+
+### Auto-Setup (Recommended)
+
+```python
+from aiogram import Bot, Dispatcher
+from aiogram_cmds.auto_setup import setup_commands_auto
+
+async def on_startup():
+    # Automatically set up commands with sensible defaults
+    command_manager = await setup_commands_auto(bot)
+    # Commands are ready to use!
+
+# Your handlers
+@dp.message(Command("start"))
+async def handle_start(message: Message):
+    await message.answer("Welcome! Use /help to see available commands.")
+```
+
+### Simple Mode
+
+```python
+from aiogram import Bot, Dispatcher
+from aiogram_cmds import CommandScopeManager, load_settings, build_translator_from_i18n
+
+# Load settings from pyproject.toml or use defaults
+settings = load_settings()
+translator = build_translator_from_i18n(i18n)  # Your aiogram i18n instance
+
+# Create manager
+manager = CommandScopeManager(bot, settings=settings, translator=translator)
+
+# Set up all command scopes
+await manager.setup_all()
+
+# Update user commands dynamically
+await manager.update_user_commands(
+    user_id=12345,
+    is_registered=True,
+    has_vehicle=False,
+    user_language="en"
+)
+```
+
+### Advanced Mode
+
+```python
+from aiogram_cmds import CmdsConfig, CommandDef, ProfileDef, ScopeDef, MenuButtonDef
+
+# Define your command configuration
+config = CmdsConfig(
+    languages=["en", "ru", "es"],
+    commands={
+        "start": CommandDef(i18n_key="start.desc"),
+        "help": CommandDef(i18n_key="help.desc"),
+        "profile": CommandDef(i18n_key="profile.desc"),
+        "admin": CommandDef(i18n_key="admin.desc"),
+    },
+    profiles={
+        "guest": ProfileDef(include=["start", "help"]),
+        "user": ProfileDef(include=["start", "help", "profile"]),
+        "admin": ProfileDef(include=["start", "help", "profile", "admin"]),
+    },
+    scopes=[
+        ScopeDef(scope="all_private_chats", profile="guest"),
+        ScopeDef(scope="chat", chat_id=12345, profile="admin"),
+    ],
+    menu_button=MenuButtonDef(mode="commands"),
+)
+
+# Create manager with custom profile resolver
+def my_profile_resolver(flags):
+    if flags.is_admin:
+        return "admin"
+    elif flags.is_registered:
+        return "user"
+    return "guest"
+
+manager = CommandScopeManager(
+    bot, 
+    config=config, 
+    profile_resolver=my_profile_resolver
+)
+await manager.setup_all()
+```
+
+## 🎯 Use Cases
+
+### E-commerce Bot
+```python
+# Different commands for different user states
+profiles = {
+    "visitor": ProfileDef(include=["start", "catalog", "help"]),
+    "customer": ProfileDef(include=["start", "catalog", "cart", "orders", "help"]),
+    "vip": ProfileDef(include=["start", "catalog", "cart", "orders", "vip_offers", "help"]),
+}
+```
+
+### Admin Bot
+```python
+# Admin commands only for specific users
+scopes = [
+    ScopeDef(scope="all_private_chats", profile="user"),
+    ScopeDef(scope="chat_member", chat_id=12345, user_id=67890, profile="admin"),
+]
+```
+
+### Multi-Language Bot
+```python
+# Commands in multiple languages
+config = CmdsConfig(
+    languages=["en", "ru", "es", "fr"],
+    commands={
+        "start": CommandDef(i18n_key="commands.start"),
+        "help": CommandDef(i18n_key="commands.help"),
+    }
+)
+```
+
+## 📚 Documentation
+
+👉 **[Full Documentation](https://aiogram-cmds.dev)** ← Start here!
+
+* **[Quickstart](https://aiogram-cmds.dev/quickstart/)** - Get started in 5 minutes
+* **[Configuration](https://aiogram-cmds.dev/configuration/)** - Complete configuration guide
+* **[API Reference](https://aiogram-cmds.dev/api/)** - Full API documentation
+* **[Tutorials](https://aiogram-cmds.dev/tutorials/)** - Step-by-step guides
+* **[Examples](https://aiogram-cmds.dev/examples/)** - Complete working examples
+
+## 🏗️ Architecture
+
+aiogram-cmds provides three levels of complexity:
+
+1. **Auto-Setup**: Zero configuration, works out of the box
+2. **Simple Mode**: Settings-based configuration with policies
+3. **Advanced Mode**: Full control with profiles, scopes, and custom resolvers
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Auto-Setup    │    │   Simple Mode    │    │  Advanced Mode  │
+│                 │    │                  │    │                 │
+│ setup_commands_ │    │ CmdsSettings +   │    │ CmdsConfig +    │
+│ auto()          │    │ CommandPolicy    │    │ ProfileResolver │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+         │                       │                       │
+         └───────────────────────┼───────────────────────┘
+                                 │
+                    ┌──────────────────┐
+                    │ CommandScopeMgr  │
+                    │                  │
+                    │ • setup_all()    │
+                    │ • update_user()  │
+                    │ • clear_user()   │
+                    └──────────────────┘
+```
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ArmanAvanesyan/aiogram-cmds.git
+cd aiogram-cmds
+
+# Set up development environment
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check .
+uv run ruff format .
+```
+
+## 💬 Community & Support
+
+* 💬 **[Discussions](https://github.com/ArmanAvanesyan/aiogram-cmds/discussions)** - Questions, ideas, and community chat
+* 🐛 **[Issues](https://github.com/ArmanAvanesyan/aiogram-cmds/issues)** - Bug reports and feature requests
+* 📖 **[Documentation](https://aiogram-cmds.dev)** - Complete guides and API reference
+
+## 🔒 Security
+
+For security issues, see [SECURITY.md](SECURITY.md).
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+* Built for [aiogram v3](https://github.com/aiogram/aiogram) - Modern Telegram Bot API framework
+* Inspired by the need for robust command management in production environments
+
+## 📊 Project Status
+
+- ✅ **Core Features**: Command management, i18n, profiles, scopes
+- ✅ **Documentation**: Comprehensive guides and API reference
+- ✅ **Testing**: Unit, integration, and performance tests
+- ✅ **CI/CD**: Automated testing and deployment
+- 🚧 **Examples**: Working bot examples (in progress)
+- 🔮 **Future**: Rate limiting, caching, advanced analytics
+
+---
+
+**Made with ❤️ for the aiogram community**

aiogram_cmds-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+aiogram_cmds/__init__.py,sha256=DGYWAquSElFPKqOyqQd8VVjAKwVviC_1dZ4uuT0qmrs,2240
+aiogram_cmds/apply.py,sha256=FwtmZD-xxnn_-otfMYZfqPoRqbaQDaCx0p8edBCh54Q,2662
+aiogram_cmds/auto_setup.py,sha256=OC2oCW3Y8bh30cA2-grVtidLWjhrnFKG3j1tQS-kXOA,4921
+aiogram_cmds/builder.py,sha256=ZlCJhpc2GPFcfmrqCz7aUfggMwjmB0X4lVUxJ5BywsI,2347
+aiogram_cmds/builders_configured.py,sha256=sihthu9XG6Xwj3I-ystLR-DEQ5OetMORXBmcTueKmcs,1952
+aiogram_cmds/customize.py,sha256=pLTzVw2W8vng5WN9CeTeMXHGbp8R9z_HJfYEz6zNfc4,1934
+aiogram_cmds/dynamic.py,sha256=mGA05euNAbdc4rN-u8ROgUzaMk9U0-DLSDnUOLQAItc,1062
+aiogram_cmds/manager.py,sha256=fuF_1wR_0C--b5v1rl0dRmh0IiPmNcuEMgNjSb8nTLY,4990
+aiogram_cmds/policy.py,sha256=Ex68-vtYonUqbdC1p00GXSPSToHW5hTLF3s01snr0c0,990
+aiogram_cmds/registry.py,sha256=5-tG-Cz3pAg4iNHiKuOG2RM3C-kXi1hzO7k6j0istNc,646
+aiogram_cmds/setters.py,sha256=dKkM0VIoug2-LJfzTnUgpdB-YXD720hivXn3ssswnuI,2748
+aiogram_cmds/settings.py,sha256=UctpHLsbP_jthkX1_zIKB_2ZSygz9W9v0n8WDiHWHTs,1656
+aiogram_cmds/translator.py,sha256=499Y3nmu78vj-TZcaEWpN59ycV4osjHOgELsvOUzMuY,818
+aiogram_cmds/version.py,sha256=NdAm1Oirm_zG5tKFJB3vRPaOpBT057H5usna3_9MM-g,67
+aiogram_cmds-0.1.0.dist-info/METADATA,sha256=JZHTu58X1p53jcD8f31w7LIq4G2ORCvwOAeOPwldLRk,10002
+aiogram_cmds-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aiogram_cmds-0.1.0.dist-info/licenses/LICENSE,sha256=uboqwLY50frOnHJ4Mo4x3F85t7WiVK5CJRNBNokhSOg,1085
+aiogram_cmds-0.1.0.dist-info/RECORD,,

aiogram_cmds-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aiogram_cmds-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 aiogram-sentinel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.