vtf io io

↑ vtf-io

io

The module contains the basic interfaces to the stdin stream for creating the input objects of the framework, the query function kbhit, and an output function. Also, other objects for handling the generic input, such as sentinels for too fast inputs, and an adapter for stdin that allows InputSuper to supervise manual escape sequences.

The input objects are always created by a vtiinterpreter from the stdin stream.

Module contents

Functions

io._kbhit() -> bool ¶

The original kbhit function.

io.flushio() -> None ¶

Flush stdin and stdout.

io.getch(block=False, interpreter=MainInterpreter()) -> Char | Key | Mouse | Reply | EscSegment ¶

Read an input from stdin and complete sequential inputs (UTF8 sequence / escape sequences). Block until an input can be read if block is True, otherwise return Char("") if nothing can be read. For the creation of the objects interpreter is used.

io.kbhit() -> bool ¶

Returns whether stdin is waiting to be read. This function can be overwritten by StdinAdapter.

io.out(*__s, sep="", end="", flush=False) -> None ¶

Write to stdout.

Objects

Stdin readers

class io.Input(Thread) ¶

This class provides methods to read from stdin. The MainInterpreter is accessible via __interpreter__. Can be started as a daemon thread to pipe the input in the background during a loop.

Manual entry of escape sequences will cause blocking until it is completed correctly (may cause errors if the sequence is informal).

Can be used as a contextmanager/suit (with): [ Resets the emulator modifications (mod) and ] stops the thread loop on exit. Note that if thread_block is True, the reading process in the thread blocks even after exiting until the next character; in combination with mod it blocks even until the next line break!

Spam handlers works most reactively in combination with thread_block. For more information see the SpamHandle, SpamHandleNicer, SpamHandleRestrictive and SpamHandleOne.

__interpreter__: MainInterpreter

modblock: ModItem | ModItemsHandle | ModDummy

modecho: ModItem | ModDummy

t_block: bool

t_keepalive: bool

t_smoothness: float

t_spam: SpamHandle | Callable

__enter__() -> Input ¶

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

__init__(thread_smoothness=.003, thread_block=False, thread_spam=SpamHandle(), mod=True) ¶

The thread loop can be slowed down for a smoother run over thread_smoothness. If thread_block is True, this parameter is ignored and blocking read from stdin is enabled. A handle for fast inputs can be set via thread_spam as an SpamHandler object. If mod is True, the emulator is modified for the function of the object and the reset via the contextmanager/suit/exit is available (non-block and non-echo if not already modified accordingly). The items are then accessible under modblock and modecho in the object. The value reset_atexit in the ModItem's is True by default to reset the modifications to the emulator when exiting the Python interpreter.

exit() -> None ¶

[ Reset the emulator modifications ] and stop the thread loop.

getch(block=False) -> Char | Key | Mouse | Reply | EscSegment ¶

Read an input from stdin and complete sequential inputs (UTF8 sequence / escape sequences). Block until an input can be read if block is True, otherwise return Char("") if nothing can be read.

staticmethod kbhit() -> bool

Returns whether stdin [ adapter ] is waiting to be read.

pipe_get(block=False) -> Char | Key | Mouse | Reply | EscSegment ¶

Read an object from the pipe. Block until an object can be read if block is True, otherwise return Char("") if nothing can be read.

read(get=True, block=True, smoothness=.0, flush_io=False) -> Char | Key | Mouse | Reply | EscSegment | None ¶

Flush stdin and stdout if flush_io is True. Then wait smoothness seconds before reading from stdin (block is forwarded to getch). Return the read object if get is True, otherwise put it in the pipe.

run() -> None ¶

Read with or without blocking (self.t_block) while self.t_keepalive is True and put the objects in the pipe. Wait self.t_smoothness seconds in an iteration if self.t_block is False.

send(block=False) -> bool ¶

