Top-Level Definitions

Constants

term_image.DEFAULT_QUERY_TIMEOUT: Final[float] = 0.1

Default timeout for Terminal Queries

See also

set_query_timeout().

Enumerations

class term_image.AutoCellRatio

Bases: Enum

Auto Cell Ratio enumeration and support status.

See also

set_cell_ratio().

Attributes:

FIXED	Fixed cell ratio.
DYNAMIC	Dynamic cell ratio.
is_supported	Auto cell ratio support status.

FIXED

Fixed cell ratio.

DYNAMIC

Dynamic cell ratio.

is_supported: ClassVar[bool | None]

Auto cell ratio support status. Can be

• None -> support status not yet determined

• True -> supported

• False -> not supported

Can be explicitly set when using auto cell ratio but want to avoid the support check in a situation where the support status is foreknown. Can help to avoid being wrongly detected as unsupported on a queried terminal that doesn’t respond on time.

For instance, when using multiprocessing, if the support status has been determined in the main process, this value can simply be passed on to and set within the child processes.

Functions

disable_queries	Disables Terminal Queries.
disable_win_size_swap	Disables a workaround for terminal emulators that wrongly report window dimensions swapped.
enable_queries	Re-Enables Terminal Queries.
enable_win_size_swap	Enables a workaround for terminal emulators that wrongly report window dimensions swapped.
get_cell_ratio	Returns the global cell ratio.
set_cell_ratio	Sets the global cell ratio.
set_query_timeout	Sets the timeout for Terminal Queries.

term_image.disable_queries()

Disables Terminal Queries.

To re-enable queries, call enable_queries().

Note

This affects all dependent features.

term_image.disable_win_size_swap()

Disables a workaround for terminal emulators that wrongly report window dimensions swapped.

This workaround is disabled by default. While disabled, the window dimensions reported by the active terminal are used as-is.

Note

This affects Auto Cell Ratio computation and size computations for Graphics-based Render Styles.

term_image.enable_queries()

Re-Enables Terminal Queries.

Queries are enabled by default. To disable, call disable_queries().

Note

This affects all dependent features.

term_image.enable_win_size_swap()

Enables a workaround for terminal emulators that wrongly report window dimensions swapped.

While enabled, the window dimensions reported by the active terminal are swapped. This workaround is required on some older VTE-based terminal emulators.

Note

This affects Auto Cell Ratio computation and size computations for Graphics-based Render Styles.

term_image.get_cell_ratio()

Returns the global cell ratio.

See also

set_cell_ratio().

term_image.set_cell_ratio(ratio)

Sets the global cell ratio.

Parameters:

ratio (float | AutoCellRatio) –

Can be one of the following values.

• A positive float value.

• AutoCellRatio.FIXED, the ratio is immediately determined from the active terminal.

• AutoCellRatio.DYNAMIC, the ratio is determined from the active terminal whenever get_cell_ratio() is called, though with some caching involved, such that the ratio is re-determined only if the terminal size changes.

Raises:

• ValueError – ratio is a non-positive float.

• term_image.exceptions.TermImageError – Auto cell ratio is not supported in the active terminal or on the current platform.

This value is taken into consideration when setting image sizes for text-based render styles, in order to preserve the aspect ratio of images drawn to the terminal.

Note

Changing the cell ratio does not automatically affect any image that has a fixed size. For a change in cell ratio to take effect, the image’s size has to be re-set.

Important

See Auto Cell Ratio for details about the auto modes.

term_image.set_query_timeout(timeout)

Sets the timeout for Terminal Queries.

Parameters:

timeout (float) – Time limit for awaiting a response from the terminal, in seconds.

Raises:

ValueError – timeout is less than or equal to zero.