signal-bot/signal_bot/help_command.py
Krzysztof kuhy Rudnicki 14d422295f feat: a word with two meanings gets the one made of steel
!pułapka (and !trap, !sidła, !wnyk, !potrzask, 26 spellings in all) posts a
photograph of the literal device -- a bear trap, a mousetrap, a snare, a fish
weir -- captioned with what Commons says it is.

The pool is 2218 Commons page ids, harvested by tool/gen_traps.py from a
curated seed list and committed. Page ids and not filenames on purpose: a
filename carries photographers' and sitters' names, and one of those
colliding with a label somebody mints from the chat would wedge
check_personal_data.py permanently, over data nobody can edit by hand.
_repo_vocabulary() subtracts aliases.json and nothing else, so it would not
have caught it. An integer cannot carry a name.

Nothing is cached. !papież caches because 267 portraits are a closed set a
group works through; a uniform draw from 2218 warms a cache essentially
never, so this fetches per call the way !kot and !pies do.

What the harvest measured, and now enforces:

- five plausible seed categories do not exist (Snares, Man traps, Hunting
  traps, Wasp traps, Animal trapping). A missing category is an empty answer,
  not an error, so verify_seeds() asks Commons before harvesting and fails
  loudly naming all of them.
- depth three from Category:Fish traps reaches Alfred Sisley's net paintings.
  Depth one, from seeds picked by hand.
- "<thing> in art" categories are paintings: Mousetraps in art put a Robert
  Campin altarpiece in the pool. Pruned by pattern, since Commons mints a new
  one whenever somebody needs it. Booby traps, the Wolfsangel, camera traps
  and animals dying in traps are pruned by name.
- Commons rate-limits hard, so a partial harvest must not be committed
  silently: 429 backs off, and a short pool refuses to write at all.

Descriptions are HTML and sometimes say nothing, so the tags come out, the
Fisheries records' trailing catalogue list is cut, a description naming only
the country falls back to the filename, and the file's own page is always
linked.

!łapka is not an alias: it resolves to !papa at distance two, which
test_nearest.py fails on, and rightly -- the suggestion would be a coin toss.

signal_bot/commons.py is the imageinfo query both Commons commands now share;
portraits.py keeps its behaviour and its tests unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01416TegJ3sa8xL5qGGgrygP
2026-08-31 18:01:27 +02:00

155 lines
6.0 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
from signal_bot.pack_command import NAME_PREFIX
if TYPE_CHECKING:
from collections.abc import Sequence
from signal_bot.context import CommandContext
from signal_bot.decorators import Decorator
from signal_bot.registry import Command, 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", "trap")),
("Papież", ("pope",)),
("Propozycje", ("suggest",)),
(
"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."
# The private album, when a group has one. Its heading is here and its
# commands are not: they come from a file this repository never sees, so
# GROUPS could not name them even if it wanted to -- and naming an optional
# command there would make !pomoc fail in every group that has no pack.
PACK_HEADING: Final = "Zdjęcia"
PACK_HINT: Final = "Kilka naraz ({first} {second}) = zdjęcie, na którym są wszyscy."
# The two commands that act on the album rather than posting one person from
# it. Their own block, so the "kilka naraz" hint above keeps describing the
# people entries it was written for. Spelled from NAME_PREFIX rather than
# imported, so !pomoc does not pull the ingest path in just to print a line.
ALBUM_HEADING: Final = "Album"
ALBUM_NAMES: Final = (f"{NAME_PREFIX}add", f"{NAME_PREFIX}random")
def _line(command: Command) -> str:
"""One command as !pomoc prints it."""
return f"{command.primary} — {command.description}"
def _pack_block(commands: Sequence[Command]) -> str:
"""The album's own block, or "" for a group that has no album.
Built from whatever is registered rather than from a table, because the
entries are private data: this file cannot know how many there are or
what they are called, and must not need to.
"""
entries = [c for c in commands if c.name.startswith(NAME_PREFIX) and c.name not in ALBUM_NAMES]
if not entries:
return ""
lines = [PACK_HEADING, *(_line(command) for command in entries)]
if len(entries) > 1:
lines.append(PACK_HINT.format(first=entries[0].primary, second=entries[1].primary))
return "\n".join(lines)
def _album_block(commands: Sequence[Command]) -> str:
"""The !add_photo / !random block, or "" where there is no album."""
entries = [c for c in commands if c.name in ALBUM_NAMES]
if not entries:
return ""
return "\n".join([ALBUM_HEADING, *(_line(command) for command in entries)])
def render_help(commands: Sequence[Command], group_id: str) -> str:
"""Render the command list for one group, grouped, in registration order.
Per group, because a command can be scoped to one: the private album
exists in its own groups and nowhere else, and a help text that listed it
everywhere would announce it to every group the bot is in.
"""
visible = [command for command in commands if command.allowed_in(group_id)]
by_name = {command.name: command for command in visible}
# 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.extend(block for block in (_pack_block(visible), _album_block(visible)) if block)
blocks.append(
"\n".join(
_line(c)
for c in visible
if c.name not in grouped and not c.name.startswith(NAME_PREFIX)
)
)
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, ctx.group_id))
wrapped = decorate(handler) if decorate is not None else handler
registry.register(COMMAND_NAME, table[COMMAND_NAME], wrapped, DESCRIPTION)