name : _win32_console.py """Light wrapper around the Win32 Console API - this module should only be imported on Windows The API that this module wraps is documented at https://docs.microsoft.com/en-us/windows/console/console-functions """ import ctypes import sys from typing import Any windll: Any = None if sys.platform == "win32": windll = ctypes.LibraryLoader(ctypes.WinDLL) else: raise ImportError(f"{__name__} can only be imported on Windows") import time from ctypes import Structure, byref, wintypes from typing import IO, NamedTuple, Type, cast from pip._vendor.rich.color import ColorSystem from pip._vendor.rich.style import Style STDOUT = -11 ENABLE_VIRTUAL_TERMINAL_PROCESSING = 4 COORD = wintypes._COORD class LegacyWindowsError(Exception): pass class WindowsCoordinates(NamedTuple): """Coordinates in the Windows Console API are (y, x), not (x, y). This class is intended to prevent that confusion. Rows and columns are indexed from 0. This class can be used in place of wintypes._COORD in arguments and argtypes. """ row: int col: int @classmethod def from_param(cls, value: "WindowsCoordinates") -> COORD: """Converts a WindowsCoordinates into a wintypes _COORD structure. This classmethod is internally called by ctypes to perform the conversion. Args: value (WindowsCoordinates): The input coordinates to convert. Returns: wintypes._COORD: The converted coordinates struct. """ return COORD(value.col, value.row) class CONSOLE_SCREEN_BUFFER_INFO(Structure): _fields_ = [ ("dwSize", COORD), ("dwCursorPosition", COORD), ("wAttributes", wintypes.WORD), ("srWindow", wintypes.SMALL_RECT), ("dwMaximumWindowSize", COORD), ] class CONSOLE_CURSOR_INFO(ctypes.Structure): _fields_ = [("dwSize", wintypes.DWORD), ("bVisible", wintypes.BOOL)] _GetStdHandle = windll.kernel32.GetStdHandle _GetStdHandle.argtypes = [ wintypes.DWORD, ] _GetStdHandle.restype = wintypes.HANDLE def GetStdHandle(handle: int = STDOUT) -> wintypes.HANDLE: """Retrieves a handle to the specified standard device (standard input, standard output, or standard error). Args: handle (int): Integer identifier for the handle. Defaults to -11 (stdout). Returns: wintypes.HANDLE: The handle """ return cast(wintypes.HANDLE, _GetStdHandle(handle)) _GetConsoleMode = windll.kernel32.GetConsoleMode _GetConsoleMode.argtypes = [wintypes.HANDLE, wintypes.LPDWORD] _GetConsoleMode.restype = wintypes.BOOL def GetConsoleMode(std_handle: wintypes.HANDLE) -> int: """Retrieves the current input mode of a console's input buffer or the current output mode of a console screen buffer. Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. Raises: LegacyWindowsError: If any error occurs while calling the Windows console API. Returns: int: Value representing the current console mode as documented at https://docs.microsoft.com/en-us/windows/console/getconsolemode#parameters """ console_mode = wintypes.DWORD() success = bool(_GetConsoleMode(std_handle, console_mode)) if not success: raise LegacyWindowsError("Unable to get legacy Windows Console Mode") return console_mode.value _FillConsoleOutputCharacterW = windll.kernel32.FillConsoleOutputCharacterW _FillConsoleOutputCharacterW.argtypes = [ wintypes.HANDLE, ctypes.c_char, wintypes.DWORD, cast(Type[COORD], WindowsCoordinates), ctypes.POINTER(wintypes.DWORD), ] _FillConsoleOutputCharacterW.restype = wintypes.BOOL def FillConsoleOutputCharacter( std_handle: wintypes.HANDLE, char: str, length: int, start: WindowsCoordinates, ) -> int: """Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates. Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. char (str): The character to write. Must be a string of length 1. length (int): The number of times to write the character. start (WindowsCoordinates): The coordinates to start writing at. Returns: int: The number of characters written. """ character = ctypes.c_char(char.encode()) num_characters = wintypes.DWORD(length) num_written = wintypes.DWORD(0) _FillConsoleOutputCharacterW( std_handle, character, num_characters, start, byref(num_written), ) return num_written.value _FillConsoleOutputAttribute = windll.kernel32.FillConsoleOutputAttribute _FillConsoleOutputAttribute.argtypes = [ wintypes.HANDLE, wintypes.WORD, wintypes.DWORD, cast(Type[COORD], WindowsCoordinates), ctypes.POINTER(wintypes.DWORD), ] _FillConsoleOutputAttribute.restype = wintypes.BOOL def FillConsoleOutputAttribute( std_handle: wintypes.HANDLE, attributes: int, length: int, start: WindowsCoordinates, ) -> int: """Sets the character attributes for a specified number of character cells, beginning at the specified coordinates in a screen buffer. Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. attributes (int): Integer value representing the foreground and background colours of the cells. length (int): The number of cells to set the output attribute of. start (WindowsCoordinates): The coordinates of the first cell whose attributes are to be set. Returns: int: The number of cells whose attributes were actually set. """ num_cells = wintypes.DWORD(length) style_attrs = wintypes.WORD(attributes) num_written = wintypes.DWORD(0) _FillConsoleOutputAttribute( std_handle, style_attrs, num_cells, start, byref(num_written) ) return num_written.value _SetConsoleTextAttribute = windll.kernel32.SetConsoleTextAttribute _SetConsoleTextAttribute.argtypes = [ wintypes.HANDLE, wintypes.WORD, ] _SetConsoleTextAttribute.restype = wintypes.BOOL def SetConsoleTextAttribute( std_handle: wintypes.HANDLE, attributes: wintypes.WORD ) -> bool: """Set the colour attributes for all text written after this function is called. Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. attributes (int): Integer value representing the foreground and background colours. Returns: bool: True if the attribute was set successfully, otherwise False. """ return bool(_SetConsoleTextAttribute(std_handle, attributes)) _GetConsoleScreenBufferInfo = windll.kernel32.GetConsoleScreenBufferInfo _GetConsoleScreenBufferInfo.argtypes = [ wintypes.HANDLE, ctypes.POINTER(CONSOLE_SCREEN_BUFFER_INFO), ] _GetConsoleScreenBufferInfo.restype = wintypes.BOOL def GetConsoleScreenBufferInfo( std_handle: wintypes.HANDLE, ) -> CONSOLE_SCREEN_BUFFER_INFO: """Retrieves information about the specified console screen buffer. Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. Returns: CONSOLE_SCREEN_BUFFER_INFO: A CONSOLE_SCREEN_BUFFER_INFO ctype struct contain information about screen size, cursor position, colour attributes, and more.""" console_screen_buffer_info = CONSOLE_SCREEN_BUFFER_INFO() _GetConsoleScreenBufferInfo(std_handle, byref(console_screen_buffer_info)) return console_screen_buffer_info _SetConsoleCursorPosition = windll.kernel32.SetConsoleCursorPosition _SetConsoleCursorPosition.argtypes = [ wintypes.HANDLE, cast(Type[COORD], WindowsCoordinates), ] _SetConsoleCursorPosition.restype = wintypes.BOOL def SetConsoleCursorPosition( std_handle: wintypes.HANDLE, coords: WindowsCoordinates ) -> bool: """Set the position of the cursor in the console screen Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. coords (WindowsCoordinates): The coordinates to move the cursor to. Returns: bool: True if the function succeeds, otherwise False. """ return bool(_SetConsoleCursorPosition(std_handle, coords)) _GetConsoleCursorInfo = windll.kernel32.GetConsoleCursorInfo _GetConsoleCursorInfo.argtypes = [ wintypes.HANDLE, ctypes.POINTER(CONSOLE_CURSOR_INFO), ] _GetConsoleCursorInfo.restype = wintypes.BOOL def GetConsoleCursorInfo( std_handle: wintypes.HANDLE, cursor_info: CONSOLE_CURSOR_INFO ) -> bool: """Get the cursor info - used to get cursor visibility and width Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. cursor_info (CONSOLE_CURSOR_INFO): CONSOLE_CURSOR_INFO ctype struct that receives information about the console's cursor. Returns: bool: True if the function succeeds, otherwise False. """ return bool(_GetConsoleCursorInfo(std_handle, byref(cursor_info))) _SetConsoleCursorInfo = windll.kernel32.SetConsoleCursorInfo _SetConsoleCursorInfo.argtypes = [ wintypes.HANDLE, ctypes.POINTER(CONSOLE_CURSOR_INFO), ] _SetConsoleCursorInfo.restype = wintypes.BOOL def SetConsoleCursorInfo( std_handle: wintypes.HANDLE, cursor_info: CONSOLE_CURSOR_INFO ) -> bool: """Set the cursor info - used for adjusting cursor visibility and width Args: std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. cursor_info (CONSOLE_CURSOR_INFO): CONSOLE_CURSOR_INFO ctype struct containing the new cursor info. Returns: bool: True if the function succeeds, otherwise False. """ return bool(_SetConsoleCursorInfo(std_handle, byref(cursor_info))) _SetConsoleTitle = windll.kernel32.SetConsoleTitleW _SetConsoleTitle.argtypes = [wintypes.LPCWSTR] _SetConsoleTitle.restype = wintypes.BOOL def SetConsoleTitle(title: str) -> bool: """Sets the title of the current console window Args: title (str): The new title of the console window. Returns: bool: True if the function succeeds, otherwise False. """ return bool(_SetConsoleTitle(title)) class LegacyWindowsTerm: """This class allows interaction with the legacy Windows Console API. It should only be used in the context of environments where virtual terminal processing is not available. However, if it is used in a Windows environment, the entire API should work. Args: file (IO[str]): The file which the Windows Console API HANDLE is retrieved from, defaults to sys.stdout. """ BRIGHT_BIT = 8 # Indices are ANSI color numbers, values are the corresponding Windows Console API color numbers ANSI_TO_WINDOWS = [ 0, # black The Windows colours are defined in wincon.h as follows: 4, # red define FOREGROUND_BLUE 0x0001 -- 0000 0001 2, # green define FOREGROUND_GREEN 0x0002 -- 0000 0010 6, # yellow define FOREGROUND_RED 0x0004 -- 0000 0100 1, # blue define FOREGROUND_INTENSITY 0x0008 -- 0000 1000 5, # magenta define BACKGROUND_BLUE 0x0010 -- 0001 0000 3, # cyan define BACKGROUND_GREEN 0x0020 -- 0010 0000 7, # white define BACKGROUND_RED 0x0040 -- 0100 0000 8, # bright black (grey) define BACKGROUND_INTENSITY 0x0080 -- 1000 0000 12, # bright red 10, # bright green 14, # bright yellow 9, # bright blue 13, # bright magenta 11, # bright cyan 15, # bright white ] def __init__(self, file: "IO[str]") -> None: handle = GetStdHandle(STDOUT) self._handle = handle default_text = GetConsoleScreenBufferInfo(handle).wAttributes self._default_text = default_text self._default_fore = default_text & 7 self._default_back = (default_text >> 4) & 7 self._default_attrs = self._default_fore | (self._default_back << 4) self._file = file self.write = file.write self.flush = file.flush @property def cursor_position(self) -> WindowsCoordinates: """Returns the current position of the cursor (0-based) Returns: WindowsCoordinates: The current cursor position. """ coord: COORD = GetConsoleScreenBufferInfo(self._handle).dwCursorPosition return WindowsCoordinates(row=cast(int, coord.Y), col=cast(int, coord.X)) @property def screen_size(self) -> WindowsCoordinates: """Returns the current size of the console screen buffer, in character columns and rows Returns: WindowsCoordinates: The width and height of the screen as WindowsCoordinates. """ screen_size: COORD = GetConsoleScreenBufferInfo(self._handle).dwSize return WindowsCoordinates( row=cast(int, screen_size.Y), col=cast(int, screen_size.X) ) def write_text(self, text: str) -> None: """Write text directly to the terminal without any modification of styles Args: text (str): The text to write to the console """ self.write(text) self.flush() def write_styled(self, text: str, style: Style) -> None: """Write styled text to the terminal. Args: text (str): The text to write style (Style): The style of the text """ color = style.color bgcolor = style.bgcolor if style.reverse: color, bgcolor = bgcolor, color if color: fore = color.downgrade(ColorSystem.WINDOWS).number fore = fore if fore is not None else 7 # Default to ANSI 7: White if style.bold: fore = fore | self.BRIGHT_BIT if style.dim: fore = fore & ~self.BRIGHT_BIT fore = self.ANSI_TO_WINDOWS[fore] else: fore = self._default_fore if bgcolor: back = bgcolor.downgrade(ColorSystem.WINDOWS).number back = back if back is not None else 0 # Default to ANSI 0: Black back = self.ANSI_TO_WINDOWS[back] else: back = self._default_back assert fore is not None assert back is not None SetConsoleTextAttribute( self._handle, attributes=ctypes.c_ushort(fore | (back << 4)) ) self.write_text(text) SetConsoleTextAttribute(self._handle, attributes=self._default_text) def move_cursor_to(self, new_position: WindowsCoordinates) -> None: """Set the position of the cursor Args: new_position (WindowsCoordinates): The WindowsCoordinates representing the new position of the cursor. """ if new_position.col < 0 or new_position.row < 0: return SetConsoleCursorPosition(self._handle, coords=new_position) def erase_line(self) -> None: """Erase all content on the line the cursor is currently located at""" screen_size = self.screen_size cursor_position = self.cursor_position cells_to_erase = screen_size.col start_coordinates = WindowsCoordinates(row=cursor_position.row, col=0) FillConsoleOutputCharacter( self._handle, " ", length=cells_to_erase, start=start_coordinates ) FillConsoleOutputAttribute( self._handle, self._default_attrs, length=cells_to_erase, start=start_coordinates, ) def erase_end_of_line(self) -> None: """Erase all content from the cursor position to the end of that line""" cursor_position = self.cursor_position cells_to_erase = self.screen_size.col - cursor_position.col FillConsoleOutputCharacter( self._handle, " ", length=cells_to_erase, start=cursor_position ) FillConsoleOutputAttribute( self._handle, self._default_attrs, length=cells_to_erase, start=cursor_position, ) def erase_start_of_line(self) -> None: """Erase all content from the cursor position to the start of that line""" row, col = self.cursor_position start = WindowsCoordinates(row, 0) FillConsoleOutputCharacter(self._handle, " ", length=col, start=start) FillConsoleOutputAttribute( self._handle, self._default_attrs, length=col, start=start ) def move_cursor_up(self) -> None: """Move the cursor up a single cell""" cursor_position = self.cursor_position SetConsoleCursorPosition( self._handle, coords=WindowsCoordinates( row=cursor_position.row - 1, col=cursor_position.col ), ) def move_cursor_down(self) -> None: """Move the cursor down a single cell""" cursor_position = self.cursor_position SetConsoleCursorPosition( self._handle, coords=WindowsCoordinates( row=cursor_position.row + 1, col=cursor_position.col, ), ) def move_cursor_forward(self) -> None: """Move the cursor forward a single cell. Wrap to the next line if required.""" row, col = self.cursor_position if col == self.screen_size.col - 1: row += 1 col = 0 else: col += 1 SetConsoleCursorPosition( self._handle, coords=WindowsCoordinates(row=row, col=col) ) def move_cursor_to_column(self, column: int) -> None: """Move cursor to the column specified by the zero-based column index, staying on the same row Args: column (int): The zero-based column index to move the cursor to. """ row, _ = self.cursor_position SetConsoleCursorPosition(self._handle, coords=WindowsCoordinates(row, column)) def move_cursor_backward(self) -> None: """Move the cursor backward a single cell. Wrap to the previous line if required.""" row, col = self.cursor_position if col == 0: row -= 1 col = self.screen_size.col - 1 else: col -= 1 SetConsoleCursorPosition( self._handle, coords=WindowsCoordinates(row=row, col=col) ) def hide_cursor(self) -> None: """Hide the cursor""" current_cursor_size = self._get_cursor_size() invisible_cursor = CONSOLE_CURSOR_INFO(dwSize=current_cursor_size, bVisible=0) SetConsoleCursorInfo(self._handle, cursor_info=invisible_cursor) def show_cursor(self) -> None: """Show the cursor""" current_cursor_size = self._get_cursor_size() visible_cursor = CONSOLE_CURSOR_INFO(dwSize=current_cursor_size, bVisible=1) SetConsoleCursorInfo(self._handle, cursor_info=visible_cursor) def set_title(self, title: str) -> None: """Set the title of the terminal window Args: title (str): The new title of the console window """ assert len(title) < 255, "Console title must be less than 255 characters" SetConsoleTitle(title) def _get_cursor_size(self) -> int: """Get the percentage of the character cell that is filled by the cursor""" cursor_info = CONSOLE_CURSOR_INFO() GetConsoleCursorInfo(self._handle, cursor_info=cursor_info) return int(cursor_info.dwSize) if __name__ == "__main__": handle = GetStdHandle() from pip._vendor.rich.console import Console console = Console() term = LegacyWindowsTerm(sys.stdout) term.set_title("Win32 Console Examples") style = Style(color="black", bgcolor="red") heading = Style.parse("black on green") # Check colour output console.rule("Checking colour output") console.print("[on red]on red!") console.print("[blue]blue!") console.print("[yellow]yellow!") console.print("[bold yellow]bold yellow!") console.print("[bright_yellow]bright_yellow!") console.print("[dim bright_yellow]dim bright_yellow!") console.print("[italic cyan]italic cyan!") console.print("[bold white on blue]bold white on blue!") console.print("[reverse bold white on blue]reverse bold white on blue!") console.print("[bold black on cyan]bold black on cyan!") console.print("[black on green]black on green!") console.print("[blue on green]blue on green!") console.print("[white on black]white on black!") console.print("[black on white]black on white!") console.print("[#1BB152 on #DA812D]#1BB152 on #DA812D!") # Check cursor movement console.rule("Checking cursor movement") console.print() term.move_cursor_backward() term.move_cursor_backward() term.write_text("went back and wrapped to prev line") time.sleep(1) term.move_cursor_up() term.write_text("we go up") time.sleep(1) term.move_cursor_down() term.write_text("and down") time.sleep(1) term.move_cursor_up() term.move_cursor_backward() term.move_cursor_backward() term.write_text("we went up and back 2") time.sleep(1) term.move_cursor_down() term.move_cursor_backward() term.move_cursor_backward() term.write_text("we went down and back 2") time.sleep(1) # Check erasing of lines term.hide_cursor() console.print() console.rule("Checking line erasing") console.print("\n...Deleting to the start of the line...") term.write_text("The red arrow shows the cursor location, and direction of erase") time.sleep(1) term.move_cursor_to_column(16) term.write_styled("<", Style.parse("black on red")) term.move_cursor_backward() time.sleep(1) term.erase_start_of_line() time.sleep(1) console.print("\n\n...And to the end of the line...") term.write_text("The red arrow shows the cursor location, and direction of erase") time.sleep(1) term.move_cursor_to_column(16) term.write_styled(">", Style.parse("black on red")) time.sleep(1) term.erase_end_of_line() time.sleep(1) console.print("\n\n...Now the whole line will be erased...") term.write_styled("I'm going to disappear!", style=Style.parse("black on cyan")) time.sleep(1) term.erase_line() term.show_cursor() print("\n")