Terminal

Module: terminaltexteffects.engine.terminal

A class for managing the terminal state and output.

Attributes:

Name	Type	Description
config	TerminalConfig	Configuration for the terminal.
canvas	Canvas	The canvas in the terminal.
character_by_input_coord	dict[Coord, EffectCharacter]	A dictionary of characters by their input coordinates.

Methods:

Name	Description
get_piped_input	Gets the piped input from stdin.
prep_canvas	Prepares the terminal for the effect by adding empty lines and hiding the cursor.
restore_cursor	Restores the cursor visibility.
get_characters	bool = True, fill_chars: bool = False, added_chars: bool = False, sort: CharacterSort = CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT) -> list[EffectCharacter]: Get a list of all EffectCharacters in the terminal with an optional sort.
get_characters_grouped	CharacterGroup = CharacterGroup.ROW_TOP_TO_BOTTOM, input_characters: bool = True, fill_chars: bool = False, added_chars: bool = False) -> list[list[EffectCharacter]]: Get a list of all EffectCharacters grouped by the specified CharacterGroup grouping.
get_character_by_input_coord	Coord) -> EffectCharacter | None: Get an EffectCharacter by its input coordinates.
set_character_visibility	EffectCharacter, is_visible: bool): Set the visibility of a character.
get_formatted_output_string	Get the formatted output string based on the current terminal state.
print	str, enforce_frame_rate: bool = True): Prints the current terminal state to stdout while preserving the cursor position.

Source code in terminaltexteffects/engine/terminal.py

