basedpyright 1.12.6 → 1.13.0

package/dist/typeshed-fallback/stdlib/_curses.pyi

@@ -275,85 +275,580 @@ REPORT_MOUSE_POSITION: int
 _C_API: Any
 version: bytes
 
-def baudrate() -> int: ...
-def beep() -> None: ...
-def can_change_color() -> bool: ...
-def cbreak(flag: bool = True, /) -> None: ...
-def color_content(color_number: int, /) -> tuple[int, int, int]: ...
-def color_pair(pair_number: int, /) -> int: ...
-def curs_set(visibility: int, /) -> int: ...
-def def_prog_mode() -> None: ...
-def def_shell_mode() -> None: ...
-def delay_output(ms: int, /) -> None: ...
-def doupdate() -> None: ...
-def echo(flag: bool = True, /) -> None: ...
-def endwin() -> None: ...
-def erasechar() -> bytes: ...
+def baudrate() -> int:
+    """Return the output speed of the terminal in bits per second."""
+    ...
+def beep() -> None:
+    """Emit a short attention sound."""
+    ...
+def can_change_color() -> bool:
+    """Return True if the programmer can change the colors displayed by the terminal."""
+    ...
+def cbreak(flag: bool = True, /) -> None:
+    """
+    Enter cbreak mode.
+
+      flag
+        If false, the effect is the same as calling nocbreak().
+
+    In cbreak mode (sometimes called "rare" mode) normal tty line buffering is
+    turned off and characters are available to be read one by one.  However,
+    unlike raw mode, special characters (interrupt, quit, suspend, and flow
+    control) retain their effects on the tty driver and calling program.
+    Calling first raw() then cbreak() leaves the terminal in cbreak mode.
+    """
+    ...
+def color_content(color_number: int, /) -> tuple[int, int, int]:
+    """
+    Return the red, green, and blue (RGB) components of the specified color.
+
+      color_number
+        The number of the color (0 - (COLORS-1)).
+
+    A 3-tuple is returned, containing the R, G, B values for the given color,
+    which will be between 0 (no component) and 1000 (maximum amount of component).
+    """
+    ...
+def color_pair(pair_number: int, /) -> int:
+    """
+    Return the attribute value for displaying text in the specified color.
+
+      pair_number
+        The number of the color pair.
+
+    This attribute value can be combined with A_STANDOUT, A_REVERSE, and the
+    other A_* attributes.  pair_number() is the counterpart to this function.
+    """
+    ...
+def curs_set(visibility: int, /) -> int:
+    """
+    Set the cursor state.
+
+      visibility
+        0 for invisible, 1 for normal visible, or 2 for very visible.
+
+    If the terminal supports the visibility requested, the previous cursor
+    state is returned; otherwise, an exception is raised.  On many terminals,
+    the "visible" mode is an underline cursor and the "very visible" mode is
+    a block cursor.
+    """
+    ...
+def def_prog_mode() -> None:
+    """
+    Save the current terminal mode as the "program" mode.
+
+    The "program" mode is the mode when the running program is using curses.
+
+    Subsequent calls to reset_prog_mode() will restore this mode.
+    """
+    ...
+def def_shell_mode() -> None:
+    """
+    Save the current terminal mode as the "shell" mode.
+
+    The "shell" mode is the mode when the running program is not using curses.
+
+    Subsequent calls to reset_shell_mode() will restore this mode.
+    """
+    ...
+def delay_output(ms: int, /) -> None:
+    """
+    Insert a pause in output.
+
+    ms
+      Duration in milliseconds.
+    """
+    ...
+def doupdate() -> None:
+    """Update the physical screen to match the virtual screen."""
+    ...
+def echo(flag: bool = True, /) -> None:
+    """
+    Enter echo mode.
+
+      flag
+        If false, the effect is the same as calling noecho().
+
+    In echo mode, each character input is echoed to the screen as it is entered.
+    """
+    ...
+def endwin() -> None:
+    """De-initialize the library, and return terminal to normal status."""
+    ...
+def erasechar() -> bytes:
+    """Return the user's current erase character."""
+    ...
 def filter() -> None: ...
-def flash() -> None: ...
-def flushinp() -> None: ...
+def flash() -> None:
+    """
+    Flash the screen.
+
+    That is, change it to reverse-video and then change it back in a short interval.
+    """
+    ...
+def flushinp() -> None:
+    """
+    Flush all input buffers.
+
+    This throws away any typeahead that has been typed by the user and has not
+    yet been processed by the program.
+    """
+    ...
 
 if sys.version_info >= (3, 9):
