#!/usr/bin/env python3 """Генератор справки по командам. Из единственного источника правды (commands.yaml) делает: * ответ /help для каждого бота — только его команды; * docs/COMMANDS.md — общий справочник в репозитории; * подсказку при опечатке. Зачем: команды не должны жить в голове и не должны быть зашиты в код. Добавить команду = добавить запись в commands.yaml, а справка обновится сама. Использование: python3 gen_help.py — показать справку всем ботам python3 gen_help.py --bot adm — справка одного бота python3 gen_help.py --command restart — подробно про команду python3 gen_help.py --markdown FILE — записать общий справочник python3 gen_help.py --suggest statsu — подсказать похожую команду """ from __future__ import annotations import argparse import difflib import os import re import sys try: import yaml except ImportError: # запасной разбор, если PyYAML не установлен yaml = None CATALOG = os.getenv("COMMANDS_FILE", os.path.join(os.path.dirname(os.path.abspath(__file__)), "commands.yaml")) def load(path: str = CATALOG) -> dict: """Читает справочник. Если PyYAML нет — разбирает встроенным способом.""" with open(path, encoding="utf-8") as fh: text = fh.read() if yaml is not None: return yaml.safe_load(text) return _simple_parse(text) def _simple_parse(text: str) -> dict: """Минимальный разбор YAML для нашего формата — без внешних зависимостей. Понимает списки словарей с простыми значениями и списками строк. Нужен, чтобы справка работала даже там, где PyYAML не установлен. """ data: dict = {"bots": {}, "commands": []} section = None item: dict | None = None list_key = None bot_key = None bot_item: dict | None = None for raw in text.split("\n"): line = raw.rstrip() if not line or line.lstrip().startswith("#"): continue stripped = line.strip() if line.startswith("bots:") and not line.startswith(" "): section, item, bot_item = "bots", None, None continue if line.startswith("commands:") and not line.startswith(" "): section, item, bot_item = "commands", None, None continue if section == "bots": if line.startswith(" ") and not line.startswith(" ") and stripped.endswith(":"): bot_key = stripped[:-1] bot_item = {} data["bots"][bot_key] = bot_item continue if bot_item is not None and ":" in stripped: k, v = stripped.split(":", 1) bot_item[k.strip()] = v.strip() continue continue if section == "commands": if stripped.startswith("- "): rest = stripped[2:] # НОВАЯ КОМАНДА начинается со «- имя:» — есть двоеточие # сразу после имени поля. Элемент списка (пример, вариант) # двоеточия не имеет: «- /status». if re.match(r"^[A-Za-z_][A-Za-z0-9_]*:", rest): item = {} data["commands"].append(item) list_key = None k, v = rest.split(":", 1) item[k.strip()] = v.strip() continue if list_key and item is not None: item[list_key].append(rest.strip().strip('"\'')) continue continue if item is None: continue if stripped.endswith(":"): list_key = stripped[:-1] item[list_key] = [] continue if ":" in stripped: k, v = stripped.split(":", 1) item[k.strip()] = v.strip().strip('"\'') list_key = None return data def _named_commands(data: dict) -> list[dict]: """Только записи с именем команды. Разбор может дать служебные записи без поля command — они пропускаются, чтобы справка не падала. """ return [c for c in data.get("commands", []) if c.get("command")] def commands_for(data: dict, bot: str) -> list[dict]: """Команды бота: его собственные плюс общие (bot: all).""" out = [] for cmd in _named_commands(data): if cmd.get("bot") in (bot, "all"): out.append(cmd) return out def help_text(data: dict, bot: str) -> str: """Справка для бота. Коротко: название, вызов, описание.""" info = data.get("bots", {}).get(bot, {}) lines = [] if info.get("name"): lines.append(f"{info['name']} — {info.get('purpose', '')}") lines.append("") ready = [c for c in commands_for(data, bot) if c.get("status") != "planned"] planned = [c for c in commands_for(data, bot) if c.get("status") == "planned"] lines.append("Доступные команды:") for cmd in ready: access = " (только админ)" if cmd.get("access") == "admin" else "" lines.append(f"/{cmd['command']} — {cmd.get('description', '')}{access}") if planned: lines.append("") lines.append("Готовятся:") for cmd in planned: lines.append(f"/{cmd['command']} — {cmd.get('description', '')}") lines.append("") lines.append("Подробнее о команде: /help <команда>") return "\n".join(lines) def command_help(data: dict, name: str) -> str | None: """Подробная справка по одной команде.""" name = name.lstrip("/!").strip() for cmd in _named_commands(data): if cmd.get("command") == name or name in (cmd.get("aliases") or []): lines = [f"/{cmd['command']} — {cmd.get('title', '')}"] lines.append(cmd.get("description", "")) lines.append("") lines.append(f"Вызов: {cmd.get('usage', '/' + cmd['command'])}") if cmd.get("examples"): lines.append("Примеры:") for ex in cmd["examples"]: lines.append(f" {ex}") if cmd.get("aliases"): lines.append(f"Варианты: {', '.join(cmd['aliases'])}") if cmd.get("access") == "admin": lines.append("Доступ: только администратор") if cmd.get("status") == "planned": lines.append("Состояние: готовится, пока не работает") if cmd.get("bot") and cmd["bot"] != "all": lines.append(f"Бот: {data.get('bots', {}).get(cmd['bot'], {}).get('name', cmd['bot'])}") return "\n".join(lines) return None def suggest(data: dict, wrong: str | None) -> str | None: """Подсказка при опечатке: «возможно, вы имели в виду».""" if not wrong: return None names = [c["command"] for c in _named_commands(data)] close = difflib.get_close_matches(wrong.lstrip("/!").strip(), names, n=1, cutoff=0.6) if close: return f"Команда не распознана. Возможно, вы имели в виду /{close[0]}? Список: /help" return "Команда не распознана. Список команд: /help" def markdown(data: dict) -> str: """Общий справочник для репозитория.""" lines = ["# Справочник команд", "", "Файл создан автоматически из `ops/bots/commands.yaml`.", "**Правьте справочник, а не этот файл.**", ""] for bot_key, info in data.get("bots", {}).items(): cmds = [c for c in commands_for(data, bot_key) if c.get("bot") == bot_key] if not cmds: continue lines.append(f"## {info.get('name', bot_key)} — {info.get('purpose', '')}") if info.get("about"): lines.append(info["about"]) lines.append("") lines.append("| Команда | Что делает | Доступ | Состояние |") lines.append("|---|---|---|---|") for cmd in cmds: access = "админ" if cmd.get("access") == "admin" else "все" state = "готово" if cmd.get("status") != "planned" else "готовится" lines.append(f"| `{cmd.get('usage', '/' + cmd['command'])}` | " f"{cmd.get('description', '')} | {access} | {state} |") lines.append("") lines.append("## Общие команды") lines.append("") for cmd in _named_commands(data): if cmd.get("bot") == "all": lines.append(f"- `{cmd.get('usage')}` — {cmd.get('description', '')}") lines.append("") return "\n".join(lines) def main() -> int: ap = argparse.ArgumentParser(description="Генератор справки по командам") ap.add_argument("--bot", help="показать справку одного бота") ap.add_argument("--command", help="подробно про команду") ap.add_argument("--suggest", help="подсказать похожую команду") ap.add_argument("--markdown", metavar="FILE", help="записать общий справочник") ap.add_argument("--catalog", default=CATALOG, help="путь к справочнику") args = ap.parse_args() if not os.path.exists(args.catalog): print(f"справочник не найден: {args.catalog}", file=sys.stderr) return 1 data = load(args.catalog) if args.command: print(command_help(data, args.command) or "Команда не найдена") return 0 if args.suggest: print(suggest(data, args.suggest) or "") return 0 if args.markdown: with open(args.markdown, "w", encoding="utf-8") as fh: fh.write(markdown(data)) print(f"записан справочник: {args.markdown}") return 0 if args.bot: print(help_text(data, args.bot)) return 0 for bot in data.get("bots", {}): print("=" * 60) print(help_text(data, bot)) print() return 0 if __name__ == "__main__": raise SystemExit(main())