Skip to content

calista.entrypoints.cli.helpers.hyperlinks

OSC-8 hyperlink utilities for the Calista CLI.

Provides a small heuristic to detect whether the active text stream supports OSC-8 terminal hyperlinks and a helper to render a URL as a clickable link, falling back to plain text when unsupported. Pure formatting only.

supports_osc8(stream=None)

Heuristically detect whether the target stream supports OSC-8 hyperlinks.

Parameters:

Name Type Description Default
stream TextIO | None

File-like text stream to probe; defaults to sys.stdout.

 None

Returns:

Name Type Description
bool bool

True if hyperlinks should be emitted; False otherwise.
Notes
  • Returns False when the stream is not a TTY (e.g., piped or redirected).
  • Uses a conservative allowlist based on terminal identifiers (e.g., VS Code, iTerm2, WezTerm, Kitty, Windows Terminal).
  • This is a best-effort check; some pagers or settings may still strip escapes.

Return an OSC-8 hyperlink with a graceful fallback for unsupported terminals.

Parameters:

Name Type Description Default
url str

Target URL.

 required

Returns:

Name Type Description
str str

The URL wrapped in OSC-8 sequences when supported, otherwise a
str

plain URL string.
Notes
  • Uses BEL (\x07) as the OSC-8 terminator for broad terminal support.