Skip to main content

pick an option in the terminal with a simple GUI

Project description

pick [![Build Status](]( [![PyPI](](

**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


>>> 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


>>> [('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


Please choose an option:

* option1


>>> ({ '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]( predefined color constants, passed as a string:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Built Distribution

pick2-0.7.1-py2.py3-none-any.whl (7.4 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page