pzp
==============
Pure-python fzf-inspired element picker
[](https://github.com/andreax79/pzp/actions)
[](https://badge.fury.io/py/pzp)
[](https://pypi.org/project/pzp)
[](https://pepy.tech/project/pzp)
[](https://github.com/psf/black)
[](https://snyk.io/test/github/andreax79/pzp)
[](https://pzp.readthedocs.io/en/latest/)
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`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) option.
Also, with the [`height`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) argument you can limit the window height.
```python
pzp.pzp(candidates=range(0, 1000), fullscreen=False, height=20)
```
[](https://asciinema.org/a/WtgiYfdtZjlShbeZaHuf5hWCZ?autoplay=1)
You can choose between the following layout using the [`layout`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) 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`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) argument allows you to bind one or more keys to one action.
You can use it to customize key bindings or implementing custom behaviors.
```python
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`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) 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()`](https://pzp.readthedocs.io/en/latest/api/module/#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](https://github.com/pallets/click) needs to be installed.
For instance, you can ask for a valid integer:
```python
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:
```python
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()`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.confirm).
By default, it returns the result of the prompt as a boolean value:
```python
if pzp.confirm('Are you sure?', default=True):
print('Ok')
```
Licence
-------
MIT
Links
-----
* [fzf](https://github.com/junegunn/fzf)
* [ANSI Escape Sequences](https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797)
* [pyte, python terminal emulator](https://github.com/selectel/pyte)
* [Grip, GitHub Readme Instant Preview](https://github.com/joeyespo/grip)
* [Black, The Uncompromising Code Formatter](https://github.com/psf/black)
* [mkdocstrings, Automatic documentation from sources](https://github.com/mkdocstrings/mkdocstrings)
* [Click, Command Line Interface Creation Kit](https://github.com/pallets/click)
Raw data
{
"_id": null,
"home_page": "http://github.com/andreax79/pzp",
"name": "pzp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "fzf, picker, cli",
"author": "Andrea Bonomi",
"author_email": "andrea.bonomi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0e/d6/37b838d97b433c12b7cdb6d795c1e6fefbac74f90573d984e936918926a9/pzp-0.0.28.tar.gz",
"platform": "any",
"description": "pzp\n==============\n\nPure-python fzf-inspired element picker\n\n[](https://github.com/andreax79/pzp/actions)\n[](https://badge.fury.io/py/pzp)\n[](https://pypi.org/project/pzp)\n[](https://pepy.tech/project/pzp)\n[](https://github.com/psf/black)\n[](https://snyk.io/test/github/andreax79/pzp)\n[](https://pzp.readthedocs.io/en/latest/)\n\nRequirements\n-----------\n* Python 3.6+\n\nInstall\n-------\n\n```\npip install pzp\n```\n\nUsage\n-----\n\n```\nimport pzp\npzp.pzp(['a', 'b', 'c'])\n```\n\n\n### Layout\n\nThe finder by default starts in fullscreen mode. You can make it start below the\ncursor with [`fullscreen=False`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) option.\nAlso, with the [`height`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) argument you can limit the window height.\n\n```python\npzp.pzp(candidates=range(0, 1000), fullscreen=False, height=20)\n```\n\n[](https://asciinema.org/a/WtgiYfdtZjlShbeZaHuf5hWCZ?autoplay=1)\n\nYou can choose between the following layout using the [`layout`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) option.\n\n* **default** Display from the bottom of the screen\n* **reverse** Display from the top of the screen\n* **reverse-list** Display from the top of the screen, prompt at the bottom\n\n### Search syntax\n\nThe finder starts in \"extended-search mode\" where you can type in multiple search\nterms delimited by spaces. e.g. `^music .mp3$ sbtrkt !fire`\n\n| Token | Match type | Description |\n| ------------ | -------------------------- | ------------------------------------ |\n| `t1 t2` | tokens-match | Items that include `t1` and `t2` |\n| `'star wars` | line-match (not-splitted) | Items that include `star wars` |\n| `^music` | prefix-exact-match | Items that start with `music` |\n| `.py$` | suffix-exact-match | Items that end with `.py` |\n| `!fire` | inverse-exact-match | Items that do not include `fire` |\n| `!^music` | inverse-prefix-exact-match | Items that do not start with `music` |\n| `!.py$` | inverse-suffix-exact-match | Items that do not end with `.py` |\n\n### Key/Event Bindings\n\n[`keys_binding`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) argument allows you to bind one or more keys to one action.\nYou can use it to customize key bindings or implementing custom behaviors.\n\n```python\ntry:\n item = pzp.pzp(\n candidates=candidates,\n keys_binding={\n \"custom-action\": [\"ctrl-o\"],\n \"exclamation\": [\"!\"]\n },\n )\n print(item)\nexcept CustomAction as action:\n print(action.action)\n print(action.selected_item)\n```\n\n#### Available Keys\n\n| Key | Synonyms type |\n| --------------------- | --------------------- |\n| space | |\n| tab | |\n| btab | shift-tab |\n| enter | |\n| esc | |\n| insert | |\n| del | |\n| bspace | bs |\n| up | |\n| down | |\n| left | |\n| right | |\n| home | |\n| end | |\n| pgdn | page-down |\n| pgup | page-up |\n| f1 - f12 | |\n| ctrl-/ | |\n| ctrl-\\ | |\n| ctrl-] | |\n| ctrl-^ | |\n| ctrl-a - ctrl-z | |\n| any single character | |\n\n#### Available Actions\n\nA key can be bound to one of following actions or to a custom action.\n\n| *Action** | *Default binding* |\n| ------------------------- | ------------------------------------- |\n| **accept** | *enter* |\n| **abort** | *ctrl-c* *ctrl-g* *ctrl-q* *esc* |\n| **beginning-of-line** | *ctrl-a* *home* |\n| **backward-char** | *ctrl-b* *left* |\n| **forward-char** | *ctrl-f* *right* |\n| **end-of-line** | *ctrl-e* *end* |\n| **backward-delete-char** | *ctrl-h* *bspace* |\n| **delete-char** | *del* |\n| **up** | *ctrl-k* *ctrl-p* *up* |\n| **down** | *ctrl-j* *ctrl-n* *down* |\n| **page-down** | *pgdn* |\n| **page-up** | *pgup* |\n| **ignore** | |\n\n### Lazy Mode\n\n[`lazy`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.pzp) argument allows you to enable the lazy mode.\nIf the Lazy mode is enabled, starts the finder only if the candidates are more than one.\nIf there is only one match returns the only match, if there is no match returns None.\n\nUser Input Prompts\n------------------\n\nTo ask for user input, you can use the [`pzp.prompt()`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.prompt) function.\nThis function is designed to be a drop-in replacement for the `click.input()` function.\nBy default, it accepts strings, but you can ask for any other type.\nIn order to do this, [Click](https://github.com/pallets/click) needs to be installed.\n\nFor instance, you can ask for a valid integer:\n\n```python\nvalue = pzp.prompt('Please enter a valid integer', type=int)\n```\n\nAdditionally, the type will be determined automatically if a default value is provided.\nFor instance, the following will only accept floats:\n\n```python\nvalue = pzp.prompt('Please enter a number', default=42.0)\n```\n\nConfirmation Prompts\n--------------------\n\nTo ask if a user wants to continue with an action, you can use the [`pzp.confirm()`](https://pzp.readthedocs.io/en/latest/api/module/#pzp.confirm).\nBy default, it returns the result of the prompt as a boolean value:\n\n```python\nif pzp.confirm('Are you sure?', default=True):\n print('Ok')\n```\n\nLicence\n-------\nMIT\n\nLinks\n-----\n\n* [fzf](https://github.com/junegunn/fzf)\n* [ANSI Escape Sequences](https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797)\n* [pyte, python terminal emulator](https://github.com/selectel/pyte)\n* [Grip, GitHub Readme Instant Preview](https://github.com/joeyespo/grip)\n* [Black, The Uncompromising Code Formatter](https://github.com/psf/black)\n* [mkdocstrings, Automatic documentation from sources](https://github.com/mkdocstrings/mkdocstrings)\n* [Click, Command Line Interface Creation Kit](https://github.com/pallets/click)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pure-python fzf-inspired element picker",
"version": "0.0.28",
"project_urls": {
"Bug Tracker": "http://github.com/andreax79/pzp/issues",
"Documentation": "https://pzp.readthedocs.io/en/latest/",
"Homepage": "http://github.com/andreax79/pzp",
"Source Code": "http://github.com/andreax79/pzp"
},
"split_keywords": [
"fzf",
" picker",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "137c27586576587cbab57850081f04df07b7e3f185794982deacb1b697d73ecb",
"md5": "a0b94b611a258ba09b30a82f1fd6b2a3",
"sha256": "e90deea90538d99199f9b129f46d09a0b3308ab4b59512d8e8629bba49834da5"
},
"downloads": -1,
"filename": "pzp-0.0.28-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0b94b611a258ba09b30a82f1fd6b2a3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 25630,
"upload_time": "2025-02-08T17:02:40",
"upload_time_iso_8601": "2025-02-08T17:02:40.235091Z",
"url": "https://files.pythonhosted.org/packages/13/7c/27586576587cbab57850081f04df07b7e3f185794982deacb1b697d73ecb/pzp-0.0.28-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ed637b838d97b433c12b7cdb6d795c1e6fefbac74f90573d984e936918926a9",
"md5": "4fbbcda16f5c90ec8131a12d3f7c6e61",
"sha256": "c4edf1dafe724f9731cf8a5aed483f7f6b1016425c30855258b7e3fcb9bbd04e"
},
"downloads": -1,
"filename": "pzp-0.0.28.tar.gz",
"has_sig": false,
"md5_digest": "4fbbcda16f5c90ec8131a12d3f7c6e61",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 25150,
"upload_time": "2025-02-08T17:02:42",
"upload_time_iso_8601": "2025-02-08T17:02:42.100187Z",
"url": "https://files.pythonhosted.org/packages/0e/d6/37b838d97b433c12b7cdb6d795c1e6fefbac74f90573d984e936918926a9/pzp-0.0.28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 17:02:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andreax79",
"github_project": "pzp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pzp"
}
JSON