-    def get_escdelay() -> int: ...
-    def get_tabsize() -> int: ...
+    def get_escdelay() -> int:
+        """
+        Gets the curses ESCDELAY setting.
+
+        Gets the number of milliseconds to wait after reading an escape character,
+        to distinguish between an individual escape character entered on the
+        keyboard from escape sequences sent by cursor and function keys.
+        """
+        ...
+    def get_tabsize() -> int:
+        """
+        Gets the curses TABSIZE setting.
+
+        Gets the number of columns used by the curses library when converting a tab
+        character to spaces as it adds the tab to a window.
+        """
+        ...
+
+def getmouse() -> tuple[int, int, int, int, int]:
+    """
+    Retrieve the queued mouse event.
+
+    After getch() returns KEY_MOUSE to signal a mouse event, this function
+    returns a 5-tuple (id, x, y, z, bstate).
+    """
+    ...
+def getsyx() -> tuple[int, int]:
+    """
+    Return the current coordinates of the virtual screen cursor.
+
+    Return a (y, x) tuple.  If leaveok is currently true, return (-1, -1).
+    """
+    ...
+def getwin(file: SupportsRead[bytes], /) -> _CursesWindow:
+    """
+    Read window related data stored in the file by an earlier putwin() call.
 
-def getmouse() -> tuple[int, int, int, int, int]: ...
-def getsyx() -> tuple[int, int]: ...
-def getwin(file: SupportsRead[bytes], /) -> _CursesWindow: ...
-def halfdelay(tenths: int, /) -> None: ...
-def has_colors() -> bool: ...
+    The routine then creates and initializes a new window using that data,
+    returning the new window object.
+    """
+    ...
+def halfdelay(tenths: int, /) -> None:
+    """
+    Enter half-delay mode.
+
+      tenths
+        Maximal blocking delay in tenths of seconds (1 - 255).
+
+    Use nocbreak() to leave half-delay mode.
+    """
+    ...
+def has_colors() -> bool:
+    """Return True if the terminal can display colors; otherwise, return False."""
+    ...
 
 if sys.version_info >= (3, 10):
-    def has_extended_color_support() -> bool: ...
-
-def has_ic() -> bool: ...
-def has_il() -> bool: ...
-def has_key(key: int, /) -> bool: ...
-def init_color(color_number: int, r: int, g: int, b: int, /) -> None: ...
-def init_pair(pair_number: int, fg: int, bg: int, /) -> None: ...
-def initscr() -> _CursesWindow: ...
+    def has_extended_color_support() -> bool:
+        """
+        Return True if the module supports extended colors; otherwise, return False.
+
+        Extended color support allows more than 256 color-pairs for terminals
+        that support more than 16 colors (e.g. xterm-256color).
+        """
+        ...
+
+def has_ic() -> bool:
+    """Return True if the terminal has insert- and delete-character capabilities."""
+    ...
+def has_il() -> bool:
+    """Return True if the terminal has insert- and delete-line capabilities."""
+    ...
+def has_key(key: int, /) -> bool:
+    """
+    Return True if the current terminal type recognizes a key with that value.
+
+    key
+      Key number.
+    """
+    ...
+def init_color(color_number: int, r: int, g: int, b: int, /) -> None:
+    """
+    Change the definition of a color.
+
+      color_number
+        The number of the color to be changed (0 - (COLORS-1)).
+      r
+        Red component (0 - 1000).
+      g
+        Green component (0 - 1000).
+      b
+        Blue component (0 - 1000).
+
+    When init_color() is used, all occurrences of that color on the screen
+    immediately change to the new definition.  This function is a no-op on
+    most terminals; it is active only if can_change_color() returns true.
+    """
+    ...
+def init_pair(pair_number: int, fg: int, bg: int, /) -> None:
+    """
+    Change the definition of a color-pair.
+
+      pair_number
+        The number of the color-pair to be changed (1 - (COLOR_PAIRS-1)).
+      fg
+        Foreground color number (-1 - (COLORS-1)).
+      bg
+        Background color number (-1 - (COLORS-1)).
+
+    If the color-pair was previously initialized, the screen is refreshed and
+    all occurrences of that color-pair are changed to the new definition.
+    """
+    ...
+def initscr() -> _CursesWindow:
+    """
+    Initialize the library.
+
+    Return a WindowObject which represents the whole screen.
+    """
+    ...
 def intrflush(flag: bool, /) -> None: ...
