pzp

Pure-python fzf-inspired element picker

Requirements

Python 3.6+

Install

pip install pzp

Usage

import pzp
pzp.pzp(['a', 'b', 'c'])

Layout

The finder by default starts in fullscreen mode. You can make it start below the cursor with fullscreen=False option. Also, with the height argument you can limit the window height.

pzp.pzp(candidates=range(0, 1000), fullscreen=False, height=20)

You can choose between the following layout using the layout option.

default Display from the bottom of the screen
reverse Display from the top of the screen
reverse-list Display from the top of the screen, prompt at the bottom

Search syntax

The finder starts in "extended-search mode" where you can type in multiple search terms delimited by spaces. e.g. ^music .mp3$ sbtrkt !fire

Token	Match type	Description
`t1 t2`	tokens-match	Items that include `t1` and `t2`
`'star wars`	line-match (not-splitted)	Items that include `star wars`
`^music`	prefix-exact-match	Items that start with `music`
`.py$`	suffix-exact-match	Items that end with `.py`
`!fire`	inverse-exact-match	Items that do not include `fire`
`!^music`	inverse-prefix-exact-match	Items that do not start with `music`
`!.py$`	inverse-suffix-exact-match	Items that do not end with `.py`

Key/Event Bindings

keys_binding argument allows you to bind one or more keys to one action. You can use it to customize key bindings or implementing custom behaviors.

try:
    item = pzp.pzp(
        candidates=candidates,
        keys_binding={
            "custom-action": ["ctrl-o"],
            "exclamation": ["!"]
        },
    )
    print(item)
except CustomAction as action:
    print(action.action)
    print(action.selected_item)

Available Keys

Key	Synonyms type
space
tab
btab	shift-tab
enter
esc
insert
del
bspace	bs
up
down
left
right
home
end
pgdn	page-down
pgup	page-up
f1 - f12
ctrl-/
ctrl-\
ctrl-]
ctrl-^
ctrl-a - ctrl-z
any single character

Available Actions

A key can be bound to one of following actions or to a custom action.

Action*	Default binding
accept	enter
abort	ctrl-c ctrl-g ctrl-q esc
beginning-of-line	ctrl-a home
backward-char	ctrl-b left
forward-char	ctrl-f right
end-of-line	ctrl-e end
backward-delete-char	ctrl-h bspace
delete-char	del
up	ctrl-k ctrl-p up
down	ctrl-j ctrl-n down
page-down	pgdn
page-up	pgup
ignore

Lazy Mode

lazy argument allows you to enable the lazy mode. If the Lazy mode is enabled, starts the finder only if the candidates are more than one. If there is only one match returns the only match, if there is no match returns None.

User Input Prompts

To ask for user input, you can use the pzp.prompt() function. This function is designed to be a drop-in replacement for the click.input() function. By default, it accepts strings, but you can ask for any other type. In order to do this, Click needs to be installed.

For instance, you can ask for a valid integer:

value = pzp.prompt('Please enter a valid integer', type=int)

Additionally, the type will be determined automatically if a default value is provided. For instance, the following will only accept floats:

value = pzp.prompt('Please enter a number', default=42.0)

Confirmation Prompts

To ask if a user wants to continue with an action, you can use the pzp.confirm(). By default, it returns the result of the prompt as a boolean value:

if pzp.confirm('Are you sure?', default=True):
    print('Ok')

Licence

MIT

Metadata

Release files for pzp 0.0.28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pzp 0.0.28
File	Size	Uploaded
pzp-0.0.28.tar.gz	25.1 kB	Feb 8, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for pzp 0.0.28
File	Interpreter	ABI	Platform	Reset
pzp-0.0.28-py2.py3-none-any.whl 25.6 kB Feb 8, 2025	Python 3, Python 2	none	any	Details

Total release size: 50.8 kB

Release files / pzp-0.0.28.tar.gz

Download URL	pzp-0.0.28.tar.gz
Size	25.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`c4edf1dafe724f9731cf8a5aed483f7f6b1016425c30855258b7e3fcb9bbd04e`
BLAKE2b-256 checksum How to use checksums	`0ed637b838d97b433c12b7cdb6d795c1e6fefbac74f90573d984e936918926a9`
Upload date	Feb 8, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.12.0 requests/2.32.3 setuptools/75.8.0 requests-toolbelt/1.0.0 tqdm/4.67.1 CPython/3.12.8`

Release files / pzp-0.0.28-py2.py3-none-any.whl

Download URL	pzp-0.0.28-py2.py3-none-any.whl
Size	25.6 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`e90deea90538d99199f9b129f46d09a0b3308ab4b59512d8e8629bba49834da5`
BLAKE2b-256 checksum How to use checksums	`137c27586576587cbab57850081f04df07b7e3f185794982deacb1b697d73ecb`
Upload date	Feb 8, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.12.0 requests/2.32.3 setuptools/75.8.0 requests-toolbelt/1.0.0 tqdm/4.67.1 CPython/3.12.8`