Commandline User Tools for Input Easification
Project description
CUTIE
Command line User Tools for Input Easification
A tool for handling common user input functions in an elegant way. It supports asking yes or no questions, selecting an element from a list with arrow keys, forcing the user to input a number and secure text entry while having many customization options.
For example the yes or no input supports forcing the user to match case, tab autocomplete and switching option with the arrow keys. The number input allows setting a minum and a maximum, entering floats or forcing the user to use integers. It will only return once the user inputs a number in that format, showing a warning to them if it does not conform.
It should work on all major operating systems (Mac, Linux, Windows).
Usage
These are the main functions of cutie.
example.py contains an extended version of this also showing off the select_multiple
option.
import cutie
if cutie.prompt_yes_or_no('Are you brave enough to continue?'):
# List of names to select from, including some captions
names = [
'Kings:',
'Arthur, King of the Britons',
'Knights of the Round Table:',
'Sir Lancelot the Brave',
'Sir Robin the Not-Quite-So-Brave-as-Sir-Lancelot',
'Sir Bedevere the Wise',
'Sir Galahad the Pure',
'Swedish captions:',
'Møøse']
# Names which are captions and thus not selectable
captions = [0, 2, 7]
# Get the name
name = names[
cutie.select(names, caption_indices=captions, selected_index=8)]
print(f'Welcome, {name}')
# Get an integer greater or equal to 0
age = cutie.get_number(
'What is your age?',
min_value=0,
allow_float=False)
# Get input without showing it being typed
quest = cutie.secure_input('What is your quest?')
print(f'{name}\'s quest (who is {age}) is {quest}.')
When run, as demonstrated in the gif above it yields this output:
Are you brave enough to continue? (Y/N) Yes
Kings:
[ ] Arthur, King of the Britons
Knights of the Round Table:
[ ] Sir Lancelot the Brave
[x] Sir Robin the Not-Quite-So-Brave-as-Sir-Lancelot
[ ] Sir Bedevere the Wise
[ ] Sir Galahad the Pure
Swedish captions:
[ ] Møøse
Welcome, Sir Robin the Not-Quite-So-Brave-as-Sir-Lancelot
What is your age? 31
What is your quest?
Sir Robin the Not-Quite-So-Brave-as-Sir-Lancelot's quest (who is 31) is to find the holy grail.
Installation
With pip from pypi:
pip3 install cutie
With pip from source or in a virtual environment:
pip3 install -r requirements.txt
Documentation
get_number
Get a number from user input. If an invalid number is entered the user will be prompted again.
Arguments
argument | type | default | description |
---|---|---|---|
prompt |
str | The prompt asking the user to input. | |
min_value |
float, optional | - infinity | The [inclusive] minimum value. |
max_value |
float, optional | infinity | The [inclusive] maximum value. |
allow_float |
bool, optional | True | Allow floats or force integers. |
Returns
The number input by the user.
secure_input
Get secure input without showing it in the command line.
Arguments
argument | type | description |
---|---|---|
prompt |
str | The prompt asking the user to input. |
Returns
The secure input.
select
Select an option from a list.
Arguments
argument | type | default | description |
---|---|---|---|
options |
List[str] | The options to select from. | |
caption_indices |
List[int], optional | None |
Non-selectable indices. |
deselected_prefix |
str, optional | [ ] |
Prefix for deselected option. |
selected_prefix |
str, optional | [x] |
Prefix for selected option. |
caption_prefix |
str, optional | |
Prefix for captions. |
selected_index |
int, optional | 0 | The index to be selected at first. |
Returns
The index that has been selected.
select_multiple
Select multiple options from a list.
It per default shows a "confirm" button. In that case space bar and enter select a line. The button can be hidden. In that case space bar selects the line and enter confirms the selection.
This is not in the example in this readme, but in example.py.
Arguments
argument | type | default | description |
---|---|---|---|
options |
List[str] | The options to select from. | |
caption_indices |
List[int], optional | Non-selectable indices. | |
deselected_unticked_prefix |
str, optional | ( ) |
Prefix for lines that are not selected and not ticked . |
deselected_ticked_prefix |
str, optional | (x) |
Prefix for lines that are not selected but ticked . |
selected_unticked_prefix |
str, optional | { } |
Prefix for lines that are selected but not ticked . |
selected_ticked_prefix |
str, optional | {x} |
Prefix for lines that are selected and ticked . |
caption_prefix |
str, optional | |
Prefix for captions. |
ticked_indices |
List[int], optional | [] |
Indices that are ticked initially. |
cursor_index |
int, optional | 0 | The index the cursor starts at. |
minimal_count |
int, optional | 0 | The minimal amount of lines that have to be ticked. |
maximal_count |
int, optional | infinity | The maximal amount of lines that have to be ticked. |
hide_confirm |
bool, optional | False |
Hide the confirm button. This causes <ENTER> to confirm the entire selection and not just tick the line. |
deselected_confirm_label |
str, optional | (( confirm )) |
The confirm label if not selected. |
selected_confirm_label |
str, optional | {{ confirm }} |
The confirm label if selected. |
Returns
A list of indices that have been selected.
prompt_yes_or_no
Prompt the user to input yes or no.
Arguments
argument | type | default | description |
---|---|---|---|
question |
str | The prompt asking the user to input. | |
yes_text |
str, optional | Yes |
The text corresponding to 'yes'. |
no_text |
str, optional | No |
The text corresponding to 'no'. |
has_to_match_case |
bool, optional | False |
Does the case have to match. |
enter_empty_confirms |
bool, optional | True | Does enter on empty string work. |
default_is_yes |
bool, optional | False | Is yes selected by default |
deselected_prefix |
str, optional | |
Prefix if something is deselected. |
selected_prefix |
str, optional | > |
Prefix if something is selected |
abort_value |
bool, optional | None |
The value on interrupt. |
char_prompt |
bool, optional | True |
Add a [Y/N] to the prompt. |
Returns
The bool what has been selected.
Contributing
If you want to contribute, please feel free to suggest features or implement them yourself.
Also please report any issues and bugs you might find!
Authors
License
The project is licensed under the MIT-License.
Acknowledgments
- This project uses the module Readchar for direct input handling.
GNU Terry Pratchett
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.