Raw Display Attributes

class urwid.AttrSpec(fg: str = 'inherit', bg: str = 'inherit', colors: Literal[1, 16, 88, 256, 16777216] = 256, *, hyperlink: Hyperlink | str | None = None)

Text attribute specification, encoding foreground and background colors and display settings.

Parameters:

• fg –

  a string containing a comma-separated foreground color and settings

  Color values: ‘default’ (use the terminal’s default foreground), ‘inherit’ (take the color from the enclosing attribute, see layered_over()), ‘black’, ‘dark red’, ‘dark green’, ‘brown’, ‘dark blue’, ‘dark magenta’, ‘dark cyan’, ‘light gray’, ‘dark gray’, ‘light red’, ‘light green’, ‘yellow’, ‘light blue’, ‘light magenta’, ‘light cyan’, ‘white’

  High-color example values: ‘#009’ (0% red, 0% green, 60% red, like HTML colors) ‘#23facc’ (RRGGBB hex color code) ‘#fcc’ (100% red, 80% green, 80% blue) ‘g40’ (40% gray, decimal), ‘g#cc’ (80% gray, hex), ‘#000’, ‘g0’, ‘g#00’ (black), ‘#fff’, ‘g100’, ‘g#ff’ (white) ‘h8’ (color number 8), ‘h255’ (color number 255)

  Setting: ‘bold’, ‘italics’, ‘underline’, ‘blink’, ‘standout’, ‘strikethrough’, ‘faint’; with ‘no-’ in front (‘no-bold’) a setting is turned off rather than taken from the enclosing attribute; it is part of the attribute, so ‘red,no-bold’ and ‘red’ are unequal

  Some terminals use ‘bold’ for bright colors. Most terminals ignore the ‘blink’ setting. If the color is not given then ‘default’ will be assumed.

• bg –

  a string containing the background color

  Color values: ‘default’ (use the terminal’s default background), ‘inherit’ (take the color from the enclosing attribute), ‘black’, ‘dark red’, ‘dark green’, ‘brown’, ‘dark blue’, ‘dark magenta’, ‘dark cyan’, ‘light gray’

  High-color exaples: see fg examples above

  An empty string will be treated the same as ‘default’.

• colors –

  the maximum colors available for the specification

  Valid values include: 1, 16, 88, 256, and 2**24. High-color values are only usable with 88, 256, or 2**24 colors. With 1 color only the foreground settings may be used.

• hyperlink – the terminal hyperlink of the text, a string being its URI; None takes the link of the enclosing attribute, and NO_HYPERLINK hides it.

Raises:

• AttrSpecError – colors is not a supported palette size. fg or bg is invalid, or needs more colours than colors.

• ValueError – hyperlink is a string that is not a valid Hyperlink URI.

>>> AttrSpec("dark red", "light gray", 16)
AttrSpec('dark red', 'light gray')
>>> AttrSpec("yellow, underline, bold", "dark blue")
AttrSpec('yellow,bold,underline', 'dark blue')
>>> AttrSpec("#ddb", "#004", 256)  # closest colors will be found
AttrSpec('#dda', '#006')
>>> AttrSpec("#ddb", "#004", 88)
AttrSpec('#ccc', '#000', colors=88)
>>> AttrSpec("inherit,bold", "dark blue")
AttrSpec('inherit,bold', 'dark blue')
>>> AttrSpec(hyperlink="https://urwid.org")
AttrSpec('inherit', 'inherit', hyperlink=Hyperlink(uri='https://urwid.org', id=''))

property background: str

Return the background color.

property background_basic: bool

Return whether the background color is one of the 16 basic colors.

property background_high: bool

Return whether the background color is a 88- or 256-color palette entry.

property background_inherit: bool

Return whether the background color is taken from the enclosing attribute.

property background_number: int

Return the encoded background color number.

property background_true: bool

Return whether the background color is a 24-bit true color.

property blink: bool

Return whether the blink setting is enabled.

