Global Settings

urwid.set_encoding(encoding: str) → None

Set the byte encoding to assume for processing strings, and to use when converting unicode strings.

urwid.set_ascii_fallbacks(fallbacks: Mapping[str, str]) → None

Replace the table of replacements for characters the target encoding cannot encode.

When the target encoding is not UTF-8, a character it cannot encode is output as its fallback from this table, or as ? when the table has none. The table is consulted only for such characters: a character the encoding can encode (é in ISO-8859-1) is output as it is, and the table is not used at all with a UTF-8 target encoding.

The DEC drawing characters listed in the manual are translated to the terminal’s alternate character set before the table is consulted, so a fallback for one of them is never used.

Text layout measures the original text, so a fallback has to occupy the same single column as the character it replaces:

  • a key is one character, one column wide, and not printable ASCII;

  • a value is one printable ASCII character or one of the DEC drawing characters, which is output through the alternate character set.

A str element of byte text markup uses only the printable ASCII fallbacks, since byte text cannot carry the DEC drawing characters.

Every call replaces the whole table, and {} clears it. The mapping is copied, so changing it afterwards has no effect. The table is validated as a whole: when an entry is rejected, the previous table stays in use.

Canvases rendered before the call keep their old output; call urwid.CanvasCache.clear() to redraw them. urwid.font still reports a font that uses a non-DEC character as needing UTF-8, fallback or not.

>>> import urwid
>>> urwid.set_ascii_fallbacks({"•": "*", "█": "│"})
>>> urwid.set_ascii_fallbacks({})
Parameters:

fallbacks – replacement character for each character, keyed by the character it replaces.

Raises:

  • TypeError – a key or a value is not a str.

  • ValueError – a key or a value breaks one of the rules above; the message names it.

urwid.get_ascii_fallbacks() → Mapping[str, str]

Return the table set by set_ascii_fallbacks(), read-only and as it was passed.

A later set_ascii_fallbacks() call does not change the returned mapping.

>>> import urwid
>>> urwid.set_ascii_fallbacks({"•": "*"})
>>> dict(urwid.get_ascii_fallbacks())
{'•': '*'}
>>> urwid.set_ascii_fallbacks({})
urwid.get_encoding_mode() → Literal['wide', 'narrow', 'utf8']

Get the mode Urwid is using when processing text strings.

Returns:

‘narrow’ for 8-bit encodings, ‘wide’ for CJK encodings or ‘utf8’ for UTF-8 encodings.

urwid.supports_unicode() → bool

Return True if python is able to convert non-ascii unicode strings to the current encoding.