# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """What a Wikimedia Commons image fetch needs, shared by its two callers. `!papież` names a file by title and caches the result; `!pułapka` names one by page id and does not cache anything. Everything between those two ends -- the query, the width, the place `thumburl` turns up in the answer -- is identical, so it lives here rather than twice. """ from __future__ import annotations import html import re from typing import Any, Final from signal_bot.http_client import ImageFetchError # Where imageinfo puts the thumbnail URL in its reply. The same path whether # the file was named by title or by page id. THUMB_PATH: Final = ("query", "pages", 0, "imageinfo", 0, "thumburl") # Commons hosts these four for the 267 portraits: 245 jpg, 15 png, 6 gif, # 1 jpeg. An unknown suffix is refused rather than guessed, because the # extension is what tells Signal how to render the attachment. SUFFIXES: Final = frozenset({".jpg", ".jpeg", ".png", ".gif"}) # Long enough to say what the thing is, short enough not to bury the photo. CAPTION_LIMIT: Final = 220 _TAGS: Final = re.compile(r"<[^>]+>") # The Fisheries records put their prose first and then an HTML list of # catalogue fields ("Subject: Fishing nets", "Tag: Fisheries Techniques"). # Cutting at the list keeps the sentence and drops the filing cabinet. _LIST: Final = " dict[str, str]: """Build the imageinfo query for one Commons file. Args: width: Thumbnail width to ask for, in pixels. title: Full page title, "File:" prefix included. page_id: Commons page id. Preferred where the caller stores a list, because an integer cannot carry somebody's name into the repository the way a filename can. describe: Also ask for the file's description, so one request answers both what the picture is and where it lives. Returns: Query parameters, ready for ImageFetcher.fetch_bytes. Raises: ValueError: If both or neither of title and page_id were given. Silently preferring one would make a caller's typo look like a missing file, which is the same shape as a real 404. """ if (title is None) == (page_id is None): msg = "name a Commons file by exactly one of title or page_id" raise ValueError(msg) selector = {"titles": title} if title is not None else {"pageids": str(page_id)} described = ( {"iiprop": "url|extmetadata", "iiextmetadatafilter": "ImageDescription"} if describe else {"iiprop": "url"} ) return { "action": "query", "format": "json", "formatversion": "2", "prop": "imageinfo", "iiurlwidth": str(width), **described, **selector, } def page_of(document: object) -> dict[str, Any]: """Return the single page an imageinfo answer describes. Raises: ImageFetchError: If Commons answered without one -- a deleted or renumbered page id comes back as `{"missing": true}` and has no imageinfo at all. """ pages = document.get("query", {}).get("pages", []) if isinstance(document, dict) else [] if not pages or not pages[0].get("imageinfo"): msg = f"Commons named no image: {document!r:.200}" raise ImageFetchError(msg) page: dict[str, Any] = pages[0] return page def caption_for(page: dict[str, Any]) -> str: """Return the line that rides along with the photograph. Commons descriptions are HTML, sometimes several languages deep, and sometimes only the filename repeated back. So the tags come out, the catalogue list is cut, and a description that says nothing falls back to the title -- but the file's own page is always linked, because that is what answers "what am I even looking at" when the rest does not. 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. """ info = page["imageinfo"][0] raw = str(info.get("extmetadata", {}).get("ImageDescription", {}).get("value", "")) text = " ".join(html.unescape(_TAGS.sub(" ", raw.split(_LIST, 1)[0])).split()) if text.lower().startswith(_BOILERPLATE): text = "" if not text: text = str(page.get("title", "")).removeprefix("File:").rsplit(".", 1)[0] if len(text) > CAPTION_LIMIT: text = text[:CAPTION_LIMIT].rstrip() + "…" url = str(info.get("descriptionurl", "")) return f"{text}\n{url}" if url else text