-def is_term_resized(nlines: int, ncols: int, /) -> bool: ...
-def isendwin() -> bool: ...
-def keyname(key: int, /) -> bytes: ...
-def killchar() -> bytes: ...
-def longname() -> bytes: ...
-def meta(yes: bool, /) -> None: ...
-def mouseinterval(interval: int, /) -> None: ...
-def mousemask(newmask: int, /) -> tuple[int, int]: ...
-def napms(ms: int, /) -> int: ...
-def newpad(nlines: int, ncols: int, /) -> _CursesWindow: ...
-def newwin(nlines: int, ncols: int, begin_y: int = ..., begin_x: int = ..., /) -> _CursesWindow: ...
-def nl(flag: bool = True, /) -> None: ...
-def nocbreak() -> None: ...
-def noecho() -> None: ...
-def nonl() -> None: ...
-def noqiflush() -> None: ...
-def noraw() -> None: ...
-def pair_content(pair_number: int, /) -> tuple[int, int]: ...
-def pair_number(attr: int, /) -> int: ...
-def putp(string: ReadOnlyBuffer, /) -> None: ...
-def qiflush(flag: bool = True, /) -> None: ...
-def raw(flag: bool = True, /) -> None: ...
-def reset_prog_mode() -> None: ...
-def reset_shell_mode() -> None: ...
-def resetty() -> None: ...
-def resize_term(nlines: int, ncols: int, /) -> None: ...
-def resizeterm(nlines: int, ncols: int, /) -> None: ...
-def savetty() -> None: ...
+def is_term_resized(nlines: int, ncols: int, /) -> bool:
+    """
+    Return True if resize_term() would modify the window structure, False otherwise.
+
+    nlines
+      Height.
+    ncols
+      Width.
+    """
+    ...
+def isendwin() -> bool:
+    """Return True if endwin() has been called."""
+    ...
+def keyname(key: int, /) -> bytes:
+    """
+    Return the name of specified key.
+
+    key
+      Key number.
+    """
+    ...
+def killchar() -> bytes:
+    """Return the user's current line kill character."""
+    ...
+def longname() -> bytes:
+    """
+    Return the terminfo long name field describing the current terminal.
+
+    The maximum length of a verbose description is 128 characters.  It is defined
+    only after the call to initscr().
+    """
+    ...
+def meta(yes: bool, /) -> None:
+    """
+    Enable/disable meta keys.
+
+    If yes is True, allow 8-bit characters to be input.  If yes is False,
+    allow only 7-bit characters.
+    """
+    ...
+def mouseinterval(interval: int, /) -> None:
+    """
+    Set and retrieve the maximum time between press and release in a click.
+
+      interval
+        Time in milliseconds.
+
+    Set the maximum time that can elapse between press and release events in
+    order for them to be recognized as a click, and return the previous interval
+    value.
+    """
+    ...
+def mousemask(newmask: int, /) -> tuple[int, int]:
+    """
+    Set the mouse events to be reported, and return a tuple (availmask, oldmask).
+
+    Return a tuple (availmask, oldmask).  availmask indicates which of the
+    specified mouse events can be reported; on complete failure it returns 0.
+    oldmask is the previous value of the given window's mouse event mask.
+    If this function is never called, no mouse events are ever reported.
+    """
+    ...
+def napms(ms: int, /) -> int:
+    """
+    Sleep for specified time.
+
+    ms
+      Duration in milliseconds.
+    """
+    ...
+def newpad(nlines: int, ncols: int, /) -> _CursesWindow:
+    """
+    Create and return a pointer to a new pad data structure.
+
+    nlines
+      Height.
+    ncols
+      Width.
+    """
+    ...
+def newwin(nlines: int, ncols: int, begin_y: int = ..., begin_x: int = ..., /) -> _CursesWindow:
+    """
+    newwin(nlines, ncols, [begin_y=0, begin_x=0])
+    Return a new window.
+
+      nlines
+        Height.
+      ncols
+        Width.
+      begin_y
+        Top side y-coordinate.
+      begin_x
+        Left side x-coordinate.
+
+    By default, the window will extend from the specified position to the lower
+    right corner of the screen.
+    """
+    ...
+def nl(flag: bool = True, /) -> None:
+    """
+    Enter newline mode.
+
+      flag
+        If false, the effect is the same as calling nonl().
+
+    This mode translates the return key into newline on input, and translates
+    newline into return and line-feed on output.  Newline mode is initially on.
+    """
+    ...
+def nocbreak() -> None:
+    """
+    Leave cbreak mode.
+
+    Return to normal "cooked" mode with line buffering.
+    """
+    ...
+def noecho() -> None:
+    """
+    Leave echo mode.
+
+    Echoing of input characters is turned off.
+    """
+    ...
+def nonl() -> None:
+    """
+    Leave newline mode.
+
+    Disable translation of return into newline on input, and disable low-level
+    translation of newline into newline/return on output.
+    """
+    ...
+def noqiflush() -> None:
+    """
+    Disable queue flushing.
+
+    When queue flushing is disabled, normal flush of input and output queues
+    associated with the INTR, QUIT and SUSP characters will not be done.
+    """
+    ...
+def noraw() -> None:
+    """
+    Leave raw mode.
+
+    Return to normal "cooked" mode with line buffering.
+    """
+    ...
+def pair_content(pair_number: int, /) -> tuple[int, int]:
+    """
+    Return a tuple (fg, bg) containing the colors for the requested color pair.
+
+    pair_number
+      The number of the color pair (1 - (COLOR_PAIRS-1)).
+    """
+    ...
+def pair_number(attr: int, /) -> int:
+    """
+    Return the number of the color-pair set by the specified attribute value.
+
+    color_pair() is the counterpart to this function.
+    """
+    ...
+def putp(string: ReadOnlyBuffer, /) -> None:
+    """
+    Emit the value of a specified terminfo capability for the current terminal.
+
+    Note that the output of putp() always goes to standard output.
+    """
+    ...
+def qiflush(flag: bool = True, /) -> None:
+    """
+    Enable queue flushing.
+
+      flag
+        If false, the effect is the same as calling noqiflush().
+
+    If queue flushing is enabled, all output in the display driver queue
+    will be flushed when the INTR, QUIT and SUSP characters are read.
+    """
+    ...
+def raw(flag: bool = True, /) -> None:
+    """
+    Enter raw mode.
+
+      flag
+        If false, the effect is the same as calling noraw().
+
+    In raw mode, normal line buffering and processing of interrupt, quit,
+    suspend, and flow control keys are turned off; characters are presented to
+    curses input functions one by one.
+    """
+    ...
+def reset_prog_mode() -> None:
+    """Restore the terminal to "program" mode, as previously saved by def_prog_mode()."""
+    ...
+def reset_shell_mode() -> None:
+    """Restore the terminal to "shell" mode, as previously saved by def_shell_mode()."""
+    ...
+def resetty() -> None:
+    """Restore terminal mode."""
+    ...
+def resize_term(nlines: int, ncols: int, /) -> None:
+    """
+    Backend function used by resizeterm(), performing most of the work.
+
+      nlines
+        Height.
+      ncols
+        Width.
+
+    When resizing the windows, resize_term() blank-fills the areas that are
+    extended.  The calling application should fill in these areas with appropriate
+    data.  The resize_term() function attempts to resize all windows.  However,
+    due to the calling convention of pads, it is not possible to resize these
+    without additional interaction with the application.
+    """
+    ...
+def resizeterm(nlines: int, ncols: int, /) -> None:
+    """
+    Resize the standard and current windows to the specified dimensions.
+
+      nlines
+        Height.
+      ncols
+        Width.
+
+    Adjusts other bookkeeping data used by the curses library that record the
+    window dimensions (in particular the SIGWINCH handler).
+    """
+    ...
+def savetty() -> None:
+    """Save terminal mode."""
+    ...
 
 if sys.version_info >= (3, 9):