Read with or without blocking and put the object directly in the pipe. Returns whether the input is putted to the pipe (see SpamHandle).

start(*, daemon=True) -> None ¶

[Re-]Start the thread [ as daemon ].

stop() -> None ¶

Stop the thread loop in self.run.

class io.InputSuper(Input) ¶

Derived from Input, modified in such a way that the manual input of escape sequences is recognized and supervised. Creates ManualESC(intro=sequence) from manually entered escape sequences. Requires sys.stdin and io.kbhit to be modified via StdinAdapter.

>>> StdinAdapter()
>>> [with] [var = ] InputSuper(...

The emulator modification can be handled via the adapter instead of the input class. Therefore, the contextmanager/suit function is assigned to StdinAdapter. On exit, the exit method of StdinAdapter is executed, and the own thread is then terminated by the raised EOFError.

adapter_processing_tolerance: float = 0.002

An additional time tolerance if the next character of a sequential input cannot be read immediately. If even after that the next character cannot be read, the input is recognized as manual.

me_finals: tuple[int | tuple[int, int]]

me_tt: float

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

__init__(thread_smoothness=.003, thread_block=False, thread_spam=SpamHandle(), manual_esc_tt=.8, manual_esc_interpreter=False, manual_esc_finals=(0xa, 0xd, 0x1b)) ¶

Additional parameters:

manual_esc_tt (typing time): sets the time allowed between keystrokes. (Note: if the parameter is 0, pressing ESC will create <ManualESC(intro="\x1b")> == ManualESC() immediately.

manual_esc_interpreter: use the interpreters also for manually entered escape sequences.

manual_esc_finals: defines the final characters code numbers with which to end an manual entered escape sequence. A range can be defined via an sub-tuple inside the main-tuple ( (start, incl. end) ). By default the operating system independent input of Enter or ESC is defined.

getch(block=False) -> Char | Key | Mouse | Reply | EscSegment | ManualESC ¶

Get a character from the stdin adapter, complete sequential input (UTF8 sequence / escape sequences) but recognize and supervise manual input of esc. Block until an input can be read if block is True, otherwise return Char("") if nothing can be read.

raises:	AttributeError: sys.stdin was reset to the origin. EOFError: StdinAdapter was marked to finish and is empty.

run() -> None ¶

Read with or without blocking (self.t_block) while self.t_keepalive is True and put the objects in the pipe. Wait self.t_smoothness seconds in an iteration if self.t_block is False.

Recognize and supervise manual input of esc.

Bad Input Sentinels

Spam handlers

class io.SpamHandle ¶

A handler (callable) for repeated input.

Applied inside run in Input and executed with the input object and the pipe.

Inside __call__, an input is discarded if it was made within spamtime, it is equal to the previous input, and the counter is equal to spammax.

If pipe is empty when called, the query is skipped, the item is placed in the pipe, and the handler is reset; even if a spam condition is false.

The corresponding methods (in_spamtime and else_) are swapped out of __call__, for targeted modification in inheritances.

count: int

prev_char: Char | Key | Mouse | Reply | EscSegment | ManualESC | None

spammax: int

spamtime: int

time: int

__call__(char, pipe) -> bool ¶

__init__(spammax=0, spamtime=.4) ¶

A number of equal inputs allowed in spam time can be specified by spammax, spamtime defines the maximum cadence allowed.

else_(char, pipe) -> bool ¶

Executed when the pipe is empty, the input is not in spam time or the current item is different from the previous one.

in_spamtime(char, pipe) -> bool ¶

Executed when the input is in the spam time and the current item is equal to the previous one.

reset(char) -> None ¶

send(char, pipe) -> bool ¶

class io.SpamHandleNicer(SpamHandle) ¶

Derived from SpamHandle, modified in such a way that the repeated input of the defined types with the spam cadence is always discarded, except the pipe is empty.

__init__(*must_nice, spammax=0, spamtime=.4) ¶

A number of equal inputs allowed in spam time can be specified by spammax, spamtime defines the maximum cadence allowed.

The "nice" ones are specified as types, basic types for inputs are Char, Key, Mouse, Reply, EscSegment and ManualESC.

class io.SpamHandleOne(SpamHandle) ¶

Derived from SpamHandle, modified in such a way that all input is discarded except when the pipe is empty.

class io.SpamHandleRestrictive(SpamHandle) ¶

Derived from SpamHandle, modified in such a way that the input of the defined types requires an empty pipe.

__init__(*exclusive, spammax=0, spamtime=.4) ¶

The "exclusive" ones are specified as types, basic types for inputs are Char, Key, Mouse, Reply, EscSegment and ManualESC.

The StdinAdapter

class io.StdinAdapter(Thread, TextIO) ¶

An adapter for sys.stdin. This allows a more precise query about whether characters can be read from the stream (unlike select.select/msvcrt.kbhit, which in fact only consider a keystroke) and therefore a more dynamic processing of sequential inputs (escape sequences). Starts itself as daemon thread and reads from the original stdin while self.keepalive is True and puts the read characters into a pipe. Is assigned to sys.stdin and overwrites kbhit.

[ i ] InputSuper expects that sys.stdin has been adapted that way.

When adapter.stop or adapter.exit is executed, the loop in the thread is terminated after the next read from the original stdin; sys.stdin and kbhit is reset after the full read from the adapter; this requires the execution of adapter.get until an EOFError is raised!. Immediate abort of the reading process from the original stdin is not possible. Note that executing adapter.exit or leaving the contextmanager (with) also resets the emulator's modifications (if the parameter mod was set to True), which can cause stdin to block the reading process until the next newline. The context manager also stops the thread as described below when exiting.

__semaphore__: _Semaphore

_stdin_: TextIO[str] = sys.stdin

keepalive: bool

modblock: ModItem | ModItemsHandle | ModDummy

modecho: ModItem | ModDummy

__enter__() ¶

__exit__(exc_type, exc_val, exc_tb) ¶

__init__(mod=True) ¶

If mod is True, the emulator is modified for the function of the object (non-block and non-echo if not already modified accordingly) and the reset via the contextmanager/suit/exit is available. The items are then accessible under modblock and modecho in the object. The value reset_atexit in the ModItem's is True by default to reset the modifications to the emulator when exiting the Python interpreter.

raises:	RecursionError: if sys.stdin is already adapted.

clear() -> None ¶

drain the adapter buffer pipe

exit() ¶

[ Reset the emulator modifications and ] stop the thread loop after the next read from stdin (blocks). Note that if mod was set to True the read process of stdin is blocked not only until the next character but until the next line break. Reset sys.stdin and kbhit after everything has been read from the buffer of the adapter; this requires the execution of adapter.get until an EOFError is raised!

fileno() -> int ¶

_stdin_.fileno()

flush() -> None ¶

_stdin_.flush()

get(block=True) -> bytes ¶

Get a character from the buffer pipe of the adapter, block until a character is present or return b"" immediately if none is present.

raises:	EOFError: The adapter has been marked for termination and the buffer is empty (sys.stdin and kbhit being reset).

isatty() -> bool ¶

_stdin_.isatty()

kbhit() -> bool ¶

Returns whether a character is in the pipe or in stdin to get.

read(n) -> str ¶

adapter.get()

readable() -> bool ¶

True

run() -> None ¶

Read continuously from stdin while self.keepalive is True and put the read characters into a pipe. Block in the reading process until a character can be read.

start() -> None ¶

[Re-]Start the thread loop and overwrite sys.stdin and kbhit.

stop() -> None ¶

Stop the thread loop after the next read from stdin (blocks). Reset sys.stdin and kbhit after everything has been read from the buffer of the adapter; this requires the execution of adapter.get until an EOFError is raised!

writable() -> bool ¶

False

---

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