# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """``!random``: a photo from the album, optionally narrowed by custom tags. Custom tags define no commands of their own -- that is what keeps a hot-swap a data swap -- so this is the only door to a label ``!add_photo`` minted. Its resolver is deliberately **not** the one ``!add_photo`` uses. That one mints a key for a label nobody has; if ``!random`` shared it, every typo here would quietly create a tag, and the album would fill with keys nobody can reach. An unknown label resolves to a sentinel instead and is answered with the same line as a combination nobody photographed -- from the group's side those are the same question. Labels only, never people: ``!alfa`` already exists for those, and a second entrance with an unscoped argument list is one too many. """ from __future__ import annotations import base64 from typing import TYPE_CHECKING, Final from signal_bot.pack import MAX_NAMES, media_type from signal_bot.pack_command import NAME_PREFIX, NO_PHOTO, UNKNOWN, pick if TYPE_CHECKING: from signal_bot.context import CommandContext from signal_bot.decorators import Decorator from signal_bot.pack_holder import PackHolder from signal_bot.registry import ArgResolver, CommandRegistry, Handler COMMAND_NAME: Final = f"{NAME_PREFIX}random" DESCRIPTION: Final = "losowe zdjęcie z albumu, opcjonalnie po etykiecie" def random_resolver(holder: PackHolder) -> ArgResolver: """Turn typed labels into custom-tag keys, minting nothing. Reads through the holder rather than closing over a Pack, so a tag minted at 12:00 resolves at 12:01 without a restart. """ def resolve(words: tuple[str, ...]) -> tuple[str, ...]: custom = holder.pack.custom return tuple(custom.resolve(word) or UNKNOWN for word in words) return resolve def random_handler(holder: PackHolder) -> Handler: """Build the handler that answers ``!random``.""" async def handler(ctx: CommandContext) -> None: keys = ctx.args # The ceiling is applied to the label list directly rather than # through candidate_keysets, whose ">=" is written against a # head-plus-tail shape that !random does not have. if len(keys) > MAX_NAMES or UNKNOWN in keys: await ctx.reply(NO_PHOTO) return pack = holder.pack # An empty frozenset is a superset test that every file passes, so # bare !random needs no separate path through here. viable = pack.matching(frozenset(keys)) if not viable: await ctx.reply(NO_PHOTO) return filename = pick(viable) payload = base64.b64encode(pack.media_path(filename).read_bytes()).decode("ascii") await ctx.reply_media(payload, media_type(filename), filename) return handler def register_random_command( registry: CommandRegistry, holder: PackHolder, triggers: tuple[str, ...], *, decorate: Decorator | None = None, ) -> None: """Register ``!random``, scoped to the album's own groups.""" handler = random_handler(holder) if decorate is not None: handler = decorate(handler) registry.register( COMMAND_NAME, triggers, handler, DESCRIPTION, groups=holder.pack.groups, takes_args=True, arg_resolver=random_resolver(holder), )