Welcome to simpleinput’s documentation!

simpleinput implements functions that retrieve user inputs of some determined type.

Usage

The functions defined in this module are designed to be a more robust alternative to Python’s input and raw_input built-ins. All functions expect a certain type of input and keeps asking the user for a input of the correct type if it is not given.

A program that asks for two numbers and prints their sum could be implemented naively as

>>> print('Result: ', input('Two numbers:\n<--') + input()) 
Two numbers:
<-- 1
<-- 2
Result: 3

This is a poor implementation for two reasons: The input() built-in executes arbitrary Python code that can be exploited by malicious users. If the user types some bad numeric value it will fail by printing a nasty traceback and shutting down the program.

The float_input() function in this library works similarly, but is safer and more user friendly:

>>> print('Result: ', float_input('Two numbers:\n<--') + float_input()) 
Two numbers:
<-- 1
<-- 2
Result: 3.0

If the user types an invalid numeric string, the new implementation complains and asks for a new valid value:

>>> print('Result: ', float_input('Two numbers:\n<--') + float_input()) 
Two numbers:
<-- 1_2
    error: invalid float!
<-- 1
<-- 2
Result: 3

There are other functions specialized in different types of arguments. See the section API Documentation for extra help.

Advanced features

TODO: document me!

API Documentation

Boolean types

yn_input(text=u'<-- ', yes=u'yes', no=u'no', yn=(True, False), case=False, first_letter=True, error_msg=None, getinput=None, printline=None, error=None)

Takes a yes/no boolean input

Parameters :

text : str

Text asking for user input.

yes, no : str

Strings representing the True and False values

yn : tuple (yes, no)

Set the values of each possible yes/no result. The default is (True, False).

case : bool

If True, the input is case sensitive.

first_letter : bool

If True and the first letter of yes is different of no, it accepts a single letter as input (e.g., the string “y” becomes equivalent to “yes”).

error_msg : str

A string with the error message. The string is formated using the “str.format” method with x.format(yes=yes, no=no, indent=indent). yes and no are the same parameters listed above, and indent is a string with white spaces of the same size of the last line of the prompt text.

getinput : list or callable

If it is a list, it corresponds to a list of user inputs that is read sequentially. If it is a callable, it must be a function that asks for user input when called with no arguments.

printline : callable

Prints data to user. The default implementation simply writes data directly to sys.stdout.

error : callable

Function that prints error messages to the user. The default implementation simply calls the printline function supplied by the callee.

Examples

>>> value = yn_input('value: ', getinput=['bar', 'y'])
value: bar
       error: type "yes" or "no".
value: y
>>> value
True

tf_input(text=u'<-- ', true=u'true', false=u'false', case=False, first_letter=True, error_msg=None, getinput=None, printline=None, error=None)

Similar to yn_input, but the default values are ‘True’ and ‘False’.

Parameters :

Similar to `yn_input`, but the parameters ``yes``, ``no`` are renamed :

respectively as ``true``, ``false`` and changing ``yn`` is not :

supported. :

getinput : list or callable

If it is a list, it corresponds to a list of user inputs that is read sequentially. If it is a callable, it must be a function that asks for user input when called with no arguments.

printline : callable

Prints data to user. The default implementation simply writes data directly to sys.stdout.

error : callable

Function that prints error messages to the user. The default implementation simply calls the printline function supplied by the callee.

Examples

>>> value = tf_input('value: ', getinput=['bar', 'true'])
value: bar
       error: type "true" or "false".
value: true
>>> value
True

Numeric types

int_input(text=u'<-- ', start=None, end=None, error_msg=None, error_range=None, shift=0, getinput=None, printline=None, error=None)

Takes an integer number as input.

An alias to numeric_input with the parameter readnum set to the builtin function int.

Examples

>>> value = int_input('value: ', getinput=['0.1', '1'])
value: 0.1
       error: must be an integer!
value: 1
>>> value
1

float_input(text=u'<-- ', start=None, end=None, error_msg=None, error_range=None, shift=0, getinput=None, printline=None, error=None)

Takes an float number as input.

An alias to numeric_input with the parameter readnum set to the builtin function float.

Examples

>>> value = float_input('value: ', getinput=['None', '1'])
value: None
       error: must be a float!
value: 1
>>> value
1.0

numeric_input(text=u'<-- ', start=None, end=None, error_msg=None, error_range=None, shift=0, readnum=None, getinput=None, printline=None, error=None)

Expects a numeric input. Numbers can be integers, floating point, complex or fractions.

Parameters :

text : str

Text asking for user input.

start, end : int

Numerical range: result must be greater or equal to start and smaller or equal to end.

error_range : str

Error message shown if input does not represent a number. The string is formated using a indent keyword value which is a white space string setting the indentation identical to the user input and with the start and end values.

error_msg : str

Error message shown if input does not represent a number. Is formatted with the same arguments as error_range.

shift : int

The result is added to shift.

readnum : callable

Function that reads number from strings of text.

getinput : list or callable

If it is a list, it corresponds to a list of user inputs that is read sequentially. If it is a callable, it must be a function that asks for user input when called with no arguments.

printline : callable

Prints data to user. The default implementation simply writes data directly to sys.stdout.

error : callable

Function that prints error messages to the user. The default implementation simply calls the printline function supplied by the callee.

Examples

>>> value = numeric_input('value: ', 1, 10, getinput=['0.1', '5/2'])
value: 0.1
       error: must in range [1..10]
value: 5/2
>>> value
Fraction(5, 2)

Other

choice_input(text, choices, enum=None, prompt=None, case=False, ret_choice=True, error_msg=None, getinput=None, printline=None, error=None)

Asks user to choose between a set of options.

Parameters :

text : str

Text introducing the list of choices.

choices : iterable

List of all choices.

enum : iterable

A list of strings that represents each choice. The default is to enumerate the choices from 1 to len(choices).

prompt : bool

The message asking for the user input.

case : bool

If True, the input is case sensitive.

sep : str

A string separating the enumeration from the choice text. The default string is ‘) ‘.

ret_choice : bool or iterable

If ret_choice is True (default), it returns the choice given by the user. If it is False, it returns the index of the corresponding choice. If ret_choice is an iterable, it returns ret_choice[idx].

error_msg : str

A string with the error message.

getinput : list or callable

If it is a list, it corresponds to a list of user inputs that is read sequentially. If it is a callable, it must be a function that asks for user input when called with no arguments.

printline : callable

Prints data to user. The default implementation simply writes data directly to sys.stdout.

error : callable

Function that prints error messages to the user. The default implementation simply calls the printline function supplied by the callee.

Examples

>>> value = choice_input('Options:', ['foo', 'bar', 'foobar'], getinput=['0', '1'])
Options:
  1) foo
  2) bar
  3) foobar
<-- 0
    invalid choice!
<-- 1

Indices and tables

• Index
• Module Index
• Search Page