Term

Querying terminal info and working with ANSI terminals.

This is a low-level module upon which yuio.io builds its higher-level abstraction.

Detecting terminal capabilities

Terminal capabilities are stored in a Term object.

Usually, you don’t need to query terminal capabilities yourself, as you can use Yuio’s global configuration from yuio.io (see yuio.io.get_term()).

However, you can get a Term object by using get_term_from_stream():

yuio.term.get_term_from_stream(

ostream: TextIO,

istream: TextIO | None = None,

/,

*,

allow_env_overrides: bool = False,

) → Term

Query info about a terminal attached to the given stream.

Parameters:

• ostream – output stream.

• istream – input stream. If not given, widgets will not work with this terminal.

• allow_env_overrides – honor environment variables and CLI flags when determining capabilities of streams.

yuio.term.get_tty() → Term

Query info about TTY.

On Unix, this returns terminal connected to /dev/tty. On Windows, this returns terminal connected to CONIN$/CONOUT$.

If opening any of these fails, returns Term with stdin/stdout as a fallback.

Note

Prefer using stderr for normal IO: your users expect to be able to redirect messages from your program.

Only use /dev/tty for querying passwords or other things that must not be redirected.

class yuio.term.Term(

ostream: TextIO,

istream: TextIO,

*,

color_support: ColorSupport = NONE,

ostream_is_tty: bool = False,

istream_is_tty: bool = False,

terminal_theme: TerminalTheme | None = None,

is_unicode: bool = False,

)

This class contains all info about what kinds of things the terminal supports. If available, it will also have info about terminal’s theme, i.e. dark or light background, etc.

ostream: TextIO

Terminal’s output stream.

istream: TextIO

Terminal’s input stream.

color_support: ColorSupport

Terminal’s capability for coloring output.

ostream_is_tty: bool

Output is connecter to a terminal, and we’re not in CI.

Note that output being connected to a TTY doesn’t mean that it’s interactive: this process can be in background.

istream_is_tty: bool

Output is connecter to a terminal, and we’re not in CI.

Note that output being connected to a TTY doesn’t mean that it’s interactive: this process can be in background.

terminal_theme: TerminalTheme | None

Terminal’s default foreground, background, and text colors.

is_unicode: bool

Terminal’s output supports unicode characters.

property supports_colors: bool

Return True if terminal supports simple 8-bit color codes.

property supports_colors_256: bool

Return True if terminal supports 256-encoded colors.

property supports_colors_true: bool

Return True if terminal supports true colors.

property is_tty: bool

Return True if input and output are connected to a TTY. In this mode we can interact with the user by writing and reading lines of text.

property can_run_widgets: bool

Return True if input and output are interactive and colors are supported. In this mode we can run interactive widgets.

static make_dummy(is_unicode: bool = True) → Term

Make a dummy terminal with closed streams and no capabilities.

class yuio.term.TerminalTheme(

background: ColorValue,

foreground: ColorValue,

black: ColorValue,

bright_black: ColorValue,

red: ColorValue,

bright_red: ColorValue,

green: ColorValue,

bright_green: ColorValue,

yellow: ColorValue,

bright_yellow: ColorValue,

blue: ColorValue,

bright_blue: ColorValue,

magenta: ColorValue,

bright_magenta: ColorValue,

cyan: ColorValue,

bright_cyan: ColorValue,

white: ColorValue,

bright_white: ColorValue,

lightness: Lightness,

)

Colors and theme of the attached terminal.

background: ColorValue

Background color of a terminal.

foreground: ColorValue

Foreground color of a terminal.

black: ColorValue

Color value for the default “black” color.

bright_black: ColorValue

Color value for the default “bright black” color.

red: ColorValue

Color value for the default “red” color.

bright_red: ColorValue

Color value for the default “bright red” color.

green: ColorValue

Color value for the default “green” color.

bright_green: ColorValue

Color value for the default “bright green” color.

yellow: ColorValue

Color value for the default “yellow” color.

bright_yellow: ColorValue

Color value for the default “bright yellow” color.

blue: ColorValue

Color value for the default “blue” color.

bright_blue: ColorValue

Color value for the default “bright blue” color.

magenta: ColorValue

Color value for the default “magenta” color.

bright_magenta: ColorValue

Color value for the default “bright magenta” color.

cyan: ColorValue

Color value for the default “cyan” color.

bright_cyan: ColorValue

Color value for the default “bright cyan” color.

white: ColorValue

Color value for the default “white” color.

bright_white: ColorValue

Color value for the default “bright white” color.

lightness: Lightness

Overall color theme of a terminal, i.e. dark or light.

class yuio.term.Lightness(*values)

Overall color theme of a terminal.

Can help with deciding which colors to use when printing output.

UNKNOWN = 1

We couldn’t determine terminal background, or it wasn’t dark or bright enough to fall in one category or another.

DARK = 2

Terminal background is dark.

LIGHT = 3

Terminal background is light.

Utilities

yuio.term.stream_is_unicode(stream: TextIO, /) → bool

Determine of stream’s encoding is some version of unicode.

yuio.term.get_tty_size(fallback: tuple[int, int] = (80, 24))

Like shutil.get_terminal_size(), but uses TTY stream if it’s available.

Parameters:

fallback – tuple with width and height that will be used if query fails.

yuio.term.detect_ci() → bool

Scan environment variables to detect if we’re in a known CI environment.

yuio.term.detect_ci_color_support() → ColorSupport

Scan environment variables to detect an appropriate level of color support of a CI environment.

If we’re not in CI, return ColorSupport.NONE.

Re-imports

type yuio.term.ColorSupport

Alias of yuio.color.ColorSupport.