vtf iosys vtermios

↑ vtf-iosys

vtermios

The module contains functions for modifying the emulator communication ports, handlers for the modifications and pre-built platform-independent modification functions.

The modification of the emulator is different for Windows and Linux systems, this module brings the modification to a common denominator. Nevertheless, the range of possibilities [1] and terminal attribute values [2] differs between the systems. Compared to the Windows cmd, a terminal under Linux can be modified more extensively, for example, the cmd does not offer the possibility to define special control characters [3]. Nevertheless, the cmd can be configured for the basic use of this framework without any restrictions. Under Linux the interpretation of the ANSI escape codes in the terminal is natural, under Windows the property must be activated [4] over flags, for this the functions mod_ansiin and mod_ansiout are available in this module. Furthermore, to enable the unblocked reading of stdin, the functions mod_nonblock and mod_nonecho. For some applications it can be useful to disable features or signals in the terminal; the functions mod_nonprocess and mod_nonimpldef offer the possibility to disable e.g. the interrupt signal or the Quick Edit Mode of the Windows cmd.

Module contents

Constants

ENABLE_VIRTUAL_TERMINAL_BUILD_REQUIRED = 16257 ¶

The Windows cmd build should be greater than or equal to 16257 for comprehensive support (Current build as of 06/27/2022 is 21364).

Only available under Windows

INAPPROPRIATE_DEVICE_VALUE: int ¶

The platform-dependent os error number for inappropriate devices. Is 25 under Linux and 6 under Windows.

INVALID_HANDLE_VALUE = -1 ¶

Returned by kernel32.GetStdHandle() as an invalid value.

Only available under Windows

STDIN_FILENO: int ¶

Is the value from sys.stdin.fileno() on Linux, always -10 on Windows.

STDIN_STREAM: TextIO ¶

sys.stdin

STDOUT_FILENO: int ¶

Is rhe value from sys.stdout.fileno() on Linux, always -11 on Windows.

STDOUT_STREAM: TextIO ¶

sys.stdout

Emulator flags

The module provides the collection of the Windows console mode - constants, under Linux the values from module termios are chosen.

Microsoft Windows cmd input flags

Only available under Windows

CMD_ENABLE_AUTO_POSITION = 0x0100 ¶

CMD_ENABLE_ECHO_INPUT = 0x0004 ¶

CMD_ENABLE_EXTENDED_FLAGS = 0x0080 ¶

CMD_ENABLE_INSERT_MODE = 0x0020 ¶

CMD_ENABLE_LINE_INPUT = 0x0002 ¶

CMD_ENABLE_MOUSE_INPUT = 0x0010 ¶

CMD_ENABLE_PROCESSED_INPUT = 0x0001 ¶

CMD_ENABLE_QUICK_EDIT_MODE = 0x0040 ¶

CMD_ENABLE_VIRTUAL_TERMINAL_INPUT = 0x0200 ¶

CMD_ENABLE_WINDOW_INPUT = 0x0008 ¶

Microsoft Windows cmd output flags

Only available under Windows

CMD_ENABLE_LVB_GRID_WORLDWIDE = 0x0010 ¶

CMD_DISABLE_NEWLINE_AUTO_RETURN = 0x0008 ¶

CMD_ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004 ¶

CMD_ENABLE_WRAP_AT_EOL_OUTPUT = 0x0002 ¶

CMD_ENABLE_PROCESSED_OUTPUT = 0x0001 ¶

Global Caches

__ModItemsCache__: list[ModItem] ¶

A global list of the ModItem's, this is extended with every creation of a ModItem. To prevent repeated creation/modification, this memory is queried when the items are initialized.

__ORIGIN_FLAGS__: dict[int, list[int, int, int, int, int, int, list[bytes]] | int] ¶

A global cache for the original terminal attributes, according to the file descriptors of stdin and stdout. Will be created by a ModItem at the first opportunity. On Windows the values are single mode integers for stdin and stdout respectively; termios on Linux returns the terminal attributes in a more complex form as a unified list.

Functions

vtermios.overload __add_flag(__add, flags) -> int ¶

vtermios.__add_flag(__add, flags, on) -> list[int, int, int, int, int, int, list[bytes]] ¶