-    def set_escdelay(ms: int, /) -> None: ...
-    def set_tabsize(size: int, /) -> None: ...
-
-def setsyx(y: int, x: int, /) -> None: ...
-def setupterm(term: str | None = None, fd: int = -1) -> None: ...
-def start_color() -> None: ...
-def termattrs() -> int: ...
-def termname() -> bytes: ...
-def tigetflag(capname: str, /) -> int: ...
-def tigetnum(capname: str, /) -> int: ...
-def tigetstr(capname: str, /) -> bytes | None: ...
+    def set_escdelay(ms: int, /) -> None:
+        """
+        Sets the curses ESCDELAY setting.
+
+          ms
+            length of the delay in milliseconds.
+
+        Sets the number of milliseconds to wait after reading an escape character,
+        to distinguish between an individual escape character entered on the
+        keyboard from escape sequences sent by cursor and function keys.
+        """
+        ...
+    def set_tabsize(size: int, /) -> None:
+        """
+        Sets the curses TABSIZE setting.
+
+          size
+            rendered cell width of a tab character.
+
+        Sets the number of columns used by the curses library when converting a tab
+        character to spaces as it adds the tab to a window.
+        """
+        ...
+
+def setsyx(y: int, x: int, /) -> None:
+    """
+    Set the virtual screen cursor.
+
+      y
+        Y-coordinate.
+      x
+        X-coordinate.
+
+    If y and x are both -1, then leaveok is set.
+    """
+    ...
+def setupterm(term: str | None = None, fd: int = -1) -> None:
+    """
+    Initialize the terminal.
+
+    term
+      Terminal name.
+      If omitted, the value of the TERM environment variable will be used.
+    fd
+      File descriptor to which any initialization sequences will be sent.
+      If not supplied, the file descriptor for sys.stdout will be used.
+    """
+    ...
+def start_color() -> None:
+    """
+    Initializes eight basic colors and global variables COLORS and COLOR_PAIRS.
+
+    Must be called if the programmer wants to use colors, and before any other
+    color manipulation routine is called.  It is good practice to call this
+    routine right after initscr().
+
+    It also restores the colors on the terminal to the values they had when the
+    terminal was just turned on.
+    """
+    ...
+def termattrs() -> int:
+    """Return a logical OR of all video attributes supported by the terminal."""
+    ...
+def termname() -> bytes:
+    """Return the value of the environment variable TERM, truncated to 14 characters."""
+    ...
+def tigetflag(capname: str, /) -> int:
+    """
+    Return the value of the Boolean capability.
+
+      capname
+        The terminfo capability name.
+
+    The value -1 is returned if capname is not a Boolean capability, or 0 if
+    it is canceled or absent from the terminal description.
+    """
+    ...
+def tigetnum(capname: str, /) -> int:
+    """
+    Return the value of the numeric capability.
+
+      capname
+        The terminfo capability name.
+
+    The value -2 is returned if capname is not a numeric capability, or -1 if
+    it is canceled or absent from the terminal description.
+    """
+    ...
+def tigetstr(capname: str, /) -> bytes | None:
+    """
+    Return the value of the string capability.
+
+      capname
+        The terminfo capability name.
+
+    None is returned if capname is not a string capability, or is canceled or
+    absent from the terminal description.
+    """
+    ...
 def tparm(
     str: ReadOnlyBuffer,
     i1: int = 0,
@@ -366,19 +861,72 @@ def tparm(
     i8: int = 0,
     i9: int = 0,
     /,
-) -> bytes: ...
-def typeahead(fd: int, /) -> None: ...
-def unctrl(ch: _ChType, /) -> bytes: ...
+) -> bytes:
+    """
+    Instantiate the specified byte string with the supplied parameters.
+
+    str
+      Parameterized byte string obtained from the terminfo database.
+    """
+    ...
+def typeahead(fd: int, /) -> None:
+    """
+    Specify that the file descriptor fd be used for typeahead checking.
+
+      fd
+        File descriptor.
+
+    If fd is -1, then no typeahead checking is done.
+    """
+    ...
+def unctrl(ch: _ChType, /) -> bytes:
+    """
+    Return a string which is a printable representation of the character ch.
+
+    Control characters are displayed as a caret followed by the character,
+    for example as ^C.  Printing characters are left as they are.
+    """
+    ...
 
 if sys.version_info < (3, 12) or sys.platform != "darwin":
     # The support for macos was dropped in 3.12
