frougon/pythondialog

Python wrapper for the Unix "dialog" utility

Python wrapper for the UNIX "dialog" utility

Easy writing of graphical interfaces for terminal-based applications

Overview

pythondialog is a Python wrapper for the UNIX dialog utility originally written by Savio Lam and later rewritten by Thomas E. Dickey. Its purpose is to provide an easy to use, pythonic and as complete as possible interface to dialog from Python code.

pythondialog is free software, licensed under the GNU LGPL (GNU Lesser General Public License). Its home page is located at:

https://pythondialog.sourceforge.io/

and contains a short example, screenshots, a summary of the recent changes, links to the documentation, the Git repository, the mailing list, the issue tracker, etc.

If you want to get a quick idea of what this module allows one to do, you can download a release tarball and run demo.py:

PYTHONPATH=. python3 examples/demo.py

What is pythondialog good for? What are its limitations?

As you might infer from the name, dialog is a high-level program that generates dialog boxes. So is pythondialog. They allow you to build nice interfaces quickly and easily, but you don't have full control over the widgets, nor can you create new widgets without modifying dialog itself. If you need to do low-level stuff, you should have a look at ncurses (cf. the curses module in the Python standard library), blessings or slang instead. For sophisticated text-mode interfaces, the Urwid Python library looks rather interesting, too.

Requirements

• As of version 2.12, pythondialog requires Python 3.0 or later in the 3.x series. pythondialog 3.5.3 has been tested with Python 3.9.
• dialog version 1.3-20201126-1 (the version shipped in Debian stable and unstable in November 2021) is broken; don't waste your time with that version. dialog 1.3-20210621 works fine.
• Versions of pythondialog up to and including 3.5.1 had a backport to Python 2, however this outdated Python dialect isn't supported anymore. You may find pointers to the old packages with Python 2 support on the pythondialog home page.

• Apart from that, pythondialog requires the dialog program (or a drop-in replacement for dialog). You can download dialog from:

  https://invisible-island.net/dialog/dialog.html

  Note that some features of pythondialog may require recent versions of dialog.

Quick installation instructions

If you have a working pip setup, you should be able to install pythondialog with:

pip install pythondialog

When doing so, make sure that your pip executable runs with the Python 3 installation you want to install pythondialog for.

For more detailed instructions, you can read the INSTALL file from a release tarball. You may also want to consult the pip documentation.

Documentation

The pythondialog Manual

The pythondialog Manual is written in reStructuredText format for the Sphinx documentation generator. The HTML documentation for the latest version of pythondialog as rendered by Sphinx should be available at:

https://pythondialog.sourceforge.io/doc/

The sources for the pythondialog Manual are located in the doc top-level directory of the pythondialog distribution, but the documentation build process pulls many parts from dialog.py (mainly docstrings).

To generate the documentation yourself from dialog.py and the sources in the doc directory, first make sure you have Sphinx and Make installed. Then, you can go to the doc directory and type, for instance:

make html

You will then find the output in the _build/html subdirectory of doc. Sphinx can build the documentation in many other formats. For instance, if you have LaTeX installed, you can generate the pythondialog Manual in PDF format using:

make latexpdf

You can run make from the doc directory to see a list of the available formats. Run make clean to clean up after the documentation build process.

For those who have installed Sphinx but not Make, it is still possible to build the documentation with a command such as:

sphinx-build -b html . _build/html

run from the doc directory. Please refer to sphinx-build for more details.

Reading the docstrings from an interactive Python interpreter

If you have already installed pythondialog, you may consult its docstrings in an interactive Python interpreter this way:

>>> import dialog; help(dialog)

but only parts of the documentation are available using this method, and the result is much less convenient to use than the pythondialog Manual as generated by Sphinx.

Enabling Deprecation Warnings

There are a few places in dialog.py that send a DeprecationWarning to warn developers about obsolete features. However, because of:

• the dialog output to the terminal;
• the fact that such warnings are silenced by default since Python 2.7 and 3.2;

you have to do two things in order to see them:

• redirect the standard error stream to a file;
• enable the warnings for the Python interpreter.

For instance, to see the warnings produced when running the demo, you can do:

PYTHONPATH=. python3 -Wd examples/demo.py 2>/path/to/file

and examine /path/to/file. This can also help you to find files that are still open when your program exits.

Note:

If your program is terminated by an unhandled exception while stderr is redirected as in the preceding command, you won't see the traceback until you examine the file stderr was redirected to. This can be disturbing, as your program may exit with no apparent reason in such conditions.

For more explanations and other methods to enable deprecation warnings, please refer to:

https://docs.python.org/3/whatsnew/2.7.html

Troubleshooting