class Terminal:
    """A class for managing the terminal state and output.

    Attributes:
        config (TerminalConfig): Configuration for the terminal.
        canvas (Canvas): The canvas in the terminal.
        character_by_input_coord (dict[Coord, EffectCharacter]): A dictionary of characters by their input coordinates.

    Methods:
        get_piped_input() -> str: Gets the piped input from stdin.
        prep_canvas(): Prepares the terminal for the effect by adding empty lines and hiding the cursor.
        restore_cursor(): Restores the cursor visibility.
        get_characters(input_characters: bool = True, fill_chars: bool = False, added_chars: bool = False, sort: CharacterSort = CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT) -> list[EffectCharacter]: Get a list of all EffectCharacters in the terminal with an optional sort.
        get_characters_grouped(grouping: CharacterGroup = CharacterGroup.ROW_TOP_TO_BOTTOM, input_characters: bool = True, fill_chars: bool = False, added_chars: bool = False) -> list[list[EffectCharacter]]: Get a list of all EffectCharacters grouped by the specified CharacterGroup grouping.
        get_character_by_input_coord(coord: Coord) -> EffectCharacter | None: Get an EffectCharacter by its input coordinates.
        set_character_visibility(character: EffectCharacter, is_visible: bool): Set the visibility of a character.
        get_formatted_output_string() -> str: Get the formatted output string based on the current terminal state.
        print(output_string: str, enforce_frame_rate: bool = True): Prints the current terminal state to stdout while preserving the cursor position.

    """

    class CharacterGroup(Enum):
        """An enum specifying character groupings.

        Attributes:
            COLUMN_LEFT_TO_RIGHT: Group characters by column from left to right.
            COLUMN_RIGHT_TO_LEFT: Group characters by column from right to left.
            ROW_TOP_TO_BOTTOM: Group characters by row from top to bottom.
            ROW_BOTTOM_TO_TOP: Group characters by row from bottom to top.
            DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT: Group characters by diagonal from top left to bottom right.
            DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT: Group characters by diagonal from bottom left to top right.
            DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT: Group characters by diagonal from top right to bottom left.
            DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT: Group characters by diagonal from bottom right to top left.
            CENTER_TO_OUTSIDE_DIAMONDS: Group characters by distance from the center to the outside in diamond shapes.
            OUTSIDE_TO_CENTER_DIAMONDS: Group characters by distance from the outside to the center in diamond shapes.
        """

        COLUMN_LEFT_TO_RIGHT = auto()
        COLUMN_RIGHT_TO_LEFT = auto()
        ROW_TOP_TO_BOTTOM = auto()
        ROW_BOTTOM_TO_TOP = auto()
        DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT = auto()
        DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT = auto()
        DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT = auto()
        DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT = auto()
        CENTER_TO_OUTSIDE_DIAMONDS = auto()
        OUTSIDE_TO_CENTER_DIAMONDS = auto()

    class CharacterSort(Enum):
        """An enum for specifying character sorts.

        Attributes:
            RANDOM: Random order.
            TOP_TO_BOTTOM_LEFT_TO_RIGHT: Top to bottom, left to right.
            TOP_TO_BOTTOM_RIGHT_TO_LEFT: Top to bottom, right to left.
            BOTTOM_TO_TOP_LEFT_TO_RIGHT: Bottom to top, left to right.
            BOTTOM_TO_TOP_RIGHT_TO_LEFT: Bottom to top, right to left.
            OUTSIDE_ROW_TO_MIDDLE: Outside row to middle.
            MIDDLE_ROW_TO_OUTSIDE: Middle row to outside.
        """

        RANDOM = auto()
        TOP_TO_BOTTOM_LEFT_TO_RIGHT = auto()
        TOP_TO_BOTTOM_RIGHT_TO_LEFT = auto()
        BOTTOM_TO_TOP_LEFT_TO_RIGHT = auto()
        BOTTOM_TO_TOP_RIGHT_TO_LEFT = auto()
        OUTSIDE_ROW_TO_MIDDLE = auto()
        MIDDLE_ROW_TO_OUTSIDE = auto()

    def __init__(self, input_data: str, config: TerminalConfig | None = None):
        """Initializes the Terminal object.

        Args:
            input_data (str): The input data to be displayed in the terminal.
            config (TerminalConfig, optional): Configuration for the terminal. Defaults to None.
        """
        if config is None:
            self.config = TerminalConfig()
        else:
            self.config = config
        if not input_data:
            input_data = "No Input."
        self._input_data = input_data.replace("\t", " " * self.config.tab_width)
        self._terminal_width, self._terminal_height = self._get_terminal_dimensions()
        self.canvas = Canvas(*self._get_canvas_dimensions())
        if not self.config.ignore_terminal_dimensions:
            self.canvas_column_offset, self.canvas_row_offset = self._calc_canvas_offsets()
        else:
            self.canvas_column_offset = self.canvas_row_offset = 0
            self._terminal_width = self.canvas.right
            self._terminal_height = self.canvas.top
        # the visible_* attributes are used to determine which characters are visible on the terminal
        self.visible_top = min(self.canvas.top + self.canvas_row_offset, self._terminal_height)
        self.visible_bottom = max(self.canvas.bottom + self.canvas_row_offset, 1)
        self.visible_right = min(self.canvas.right + self.canvas_column_offset, self._terminal_width)
        self.visible_left = max(self.canvas.left + self.canvas_column_offset, 1)
        self._next_character_id = 0
        self._input_characters = self._decompose_input(self.config.xterm_colors, self.config.no_color)
        self._added_characters: list[EffectCharacter] = []
        self._input_characters = [
            character
            for character in self._input_characters
            if character.input_coord.row <= self.canvas.top and character.input_coord.column <= self.canvas.right
        ]
        self.character_by_input_coord: dict[Coord, EffectCharacter] = {
            (character.input_coord): character for character in self._input_characters
        }
        self._fill_characters = self._make_fill_characters()
        self._visible_characters: set[EffectCharacter] = set()
        self._frame_rate = self.config.frame_rate
        self._last_time_printed = time.time()
        self._update_terminal_state()

    def _calc_canvas_offsets(self) -> tuple[int, int]:
        """Calculate the canvas offsets based on the anchor point.

        Returns:
            tuple[int, int]: Canvas column offset, row offset
        """
        canvas_column_offset = canvas_row_offset = 0
        if self.config.anchor_canvas in ("s", "n", "c"):
            canvas_column_offset = (self._terminal_width // 2) - (self.canvas.width // 2)
        elif self.config.anchor_canvas in ("se", "e", "ne"):
            canvas_column_offset = self._terminal_width - self.canvas.width
        if self.config.anchor_canvas in ("w", "e", "c"):
            canvas_row_offset = self._terminal_height // 2 - self.canvas.height // 2
        elif self.config.anchor_canvas in ("nw", "n", "ne"):
            canvas_row_offset = self._terminal_height - self.canvas.height
        return canvas_column_offset, canvas_row_offset

    def _get_canvas_dimensions(self) -> tuple[int, int]:
        """Determine the canvas dimensions using the input data dimensions, terminal dimensions, and text wrapping.

        Returns:
            tuple[int, int]: Canvas height, width.
        """
        if self.config.canvas_width > 0:
            canvas_width = self.config.canvas_width
        elif self.config.canvas_width == 0:
            canvas_width = self._terminal_width
        else:
            input_width = max([len(line.rstrip()) for line in self._input_data.splitlines()])
            if self.config.wrap_text and not self.config.ignore_terminal_dimensions:
                canvas_width = min(self._terminal_width, input_width)
            else:
                canvas_width = input_width
        if self.config.canvas_height > 0:
            canvas_height = self.config.canvas_height
        elif self.config.canvas_height == 0:
            canvas_height = self._terminal_height
        else:
            if self.config.wrap_text:
                canvas_height = len(self._wrap_lines(self._input_data.splitlines(), canvas_width))
            else:
                canvas_height = len(self._input_data.splitlines())

        return canvas_height, canvas_width

    def _get_terminal_dimensions(self) -> tuple[int, int]:
        """Gets the terminal dimensions.

        Returns:
            tuple[int, int]: terminal width and height
        """
        try:
            terminal_width, terminal_height = shutil.get_terminal_size()
        except OSError:
            # If the terminal size cannot be determined, return default values
            return 80, 24
        return terminal_width, terminal_height

    @staticmethod
    def get_piped_input() -> str:
        """Gets the piped input from stdin.

        This method checks if there is any piped input from the standard input (stdin).
        If there is no piped input, it returns an empty string.
        If there is piped input, it reads the input data from stdin and returns it as a string.

        The `sys.stdin.isatty()` check is used to determine if the program is being run interactively
        or if there is piped input. When the program is run interactively, `sys.stdin.isatty()` returns True,
        indicating that there is no piped input. In this case, the method returns an empty string.

        Returns:
            str: The piped input from stdin as a string, or an empty string if there is no piped input.
        """
        if sys.stdin.isatty():
            return ""
        return sys.stdin.read()

    def _wrap_lines(self, lines: list[str], width: int) -> list[str]:
        """
        Wraps the given lines of text to fit within the width of the canvas.

        Args:
            lines (list): The lines of text to be wrapped.
            width (int): The maximum length of a line.

        Returns:
            list: The wrapped lines of text.
        """
        wrapped_lines = []
        for line in lines:
            line = line.rstrip()
            while len(line) > width:
                wrapped_lines.append(line[:width])
                line = line[width:]
            wrapped_lines.append(line)
        return wrapped_lines

    def _decompose_input(self, use_xterm_colors: bool, no_color: bool) -> list[EffectCharacter]:
        """Decomposes the output into a list of Character objects containing the symbol and its row/column coordinates
        relative to the anchor point in the Canvas.

        Coordinates are relative to the cursor row position at the time of execution. 1,1 is the bottom left corner of the row
        above the cursor.

        Args:
            use_xterm_colors (bool): whether to convert colors to the closest XTerm-256 color

        Returns:
            list[Character]: list of EffectCharacter objects
        """

        formatted_lines = []
        if not self._input_data.strip():
            self._input_data = "No Input."
        lines = self._input_data.splitlines()
        formatted_lines = (
            self._wrap_lines(lines, self.canvas.right) if self.config.wrap_text else [line for line in lines]
        )
        input_height = len(formatted_lines)
        input_characters: list[EffectCharacter] = []
        for row, line in enumerate(formatted_lines):
            for column, symbol in enumerate(line, start=1):
                if symbol != " ":
                    character = EffectCharacter(self._next_character_id, symbol, column, input_height - row)
                    character.animation.use_xterm_colors = use_xterm_colors
                    character.animation.no_color = no_color
                    input_characters.append(character)
                    self._next_character_id += 1

        anchored_characters = self.canvas._anchor_text(input_characters, self.config.anchor_text)
        return [char for char in anchored_characters if self.canvas.coord_is_in_canvas(char._input_coord)]

    def _make_fill_characters(self) -> list[EffectCharacter]:
        """Creates a list of characters to fill the empty spaces in the canvas. The characters input_symbol is a space.
        The fill characters are added to the character_by_input_coord dictionary.

        Returns:
            list[EffectCharacter]: list of characters
        """
        fill_characters = []
        for row in range(1, self.canvas.top + 1):
            for column in range(1, self.canvas.right + 1):
                coord = Coord(column, row)
                if coord not in self.character_by_input_coord:
                    fill_char = EffectCharacter(self._next_character_id, " ", column, row)
                    fill_char.is_fill_character = True
                    fill_char.animation.use_xterm_colors = self.config.xterm_colors
                    fill_char.animation.no_color = self.config.no_color
                    fill_characters.append(fill_char)
                    self.character_by_input_coord[coord] = fill_char
                    self._next_character_id += 1
        return fill_characters

    def add_character(self, symbol: str, coord: Coord) -> EffectCharacter:
        """Adds a character to the terminal for printing. Used to create characters that are not in the input data.

        Args:
            symbol (str): symbol to add
            coord: (Coord): set character's input coordinates

        Returns:
            EffectCharacter: the character that was added
        """
        character = EffectCharacter(self._next_character_id, symbol, coord.column, coord.row)
        character.animation.use_xterm_colors = self.config.xterm_colors
        character.animation.no_color = self.config.no_color
        self._added_characters.append(character)
        self._next_character_id += 1
        return character

    def get_characters(
        self,
        *,
        input_characters: bool = True,
        fill_chars: bool = False,
        added_chars: bool = False,
        sort: CharacterSort = CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT,
    ) -> list[EffectCharacter]:
        """Get a list of all EffectCharacters in the terminal with an optional sort.

        Args:
            input_characters (bool, optional): whether to include input characters. Defaults to True.
            fill_chars (bool, optional): whether to include fill characters. Defaults to False.
            added_chars (bool, optional): whether to include added characters. Defaults to False.
            sort (CharacterSort, optional): order to sort the characters. Defaults to CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT.

        Returns:
            list[EffectCharacter]: list of EffectCharacters in the terminal
        """
        all_characters: list[EffectCharacter] = []
        if input_characters:
            all_characters.extend(self._input_characters)
        if fill_chars:
            all_characters.extend(self._fill_characters)
        if added_chars:
            all_characters.extend(self._added_characters)

        # default sort TOP_TO_BOTTOM_LEFT_TO_RIGHT
        all_characters.sort(key=lambda character: (-character.input_coord.row, character.input_coord.column))

        if sort is self.CharacterSort.RANDOM:
            random.shuffle(all_characters)

        elif sort in (self.CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT, self.CharacterSort.BOTTOM_TO_TOP_RIGHT_TO_LEFT):
            if sort is self.CharacterSort.BOTTOM_TO_TOP_RIGHT_TO_LEFT:
                all_characters.reverse()

        elif sort in (self.CharacterSort.BOTTOM_TO_TOP_LEFT_TO_RIGHT, self.CharacterSort.TOP_TO_BOTTOM_RIGHT_TO_LEFT):
            all_characters.sort(key=lambda character: (character.input_coord.row, character.input_coord.column))
            if sort is self.CharacterSort.TOP_TO_BOTTOM_RIGHT_TO_LEFT:
                all_characters.reverse()

        elif sort in (self.CharacterSort.OUTSIDE_ROW_TO_MIDDLE, self.CharacterSort.MIDDLE_ROW_TO_OUTSIDE):
            all_characters = [
                all_characters.pop(0) if i % 2 == 0 else all_characters.pop(-1) for i in range(len(all_characters))
            ]
            if sort is self.CharacterSort.MIDDLE_ROW_TO_OUTSIDE:
                all_characters.reverse()

        return all_characters

    def get_characters_grouped(
        self,
        grouping: CharacterGroup = CharacterGroup.ROW_TOP_TO_BOTTOM,
        *,
        input_characters: bool = True,
        fill_chars: bool = False,
        added_chars: bool = False,
    ) -> list[list[EffectCharacter]]:
        """Get a list of all EffectCharacters grouped by the specified CharacterGroup grouping.

        Args:
            grouping (CharacterGroup, optional): order to group the characters. Defaults to ROW_TOP_TO_BOTTOM.
            input_characters (bool, optional): whether to include input characters. Defaults to True.
            fill_chars (bool, optional): whether to include fill characters. Defaults to False.
            added_chars (bool, optional): whether to include added characters. Defaults to False.

        Returns:
            list[list[EffectCharacter]]: list of lists of EffectCharacters in the terminal. Inner lists correspond to groups as specified in the grouping.
        """
        all_characters: list[EffectCharacter] = []
        if input_characters:
            all_characters.extend(self._input_characters)
        if fill_chars:
            all_characters.extend(self._fill_characters)
        if added_chars:
            all_characters.extend(self._added_characters)

        all_characters.sort(key=lambda character: (character.input_coord.row, character.input_coord.column))

        if grouping in (self.CharacterGroup.COLUMN_LEFT_TO_RIGHT, self.CharacterGroup.COLUMN_RIGHT_TO_LEFT):
            columns = []
            for column_index in range(self.canvas.right + 1):
                characters_in_column = [
                    character for character in all_characters if character.input_coord.column == column_index
                ]
                if characters_in_column:
                    columns.append(characters_in_column)
            if grouping == self.CharacterGroup.COLUMN_RIGHT_TO_LEFT:
                columns.reverse()
            return columns

        elif grouping in (self.CharacterGroup.ROW_BOTTOM_TO_TOP, self.CharacterGroup.ROW_TOP_TO_BOTTOM):
            rows = []
            for row_index in range(self.canvas.top + 1):
                characters_in_row = [
                    character for character in all_characters if character.input_coord.row == row_index
                ]
                if characters_in_row:
                    rows.append(characters_in_row)
            if grouping == self.CharacterGroup.ROW_TOP_TO_BOTTOM:
                rows.reverse()
            return rows
        elif grouping in (
            self.CharacterGroup.DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT,
            self.CharacterGroup.DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT,
        ):
            diagonals = []
            for diagonal_index in range(self.canvas.top + self.canvas.right + 1):
                characters_in_diagonal = [
                    character
                    for character in all_characters
                    if character.input_coord.row + character.input_coord.column == diagonal_index
                ]
                if characters_in_diagonal:
                    diagonals.append(characters_in_diagonal)
            if grouping == self.CharacterGroup.DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT:
                diagonals.reverse()
            return diagonals
        elif grouping in (
            self.CharacterGroup.DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT,
            self.CharacterGroup.DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT,
        ):
            diagonals = []
            for diagonal_index in range(self.canvas.left - self.canvas.top, self.canvas.right - self.canvas.bottom + 1):
                characters_in_diagonal = [
                    character
                    for character in all_characters
                    if character.input_coord.column - character.input_coord.row == diagonal_index
                ]
                if characters_in_diagonal:
                    diagonals.append(characters_in_diagonal)
            if grouping == self.CharacterGroup.DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT:
                diagonals.reverse()
            return diagonals
        elif grouping in (
            self.CharacterGroup.CENTER_TO_OUTSIDE_DIAMONDS,
            self.CharacterGroup.OUTSIDE_TO_CENTER_DIAMONDS,
        ):
            distance_map: dict[int, list[EffectCharacter]] = {}
            center_out = []
            for character in all_characters:
                distance = abs(character.input_coord.column - self.canvas.center.column) + abs(
                    character.input_coord.row - self.canvas.center.row
                )
                if distance not in distance_map:
                    distance_map[distance] = []
                distance_map[distance].append(character)
            for distance in sorted(
                distance_map.keys(), reverse=grouping is self.CharacterGroup.OUTSIDE_TO_CENTER_DIAMONDS
            ):
                center_out.append(distance_map[distance])
            return center_out

        else:
            raise ValueError(f"Invalid sort_order: {grouping}")

    def get_character_by_input_coord(self, coord: Coord) -> EffectCharacter | None:
        """Get an EffectCharacter by its input coordinates.

        Args:
            coord (Coord): input coordinates of the character

        Returns:
            EffectCharacter | None: the character at the specified coordinates, or None if no character is found
        """
        if coord not in self.character_by_input_coord:
            return None
        return self.character_by_input_coord[coord]

    def set_character_visibility(self, character: EffectCharacter, is_visible: bool) -> None:
        """Set the visibility of a character.

        Args:
            character (EffectCharacter): the character to set visibility for
            is_visible (bool): whether the character should be visible
        """
        character._is_visible = is_visible
        if is_visible:
            self._visible_characters.add(character)
        else:
            self._visible_characters.discard(character)

    def get_formatted_output_string(self) -> str:
        """Get the formatted output string based on the current terminal state.

        This method updates the internal terminal representation state before returning the formatted output string.

        Returns:
            str: The formatted output string.
        """
        self._update_terminal_state()
        output_string = "\n".join(self.terminal_state[::-1])
        return output_string

    def _update_terminal_state(self):
        """Update the internal representation of the terminal state with the current position
        of all visible characters.
        """
        rows = [[" " for _ in range(self.visible_right)] for _ in range(self.visible_top)]
        for character in sorted(self._visible_characters, key=lambda c: c.layer):
            row = character.motion.current_coord.row + self.canvas_row_offset
            column = character.motion.current_coord.column + self.canvas_column_offset
            if self.visible_bottom <= row <= self.visible_top and self.visible_left <= column <= self.visible_right:
                rows[row - 1][column - 1] = character.animation.current_character_visual.formatted_symbol
        terminal_state = ["".join(row) for row in rows]
        self.terminal_state = terminal_state

    def prep_canvas(self) -> None:
        """Prepares the terminal for the effect by adding empty lines and hiding the cursor."""
        sys.stdout.write(ansitools.HIDE_CURSOR())
        sys.stdout.write(("\n" * (self.visible_top)))
        sys.stdout.write(ansitools.DEC_SAVE_CURSOR_POSITION())

    def restore_cursor(self, end_symbol: str = "\n") -> None:
        """Restores the cursor visibility and prints the end_symbol.

        Args:
            end_symbol (str, optional): The symbol to print after the effect has completed. Defaults to newline.
        """
        sys.stdout.write(ansitools.SHOW_CURSOR())
        sys.stdout.write(end_symbol)

    def print(self, output_string: str, *, enforce_frame_rate: bool = True) -> None:
        """Prints the current terminal state to stdout while preserving the cursor position.

        Args:
            output_string (str): The string to be printed.
            enforce_frame_rate (bool, optional): Whether to enforce the frame rate set in the terminal config. Defaults to True.

        Notes:
            This method includes animation timing to control the frame rate.
            If the time since the last print is less than required to limit the frame rate, the method will sleep for the remaining time
            to ensure a consistent animation speed.

        """
        if enforce_frame_rate:
            self.enforce_framerate()
        self.move_cursor_to_top()
        sys.stdout.write(output_string)
        sys.stdout.flush()

    def enforce_framerate(self):
        """Enforces the frame rate set in the terminal config by sleeping if the time since
        the last frame is shorter than the expected frame delay."""
        frame_delay = 1 / self._frame_rate
        time_since_last_print = time.time() - self._last_time_printed
        if time_since_last_print < frame_delay:
            time.sleep(frame_delay - time_since_last_print)
        self._last_time_printed = time.time()

    def move_cursor_to_top(self):
        """Restores the cursor position to the top of the canvas."""
        sys.stdout.write(ansitools.DEC_RESTORE_CURSOR_POSITION())
        sys.stdout.write(ansitools.MOVE_CURSOR_UP(self.visible_top))

CharacterGroup

Bases: Enum

An enum specifying character groupings.

Attributes:

Name	Type	Description
COLUMN_LEFT_TO_RIGHT		Group characters by column from left to right.
COLUMN_RIGHT_TO_LEFT		Group characters by column from right to left.
ROW_TOP_TO_BOTTOM		Group characters by row from top to bottom.
ROW_BOTTOM_TO_TOP		Group characters by row from bottom to top.
DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT		Group characters by diagonal from top left to bottom right.
DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT		Group characters by diagonal from bottom left to top right.
DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT		Group characters by diagonal from top right to bottom left.
DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT		Group characters by diagonal from bottom right to top left.
CENTER_TO_OUTSIDE_DIAMONDS		Group characters by distance from the center to the outside in diamond shapes.
OUTSIDE_TO_CENTER_DIAMONDS		Group characters by distance from the outside to the center in diamond shapes.

Source code in terminaltexteffects/engine/terminal.py

class CharacterGroup(Enum):
    """An enum specifying character groupings.

    Attributes:
        COLUMN_LEFT_TO_RIGHT: Group characters by column from left to right.
        COLUMN_RIGHT_TO_LEFT: Group characters by column from right to left.
        ROW_TOP_TO_BOTTOM: Group characters by row from top to bottom.
        ROW_BOTTOM_TO_TOP: Group characters by row from bottom to top.
        DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT: Group characters by diagonal from top left to bottom right.
        DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT: Group characters by diagonal from bottom left to top right.
        DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT: Group characters by diagonal from top right to bottom left.
        DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT: Group characters by diagonal from bottom right to top left.
        CENTER_TO_OUTSIDE_DIAMONDS: Group characters by distance from the center to the outside in diamond shapes.
        OUTSIDE_TO_CENTER_DIAMONDS: Group characters by distance from the outside to the center in diamond shapes.
    """

    COLUMN_LEFT_TO_RIGHT = auto()
    COLUMN_RIGHT_TO_LEFT = auto()
    ROW_TOP_TO_BOTTOM = auto()
    ROW_BOTTOM_TO_TOP = auto()
    DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT = auto()
    DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT = auto()
    DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT = auto()
    DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT = auto()
    CENTER_TO_OUTSIDE_DIAMONDS = auto()
    OUTSIDE_TO_CENTER_DIAMONDS = auto()

CharacterSort

Bases: Enum

An enum for specifying character sorts.

Attributes:

Name	Type	Description
RANDOM		Random order.
TOP_TO_BOTTOM_LEFT_TO_RIGHT		Top to bottom, left to right.
TOP_TO_BOTTOM_RIGHT_TO_LEFT		Top to bottom, right to left.
BOTTOM_TO_TOP_LEFT_TO_RIGHT		Bottom to top, left to right.
BOTTOM_TO_TOP_RIGHT_TO_LEFT		Bottom to top, right to left.
OUTSIDE_ROW_TO_MIDDLE		Outside row to middle.
MIDDLE_ROW_TO_OUTSIDE		Middle row to outside.

Source code in terminaltexteffects/engine/terminal.py

class CharacterSort(Enum):
    """An enum for specifying character sorts.

    Attributes:
        RANDOM: Random order.
        TOP_TO_BOTTOM_LEFT_TO_RIGHT: Top to bottom, left to right.
        TOP_TO_BOTTOM_RIGHT_TO_LEFT: Top to bottom, right to left.
        BOTTOM_TO_TOP_LEFT_TO_RIGHT: Bottom to top, left to right.
        BOTTOM_TO_TOP_RIGHT_TO_LEFT: Bottom to top, right to left.
        OUTSIDE_ROW_TO_MIDDLE: Outside row to middle.
        MIDDLE_ROW_TO_OUTSIDE: Middle row to outside.
    """

    RANDOM = auto()
    TOP_TO_BOTTOM_LEFT_TO_RIGHT = auto()
    TOP_TO_BOTTOM_RIGHT_TO_LEFT = auto()
    BOTTOM_TO_TOP_LEFT_TO_RIGHT = auto()
    BOTTOM_TO_TOP_RIGHT_TO_LEFT = auto()
    OUTSIDE_ROW_TO_MIDDLE = auto()
    MIDDLE_ROW_TO_OUTSIDE = auto()

__init__(input_data, config=None)

Initializes the Terminal object.

Parameters:

Name	Type	Description	Default
input_data	str	The input data to be displayed in the terminal.	required
config	TerminalConfig	Configuration for the terminal. Defaults to None.	None

Source code in terminaltexteffects/engine/terminal.py

def __init__(self, input_data: str, config: TerminalConfig | None = None):
    """Initializes the Terminal object.

    Args:
        input_data (str): The input data to be displayed in the terminal.
        config (TerminalConfig, optional): Configuration for the terminal. Defaults to None.
    """
    if config is None:
        self.config = TerminalConfig()
    else:
        self.config = config
    if not input_data:
        input_data = "No Input."
    self._input_data = input_data.replace("\t", " " * self.config.tab_width)
    self._terminal_width, self._terminal_height = self._get_terminal_dimensions()
    self.canvas = Canvas(*self._get_canvas_dimensions())
    if not self.config.ignore_terminal_dimensions:
        self.canvas_column_offset, self.canvas_row_offset = self._calc_canvas_offsets()
    else:
        self.canvas_column_offset = self.canvas_row_offset = 0
        self._terminal_width = self.canvas.right
        self._terminal_height = self.canvas.top
    # the visible_* attributes are used to determine which characters are visible on the terminal
    self.visible_top = min(self.canvas.top + self.canvas_row_offset, self._terminal_height)
    self.visible_bottom = max(self.canvas.bottom + self.canvas_row_offset, 1)
    self.visible_right = min(self.canvas.right + self.canvas_column_offset, self._terminal_width)
    self.visible_left = max(self.canvas.left + self.canvas_column_offset, 1)
    self._next_character_id = 0
    self._input_characters = self._decompose_input(self.config.xterm_colors, self.config.no_color)
    self._added_characters: list[EffectCharacter] = []
    self._input_characters = [
        character
        for character in self._input_characters
        if character.input_coord.row <= self.canvas.top and character.input_coord.column <= self.canvas.right
    ]
    self.character_by_input_coord: dict[Coord, EffectCharacter] = {
        (character.input_coord): character for character in self._input_characters
    }
    self._fill_characters = self._make_fill_characters()
    self._visible_characters: set[EffectCharacter] = set()
    self._frame_rate = self.config.frame_rate
    self._last_time_printed = time.time()
    self._update_terminal_state()

add_character(symbol, coord)

Adds a character to the terminal for printing. Used to create characters that are not in the input data.

Parameters:

Name	Type	Description	Default
symbol	str	symbol to add	required
coord	Coord	(Coord): set character's input coordinates	required

Returns:

Name	Type	Description
EffectCharacter	EffectCharacter	the character that was added

Source code in terminaltexteffects/engine/terminal.py

def add_character(self, symbol: str, coord: Coord) -> EffectCharacter:
    """Adds a character to the terminal for printing. Used to create characters that are not in the input data.

    Args:
        symbol (str): symbol to add
        coord: (Coord): set character's input coordinates

    Returns:
        EffectCharacter: the character that was added
    """
    character = EffectCharacter(self._next_character_id, symbol, coord.column, coord.row)
    character.animation.use_xterm_colors = self.config.xterm_colors
    character.animation.no_color = self.config.no_color
    self._added_characters.append(character)
    self._next_character_id += 1
    return character

enforce_framerate()

Enforces the frame rate set in the terminal config by sleeping if the time since the last frame is shorter than the expected frame delay.

Source code in terminaltexteffects/engine/terminal.py

def enforce_framerate(self):
    """Enforces the frame rate set in the terminal config by sleeping if the time since
    the last frame is shorter than the expected frame delay."""
    frame_delay = 1 / self._frame_rate
    time_since_last_print = time.time() - self._last_time_printed
    if time_since_last_print < frame_delay:
        time.sleep(frame_delay - time_since_last_print)
    self._last_time_printed = time.time()

get_character_by_input_coord(coord)

Get an EffectCharacter by its input coordinates.

Parameters:

Name	Type	Description	Default
coord	Coord	input coordinates of the character	required

Returns:

Type	Description
EffectCharacter | None	EffectCharacter | None: the character at the specified coordinates, or None if no character is found

Source code in terminaltexteffects/engine/terminal.py

def get_character_by_input_coord(self, coord: Coord) -> EffectCharacter | None:
    """Get an EffectCharacter by its input coordinates.

    Args:
        coord (Coord): input coordinates of the character

    Returns:
        EffectCharacter | None: the character at the specified coordinates, or None if no character is found
    """
    if coord not in self.character_by_input_coord:
        return None
    return self.character_by_input_coord[coord]

get_characters(*, input_characters=True, fill_chars=False, added_chars=False, sort=CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT)

Get a list of all EffectCharacters in the terminal with an optional sort.

Parameters:

Name	Type	Description	Default
input_characters	bool	whether to include input characters. Defaults to True.	True
fill_chars	bool	whether to include fill characters. Defaults to False.	False
added_chars	bool	whether to include added characters. Defaults to False.	False
sort	CharacterSort	order to sort the characters. Defaults to CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT.	TOP_TO_BOTTOM_LEFT_TO_RIGHT

Returns:

Type	Description
list[EffectCharacter]	list[EffectCharacter]: list of EffectCharacters in the terminal

Source code in terminaltexteffects/engine/terminal.py

def get_characters(
    self,
    *,
    input_characters: bool = True,
    fill_chars: bool = False,
    added_chars: bool = False,
    sort: CharacterSort = CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT,
) -> list[EffectCharacter]:
    """Get a list of all EffectCharacters in the terminal with an optional sort.

    Args:
        input_characters (bool, optional): whether to include input characters. Defaults to True.
        fill_chars (bool, optional): whether to include fill characters. Defaults to False.
        added_chars (bool, optional): whether to include added characters. Defaults to False.
        sort (CharacterSort, optional): order to sort the characters. Defaults to CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT.

    Returns:
        list[EffectCharacter]: list of EffectCharacters in the terminal
    """
    all_characters: list[EffectCharacter] = []
    if input_characters:
        all_characters.extend(self._input_characters)
    if fill_chars:
        all_characters.extend(self._fill_characters)
    if added_chars:
        all_characters.extend(self._added_characters)

    # default sort TOP_TO_BOTTOM_LEFT_TO_RIGHT
    all_characters.sort(key=lambda character: (-character.input_coord.row, character.input_coord.column))

    if sort is self.CharacterSort.RANDOM:
        random.shuffle(all_characters)

    elif sort in (self.CharacterSort.TOP_TO_BOTTOM_LEFT_TO_RIGHT, self.CharacterSort.BOTTOM_TO_TOP_RIGHT_TO_LEFT):
        if sort is self.CharacterSort.BOTTOM_TO_TOP_RIGHT_TO_LEFT:
            all_characters.reverse()

    elif sort in (self.CharacterSort.BOTTOM_TO_TOP_LEFT_TO_RIGHT, self.CharacterSort.TOP_TO_BOTTOM_RIGHT_TO_LEFT):
        all_characters.sort(key=lambda character: (character.input_coord.row, character.input_coord.column))
        if sort is self.CharacterSort.TOP_TO_BOTTOM_RIGHT_TO_LEFT:
            all_characters.reverse()

    elif sort in (self.CharacterSort.OUTSIDE_ROW_TO_MIDDLE, self.CharacterSort.MIDDLE_ROW_TO_OUTSIDE):
        all_characters = [
            all_characters.pop(0) if i % 2 == 0 else all_characters.pop(-1) for i in range(len(all_characters))
        ]
        if sort is self.CharacterSort.MIDDLE_ROW_TO_OUTSIDE:
            all_characters.reverse()

    return all_characters

get_characters_grouped(grouping=CharacterGroup.ROW_TOP_TO_BOTTOM, *, input_characters=True, fill_chars=False, added_chars=False)

Get a list of all EffectCharacters grouped by the specified CharacterGroup grouping.

Parameters:

Name	Type	Description	Default
grouping	CharacterGroup	order to group the characters. Defaults to ROW_TOP_TO_BOTTOM.	ROW_TOP_TO_BOTTOM
input_characters	bool	whether to include input characters. Defaults to True.	True
fill_chars	bool	whether to include fill characters. Defaults to False.	False
added_chars	bool	whether to include added characters. Defaults to False.	False

Returns:

Type	Description
list[list[EffectCharacter]]	list[list[EffectCharacter]]: list of lists of EffectCharacters in the terminal. Inner lists correspond to groups as specified in the grouping.

Source code in terminaltexteffects/engine/terminal.py

def get_characters_grouped(
    self,
    grouping: CharacterGroup = CharacterGroup.ROW_TOP_TO_BOTTOM,
    *,
    input_characters: bool = True,
    fill_chars: bool = False,
    added_chars: bool = False,
) -> list[list[EffectCharacter]]:
    """Get a list of all EffectCharacters grouped by the specified CharacterGroup grouping.

    Args:
        grouping (CharacterGroup, optional): order to group the characters. Defaults to ROW_TOP_TO_BOTTOM.
        input_characters (bool, optional): whether to include input characters. Defaults to True.
        fill_chars (bool, optional): whether to include fill characters. Defaults to False.
        added_chars (bool, optional): whether to include added characters. Defaults to False.

    Returns:
        list[list[EffectCharacter]]: list of lists of EffectCharacters in the terminal. Inner lists correspond to groups as specified in the grouping.
    """
    all_characters: list[EffectCharacter] = []
    if input_characters:
        all_characters.extend(self._input_characters)
    if fill_chars:
        all_characters.extend(self._fill_characters)
    if added_chars:
        all_characters.extend(self._added_characters)

    all_characters.sort(key=lambda character: (character.input_coord.row, character.input_coord.column))

    if grouping in (self.CharacterGroup.COLUMN_LEFT_TO_RIGHT, self.CharacterGroup.COLUMN_RIGHT_TO_LEFT):
        columns = []
        for column_index in range(self.canvas.right + 1):
            characters_in_column = [
                character for character in all_characters if character.input_coord.column == column_index
            ]
            if characters_in_column:
                columns.append(characters_in_column)
        if grouping == self.CharacterGroup.COLUMN_RIGHT_TO_LEFT:
            columns.reverse()
        return columns

    elif grouping in (self.CharacterGroup.ROW_BOTTOM_TO_TOP, self.CharacterGroup.ROW_TOP_TO_BOTTOM):
        rows = []
        for row_index in range(self.canvas.top + 1):
            characters_in_row = [
                character for character in all_characters if character.input_coord.row == row_index
            ]
            if characters_in_row:
                rows.append(characters_in_row)
        if grouping == self.CharacterGroup.ROW_TOP_TO_BOTTOM:
            rows.reverse()
        return rows
    elif grouping in (
        self.CharacterGroup.DIAGONAL_BOTTOM_LEFT_TO_TOP_RIGHT,
        self.CharacterGroup.DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT,
    ):
        diagonals = []
        for diagonal_index in range(self.canvas.top + self.canvas.right + 1):
            characters_in_diagonal = [
                character
                for character in all_characters
                if character.input_coord.row + character.input_coord.column == diagonal_index
            ]
            if characters_in_diagonal:
                diagonals.append(characters_in_diagonal)
        if grouping == self.CharacterGroup.DIAGONAL_TOP_RIGHT_TO_BOTTOM_LEFT:
            diagonals.reverse()
        return diagonals
    elif grouping in (
        self.CharacterGroup.DIAGONAL_TOP_LEFT_TO_BOTTOM_RIGHT,
        self.CharacterGroup.DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT,
    ):
        diagonals = []
        for diagonal_index in range(self.canvas.left - self.canvas.top, self.canvas.right - self.canvas.bottom + 1):
            characters_in_diagonal = [
                character
                for character in all_characters
                if character.input_coord.column - character.input_coord.row == diagonal_index
            ]
            if characters_in_diagonal:
                diagonals.append(characters_in_diagonal)
        if grouping == self.CharacterGroup.DIAGONAL_BOTTOM_RIGHT_TO_TOP_LEFT:
            diagonals.reverse()
        return diagonals
    elif grouping in (
        self.CharacterGroup.CENTER_TO_OUTSIDE_DIAMONDS,
        self.CharacterGroup.OUTSIDE_TO_CENTER_DIAMONDS,
    ):
        distance_map: dict[int, list[EffectCharacter]] = {}
        center_out = []
        for character in all_characters:
            distance = abs(character.input_coord.column - self.canvas.center.column) + abs(
                character.input_coord.row - self.canvas.center.row
            )
            if distance not in distance_map:
                distance_map[distance] = []
            distance_map[distance].append(character)
        for distance in sorted(
            distance_map.keys(), reverse=grouping is self.CharacterGroup.OUTSIDE_TO_CENTER_DIAMONDS
        ):
            center_out.append(distance_map[distance])
        return center_out

    else:
        raise ValueError(f"Invalid sort_order: {grouping}")

get_formatted_output_string()

Get the formatted output string based on the current terminal state.

This method updates the internal terminal representation state before returning the formatted output string.

Returns:

Name	Type	Description
str	str	The formatted output string.

Source code in terminaltexteffects/engine/terminal.py

def get_formatted_output_string(self) -> str:
    """Get the formatted output string based on the current terminal state.

    This method updates the internal terminal representation state before returning the formatted output string.

    Returns:
        str: The formatted output string.
    """
    self._update_terminal_state()
    output_string = "\n".join(self.terminal_state[::-1])
    return output_string

get_piped_input() staticmethod

Gets the piped input from stdin.

This method checks if there is any piped input from the standard input (stdin). If there is no piped input, it returns an empty string. If there is piped input, it reads the input data from stdin and returns it as a string.

The sys.stdin.isatty() check is used to determine if the program is being run interactively or if there is piped input. When the program is run interactively, sys.stdin.isatty() returns True, indicating that there is no piped input. In this case, the method returns an empty string.

Returns:

Name	Type	Description
str	str	The piped input from stdin as a string, or an empty string if there is no piped input.

Source code in terminaltexteffects/engine/terminal.py

@staticmethod
def get_piped_input() -> str:
    """Gets the piped input from stdin.

    This method checks if there is any piped input from the standard input (stdin).
    If there is no piped input, it returns an empty string.
    If there is piped input, it reads the input data from stdin and returns it as a string.

    The `sys.stdin.isatty()` check is used to determine if the program is being run interactively
    or if there is piped input. When the program is run interactively, `sys.stdin.isatty()` returns True,
    indicating that there is no piped input. In this case, the method returns an empty string.

    Returns:
        str: The piped input from stdin as a string, or an empty string if there is no piped input.
    """
    if sys.stdin.isatty():
        return ""
    return sys.stdin.read()

move_cursor_to_top()

Restores the cursor position to the top of the canvas.

Source code in terminaltexteffects/engine/terminal.py

def move_cursor_to_top(self):
    """Restores the cursor position to the top of the canvas."""
    sys.stdout.write(ansitools.DEC_RESTORE_CURSOR_POSITION())
    sys.stdout.write(ansitools.MOVE_CURSOR_UP(self.visible_top))

prep_canvas()

Prepares the terminal for the effect by adding empty lines and hiding the cursor.

Source code in terminaltexteffects/engine/terminal.py

def prep_canvas(self) -> None:
    """Prepares the terminal for the effect by adding empty lines and hiding the cursor."""
    sys.stdout.write(ansitools.HIDE_CURSOR())
    sys.stdout.write(("\n" * (self.visible_top)))
    sys.stdout.write(ansitools.DEC_SAVE_CURSOR_POSITION())

print(output_string, *, enforce_frame_rate=True)

Prints the current terminal state to stdout while preserving the cursor position.

Parameters:

Name	Type	Description	Default
output_string	str	The string to be printed.	required
enforce_frame_rate	bool	Whether to enforce the frame rate set in the terminal config. Defaults to True.	True

Notes

This method includes animation timing to control the frame rate. If the time since the last print is less than required to limit the frame rate, the method will sleep for the remaining time to ensure a consistent animation speed.

Source code in terminaltexteffects/engine/terminal.py

def print(self, output_string: str, *, enforce_frame_rate: bool = True) -> None:
    """Prints the current terminal state to stdout while preserving the cursor position.

    Args:
        output_string (str): The string to be printed.
        enforce_frame_rate (bool, optional): Whether to enforce the frame rate set in the terminal config. Defaults to True.

    Notes:
        This method includes animation timing to control the frame rate.
        If the time since the last print is less than required to limit the frame rate, the method will sleep for the remaining time
        to ensure a consistent animation speed.

    """
    if enforce_frame_rate:
        self.enforce_framerate()
    self.move_cursor_to_top()
    sys.stdout.write(output_string)
    sys.stdout.flush()

restore_cursor(end_symbol='\n')

Restores the cursor visibility and prints the end_symbol.

Parameters:

Name	Type	Description	Default
end_symbol	str	The symbol to print after the effect has completed. Defaults to newline.	'\n'

Source code in terminaltexteffects/engine/terminal.py

def restore_cursor(self, end_symbol: str = "\n") -> None:
    """Restores the cursor visibility and prints the end_symbol.

    Args:
        end_symbol (str, optional): The symbol to print after the effect has completed. Defaults to newline.
    """
    sys.stdout.write(ansitools.SHOW_CURSOR())
    sys.stdout.write(end_symbol)

set_character_visibility(character, is_visible)

Set the visibility of a character.

Parameters:

Name	Type	Description	Default
character	EffectCharacter	the character to set visibility for	required
is_visible	bool	whether the character should be visible	required

Source code in terminaltexteffects/engine/terminal.py

def set_character_visibility(self, character: EffectCharacter, is_visible: bool) -> None:
    """Set the visibility of a character.

    Args:
        character (EffectCharacter): the character to set visibility for
        is_visible (bool): whether the character should be visible
    """
    character._is_visible = is_visible
    if is_visible:
        self._visible_characters.add(character)
    else:
        self._visible_characters.discard(character)