pick2 0.7.1

pick [](https://travis-ci.org/wong2/pick) [](https://pypi.python.org/pypi/pick)
====

**pick** is a small python library to help you create curses based interactive selection
list in the terminal. See it in action:



### Installation

$ pip install pick

### Usage

**pick** comes with a simple api:

>>> from pick import pick

>>> title = 'Please choose your favorite programming language: '
>>> options = ['Java', 'JavaScript', 'Python', 'PHP', 'C++', 'Erlang', 'Haskell']
>>> option, index = pick(options, title)
>>> print option
>>> print index

**outputs**

>>> C++
>>> 4

**pick** multiselect example:

>>> from pick import pick

>>> title = 'Please choose your favorite programming language (press SPACE to mark, ENTER to continue): '
>>> options = ['Java', 'JavaScript', 'Python', 'PHP', 'C++', 'Erlang', 'Haskell']
>>> selected = pick(options, title, multi_select=True, min_selection_count=1)
>>> print selected

**outputs**

>>> [('Java', 0), ('C++', 4)]


#### Options

* `options`: a list of options to choose from
* `title`: (optional) a title above options list
* `indicator`: (optional) custom the selection indicator, defaults to *
* `default_index`: (optional) set this if the default selected option is not the first one
* `multi_select`: (optional), if set to True its possible to select multiple items by hitting SPACE
* `min_selection_count`: (optional) for multi select feature to dictate a minimum of selected items before continuing
* `options_map`: (optional) a mapping function to pass each option through before displaying
* `multi_select_foreground_color`: (optional) forground color of a selected option within multi_select mode
* `multi_select_background_color`: (optional) background color of a selected option within multi_select mode

#### Register custom handlers

sometimes you may need to register custom handlers for specific keyboard keys, you can use the `register_custom_handler` API:

>>> from pick import Picker
>>> title, options = 'Title', ['Option1', 'Option2']
>>> picker = Picker(options, title)
>>> def go_back(picker):
... return None, -1
>>> picker.register_custom_handler(ord('h'), go_back)
>>> option, index = picker.start()

* the custom handler will be called with the `picker` instance as it's parameter.
* the custom handler should either return a two element tuple, or None.
* if None is returned, the picker would continue to run, otherwise the picker will stop and return the tuple.

#### Options Map

If your options are not in a format that you want displayed (such as a dictionary), you can pass in a mapping function which each option will be run through. The return value of the function will be displayed.

* the selected option returned will be the original value and not the displayed return result from the `options_map` function.

**pick** options map example:

>>> from pick import pick

>>> title = 'Please choose an option: '
>>> options = [{'label': 'option1'}, {'label': 'option2'}, {'label': 'option3'}]

>>> def get_label(option): return option.get('label')

>>> selected = pick(options, title, indicator='*', options_map=get_label)
>>> print selected

**displays**

Please choose an option:

* option1
option2
option3

**outputs**

>>> ({ 'label': 'option1' }, 0)

### Multi-Select Colors

Using the `multi_select_foreground_color` and `multi_select_background_color` options, you can specify the colors that are used when a user selects an option as part of the multi-select mode.

The accepted colors are any of the [curses](https://docs.python.org/2/library/curses.html) predefined color constants, passed as a string:
```
'COLOR_BLACK'
'COLOR_BLUE'
'COLOR_CYAN'
'COLOR_GREEN'
'COLOR_MAGENTA'
'COLOR_RED'
'COLOR_WHITE'
'COLOR_YELLOW'
```