# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """The !wiersz command: one short public-domain Polish poem, whole. Shaped exactly like !pułapka, and for the same reason. The repository commits a pool of **identifiers** -- Commons page ids there, Wolne Lektury slugs here -- and the words arrive over the wire at the moment somebody asks. What ``commons.caption_for`` says is the rule the whole bot follows: The text is fetched at run time and posted to the group; none of it is ever written into this repository, which is why it may be free text where traps.json may not. This command was written the other way first, committing the poems themselves, and that is worth recording because it looked entirely reasonable and failed hard. ``scripts/check_personal_data.py`` refused the pack: three lines carried a real group member's name, and two still did after a filter that had already discarded 31% of the corpus. The names were at the start of a line, and a filter cannot reject those -- Polish verse capitalises every line, so a line-initial capital is the norm and not a signal. Committing several hundred Polish poems means committing several hundred Polish given names, and one collision refuses every commit on the maintainer's machine while CI, which has no private data to compare against, stays green. Slugs fixed that structurally rather than by degree, and the version that survived is also the better one: no name filter means no false positives, so the pool is far larger and poems that were being thrown away for containing an ordinary word come back. There is no cap on the rendered message, which is a decision rather than an oversight. ``commons.CAPTION_LIMIT`` bounds a caption at 220 characters because a caption is a label on a picture. A poem is the message, truncating one was ruled out when the length filter was chosen, and the worst case is bounded anyway by the caps the harvest applied: 24 lines and 1200 characters, plus a title, an author and a link. """ from __future__ import annotations import json import secrets from pathlib import Path from typing import TYPE_CHECKING, Final from signal_bot.analytics import probe from signal_bot.animals import load_aliases from signal_bot.wolnelektury import CATALOGUE, parse if TYPE_CHECKING: from collections.abc import Sequence from signal_bot.context import CommandContext from signal_bot.decorators import Decorator from signal_bot.http_client import ImageFetcher from signal_bot.registry import CommandRegistry, Handler from signal_bot.wolnelektury import Poem COMMAND_NAME: Final = "poem" DESCRIPTION: Final = "losowy wiersz" POEMS_FILE: Final = Path(__file__).with_name("poems.json") # Whole poems only, never an excerpt: a truncated poem is worse than no poem, # so these reject at harvest time rather than cutting at post time. They live # here rather than in the generator because they are the promise the pack # makes -- every committed slug is a poem this short -- and the tests assert # the shipped pack against them. MAX_LINES: Final = 24 MAX_CHARS: Final = 1200 def load_slugs(path: Path = POEMS_FILE) -> tuple[str, ...]: """Read the slug pool. The file holds Wolne Lektury slugs and nothing else, which is checked here rather than assumed -- the whole privacy argument for this command rests on the pack carrying no poem text, and this is the guard that keeps it that way when somebody regenerates it. Args: path: Where to read the pool from. Defaults to the shipped file. Returns: Every slug in the pool. Raises: ValueError: If the pool is empty or holds anything but non-empty strings. """ document = json.loads(path.read_text(encoding="utf-8")) slugs = document["poems"] if not slugs or not all(isinstance(slug, str) and slug for slug in slugs): msg = f"{path} must hold a non-empty list of Wolne Lektury slugs" raise ValueError(msg) return tuple(slugs) def random_slug(slugs: Sequence[str]) -> str: """Return one slug, uniformly at random. No memory of what came before, the same as !pułapka and for the same reason: a pool this size is not one a group works through, so a no-repeat window would be bookkeeping that never changes an answer. secrets rather than random for the reason animals.paged_url gives: the choice is not security-sensitive, but ruff's ALL rule set flags `random` and this repository forbids the noqa that would silence it. """ return slugs[secrets.randbelow(len(slugs))] def render(poem: Poem, slug: str) -> str: """The message as the group reads it: title, poem, who wrote it, where. The author's full name is safe to post and would not have been safe to commit -- see the module docstring. Posting it is the whole point of fetching it. """ return f"{poem.title}\n\n{poem.text}\n\n— {poem.author}\n{CATALOGUE.format(slug=slug)}" def poem_handler( fetcher: ImageFetcher, text_url: str, slugs: Sequence[str] | None = None, ) -> Handler: """Build the handler that posts one random poem. Raises: ValueError: If Wolne Lektury served something that is not the poem the harvest committed. The dispatcher logs and stays silent, the same as any other upstream failure -- a half-parsed poem is not something to post. """ pool = load_slugs() if slugs is None else tuple(slugs) async def handler(ctx: CommandContext) -> None: slug = random_slug(pool) # The Wolne Lektury slug, which is what the pool holds and all # it holds -- the poem, its title and its author arrive over the # wire and are never written down. See DOCS-privacy.md. probe.note_item(slug) poem = parse(await fetcher.fetch_text(text_url.format(slug=slug))) if poem is None: msg = f"wolnelektury.pl no longer serves a usable poem at {slug!r}" raise ValueError(msg) await ctx.reply(render(poem, slug)) return handler def register_poem_command( registry: CommandRegistry, fetcher: ImageFetcher, text_url: str, *, decorate: Decorator | None = None, aliases: dict[str, list[str]] | None = None, slugs: Sequence[str] | None = None, ) -> None: """Register !wiersz under every trigger aliases.json gives it.""" table = load_aliases() if aliases is None else aliases handler = poem_handler(fetcher, text_url, slugs) if decorate is not None: handler = decorate(handler) registry.register(COMMAND_NAME, table[COMMAND_NAME], handler, DESCRIPTION)