from __future__ import annotations
__all__ = ("Hyperlink",)
from typing import Generator, List, Optional, Tuple
import urwid
from .text_embed import DisplayAttribute
# NOTE: Any new "private" attribute of any subclass of an urwid class should be
# prepended with "_uw" to avoid clashes with names used by urwid itself.
ESC = "\033"
OSC = f"{ESC}]"
ST = f"{ESC}\\"
START = f"{OSC}8;id=%d;%s{ST}".encode()
END = f"{OSC}8;;{ST}".encode()
valid_byte_range = range(32, 127)
[docs]
class Hyperlink(urwid.WidgetWrap):
"""A widget containing hyperlinked text.
Args:
uri: The target of the hyperlink in URI (Uniform Resource Identifier)-encoded
form.
May be a web address (``http://...`` or ``https://...``), FTP address
(``ftp://...``), local file (``file://...``), e-mail address (``mailto:``),
etc.
Every byte of this string, after being encoded, must be within the range
``32`` to ``126`` (both inclusive).
attr: Display attribute of the hyperlink text.
text: Alternative hyperlink text. If not given or ``None``, the URI itself is
used. Must be a single-line string.
Raises:
TypeError: An argument is of an unexpected type.
ValueError: An argument is of an expected type but of an unexpected value
This widget always renders a **single line**, with *left* alignment and the
*ellipsis* wrap mode of :py:class:`urwid.Text` i.e if the widget is rendered with
a width less than the length of the hyperlink text, it is clipped at the right end
with an ellipsis appended; on the other hand, if rendered with a width greater,
it is padded with spaces on the right end.
This widget is intended to be embedded in a :py:class:`~urwidgets.TextEmbed` widget
to combine it with pure text or other widgets but may as well be used otherwise.
This widget utilizes the ``OSC 8`` escape sequence implemented by a sizable number
of mainstream terminal emulators. It utilizes the escape sequence in such a way that
hyperlinks right next to one another should be detected, highlighted and treated as
separate by any terminal emulator that correctly implements the feature. Also, if a
hyperlink is wrapped or clipped, it shouldn't break.
.. collapse:: Examples:
>>> from urwidgets import Hyperlink
>>>
>>> url = "https://urwid.org"
>>>
>>> # The hyperlinks in the outputs should be highlighted on mouse hover
>>> # and clickable (in the terminal), if supported.
>>>
>>> # Raw URI
>>> link = Hyperlink(url)
>>> canv = link.render(())
>>> print(canv.text[0].decode())
https://urwid.org
>>>
>>> # Clipped (with an ellipsis appended) when the render width (maxcols) is
>>> # shorter than the link text
>>> canv = link.render((len(url) - 4,))
>>> print(canv.text[0].decode())
https://urwid…
>>>
>>> # URI with custom text
>>> hyperlink = Hyperlink(url, text="Urwid Website")
>>> canv = hyperlink.render(())
>>> print(canv.text[0].decode())
Urwid Website
.. seealso::
`OSC 8 Specification \
<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_
Official specification for hyperlinks in terminals.
`OSC 8 adoption in terminal emulators \
<https://github.com/Alhadis/OSC8-Adoption>`_
Documentation of the adoption of the feature across terminal emulators and
terminal-based applications.
:py:class:`~urwidgets.TextEmbed`
A widget that enables the use of hyperlinks amidst normal text.
"""
no_cache = ["render"]
def __init__(
self,
uri: str,
attr: DisplayAttribute = None,
text: Optional[str] = None,
) -> None:
self._uw_set_uri(uri)
super().__init__(urwid.Text((_Attr(attr), ""), "left", "ellipsis"))
self._uw_set_text(uri if text is None else text)
def render(self, size: Tuple[int,], focus: bool = False) -> urwid.HyperlinkCanvas:
return HyperlinkCanvas(self._uw_uri, self._w.render(size, focus))
def _uw_set_text(self, text: str):
if not isinstance(text, str):
raise TypeError(f"Invalid type for 'text' (got: {type(text).__name__!r})")
if not text:
raise ValueError("Hyperlink text is empty")
if "\n" in text: # Other multi-line whitespace characters are escaped by urwid
raise ValueError(f"Multi-line text (got: {text!r})")
self._w.set_text((self._w.attrib[0][0], text))
def _uw_set_uri(self, uri: str):
if not isinstance(uri, str):
raise TypeError(f"Invalid type for 'uri' (got: {type(uri).__name__!r})")
if not uri:
raise ValueError("URI is empty")
invalid_bytes = frozenset(uri.encode()).difference(valid_byte_range)
if invalid_bytes:
raise ValueError(
f"Invalid byte '\\x{tuple(invalid_bytes)[0]:02x}' found in URI: {uri!r}"
)
self._uw_uri = uri
attrib = property(
lambda self: self._w.attrib[0][0].attr,
lambda self, attrib: self._w.set_text((_Attr(attrib), self._w.text)),
doc="""The display attirbute of the hyperlink.
:type: DisplayAttribute
GET:
Returns the display attirbute.
SET:
Sets the display attirbute.
""",
)
text = property(
lambda self: self._w.text,
_uw_set_text,
doc="""The alternate text of the hyperlink.
:type: str
GET:
Returns the alternate text.
SET:
Sets the alternate text.
""",
)
uri = property(
lambda self: self._uw_uri,
_uw_set_uri,
doc="""The target of the hyperlink.
:type: str
GET:
Returns the target.
SET:
Sets the target.
""",
)
class HyperlinkCanvas(urwid.Canvas):
cacheable = False
_uw_next_id = 0
_uw_free_ids = set()
def __init__(self, uri: str, text_canv: urwid.TextCanvas) -> None:
super().__init__()
self._uw_text_canv = text_canv
self._uw_uri = uri.encode()
self._uw_id = self._uw_get_id()
def __del__(self):
__class__._uw_free_ids.add(self._uw_id)
def cols(self):
return self._uw_text_canv.cols()
def content(
self,
trim_left: int = 0,
trim_top: int = 0,
cols: int | None = None,
rows: int | None = None,
attr: DisplayAttribute = None,
) -> Generator[List[Tuple[DisplayAttribute, Optional[str], bytes]], None, None]:
# There can only be one line since wrap="ellipsis" and the text was checked
# to not contain "\n".
content_line = next(
self._uw_text_canv.content(trim_left, trim_top, cols, rows, attr)
)
if isinstance(content_line[0][0], _Attr):
hyperlink_text, *padding = content_line
link_attr = hyperlink_text[0].attr
yield [
(None, "U", START % (self._uw_id, self._uw_uri)),
(
attr.get(link_attr, link_attr) if attr else link_attr,
*hyperlink_text[1:],
),
(None, "U", END),
*padding, # if any
]
else: # A trim containing padding only
yield content_line
def rows(self):
return self._uw_text_canv.rows()
@staticmethod
def _uw_get_id():
if __class__._uw_free_ids:
return __class__._uw_free_ids.pop()
__class__._uw_next_id += 1
return __class__._uw_next_id - 1
class _Attr:
"""Wraps a text display attribute to ensure it's always distinguished from those of
neighbouring text runs.
"""
def __init__(self, attr: DisplayAttribute):
self.attr = attr