Top-Level Definitions#

Constants#

term_image.DEFAULT_QUERY_TIMEOUT: float = 0.1#

Default timeout for Terminal Queries

See also: set_query_timeout()

Enumerations#

class term_image.AutoCellRatio(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: enum.Enum

Values for setting Auto Cell Ratio.

is_supported: bool | None = 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.

FIXED#
DYNAMIC#

See set_cell_ratio().

Functions#

term_image.disable_queries()[source]#

Disables Terminal Queries.

To re-enable queries, call enable_queries().

Note

This affects all dependent features.

term_image.disable_win_size_swap()[source]#

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()[source]#

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()[source]#

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()[source]#

Returns the global cell ratio.

See set_cell_ratio().

term_image.set_cell_ratio(ratio)[source]#

Sets the global cell ratio.

Parameters:

ratio (float | term_image.AutoCellRatio) –

Can be one of the following values.

Raises:
  • TypeError – An argument is of an inappropriate type.

  • ValueError – An argument is of an appropriate type but has an unexpected/invalid value.

  • 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.

Attention

See Auto Cell Ratio for details about the auto modes.

term_image.set_query_timeout(timeout)[source]#

Sets the timeout for Terminal Queries.

Parameters:

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

Raises:
  • TypeErrortimeout is not a float.

  • ValueErrortimeout is less than or equal to zero.