Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  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()

  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 `set_cell_ratio()`.

term_image.set_cell_ratio(ratio)

  Sets the global cell ratio.

  Parameters:

    ratio (float | term_image.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:

    - 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)

  Sets the timeout for Terminal Queries.

  Parameters:

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

  Raises:

    - TypeError – timeout is not a float.

    - ValueError – timeout is less than or equal to zero.