| Name | pickpack JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | https://github.com/anafvana/pickpack |
| Summary | Based on wong2's pick, pickpack is a terminal GUI which allows you to pick one or more options from a tree structure |
| upload_time | 2024-07-27 19:47:14 |
| maintainer | None |
| docs_url | None |
| author | Ana |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
terminal
gui
pick
tree
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pickpack
[](https://github.com/anafvana/pickpack/actions/workflows/ci.yml)
[](https://badge.fury.io/py/pickpack)
[](https://pypi.org/project/pickpack/)
**pickpack** is a small python library based on [wong2's pick](https://github.com/wong2/pick) which allows you to create a curses-based interactive selection tree in the terminal.
It was made with installation processes in mind, so that a user can select a parent node and get all children elements included. Different configurations allow for different outputs.
## Installation
$ pip install pickpack
## Options
- `options`: a RenderTree (anytree) or a list of options (if using list, `options_map_func` MUST be included)
- `title`: (optional) a title displayed above the options list
- `root_name`: (optional) name of root ("select all") node; defaults to root-node's value
- `multiselect`: (optional) if true, it is possible to select multiple values by hitting SPACE; defaults to `False`
- `singleselect_output_include_children`: (optional) if true, output in singleselect will include all children of the selected node, as well as the node itself; defaults to `False`
- `output_leaves_only`: (optional) if true, only leaf (childless) nodes will be returned; **for singleselect mode, `singleselect_output_include_children` MUST be True**; defaults to `False`
- `output_format`: (optional) allows for customising output format. 'nodeindex' = `[(Node('name'), index)]`; 'nameindex' = `[('name', index)]`; 'nodeonly' = `[Node('name')]`; 'nameonly' = `['name']`; default is 'nodeindex'
- `indicator`: (optional) custom the selection indicator
- `indicator_parentheses`: (optional) include/remove parentheses around selection indicator; defaults to `True`
- `default_index`: (optional) defines at which line the indicator will be placed when the program is started; default is `0` (first line)
- `options_map_func`: (optional for multiselect) a mapping function to pass each option through before displaying. Must return `Node`
## Usage
**pickpack** can be used by creating a tree and passing it into pickpack:
from anytree import Node, RenderTree
from pickpack import pickpack
title = 'Please choose one: '
c1 = Node('child1')
c2 = Node('child2')
p1 = Node('parent', children=[c1,c2])
options = RenderTree(p1)
option, index = pickpack(options, title)
print(option, index)
**outputs**:
Node('/parent/child1', index=1)
1
**pickpack** multiselect example returning node-name and index:
from anytree import Node, RenderTree
from pickpack import pickpack
title = 'Please choose one: '
c1 = Node('child1')
c2 = Node('child2')
p1 = Node('parent', children=[c1,c2])
options = RenderTree(p1)
option, index = pickpack(options, title, multiselect=True, min_selection_count=1, output_format='nameindex')
print(option, index)
**outputs**:
[('child1', 1), ('child2', 2)]
### Register custom handlers
To register custom handlers for specific keyboard keypresses, you can use the `register_custom_handler` property:
from anytree import Node, RenderTree
from pickpack import PickPacker
title = 'Please choose one: '
c1 = Node('child1')
c2 = Node('child2')
p1 = Node('parent', children=[c1,c2])
options = RenderTree(p1)
picker = PickPacker(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 its 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 Function
If your options are not a `RenderTree`, you can pass in a mapping function through which each option will be run. [^1]
[^1]: It MAY be also possible to use the `options_map_function` to customise how each option is displayed (as was the case with the original `options_map_function` from [wong2's pick](https://github.com/wong2/pick)). However, this behaviour has not been thoroughly tested. Feel free to submit an issue if you try it out.
The function must take in elements of the type you passed into the options (`Node` if you passed a `RenderTree`, `T` if you passed a `list[T]`) and return a `Node`.
You may also store any additional information as a custom property within the node.
**pickpack** options map function example:
from anytree import Node, RenderTree
from pickpack import pickpack
title = 'Please choose an option: '
options = [
{'label': 'option1', 'abbreviation': 'op1'},
{'label': 'option2', 'abbreviation': 'op2'},
{'label': 'option3', 'abbreviation': 'op3'}
]
def get_node(option):
return Node(option.get('label'), abbreviation=option.get('abbreviation'))
picker = PickPacker(options, title, indicator='*', options_map_func=get_node, output_format='nameindex')
**displays**:
Please choose an option:
(*) Select all
( ) └── option1
( ) └── option2
( ) └── option3
**outputs**:
>>> ({ 'label': 'option1' }, 0)
#### Map function for nested lists
**pickpack** options map function example for lists with **nesting**:
from anytree import Node, RenderTree
from pickpack import pickpack
title = 'Please choose an option: '
options = [
{'label': 'option1', 'abbreviation': 'op1', 'children':
[{'label': 'option1.1', 'abbreviation': 'op1.1',}]
},
{'label': 'option2', 'abbreviation': 'op2'},
{'label': 'option3', 'abbreviation': 'op3'}
]
def get_node(option):
children = option.get('children')
if children is not None:
children_list: list[Node] = []
for child in children:
children_list.append(get_nodes(child))
return Node(option.get('label'), children=children_list, abbreviation=option.get('abbreviation'))
else:
return Node(option.get('label'), children=None, abbreviation=option.get('abbreviation'))
picker = PickPacker(options, title, indicator='*', options_map_func=get_node, output_format='nameindex')
**displays**:
Please choose an option:
(*) Select all
( ) └── option1
( ) └── option1.1
( ) └── option2
( ) └── option3
Raw data
{
"_id": null,
"home_page": "https://github.com/anafvana/pickpack",
"name": "pickpack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "terminal, gui, pick, tree",
"author": "Ana",
"author_email": "anafvana@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d9/aa/b039f4ee3fe4b260e36992ded66128b4bf062a1e6c8f23bf016edf4d8c90/pickpack-2.0.0.tar.gz",
"platform": null,
"description": "# pickpack\n\n[](https://github.com/anafvana/pickpack/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/pickpack)\n[](https://pypi.org/project/pickpack/)\n\n**pickpack** is a small python library based on [wong2's pick](https://github.com/wong2/pick) which allows you to create a curses-based interactive selection tree in the terminal.\n\n\n\nIt was made with installation processes in mind, so that a user can select a parent node and get all children elements included. Different configurations allow for different outputs.\n\n## Installation\n\n $ pip install pickpack\n\n## Options\n\n- `options`: a RenderTree (anytree) or a list of options (if using list, `options_map_func` MUST be included)\n- `title`: (optional) a title displayed above the options list\n- `root_name`: (optional) name of root (\"select all\") node; defaults to root-node's value\n- `multiselect`: (optional) if true, it is possible to select multiple values by hitting SPACE; defaults to `False`\n- `singleselect_output_include_children`: (optional) if true, output in singleselect will include all children of the selected node, as well as the node itself; defaults to `False`\n- `output_leaves_only`: (optional) if true, only leaf (childless) nodes will be returned; **for singleselect mode, `singleselect_output_include_children` MUST be True**; defaults to `False`\n- `output_format`: (optional) allows for customising output format. 'nodeindex' = `[(Node('name'), index)]`; 'nameindex' = `[('name', index)]`; 'nodeonly' = `[Node('name')]`; 'nameonly' = `['name']`; default is 'nodeindex'\n- `indicator`: (optional) custom the selection indicator\n- `indicator_parentheses`: (optional) include/remove parentheses around selection indicator; defaults to `True`\n- `default_index`: (optional) defines at which line the indicator will be placed when the program is started; default is `0` (first line)\n- `options_map_func`: (optional for multiselect) a mapping function to pass each option through before displaying. Must return `Node`\n\n## Usage\n\n**pickpack** can be used by creating a tree and passing it into pickpack:\n\n from anytree import Node, RenderTree\n from pickpack import pickpack\n\n title = 'Please choose one: '\n\n c1 = Node('child1')\n c2 = Node('child2')\n p1 = Node('parent', children=[c1,c2])\n\n options = RenderTree(p1)\n option, index = pickpack(options, title)\n print(option, index)\n\n**outputs**:\n\n Node('/parent/child1', index=1)\n 1\n\n**pickpack** multiselect example returning node-name and index:\n\n from anytree import Node, RenderTree\n from pickpack import pickpack\n\n title = 'Please choose one: '\n\n c1 = Node('child1')\n c2 = Node('child2')\n p1 = Node('parent', children=[c1,c2])\n\n options = RenderTree(p1)\n option, index = pickpack(options, title, multiselect=True, min_selection_count=1, output_format='nameindex')\n print(option, index)\n\n**outputs**:\n\n [('child1', 1), ('child2', 2)]\n\n### Register custom handlers\n\nTo register custom handlers for specific keyboard keypresses, you can use the `register_custom_handler` property:\n\n from anytree import Node, RenderTree\n from pickpack import PickPacker\n\n title = 'Please choose one: '\n c1 = Node('child1')\n c2 = Node('child2')\n p1 = Node('parent', children=[c1,c2])\n options = RenderTree(p1)\n\n picker = PickPacker(options, title)\n def go_back(picker):\n return None, -1\n picker.register_custom_handler(ord('h'), go_back)\n option, index = picker.start()\n\n- the custom handler will be called with the `picker` instance as its parameter.\n- the custom handler should either return a two-element `tuple` or `None`.\n- if `None` is returned, the picker would continue to run; otherwise the picker will stop and return the tuple.\n\n### Options Map Function\n\nIf your options are not a `RenderTree`, you can pass in a mapping function through which each option will be run. [^1]\n\n[^1]: It MAY be also possible to use the `options_map_function` to customise how each option is displayed (as was the case with the original `options_map_function` from [wong2's pick](https://github.com/wong2/pick)). However, this behaviour has not been thoroughly tested. Feel free to submit an issue if you try it out.\n\nThe function must take in elements of the type you passed into the options (`Node` if you passed a `RenderTree`, `T` if you passed a `list[T]`) and return a `Node`.\n\nYou may also store any additional information as a custom property within the node.\n\n**pickpack** options map function example:\n\n from anytree import Node, RenderTree\n from pickpack import pickpack\n\n title = 'Please choose an option: '\n options = [\n {'label': 'option1', 'abbreviation': 'op1'},\n {'label': 'option2', 'abbreviation': 'op2'},\n {'label': 'option3', 'abbreviation': 'op3'}\n ]\n\n def get_node(option):\n return Node(option.get('label'), abbreviation=option.get('abbreviation'))\n\n picker = PickPacker(options, title, indicator='*', options_map_func=get_node, output_format='nameindex')\n\n**displays**:\n\n Please choose an option:\n\n (*) Select all\n ( ) \u2514\u2500\u2500 option1\n ( ) \u2514\u2500\u2500 option2\n ( ) \u2514\u2500\u2500 option3\n\n**outputs**:\n\n >>> ({ 'label': 'option1' }, 0)\n\n#### Map function for nested lists\n\n**pickpack** options map function example for lists with **nesting**:\n\n from anytree import Node, RenderTree\n from pickpack import pickpack\n\n title = 'Please choose an option: '\n options = [\n {'label': 'option1', 'abbreviation': 'op1', 'children':\n [{'label': 'option1.1', 'abbreviation': 'op1.1',}]\n },\n {'label': 'option2', 'abbreviation': 'op2'},\n {'label': 'option3', 'abbreviation': 'op3'}\n ]\n\n def get_node(option):\n children = option.get('children')\n if children is not None:\n children_list: list[Node] = []\n for child in children:\n children_list.append(get_nodes(child))\n return Node(option.get('label'), children=children_list, abbreviation=option.get('abbreviation'))\n else:\n return Node(option.get('label'), children=None, abbreviation=option.get('abbreviation'))\n\n picker = PickPacker(options, title, indicator='*', options_map_func=get_node, output_format='nameindex')\n\n**displays**:\n\n Please choose an option:\n\n (*) Select all\n ( ) \u2514\u2500\u2500 option1\n ( ) \u2514\u2500\u2500 option1.1\n ( ) \u2514\u2500\u2500 option2\n ( ) \u2514\u2500\u2500 option3\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Based on wong2's pick, pickpack is a terminal GUI which allows you to pick one or more options from a tree structure",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/anafvana/pickpack",
"Repository": "https://github.com/anafvana/pickpack"
},
"split_keywords": [
"terminal",
" gui",
" pick",
" tree"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d9aab039f4ee3fe4b260e36992ded66128b4bf062a1e6c8f23bf016edf4d8c90",
"md5": "1406bd810d86702a8af675d92f37f0ec",
"sha256": "a7b2af43fb4b9209cec8d50e301c87047083be770bc4414e540db39c796cf3e3"
},
"downloads": -1,
"filename": "pickpack-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1406bd810d86702a8af675d92f37f0ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9490,
"upload_time": "2024-07-27T19:47:14",
"upload_time_iso_8601": "2024-07-27T19:47:14.725399Z",
"url": "https://files.pythonhosted.org/packages/d9/aa/b039f4ee3fe4b260e36992ded66128b4bf062a1e6c8f23bf016edf4d8c90/pickpack-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-27 19:47:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anafvana",
"github_project": "pickpack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pickpack"
}
