pick

Install the core library using pip:

$ pip install pick

By default, pick uses the curses backend. If you prefer using blessed, install the optional extra:

$ pip install "pick[blessed]"

To use it, pass backend="blessed" to the pick() function.

The pick library supports different terminal rendering backends via the backend parameter in pick() or Picker.

• 'curses': The default backend using the standard Python curses module. Best for standalone terminal applications.
• 'blessed': Uses the blessed library for more advanced terminal capabilities.
• Backend instance: You can provide a custom implementation of the Backend interface to support different terminal environments or custom UI logic.

The BlessedBackend requires the blessed library as an optional dependency. If you attempt to use it without this library, an ImportError will be raised. You can install it using the following command:

pip install pick[blessed]

Use the pick function to present a list of options to a user. It returns a tuple containing the selected option and its index.

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)

To allow users to select multiple items, set multiselect=True. Users can mark items by pressing SPACE and confirm their selection with ENTER. When multiselect=True, the function returns a list of tuples, where each tuple contains (option, index).

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, multiselect=True, min_selection_count=1)

print(selected)
# Example output: [('Java', 0), ('C++', 4)]

The pick() function is the simplest way to create a terminal-based selection menu. It initializes a Picker and starts the interaction loop immediately. You can pass a list of strings or Option objects.

Returns:

• In single-select mode: A tuple of (selected_option, index).
• In multiselect mode: A list of tuples [(option, index), ...].
• If the user quits via quit_keys: None, -1 (single-select) or [] (multiselect).

from pick import pick, Option

# Simple string selection
result, index = pick(['Apple', 'Banana', 'Cherry'], title='Select a fruit')

# Advanced selection with Option objects
options = [
    Option('Apple', value=1, description='Red and crunchy'),
    Option('Banana', value=2, description='Yellow and soft'),
    Option('Cherry', value=3, description='Small and sweet'),
]
result, index = pick(options, title='Select a fruit')

The CursesBackend class provides a terminal-based implementation of the Backend interface using the Python curses standard library. It is useful for creating interactive terminal user interfaces.

When initializing, you can optionally provide an existing curses.window object. The setup() method initializes the terminal environment (setting default colors and hiding the cursor), while teardown() is intended to be handled by a curses.wrapper to ensure proper cleanup.

import curses
from pick.curses_backend import CursesBackend

# Example of manual initialization (though typically managed by a wrapper)
stdscr = curses.initscr()
backend = CursesBackend(screen=stdscr)
backend.setup()

# ... perform operations ...

backend.teardown()