Tooltips (iTerm annotations)

[jace]

I keep feeling a need for expandable content (text folding or tooltips) in non-interactive CLIs, as a way to bury extra detail. This is usually a -v flag to turn it on, but it's nice to get it without running the command again, with some assistance from the terminal app.

For example, iTerm2 has an Annotations feature that can be used for tooltips. From their documentation:

To add an annotation use on of these sequences:

OSC 1337 ; AddAnnotation=[message] ST
OSC 1337 ; AddAnnotation=[length] | [message] ST
OSC 1337 ; AddAnnotation=[message] | [length] | [x-coord] | [y-coord] ST
OSC 1337 ; AddHiddenAnnotation=[message] ST
OSC 1337 ; AddHiddenAnnotation=[length] | [message] ST
OSC 1337 ; AddHiddenAnnotation=[message] | [length] | [x-coord] | [y-coord] ST

[message]: The message to attach to the annotation.
[length]: The number of cells to annotate. Defaults to the rest of the line beginning at the start of the annotation.
[x-coord] and [y-coord]: The starting coordinate for the annotation. Defaults to the cursor's coordinate.
AddHiddenAnnotation does not reveal the annotation window at the time the escape sequence is received, while AddAnnotation opens it immediately.

It works as expected:

It's not exactly a tooltip: annotations are limited to a line and do not wrap with text, but it's good enough. What's the best way to use this in Rich? Syntax like this would be most excellent:

rich.print("An [annotate=The annotation]annotated[/] word in text")

I do not know if Rich allows adding to the console markup vocabulary. If it doesn't, maybe an object like this:

from typing import Self
import rich

class Annotated(str):
    def __new__(cls, string: str, annotation: str) -> Self:
        return str.__new__(cls, string)
    def __init__(self, string: str, annotation: str) -> None:
        self.annotation = annotation
    def __rich__(self) -> str:
        esc_ann = self.annotation.replace('[', r'\[')
        length = len(self.split('\n', 1)[0])  # Not very smart: misses markup and other break chars
        return f'\x1b]1337;AddHiddenAnnotation={length}|{esc_ann}\a{self}'

rich.print("An", Annotated("annotated", "The annotation"), "word in text")

But this is relatively verbose and breaks i18n as the string is no longer one object to pass to gettext. It also doesn't work because Rich strips the \a in the output of __rich__(). Escaping with \ doesn't work as that is only applied to \[ sequences. Even using Text.from_ansi doesn't work.

How do I get this working with Rich?

[jace]

Some progress using __rich_console__ and by making the Annotated class not subclass str:

from rich import print as rprint
from rich.text import Text
from rich.control import Control
from rich.segment import Segment

class Annotated:
    def __init__(self, string: str, annotation: str) -> None:
        self.string = string
        self.text = Text.from_markup(string)
        self.annotation = annotation
    def __str__(self) -> str:
        return self.string
    def __rich_console__(self, console, options):
        yield Segment(f'\x1b]1337;AddHiddenAnnotation={len(self.text)}|{self.annotation}\a', control=Control.bell())
        yield self.string

rprint("An", Annotated("annotated [bold]bold[/]", "The annotation"), "word in text")

Unfortunately this prints the Annotated object on its own line:

[jace]

A working solution! I'm calling it "hinted" instead of "annotated" because it's fewer chars in markup:

Markup: "[@hint='This is the hint']Hinted text[/]"

"""Add iTerm2 annotations to Rich."""

from collections.abc import Iterable
from typing import Optional

from rich import get_console
from rich import print as rprint
from rich.console import Console, ConsoleOptions, ConsoleRenderable, RenderHook
from rich.segment import Segment
from rich.style import Style
from rich.text import Text
from typing_extensions import Self


class HintedText(Text):
    """Text subclass that supports iTerm2 annotations."""

    @classmethod
    def recast(cls, text: Text) -> Self:
        """Recast from Text."""
        clone = cls(
            text.plain,
            style=text.style,
            justify=text.justify,
            overflow=text.overflow,
            no_wrap=text.no_wrap,
            end=text.end,
            tab_size=text.tab_size,
        )
        clone._spans[:] = text._spans
        return clone

    def __rich_console__(
        self, console: Console, options: ConsoleOptions
    ) -> Iterable[Segment]:
        segments = super().__rich_console__(console, options)
        for segment in segments:
            if segment.style is not None and "@hint" in segment.style.meta:
                hint_param = segment.style.meta["@hint"]
                if isinstance(hint_param, str):
                    hint_text = hint_param
                    hint_hidden = True
                elif isinstance(hint_param, tuple):
                    hint_text, hint_hidden = hint_param
                subsegments = [segment]
                try:
                    # Get all forthcoming segments until @hint is gone
                    # No support for @hint changing without a gap
                    while (
                        next_segment := next(segments)
                    ).style is not None and "@hint" in next_segment.style.meta:
                        subsegments.append(next_segment)
                except StopIteration:
                    next_segment = None
                text_length = sum(len(s.text) for s in subsegments)
                command = "AddHiddenAnnotation" if hint_hidden else "AddAnnotation"
                yield Segment(f"\x1b]1337;{command}={text_length}|{hint_text}\a")
                yield from subsegments
                if next_segment is not None:
                    yield next_segment
            else:
                yield segment


class RichHint(RenderHook):
    """Add @hint support to a Rich Console."""

    @classmethod
    def install(cls, console: Optional[Console] = None) -> None:
        console = console if console is not None else get_console()
        console.push_render_hook(cls())

    def process_renderables(
        self, renderables: list[ConsoleRenderable]
    ) -> list[ConsoleRenderable]:
        return list(self._iterate_renderables(renderables))

    def _iterate_renderables(self, renderables) -> Iterable[ConsoleRenderable]:
        for r in renderables:
            if isinstance(r, Text) and r.spans and not isinstance(r, HintedText):
                has_hints = False
                # Check for @hint in style meta
                for span in r.spans:
                    if isinstance(span.style, Style) and "@hint" in span.style.meta:
                        has_hints = True
                        break
                yield HintedText.recast(r) if has_hints else r
            else:
                yield r


if __name__ == "__main__":
    RichHint.install()
    rprint("Some [bold][@hint='First hint']hinted[/][/] text")
    rprint("Some [@hint='Second hint']mixed [bold]hinted[/][/] text")
    rprint("A [@hint='Third hint', False]default [italic]visible[/] hint[/]")
    rprint("A [@hint='Fourth hint']wrapped\nhint[/]")
    rprint("[@hint='Fifth hint']Hinted text[/]", end="")
    rprint("... doesn't mess up print settings (end, etc)")
    rprint()