Package: py-cui
A library for creating CUI/TUI interfaces with pre-built widgets in python.Easily build text-based user interfaces on both Linux and Windows.py_cuipy_cuiis a python library meant to simplify writing console user interfaces in python. It relies oncursesfor terminal rendering, which is traditionally unix-specific, however, you may use thewindows-cursesmodule to runpy_cuion windows.The main advantagepy_cuihas over typical text-based user interface builders is that it relies on widgets and a grid layout manager like most traditional graphical user interfaces. You may define a grid size, and then drop predefined widgets onto it into specific grid locations. Widgets can also be stretched accross multiple grid rows and columns. If you've ever made a Tkinter GUI, you will feel right at home. In addition,py_cuihas support for a rich collection of interactive popups such as menus, forms, file dialogs, and more.If you would like to contribute, feel free to make an issue or pull request after reading through theCONTRIBUTING.mdfile.InstallationYou may installpy_cuivia pip (usepip3if python 2 and 3 are installed side by side)pipinstallpy-cuiMake sure to run as root/sudo as required. Note that the library is titledpy_cui, but the name of the pypi package ispy-cui, though in most cases, installing withpipinstallpy_cuishould work OK.If you would like to usepy_cuidirectly from source, clone this repository with:gitclonehttps://github.com/jwlodek/py_cuiThen build/install withpip:cdpy_cui
pipinstall.If you would like to try it out without installing, first make sure thatcursesis installed (windows-cursesif on windows), and then copy one of the example files into the top directory. You may then simply run it withpython3.ExamplesBelow are some screenshots and gifs of programs written with py_cui. Additional (simpler) examples are available in theexamples/directory of this repository.py_cui_2048 - A command line version of the classic 2048 gamepy_cui_2048is a demo of usingpy_cuito build simple CUI games and applications. The entire game was made in under 400 lines of code.recoverpy - A TUI that allows for recovering lost or deleted filesrecoverpyis a utility for recovering files on linux. It will search through every inode to find your requested file block.pyautogit - A command line interface for managing git repositoriespyautogitis the first larger scale project written inpy_cui. Feel free to use it as a guide to programming withpy_cui.Getting startedThe easiest way to get set up for developing a fullpy_cuiapplication is to use the availablecookiecuttertemplate. First, install thecookiecuttertool:pipinstallcookiecutterOnce it is installed, navigate to the directory in which you would like your projects to live, and run:cookiecutterhttps://github.com/jwlodek/py_cui_cookiecutterThis will clone the template, and show prompts for several variables, including project name and description, as well as some developer information.
Once it is done, you can enter your project directory, install it with pip, and run it, and you should be able to see aHello Worldexample:cdmyproject
pipinstall.
myprojectYou are now ready to extend this template for your own application!Writing a PyCUIBasic usage ofpy_cuistarts with creating a PyCUI object, and specifiying it's grid size. Keep in mind that grid cell height and width will be measured in terminal characters, not pixels, so there is a lower limit on legal grid size, and heights will be smaller values than widths. Create this object with:root=py_cui.PyCUI(7,9)The above line will create a UI with 7 rows and 9 columns. Then, add widgets with the different add commands:label=root.add_label('Label Text',0,0)button=root.add_button('Button Text',1,2,column_span=2,command=my_function)...Finally, start the CUI withroot.start()py_cuihas support for custom key bindings for both the overview mode and focused mode, popup windows and prompts, color rendering rules, and several useful widgets. For more details on writingpy_cuibased interfaces, be sure to check on the examples and the documentationhere.Using a PyCUIThere are some basic rules that apply to allpy_cuibased interfaces. There are three key operating modes - overview mode, focus mode, and popup mode.Overview ModeOverview mode is the main control view of the interface. In this mode you use the arrow keys to move between widgets, and you may select widgets with theEnterkey. By default, you may also press buttons in this mode, unlessauto_focus_buttonsis set to false when the CUI was created.Focus ModeWhen in focus mode, you enter into a particular widget (For example a text box.). Each widget has some predefined basic controls, such as arrow keys to scroll in aScrollMenu. You may also add keybindings to functions for each particular widget. These keybindings will only apply to a widget if it is in focus mode. Enter focus mode by navigating to a widget in overview mode and hitting theEnterkey. Return to overview mode from focus mode by pressingEscape.Popup ModePopup mode simply displays a popup over the rest of the UI. Each popup type behaves slightly differently. For example, you may exit an info popup mode by pressingSpace,Enter, orEscape, while a loading popup will remain onscreen until whatever operation is being run is terminated.Unit Testspy_cuiunit tests are written forpytest. Make surepytestis installed, and simply runpytestin the root directory to run all unit tests.Powered by py_cuiBelow is a table of python projects developed with the help ofpy_cui. If you've made something, feel free to make a pull request to add it!ProjectDescriptionpypodcastsA TUI for listening to and managing podcast feeds. (Coming Soon)pyautogitA command line UI for interfacing with git features for multiple repositories.recoverpyA CUI for recovering overwritten or deleted data on linux.py_cui_2048A CUI version of the classic 2048 game.unipkgA CUI interface for managing all installed package managers on your system. (In-Progress)CUIAudioPlayerA TUI for playing back audio files in a variety of formats.tinypubA console-based ebook reader.hue-tuiA CUI controlling for Philips Hue lights.mini-radio-playerA terminal based radio interface for linux.LicenseBSD 3-Clause LicenseCopyright (c) 2019-2021, Jakub Wlodek