From 81c4dc411523f15d61c999262271d3feb3c2b25e Mon Sep 17 00:00:00 2001 From: Darren Burns Date: Thu, 3 Mar 2022 17:13:45 +0000 Subject: [PATCH] Add docstrings to Windows console wrapper functions --- rich/_win32_console.py | 109 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/rich/_win32_console.py b/rich/_win32_console.py index 265b75266..c88287564 100644 --- a/rich/_win32_console.py +++ b/rich/_win32_console.py @@ -40,6 +40,15 @@ class WindowsCoordinates(NamedTuple): @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) @@ -65,6 +74,14 @@ class CONSOLE_CURSOR_INFO(ctypes.Structure): 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)) @@ -74,6 +91,20 @@ def GetStdHandle(handle: int = STDOUT) -> wintypes.HANDLE: 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: @@ -98,8 +129,17 @@ def FillConsoleOutputCharacter( length: int, start: WindowsCoordinates, ) -> int: - """Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates.""" - assert len(char) == 1 + """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) @@ -130,6 +170,18 @@ def FillConsoleOutputAttribute( 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) @@ -150,6 +202,16 @@ def FillConsoleOutputAttribute( 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)) @@ -164,6 +226,14 @@ def SetConsoleTextAttribute( 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 @@ -180,6 +250,15 @@ def GetConsoleScreenBufferInfo( 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)) @@ -194,6 +273,15 @@ def SetConsoleCursorPosition( 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))) @@ -203,6 +291,14 @@ def SetConsoleCursorInfo( 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)) @@ -218,6 +314,15 @@ def SetConsoleTitle(title: str) -> bool: def WriteConsole(std_handle: wintypes.HANDLE, text: str) -> bool: + """Write a string of text to the console, starting at the current cursor position + + Args: + std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer. + text (str): The text to write. + + Returns: + bool: True if the function succeeds, otherwise False. + """ buffer = wintypes.LPWSTR(text) num_chars_written = wintypes.LPDWORD() return bool(