Add a constant and return the new configuration.

flags : values from __get_flags.

• @ UNIX :

  __add :

  The constant. Should be chosen from module termios.

  on :

  Specify the flag index over "in", "out", "ctrl" or "local".

• @ Windows:

  __add :

  The constant. Should be chosen from this module. (CMD_ prefix)

vtermios.overload __enable_flags(handle, flags) -> None ¶

vtermios.__enable_flags(handle, flags, when) -> None ¶

Set the values of the emulator.

handle : handle from __get_handle.

flags : values from __get_flags.

• @ UNIX :

  when :

  Default value is termios.TCSANOW.

  raises:	EnvironmentError(termios error args)

• @ Windows:

  raises:	EnvironmentError(error of GetLastError): SetConsoleMode returns False.

vtermios.overload __get_flag(flags) -> int ¶

vtermios.__get_flag(flags, on) -> int ¶

Get the termios flag value from index on.

flags must be the attribute list of __get_flags and on defines the index over "in", "out", "ctrl", "local" or can be defined over "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\" as the index of a control character.

The function always returns the numeric value as an integer and is a pseudo function under Windows.

vtermios.overload __get_flags(handle) -> int ¶

vtermios.__get_flags(handle) -> list[int, int, int, int, int, int, list[bytes]] ¶

Return the current values of the emulator.

handle : handle from __get_handle.

• @ UNIX :

  Returns the termios attribute list [iflag, oflag, cflag, lflag, ispeed, ospeed, cc].

  raises:	EnvironmentError(termios error args)

• @ Windows:

  Returns the current console mode bits of a stream as integer.

  raises:	EnvironmentError(error of GetLastError): GetConsoleMode returns False.

vtermios.__get_handle(fileno) -> int ¶

Return the handle for a stream by fileno.

Returns the handle for a stream by GetStdHandle and is a pseudo function under Linux.

raises:	EnvironmentError(error of GetLastError): GetStdHandle has returned -1.

vtermios.overload __is_set(__val, flags) -> bool ¶

vtermios.overload __is_set(__val, flags, on) -> bool ¶

vtermios.__is_set(__val, flags, on) -> bool ¶

Return whether the emulator flags contain the modification value.

flags : values from __get_flags.

• @ UNIX :

  __val :

  Depending on on, a constant must be selected from the module termios or parameterized as a control character. If on is "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\", the corresponding index of the control character is queried and __val can be specified by a character in the range 00-7f as a numeric value or bytestring, also control characters can be expressed by a Ctrl object and backspace by a DelIns object; if __val is None in this request, it is queried whether the index is deactivated.

  on :

  Specify the flag index over "in", "out", "ctrl", "local"; "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\".

• @ Windows:

  __val :

  The constant. Should be chosen from this module. (CMD_ prefix)

vtermios.overload __set_cc() -> int ¶

vtermios.__set_cc(__chr, flags, on) -> list[int, int, int, int, int, int, list[bytes]] ¶

Assign __chr to the control characters in flags on index on and return the modified attribute list. This is an pseudo function under Windows.

__chr can be specified by a character in the range 00-7f as a numeric value or bytestring, also control characters can be expressed by a Ctrl object and backspace by a DelIns object. None is used to disable the index.

flags must be the attribute list from __get_flags and the index is determined via on by "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\".

vtermios.overload __sub_flag(__rm, flags) -> int ¶

vtermios.__sub_flag(__rm, flags, on) -> list[int, int, int, int, int, int, list[bytes]] ¶

Remove a constant and return the new configuration.

flags : values from __get_flags.

• @ UNIX :

  __rm :

  The constant. Should be chosen from module termios.

  on :

  Specify the flag index over "in", "out", "ctrl" or "local".

• @ Windows:

  __rm :

  The constant. Should be chosen from this module. (CMD_ prefix)

vtermios.overload add_flag(fileno, mod_value, *, reset_atexit=True, note=None) -> ModItem ¶