If you have a problem with a pythondialog call, you should read its documentation and the dialog(1) manual page. If this is not enough, you can enable logging of shell command-line equivalents of all dialog calls made by your program with a simple call to Dialog.setup_debug(), first available in pythondialog 2.12 (the expand_file_opt parameter may be useful in versions 3.3 and later). An example of this can be found in demo.py from the examples directory.

As of version 2.12, you can also enable this debugging facility for demo.py by calling it with the --debug flag (possibly combined with --debug-expand-file-opt in pythondialog 3.3 and later, cf. demo.py --help).

Using Xdialog instead of dialog

As far as I can tell, Xdialog has not been ported to GTK+ version 2 or later. It is not in Debian stable nor unstable (November 30, 2019). It is not installed on my system (because of the GTK+ 1.2 dependency), and according to the Xdialog-specific patches I received from Peter Åstrand in 2004, was not a drop-in replacement for dialog (in particular, Xdialog seemed to want to talk to the caller through stdout instead of stderr, grrrrr!).

All this to say that, even though I didn't remove the options to use another backend than dialog, nor did I remove the handful of little, non-invasive modifications that help pythondialog work better with Xdialog, I don't really support the latter. I test everything with dialog, and nothing with Xdialog.

That being said, here is the old text of this section (from 2004), in case you are still interested:

