mirror of
https://github.com/kuhyx/signal-bot.git
synced 2026-11-11 13:27:48 +01:00
Krzysztof kuhy Rudnicki
ca38147576
Thirteen commands, and the only list of them was a README table nobody in a Signal group can read — which had itself gone stale two releases earlier, still advertising four commands after nine more had shipped. 0.1.1 gave each command an output that says what the command is; that only helps once you already know to type it. !pomoc (also !pomocy, !help, !komendy, !commands) prints all fourteen, grouped, one Polish line each. The interesting part is that it cannot go stale. CommandRegistry.register now takes the description as a REQUIRED argument, so a command that does not explain itself does not compile; and render_help prints any command that help_command.GROUPS forgot to file, under no heading, rather than dropping it. Two independent ways to fail closed, because the README proved that a hand-maintained second list is a list that drifts. Command also gained `primary`, the first raw alias. The trigger set could not supply it: those are folded skeletons in an unordered frozenset, so all that survives of "!papież" there is "!papiez", and the styled Unicode aliases come out as zalgo. aliases.json already lists the canonical Polish spelling first. The full trigger table moves to DOCS-commands.md. It did not fit in README — that file was already sitting exactly on the shared 250-line cap, and the gate caught the overflow on the first commit attempt. Exercised in testbot at the unbumped version before this bump: the live dispatcher ran it and posted the list, journal clean. pytest 708 green at 100% branch coverage, e2e green including a new scenario that asserts !pomoc mentions a command registered by a different module. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017w1HZ3cZ7neL3rFdQ6VMBA
101 lines
3.6 KiB
Python
101 lines
3.6 KiB
Python
# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
|
|
"""The !pomoc command: every command the bot has, and what each one does.
|
|
|
|
Nothing in the chat used to say the commands existed. The README's table was
|
|
the only list, it was stale within two releases, and nobody in a Signal group
|
|
reads a README anyway -- so the list is built from the registry itself. A
|
|
command cannot be registered without a description (``CommandRegistry.register``
|
|
requires one), and any command this module's ``GROUPS`` does not mention is
|
|
printed anyway, under no heading. Between those two, a new command cannot
|
|
quietly fail to appear here.
|
|
|
|
The trigger printed is ``Command.primary``, the first *raw* alias, because
|
|
``Command.triggers`` holds folded skeletons in an unordered set: "!papież"
|
|
survives there only as "!papiez", and the styled Unicode aliases would come
|
|
out as the zalgo they are.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import TYPE_CHECKING, Final
|
|
|
|
from signal_bot.animals import load_aliases
|
|
|
|
if TYPE_CHECKING:
|
|
from collections.abc import Sequence
|
|
|
|
from signal_bot.decorators import Decorator
|
|
from signal_bot.registry import Command, CommandContext, CommandRegistry
|
|
|
|
COMMAND_NAME: Final = "help"
|
|
DESCRIPTION: Final = "ta lista"
|
|
|
|
HEADING: Final = "Komendy"
|
|
|
|
# Which commands sit under which heading, in the order they are printed.
|
|
# Anything missing from here still gets printed, in a block of its own -- see
|
|
# the module docstring.
|
|
GROUPS: Final[tuple[tuple[str, tuple[str, ...]], ...]] = (
|
|
("Obrazki", ("cat", "dog", "gecko")),
|
|
("Papież", ("pope",)),
|
|
(
|
|
"Statystyki",
|
|
(
|
|
"stats_today",
|
|
"stats_yesterday",
|
|
"stats_week",
|
|
"stats_month",
|
|
"stats_year",
|
|
"stats_records",
|
|
"stats_crown",
|
|
"stats_weekdays",
|
|
"stats_me",
|
|
),
|
|
),
|
|
)
|
|
|
|
# Only the canonical spelling is listed above, but half the group types the
|
|
# English one. Without this line "!cat" looks broken to somebody holding a
|
|
# list that says "!kot".
|
|
SPELLINGS: Final = "Każda komenda ma też inne pisownie, np. !cat, !stats, !week."
|
|
|
|
|
|
def _line(command: Command) -> str:
|
|
"""One command as !pomoc prints it."""
|
|
return f"{command.primary} — {command.description}"
|
|
|
|
|
|
def render_help(commands: Sequence[Command]) -> str:
|
|
"""Render the whole command list, grouped, in registration order."""
|
|
by_name = {command.name: command for command in commands}
|
|
# Indexed, not .get(): a name in GROUPS that no command answers to is a
|
|
# typo in this file, and it should fail loudly the first time the command
|
|
# is used rather than silently drop a line.
|
|
grouped = {name for _, names in GROUPS for name in names}
|
|
blocks = [HEADING]
|
|
for title, names in GROUPS:
|
|
blocks.append("\n".join([title, *(_line(by_name[name]) for name in names)]))
|
|
blocks.append("\n".join(_line(c) for c in commands if c.name not in grouped))
|
|
blocks.append(SPELLINGS)
|
|
return "\n\n".join(blocks)
|
|
|
|
|
|
def register_help_command(
|
|
registry: CommandRegistry,
|
|
*,
|
|
decorate: Decorator | None = None,
|
|
aliases: dict[str, list[str]] | None = None,
|
|
) -> None:
|
|
"""Register !pomoc, which reads the registry it is registered on.
|
|
|
|
The registry is read when the command *runs*, not when it is registered,
|
|
so this may be wired up in any order and still list everything.
|
|
"""
|
|
table = load_aliases() if aliases is None else aliases
|
|
|
|
async def handler(ctx: CommandContext) -> None:
|
|
await ctx.reply(render_help(registry.commands))
|
|
|
|
wrapped = decorate(handler) if decorate is not None else handler
|
|
registry.register(COMMAND_NAME, table[COMMAND_NAME], wrapped, DESCRIPTION)
|