266 lines
11 KiB
Python
266 lines
11 KiB
Python
#!/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"<b>{info['name']}</b> — {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"<b>/{cmd['command']}</b> — {cmd.get('title', '')}"]
|
|
lines.append(cmd.get("description", ""))
|
|
lines.append("")
|
|
lines.append(f"Вызов: <code>{cmd.get('usage', '/' + cmd['command'])}</code>")
|
|
if cmd.get("examples"):
|
|
lines.append("Примеры:")
|
|
for ex in cmd["examples"]:
|
|
lines.append(f" <code>{ex}</code>")
|
|
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())
|