property bold: bool

Return whether the bold setting is enabled.

property colors: Literal[1, 16, 88, 256, 16777216]

Return the maximum colors required for this object.

Returns 16777216, 256, 88, 16 or 1.

copy_modified(fg: str | None = None, bg: str | None = None, colors: Literal[1, 16, 88, 256, 16777216] | None = None, *, hyperlink: Hyperlink | str | Literal[_Keep.KEEP] | None = _Keep.KEEP) → Self

Return a new AttrSpec, replacing fg, bg, colors and/or hyperlink with the given values.

Without colors, the result uses 88 colors or true color when this specification was made for them, else 256 colors, so a color can be added to a specification that has none. The hyperlink is kept unless hyperlink is given; None makes the result take the enclosing one.

The result is built with this object’s class. The hyperlink keyword is passed to its constructor only when the result has a link, so a subclass whose constructor takes only fg, bg and colors works for every other change.

Raises:

• AttrSpecError – colors is not a supported palette size, or fg or bg is invalid or needs more colors than the result has.

• ValueError – hyperlink is a string that is not a valid Hyperlink URI.

• TypeError – the result has a link and the constructor of this object’s class does not accept it.

>>> AttrSpec("inherit,bold", "inherit").copy_modified(bg="dark blue")
AttrSpec('inherit,bold', 'dark blue')
>>> AttrSpec(hyperlink="https://urwid.org").copy_modified(hyperlink=None)
AttrSpec('inherit', 'inherit')

property faint: bool

Return whether the faint setting is enabled.

property foreground: str

Return the foreground color and settings as a comma-separated string.

property foreground_basic: bool

Return whether the foreground color is one of the 16 basic colors.

property foreground_high: bool

Return whether the foreground color is a 88- or 256-color palette entry.

property foreground_inherit: bool

Return whether the foreground color is taken from the enclosing attribute.

property foreground_number: int

Return the encoded foreground color number.

property foreground_true: bool

Return whether the foreground color is a 24-bit true color.

get_rgb_values() → tuple[int | None, int | None, int | None, int | None, int | None, int | None]

Return (fg_red, fg_green, fg_blue, bg_red, bg_green, bg_blue) color components.

Each component is in the range 0-255. Values are taken from the XTerm defaults and may not exactly match the user’s terminal.

If the foreground or background is ‘default’ or ‘inherit’ then all their components will be returned as None.

>>> AttrSpec("yellow", "#ccf", colors=88).get_rgb_values()
(255, 255, 0, 205, 205, 255)
>>> AttrSpec("default", "g92").get_rgb_values()
(None, None, None, 238, 238, 238)

Raises:

ValueError – this AttrSpec holds a colour number outside the 88-colour range.

property hyperlink: Hyperlink | None

Return the terminal hyperlink, None when it is taken from the enclosing attribute.

property italics: bool

Return whether the italics setting is enabled.

layered_over(outer: AttrSpec, *, colors: Literal[1, 16, 88, 256, 16777216] | None = None) → AttrSpec

Return this attribute with its ‘inherit’ colors and its missing hyperlink taken from outer.

An attribute with no ‘inherit’ color is opaque: its colors and settings are kept unchanged. Otherwise, each setting this attribute turns on (‘bold’) or off (‘no-bold’) is kept, and a setting it does not mention is taken from outer. The result may still inherit a color, when outer inherits it too. The hyperlink is resolved on its own: without one, this attribute takes the hyperlink of outer. The result is a plain AttrSpec whenever it differs from this attribute.

Parameters:

• outer – the enclosing attribute

• colors – the color mode of the result, normally the terminal’s; None uses the larger color mode of the two attributes

Raises:

AttrSpecError – a color of either attribute needs more colors than colors.

