Skip to main content

Vertical menu widget for prompt-toolkit with optional fzf-inspired search

Project description

CI coveralls PyPI github


Vertical menu widget for the excellent prompt-toolkit, with optional fzf-inspired search

This is a demo of the included ptvertmenu-man utility:


Getting started

The example below creates a menu that shows the contents of files and directories as the cursor goes over them, with full mouse support:

#!/usr/bin/env python3
Look at files in the current directory

import os
from typing import Optional, Any

import ptvertmenu
from prompt_toolkit import Application
from prompt_toolkit.key_binding import KeyBindings
from prompt_toolkit.key_binding.bindings.focus import focus_next
from prompt_toolkit.key_binding.key_processor import KeyPressEvent
from prompt_toolkit.layout.containers import VSplit
from prompt_toolkit.layout.layout import Layout
from prompt_toolkit.styles import Style
from prompt_toolkit.widgets import Frame, TextArea

E = KeyPressEvent

def showfile(contents: TextArea, item: Optional[tuple[str, Any]], index: int) -> None:
    assert item
    name = item[1]
        if os.path.isdir(name):
            contents.text = '\n'.join(os.listdir(name))
            with open(name, "r", encoding="utf-8", errors="replace") as fd:
                contents.text =
    except Exception as exc:
        contents.text = f"Error: {exc}"

def main() -> None:
    files = [(f, f) for f in os.listdir(".")]
    contents = TextArea(text="", multiline=True, wrap_lines=True, read_only=True)
    menu = ptvertmenu.VertMenu(
        selected_handler=lambda item, index: showfile(contents, item, index),
    root_container = VSplit(
            Frame(title="Files", body=menu),
            Frame(title="Contents", body=contents),
    layout = Layout(root_container)
    style = Style.from_dict({"vertmenu.selected": "reverse"})
    kb = KeyBindings()

    def tab(event: E) -> None:

    def close(event: E) -> None:

    app: Application[None] = Application(

if __name__ == "__main__":



ptvertmenu can be installed via pypi:

pip install ptvertmenu

For nix users, it is also available as a flake.


We can also clone the github repository and install ptvertmenu from it with:

pip install .

We can also install it for the current user only by running instead:

pip install --user .


ptvertmenu uses the standard python3 infra. To develop and test the module:

  • Clone the repository and go into the directory:
    git clone
    cd ptvertmenu
  • Use venv to create a local virtual environment with
    python -m venv venv
  • Activate the environment by running the shell-specific activate script in ./venv/bin/. For [fish], for instance, run:
    source ./venv/bin/
  • Install ptvertmenu in "editable mode":
    pip install -e '.[test]'
  • To run the tests:
    Or, to run the tests with coverage:
    pytest --cov
  • Finally, to exit the environment and clean it up:
    rm -rf venv

Project details

Download files

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

Source Distribution

ptvertmenu-0.2.2.tar.gz (10.5 kB view hashes)

Uploaded Source

Built Distribution

ptvertmenu-0.2.2-py3-none-any.whl (14.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page