Starting with 2.06, there is an "Xdialog" compatibility mode that you can use if you want pythondialog to run the graphical Xdialog program (which should be found under http://xdialog.free.fr/) instead of dialog (text-mode, based on the ncurses library).

The primary supported platform is still dialog, but as long as only small modifications are enough to make pythondialog work with Xdialog, I am willing to support Xdialog if people are interested in it (which turned out to be the case for Xdialog).

The demo.py from pythondialog 2.06 has been tested with Xdialog 2.0.6 and found to work well (barring Xdialog's annoying behaviour with the file selection dialog box).

Whiptail, anyone?

Well, pythondialog seems not to work very well with whiptail. The reason is that whiptail is not compatible with dialog anymore. Although you can tell pythondialog the program you want it to invoke, only programs that are mostly dialog-compatible are supported.

History

pythondialog was originally written by Robb Shecter. Sultanbek Tezadov added some features to it (mainly the first gauge implementation, I guess). Florent Rougon rewrote most parts of the program to make it more robust and flexible so that it can give access to most features of the dialog program. Peter Åstrand took over maintainership between 2004 and 2009, with particular care for the Xdialog support. Florent Rougon took over maintainership again starting from 2009...

pythondialog's Issues

Graphical customization from python

Hello!

Amazing python project. Please tell me, is it possible to customize the interface inside python or do we always need to edit the ~/.dialogrc file?

Thanks in advance

Unexpected Textbox widget autosize when file has tabulations

Hello,

When Dialog is created with autowidgetsize=True, the textbox widget does not size correctly if file contains Tab characters.

It is probably a dialog backend upstream issue (using 1.3-20160209 here), because passing "--textbox filename 0 0" gives this same result.

I worked around this behavior by computing dimensions using maxsize() so that window covers whole terminal regardless, but it's not an ideal situation.

Msgbox and input at the same time

Hello!

I am wondering if it is possible to have two widgets at the same time, one msgbox to display text and alter in realtime and a dialog text input under. Does the library support this? With the examples, running one widget after the other I'm not sure how to approach this.

Thanks

Length of extended ASCII chars are counted wrong towards width

Using extended ASCII chars like █ are counted with a larger width as displayed in the terminal. Meaning, the dialog window extends itself more than needed. Width can't be set to a lower setting, as it will throw a DialogError and the note Can't make sub-window at (42,9), size (1,194)

This picture can only be obtained through setting width=0:

Here is the original ASCII art, for testing of course 😅.

xx______________________________________________________________xx
xx______________________________________________________________xx
xx________________________________________████████████__________xx
xx______________________________________██////////////██________xx
xx___________________________________ ██////////////////██______xx
xx_________________________________ ██//// __ ////// __ //██____xx
xx_________________________________ ██////__██//////██__//██____xx
xx__________________________________██////__██//////██__//██____xx
xx__________________________________██//////////██////////██____xx
xx__________________________________██////████//////████//██____xx
xx________________________________██////██//////██//////██______xx
xx______________________██████████////////████//////████________xx
xx____________________██//////██////////██//////////██__██______xx
xx__________________██////////////////////////////////██________xx
xx________________██//////////////////////////////////██________xx
xx____████████__██//////////////////////////////////██__________xx
xx__██////////████////////////////██////////////////██████______xx
xx██////██////////////////////////██//////////██//██//////████__xx
xx__████//////////██////////////██//////////██//██//////██////██xx
xx██////////////██████////////██████////////████__████////////██xx
xx__████████████______██████████//////////██__________████████__xx
xx______________________________██████████______________________xx
xx______________________________________________________________xx
xx______________________________________________________________xx

(It also suffice to just use a long enough line with extended ASCII symbols of course 🙊)

EDIT: I figured out how to circumvent this: Setting tab_len=1 for this window allows setting the size, but also forces one to set it manually for this window.

Showing color in dialog with \Z escape sequences

Trying to create a msgbox with color as d.msgbox("\Z1test\Zn regular",color=True) renders the string text in red with the text regular in the usual black color. However, the \ characters preceeding both the Zs remain in the text. So the above text gets rendered as \ test \ regular with the colors correct.

Am I missing something?

pythondialog = 3.5.3
dialog = Version: 1.3-20171209

Additional examples

Hi,
I was playing with your code, and was wanting to offer some additional examples:
#! /usr/bin/env python3 import locale from dialog import Dialog
''' This is almost always a good thing to do at the beginning of your programs. '''
locale.setlocale(locale.LC_ALL, '')
''' You may want to use 'autowidgetsize=True' here (requires pythondialog >= 3.1) '''
d = Dialog(dialog="dialog")
''' Dialog.set_background_title() requires pythondialog 2.13 or later '''
d.set_background_title("YES/NO Help sample")
''' In pythondialog 3.x, you can compare the return code to d.OK, Dialog.OK or
"ok" (same object). In pythondialog 2.x, you have to use d.DIALOG_OK, which
is deprecated since version 3.0.0.'''
user_selection = d.yesno("Hi, this is a yes/no dialog box. You can use this to ask
questions that have an answer of either yes or no.
BTW, do you notice that long lines will be automatically
wrapped around so that they can fit in the box? You can
also control line breaking explicitly by inserting
'backslash n' at any place you like, but in this case,
auto wrap around will be disabled and you will have to
control line breaking yourself.", title="YES/NO BOX",width=0,height=0,help_button=True)
if user_selection == d.OK:
d.msgbox("You chose yes")
elif user_selection == d.CANCEL:
d.msgbox("You chose no")
elif user_selection == d.HELP:
d.msgbox("You pressed help")
elif user_selection == d.ESC:
d.msgbox("You pressed ESC")
else:
d.msgbox("WHAT DID YOU DO?!?!")

Drop down menu, checkboxes and hidden content

Is it possible to create following elements inside of pythondialog boxes?

• Drop down menu
• Hidden content
• Checkboxes

I attach screenshot of what I would like to see, however I didn't found it in documentation.

.

best practice for unittesting?

Hi, thanks for your lib.

I don't find any doc about testing. Is that possible? If yes, what is the best practice?
Thank you !

Here is the class I would like to test for giving you an idea if it can help.

Support urwid? / Is there a pure-python dialog utility

I'd like to have the menuconfig-like interface in a pure python utility. It seems that the urwid library has some half-baked dialog.py in its examples - I wonder if this could be baked in into the lib so that no external exe would need to be called if urwid exists;

or, pythondialog speaks of "dialog-like" backends; are you aware of any that would be pure python or at least installable on Linux / Mac with pip?

\n and \\n handled the same by msgbox

from dialog import Dialog
d = Dialog()
d.msgbox("a\nb")
d.msgbox("c\\nd")
print("a\nb")
print("c\\nd")

Both msgboxes show two lines.
The print shows something different.

Is this on purpose?

Debian, python3-dialog 3.5.1, Python 3.7.3, dialog 1.3-20190211-1

Provide wheel package

Currently, pythondialog is only available as a tar.gz archive on PyPI. The problem with this is that it requires the end user to have the setuptools package installed.

Providing a wheel file would solve this.

All that would need to be done is replace

from distutils.core import setup

in setup.py with

from setuptools import setup

And then package it with python setup.py bdist_wheel

Text colored in dialog

Hello,

I use pythondialog, thank's for your job :)

I try to color text in dialog, but is not work correctly in Python3
In old version (python2), it's worked nice, but in python3, it's almost work.
When i used this : "\Z5mytext\Zn", text is colored, but \ character apears in text.

Can you help me with this ?

Regards,

python3-dialog - no '*' character echo when entering the passwords in all the password dialogs

I am currently using python3-dialog 3.4.0-1 (with Ubuntu 18.04). None of the password dialogs show the '*' characters when I enter the password but the dialog do record the password input.

Many thanks
Joe

Wrong documentation for mixedform

The documentation has a wrong assignment for attributes in elements description

it says:
0 := hidden
1 := read only

but should be:
0 := text
1 := hidden
2 := read only