>>> AttrSpec("dark red,bold", "inherit").layered_over(AttrSpec("inherit,underline", "dark blue"))
AttrSpec('dark red,bold,underline', 'dark blue')
>>> AttrSpec("dark red", "default").layered_over(AttrSpec("yellow", "dark blue"))
AttrSpec('dark red', 'default')
>>> AttrSpec("inherit,no-bold", "inherit").layered_over(AttrSpec("yellow,bold,underline", "dark blue"))
AttrSpec('yellow,underline,no-bold', 'dark blue')
>>> AttrSpec("dark red", "default").layered_over(AttrSpec("yellow,bold", "dark blue", hyperlink="https://a.b"))
AttrSpec('dark red', 'default', hyperlink=Hyperlink(uri='https://a.b', id=''))

property standout: bool

Return whether the standout setting is enabled.

property strikethrough: bool

Return whether the strikethrough setting is enabled.

style_only() → AttrSpec

Return this attribute without its hyperlink, for code that only draws colors and settings.

>>> AttrSpec("yellow", "dark blue", hyperlink="https://urwid.org").style_only()
AttrSpec('yellow', 'dark blue')

property underline: bool

Return whether the underline setting is enabled.

class urwid.Hyperlink(uri: str, *, id: str = '')

Terminal hyperlink (OSC 8) carried by an AttrSpec.

The fields keep the names of the OSC 8 specification. Only printable ASCII is accepted, so a link cannot inject other escape sequences. The URI is limited to 2083 characters and the id to 250: these are urwid’s compatibility limits, taken from the terminals that refuse longer values (VTE and iTerm2 for the URI, VTE for the id). The specification itself sets no limit.

An empty URI is the explicit “no link” state, NO_HYPERLINK: it hides the link of an enclosing attribute.

Parameters:

• uri – the link target

• id – groups the cells of one link that the terminal highlights together, when the link is drawn in several separate runs

Raises:

ValueError – uri or id holds a character outside printable ASCII or is too long, id holds : or ;, or id is given with an empty uri.

>>> Hyperlink("https://urwid.org", id="home")
Hyperlink(uri='https://urwid.org', id='home')

urwid.NO_HYPERLINK = Hyperlink(uri='', id='')

Terminal hyperlink (OSC 8) carried by an AttrSpec.

The fields keep the names of the OSC 8 specification. Only printable ASCII is accepted, so a link cannot inject other escape sequences. The URI is limited to 2083 characters and the id to 250: these are urwid’s compatibility limits, taken from the terminals that refuse longer values (VTE and iTerm2 for the URI, VTE for the id). The specification itself sets no limit.

An empty URI is the explicit “no link” state, NO_HYPERLINK: it hides the link of an enclosing attribute.

Parameters:

• uri – the link target

• id – groups the cells of one link that the terminal highlights together, when the link is drawn in several separate runs

Raises:

ValueError – uri or id holds a character outside printable ASCII or is too long, id holds : or ;, or id is given with an empty uri.

>>> Hyperlink("https://urwid.org", id="home")
Hyperlink(uri='https://urwid.org', id='home')

class urwid.LayeredAttr(*layers: Hashable)

Display attribute made of other display attributes stacked innermost first.

A screen resolves it by placing each layer over the next one with AttrSpec.layered_over(), so a layer whose foreground or background is ‘inherit’ shows the color of the layer under it. Layers are palette names or AttrSpec instances.

Stack layers, innermost first.

A layer that is itself a LayeredAttr is replaced by its layers, None (no attribute) is left out, and a layer repeated next to itself is kept once.

classmethod layer(inner: Hashable, outer: Hashable) → Hashable

Return inner placed over outer.

None (no attribute) takes part in no stack: when either is None, inner is returned. The stack is built as the constructor builds it, and a single remaining layer is returned as it is rather than wrapped.

>>> LayeredAttr.layer("red", None)
'red'
>>> LayeredAttr.layer("red", LayeredAttr.layer("bold", "blue_bg"))
LayeredAttr('red', 'bold', 'blue_bg')
>>> LayeredAttr.layer("red", "red")
'red'

property layers: tuple[Hashable, ...]

Return the layers, innermost first.