Files
buryan-infra/ops/bots/gen_help.py

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())