Home

Welcome to the choice wiki!

API Reference

Almost ready!

Basic Usage

import choice

# Get a yes or no response (default is no)
confirm = choice.Binary('Are you sure you want to delete?', False).ask()
if confirm:
    deleteIt()

# Input an arbitrary value, check for correctness
howmany = choice.Input('How many pies?', int).ask()
print("You ordered {} pies".format(howmany))

# Choose from a set of options
entree = choice.Menu(['steak', 'potatoes', 'eggplant'])

Input checking/validation

An optional second argument to Input specifies an input converter, which specifies the format (and conversion) of the input. You can use standard Python type conversions (int, float); for example, passing int makes integers the only valid input, and returns the result as an integer:

>>> result = choice.Input('Enter an int', int).ask()
Enter an int:
? abc
Invalid value
Enter an int:
? 12
>>> result
12

If you just want to check whether the input is of the correct format, use choice.validate, which takes a function that returns a boolean. For example, to check whether the input contains an "a":

>>> result = choice.Input('Enter a string with "a"', choice.validate(lambda s: 'a' in s)).ask()
Enter a string with "a":
? 12345
Invalid value
Enter a string with "a":
? qwerty
Invalid value
Enter a string with "a":
? bbbab
>>> result
'bbbab'

choice.validate returns the string the user typed. For more advanced checking, try choice.matches, which takes a regular expression (see the re module for regex syntax). choice.matches returns a tuple containing (the original string, the match object).

>>> pattern = '(?P<areacode>\d{3})-\d{3}-\d{4}'
>>> result = choice.Input('Enter a US phone #', choice.matches(pattern)).ask()
Enter a US phone #:
? hello
Invalid value
Enter a US phone #:
? 1234567890
Invalid value
Enter a US phone #:
? 123-456-7890
>>> result
('123-456-7890', <_sre.SRE_Match object at 0x10cd780a8>)
>>> result[1].group('areacode')
'123'

More Menu options

In addition to the default usage, Menu also supports pagination (in the console), per-item actions, and global actions.

Per-item actions

Pass a list of actions as the second argument to Menu:

>>> result = choice.Menu(['ribeye', 'sirlion', 'burger'], ['rare', 'medium', 'well-done']).ask()
Make a choice:
 0: ribeye
 1: sirlion
 2: burger

Enter number or name; return for next page
? 0

Select an action:
 0: rare
 1: medium
 2: well-done
 b: back
? 1

>>> result
('ribeye', 'medium')

ask() returns a tuple with the action name as the second element.

Global actions

The user can select global actions without first selecting an item. If a global action is selected, ask() returns a tuple (None, 'nameofaction'). Pass global actions as the global_actions argument to Menu():

>>> ga=['moretime', 'quit']
>>> result = choice.Menu(['ribeye', 'sirlion', 'burger'], ['rare', 'medium', 'well-done'], global_actions=ga).ask()
Make a choice:
 0: ribeye
 1: sirlion
 2: burger

    moretime
    quit

Enter number or name; return for next page
? quit

>>> result
(None, 'quit')
>>> result = choice.Menu(['ribeye', 'sirlion', 'burger'], ['rare', 'medium', 'well-done'], global_actions=ga).ask()
Make a choice:
 0: ribeye
 1: sirlion
 2: burger

    moretime
    quit

Enter number or name; return for next page
? 1

Select an action:
 0: rare
 1: medium
 2: well-done
 b: back
? b

Make a choice:
 0: ribeye
 1: sirlion
 2: burger

    moretime
    quit

Enter number or name; return for next page
? moretime

>>> result
(None, 'moretime')