Module inputs¶

Functions for terminal input.

New in version 0.3.0.

Changed in version 0.16.0: The exc_on_cancel parameters of the functions read, select, yesno, and menu now default to None. This means that the value of the new module level attribute exception_on_cancel will be used. As this defaults to True the default behavior of the functions has changed. To restore the old behavior set exception_on_cancel to False.

The terminal must support ANSI escape sequences.

Overview¶

`exception_on_cancel`	Default value for `exc_on_cancel` parameters.
`check_float`	Return a check function for floats.
`check_int`	Return a check function for integers.
`check_str`	Return a check function for strings.
`menu`	Show a simple menu.
`read`	Read a line of input and check if it is allowed.
`select`	Show an input with selectable options.
`yesno`	Show yes/no input prompt.

salmagundi.inputs.exception_on_cancel = True¶: Default value for exc_on_cancel parameters.

salmagundi.inputs.check_float(predicate)[source]¶

Return a check function for floats.

The returned function can be used as the check argument in the read() function.

Parameters: predicate (callable(float)) – predicate function

New in version 0.6.0.

salmagundi.inputs.check_int(predicate)[source]¶

Return a check function for integers.

The returned function can be used as the check argument in the read() function.

Parameters: predicate (callable(int)) – predicate function

New in version 0.6.0.

salmagundi.inputs.check_str(min_len=0, max_len=None, chars=None, negate=False)[source]¶

Return a check function for strings.

The returned function can be used as the check argument in the read() function.

Parameters

min_len (int) – minimal length of the string
max_len (int) – maximal length of the string (None means no limit)
chars (str) – allowed characters
negate (bool) – if True only characters not in chars are allowed

New in version 0.6.0.

salmagundi.inputs.menu(prompt, titles, cols=1, col_by_col=True, exc_on_cancel=None, caption=None, default=None)[source]¶

Show a simple menu.

If the input is not allowed the prompt will be shown again. The input can be cancelled with EOF (^D).

The caller has to take care that the menu will fit in the terminal.

def update():
    ...

def sort(desc=True, duration=True):
    ...

items = (
    ('Update', update),
    ('Sort duration desc', sort),
    ('Sort duration asc', sort, False),
    ('Sort size desc', sort, True, False),
    ('Sort size asc', sort, False, False),
)
i = menu('> ', tuple(x[0] for x in items))
print()
if i is not None:
    items[i][1](*items[i][2:])

[1] Update
[2] Sort duration desc
[3] Sort duration asc
[4] Sort size desc
[5] Sort size asc
>

Parameters

prompt (str) – the prompt
titles (tuple) – the titles of the menu options
cols (int) – number of columns
col_by_col (bool) – if True the menu will be filled column-by-column, otherwise row-by-row
exc_on_cancel (bool) – if True an EOF will cause an Exception; if None the value of exception_on_cancel will be used
caption (str) – caption for the menu
default (int) – number of the default menu option

Returns

index of the selected option in titles or None if cancelled and exc_on_cancel=False

Return type

int or None

Raises

EOFError – if input was cancelled and exc_on_cancel=True
TypeError – if titles is not a tuple or default is not an integer

New in version 0.4.0.

Changed in version 0.6.0: Add parameter caption

Changed in version 0.17.0: Add parameter default

salmagundi.inputs.read(prompt='', default=None, check=None, exc_on_cancel=None, *, noecho=False)[source]¶

Read a line of input and check if it is allowed.

If the input is not allowed the prompt will be shown again. The input can be cancelled with EOF (^D).

If the check parameter is set to None any input is allowed, else it must be a callable that takes a string as a parameter and returns the (converted) input value or raises ValueError if the input is not allowed.

There are 3 predefined check functions in this module: check_str(), check_int() and check_float().

>>> read('Number: ', default='42')
Number: 21
'21'
>>> read('Number: ', default='42', check=int)
Number:
42

Parameters

prompt (str) – the prompt
default (str or None) – default value that will be used if no input is provided
check (callable(str) or None) – the check parameter (see above)
exc_on_cancel (bool) – if True an EOF will cause an Exception; if None the value of exception_on_cancel will be used
noecho (bool) – if set to True getpass() will be used instead of input()

Returns

(converted) input value or None if input was cancelled and exc_on_cancel=False

Return type

str or return-type of the check callable or None

Raises

EOFError – if input was cancelled and exc_on_cancel=True
TypeError – if default is not of type str

Changed in version 0.15.0: Add parameter noecho

salmagundi.inputs.select(prompt, options, default=None, case_sensitive=False, exc_on_cancel=None)[source]¶

Show an input with selectable options.

If the input is not allowed the prompt will be shown again. The input can be cancelled with EOF (^D).

>>> select('Select: [T]op, [B]ottom, [L]eft, [R]ight > ', 'TBLR')
Select: [T]op, [B]ottom, [L]eft, [R]ight > b
1

Parameters

prompt (str) – the prompt
options (str or tuple) – the options; if all options are only 1 character a string can be used, else a tuple of strings
default (str or None) – default value that will be used if no input is provided
case_sensitive (bool) – if False case of typed characters will be ignored
exc_on_cancel (bool) – if True an EOF will cause an Exception; if None the value of exception_on_cancel will be used

Returns

index of the selected option in options or None if cancelled and exc_on_cancel=False

Return type

int or None

Raises

EOFError – if input was cancelled and exc_on_cancel=True
TypeError – if options is not str or tuple of strings

New in version 0.4.0.

salmagundi.inputs.yesno(prompt, yesno, exc_on_cancel=None)[source]¶

Show yes/no input prompt.

If the typed character (case-insensitive) is not allowed (i.e. not in yesno) the prompt will be shown again. The input can be cancelled with EOF (^D).

>>> yesno('Exit program?', 'yN')
Exit program? [yN] Y
True

Parameters

prompt (str) – the prompt
yesno (str) – the characters for yes (index 0) and no (index 1); if one is upper and the other lower case, the upper case character is the default
exc_on_cancel (bool) – if True an EOF will cause an Exception; if None the value of exception_on_cancel will be used

Returns

True for yes, False for no, None if cancelled and exc_on_cancel=False

Return type

bool or None

Raises

EOFError – if input was cancelled and exc_on_cancel=True
TypeError – if yesno is not of type str
ValueError – if yesno is not of length 2

Salmagundi

Navigation

Related Topics

Module inputs¶

Overview¶