-    def unget_wch(ch: int | str, /) -> None: ...
+    def unget_wch(ch: int | str, /) -> None:
+        """Push ch so the next get_wch() will return it."""
+        ...
+
+def ungetch(ch: _ChType, /) -> None:
+    """Push ch so the next getch() will return it."""
+    ...
+def ungetmouse(id: int, x: int, y: int, z: int, bstate: int, /) -> None:
+    """
+    Push a KEY_MOUSE event onto the input queue.
 
-def ungetch(ch: _ChType, /) -> None: ...
-def ungetmouse(id: int, x: int, y: int, z: int, bstate: int, /) -> None: ...
+    The following getmouse() will return the given state data.
+    """
+    ...
 def update_lines_cols() -> None: ...
-def use_default_colors() -> None: ...
-def use_env(flag: bool, /) -> None: ...
+def use_default_colors() -> None:
+    """
+    Allow use of default values for colors on terminals supporting this feature.
+
+    Use this to support transparency in your application.  The default color
+    is assigned to the color number -1.
+    """
+    ...
+def use_env(flag: bool, /) -> None:
+    """
+    Use environment variables LINES and COLUMNS.
+
+    If used, this function should be called before initscr() or newterm() are
+    called.
+
+    When flag is False, the values of lines and columns specified in the terminfo
+    database will be used, even if environment variables LINES and COLUMNS (used
+    by default) are set, or if curses is running in a window (in which case
+    default behavior would be to use the window size if LINES and COLUMNS are
+    not set).
+    """
+    ...
 
 class error(Exception): ...