vtermios.overload add_flag(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> ModItem ¶

vtermios.add_flag(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> ModItem ¶

Modify the emulator parameterization and return a ModItem.

• @ UNIX :

  fileno :

  File descriptor from sys.stdin | sys.stdout | sys.stderr.

  mod_value :

  Depending on mod_targ, a constant must be selected from the module termios or parameterized as a new control character. If mod_targ is "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\", the corresponding index of the control characters is set to mod_value, these can be specified by a character in the range 00-7f as a numeric value or bytestring, also control characters can be expressed by a Ctrl object and backspace by a DelIns object; if mod_value is None, the index is disabled.

  mod_targ :

  Specify the flag index over "in", "out", "ctrl", "local"; "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\".

  when :

  Default value is termios.TCSANOW.

• @ Windows:

  fileno :

  -10 (stdin) | -11 (stdout) | -12 (stderr)

  mod_value :

  The constant. Should be chosen from this module. (CMD_ prefix)

reset_atexit : reset the modification when leaving the python interpreter.

note : attach a note to the item.

raises:	RecursionError(msg, index): an item of the same modification is already in __ModItemsCache__. Decisive attributes: fileno, mod_value, mod_targ. raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.cache_purge() -> None ¶

Perform purge of each item in the __ModItemsCache__, which will resets all modifications of them and clears the __ModItemsCache__.

vtermios.overload check_build() -> None ¶

vtermios.check_build(__build) -> None ¶

• @ UNIX :

  Do nothing.

• @ Windows:

  Check if the Windows build is greater than or equal to __build and raise EnvironmentError if not. Is automatically called by the functions mod_ansiin and mod_ansiout with the value ENABLE_VIRTUAL_TERMINAL_BUILD_REQUIRED.

vtermios.mod_ansiin() -> ModDummy | ModItem ¶

• @ UNIX :

  Do nothing and return ModDummy.

• @ Windows:

  Enable virtual terminal input (converts user input into ansi escape sequences). Return the ModItem -- on recursion error from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.mod_ansiout() -> ModDummy | ModItem ¶

• @ UNIX :

  Do nothing and return ModDummy.

• @ Windows:

  Enable virtual terminal processing (process output ansi escape sequences). Return the ModItem -- on recursion error from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.mod_nonblock() -> ModItemsHandle | ModItem ¶

Enable non-blocked reading from stdin.

• @ UNIX :

  Return the ModItem -- on recursion error from __ModItemsCache__.

• @ Windows:

  The Windows cmd requires nonecho for this modification, so mod_nonecho is executed first.

  Return the ModItem's per constant as ModItemsHandle(CMD_ENABLE_ECHO_INPUT, CMD_ENABLE_LINE_INPUT) -- on recursion errors from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.mod_nonecho() -> ModItem ¶

Disable the echo on user input. Return the ModItem -- on recursion error from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.mod_nonimpldef() -> ModItemsHandle ¶

• @ UNIX :

  Disable implementation-defined input/output processing.

  Return the ModItem's per constant as ModItemsHandle(IEXTEN, OPOST) -- on recursion errors from __ModItemsCache__.

• @ Windows:

  Disable the Quick Edit Mode of the cmd by enabling the Extended Flags and removing the Quick Edit Mode Bit.

  Return the ModItem's per constant as ModItemsHandle(CMD_ENABLE_EXTENDED_FLAGS, CMD_ENABLE_QUICK_EDIT_MODE) -- on recursion errors from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.mod_nonprocess() -> ModItemsHandle | ModItem ¶

Disable the processing of control characters by the terminal.

• @ UNIX :

  Disabled keystrokes:

  • INTR (Ctrl-C) by termios.ISIG
  • SUSP (Ctrl-Z) by termios.ISIG
  • QUIT (Ctrl-\) by termios.ISIG
  • XON (Ctrl-Q) by termios.IXON
  • XOFF (Ctrl-S) by termios.IXON

  Return the ModItem's per constant as ModItemsHandle(ISIG, IXON) -- on recursion errors from __ModItemsCache__.

• @ Windows:

  Disabled keystrokes:

  • INTR (Ctrl-C) by CMD_ENABLE_PROCESSED_INPUT
  • "Select" (Shift-Arrow) by CMD_ENABLE_PROCESSED_INPUT

  Return the ModItem -- on recursion error from __ModItemsCache__.

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

vtermios.regedit_permanent_virtual_terminal_level_syscommand(value) -> str ¶

vtermios.overload request(fileno, mod_value) -> bool ¶

vtermios.overload request(fileno, mod_value, mod_targ) -> bool ¶

vtermios.request(fileno, mod_value, mod_targ) -> bool ¶

Return whether the emulator flags contain the modification value.

• @ UNIX :

  fileno :

  File descriptor from sys.stdin | sys.stdout | sys.stderr.

  mod_value :

  Depending on mod_targ, a constant must be selected from the module termios or parameterized as a control character. If mod_targ is "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\", the corresponding index of the control character is queried and mod_value can be specified by a character in the range 00-7f as a numeric value or bytestring, also control characters can be expressed by a Ctrl object and backspace by a DelIns object; if mod_value is None in this request, it is queried whether the index is deactivated.

  mod_targ :

  Specify the flag index over "in", "out", "ctrl", "local"; "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\".

• @ Windows:

  fileno :

  -10 (stdin) | -11 (stdout) | -12 (stderr)

  mod_value :

  The constant. Should be chosen from this module. (CMD_ prefix)

raises:	raise EnvironmentError(termios error | error of GetLastError): an error occurred during the request.

vtermios.overload sub_flag(fileno, mod_value, *, reset_atexit=True, note=None) -> ModItem ¶

vtermios.sub_flag(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> ModItem ¶

Modify the emulator parameterization and return a ModItem.

• @ UNIX :

  fileno :

  File descriptor from sys.stdin | sys.stdout | sys.stderr.

  mod_value :

  The constant. Should be chosen from module termios.

  mod_targ :

  Specify the flag index over "in", "out", "ctrl" or "local".

  when :

  Default value is termios.TCSANOW.

• @ Windows:

  fileno :

  -10 (stdin) | -11 (stdout) | -12 (stderr)

  mod_value :

  The constant. Should be chosen from this module. (CMD_ prefix)

reset_atexit : reset the modification when leaving the python interpreter.

note : attach a note to the item.

raises:	RecursionError(msg, index): an item of the same modification is already in __ModItemsCache__. Decisive attributes: fileno, mod_value, mod_targ. raise EnvironmentError(termios error | error of GetLastError): an error occurred during the modification.

Objects

Handler

Items

class vtermios.ModDummy ¶

A null/pseudo object for modifications that are not applied depending on the operating system.

__bool__() -> bool ¶

False

__len__() -> int ¶

0

class vtermios.ModItem ¶

An item to handling modifications on the emulator.

fileno: int

mod_targ: Literal["in", "out", "ctrl", "local", "ctrl+C", "ctrl+Q", "ctrl+S", "ctrl+\"] | ...

mod_value: int

mod_when: int | ...

note: Any

origin_state: bool

reset_atexit: bool

__eq__(other) -> bool ¶

hash == hash

__hash__() -> int ¶

Composed of (fileno, mod_value, mod_targ)

overload __init__(fileno, mod_value, *, reset_atexit=True, note=None) -> None ¶

overload __init__(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> None ¶

__init__(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) ¶

• @ UNIX :

  fileno :

  File descriptor from sys.stdin | sys.stdout | sys.stderr.

  mod_value :

  Depending on mod_targ, a constant must be selected from the module termios or parameterized as a new control character. If mod_targ is "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\", the corresponding index of the control characters is the mod_value target, mod_value can then be specified by a character in the range 00-7f as a numeric value or bytestring, also control characters can be expressed by a Ctrl object and backspace by a DelIns object; None is the value to disable the index.

  mod_targ :

  Specify the flag index over "in", "out", "ctrl", "local"; "ctrl+C", "ctrl+Q", "ctrl+S" or "ctrl+\".

  when :

  Default value is termios.TCSANOW.

• @ Windows:

  fileno :

  -10 (stdin) | -11 (stdout) | -12 (stderr)

  mod_value :

  The constant. Should be chosen from this module. (CMD_ prefix)

reset_atexit : [ Execute addition functions, then ] reset the modification when leaving the python interpreter.

note : attach a note to the item.

raises:	RecursionError(msg, index): if an item of the same modification is already in __ModItemsCache__. Decisive attributes: fileno, mod_value and mod_targ.

__int__() -> int ¶

mod_value

add_before_reset_atexit(func) -> None ¶

Add a function to the additional exit functions, these will be executed in lifo order when exiting the interpreter, before resetting the modification. Or when the purge method is executed.

add_flag() -> None ¶

Add the modification value to the emulator flags.

staticmethod from_recursion(e) -> ModItem ¶

Return the item from the __ModItemsCache__ by the error raised from init.

@overload

classmethod instance(fileno, mod_value, *, reset_atexit=True, note=None) -> ModItem ¶

@overload

classmethod instance(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> ModItem ¶

classmethod instance(fileno, mod_value, mod_targ, mod_when=TCSANOW, *, reset_atexit=True, note=None) -> ModItem ¶

Try to create the item; on recursion error return the item from __ModItemsCache__.

origin() -> bool ¶

origin_state

Whether the modification value was set in the emulator flags before modification.

purge() -> None ¶

Unregister the reset function at exit, execute the additional exit functions in lifo order then the reset method and remove the item from __ModItemsCache__.

request() -> bool ¶

Whether the modification flag is currently set.

reset() -> None ¶

Resets the modification value to the initialization state.

sub_flag() -> None ¶

Remove the modification value from the emulator flags.

class vtermios.ModItemsHandle(tuple[ModItem]) ¶

A handler for modifications with multiple constants. Supports via iterations reset (lifo), sub_flag (lifo), add_flag (fifo), origin (fifo), request (fifo) and purge (lifo).

add_flag() -> None ¶

Add the modification values to the emulator flags.

origin() -> tuple[bool, ...] ¶

Whether the modification values was present in the emulator flags at initialization.

purge() -> None ¶

Unregister the reset functions at exit, execute the additional exit functions in lifo order then the reset method and remove the item from __ModItemsCache__.

request() -> tuple[bool, ...] ¶

Whether the modification flags are currently set.

reset() -> None ¶

Resets the modification values to the initialization state.

sub_flag() -> None ¶

Remove the modification values from the emulator flags.

Contextmanager

class vtermios.InappropriateDeviceHandler ¶

A contextmanager/suit for the modification functions. Primarily for debugging. Allows explicit handling of Inappropriate Device Errors (unusual error, raised e.g. when trying to modify the python shell in pycharm or also when working with pipes in the bash).

Application example:

The following block disables some escape sequences directly in the framework when an Inappropriate Device Error is raised.

>>> with InappropriateDeviceHandler(
>>>     action=lambda exp: (
>>>         vtframework.iodata.sgr.__STYLE_GATE__.destroy(),
>>>         vtframework.iodata.decpm.__DECPM_GATE__.destroy()
>>>         )
>>>     ):
>>>     mod_* ...

action: Callable[ [Exception], Any]

other_action: Callable[ [Exception], Any]

__enter__() -> None ¶

__exit__(exc_type, exc_val, exc_tb) -> Any ¶

__init__(action=..., other_action=...) -> None ¶

action will be executed when an Inappropriate Device Error (error number 6 under Windows, 25 under UNIX) is raised (default handling is raising).

other_action is executed on all other errors.

The functions receive the error as parameter and the return value is returned from __exit__.

handle(exc) -> Any ¶

Perform the action for exc.

staticmethod is_inappropriatedeverr(exc) -> bool ¶

Return whether exc is an inappropriate device error.

---

[1]	https://manpages.debian.org/bullseye/manpages-dev/termios.3.en.html#DESCRIPTION https://learn.microsoft.com/en-us/windows/console/setconsolemode#parameters

[2]	https://manpages.debian.org/bullseye/manpages-dev/termios.3.en.html#The_termios_structure https://learn.microsoft.com/en-us/windows/console/getconsolemode

[3]	https://manpages.debian.org/bullseye/manpages-dev/termios.3.en.html#VDISCARD ff.

[4]	https://learn.microsoft.com/en-us/windows/console/getconsolemode#parameters

---

Date:	11 Nov 2022
Version:	0.1
Author:	Adrian Hoefflin [srccircumflex]
Doc-Generator:	"pyiStructure-RSTGenerator" <prototype>