Package: python2-pythondialog
Easy writing of graphical interfaces for terminal-based applicationsWARNINGThis version is a backport of pythondialog to Python 2. Unless youreallyhave to use Python 2, you should go to thepythondialog home
pageand download the reference implementation which, at the time of
this writing (December 2019) and for the foreseeable future, is targeted
at Python 3.This version is only here to help users who are somehow forced to still
use Python 2, even though Python 3.0 was released on December 3, 2008.
Python 2 hasreached its end of life, and so does this
backport.This backport is now unsupported. Don’t expect any further
updates.If, despite all of these warnings, you still want to use it, be sure to
read theBackport-specific notesbelow.Overviewpythondialog is a Python wrapper for the UNIXdialogutility
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 todialogfrom Python code.pythondialog is free software, licensed under the GNU LGPL (GNU Lesser
General Public License). Its home page is located at:http://pythondialog.sourceforge.net/and contains ashort example,screenshots, asummary of the recent
changes, links to thedocumentation, theGit repository, themailing list, theissue 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 rundemo.py:PYTHONPATH=. python2 examples/demo.pyNotes:the preceding command usespython2because we want to use the
Python 2 backport of pythondialog;depending on your system, you may have to replacepython2withpythonorpython2.7, for instance.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 atncurses(cf. thecursesmodule in the Python standard library),blessingsor slang instead. For sophisticated text-mode interfaces, theUrwid
Python librarylooks rather interesting, too.RequirementsThisnow unsupportedbackport of pythondialog requires Python 2.6
or later in the 2.x series. It has been tested with Python 2.7.The reference implementation supports more recent versions of the
Python interpreter. Please visit thepythondialog home pagefor
more information.Apart from that, pythondialog requires thedialogprogram (or a
drop-in replacement for dialog). You can download dialog from:https://invisible-island.net/dialog/dialog.htmlNote that some features of pythondialog may require recent versions of
dialog.Quick installation instructionsIf you have a workingpipsetup,
you should be able to install this backport of pythondialog with:pip install python2-pythondialogWhen doing so, make sure that yourpipexecutable runs with the
Python 2 installation you want to install the backport for.For more detailed instructions, you can read theINSTALLfile from a
release tarball. You may also want to consult thepip documentation.Backport-specific notesThe pythondialog documentation is written for the reference
implementation (Python 3 at the time of this writing). To be on the
safe side when using the Python 2 backport, you should use Unicode
strings every time you pass “string data” to pythondialog, and you
will get Unicode strings in return. Indeed, these correspond directly
to Python 3 strings, and modern versions of pythondialog (>= 2.12) are
all based on this type of string.The pythondialog documentation consistently uses the term “string” (as
opposed to “Unicode string”) because it has been written for Python 3,
butyou should definitely use Unicode strings when using the
Python 2 backport. Many things happen to work with byte strings, but
in most cases, this is pure coincidence; others fail, and won’t be
fixed. This is not a bug.The easiest way to use Unicode strings everywhere (or almost
everywhere) in Python 2.x with x >= 6, consists in using:from __future__ import unicode_literalsat the beginning of your Python files. This method has the additional
benefit of preparing your transition to Python 3.Don’t usestr()in Python 2 on objects such as pythondialog
exceptions ordialog.DialogBackendVersioninstances; useunicode()instead, which is the Python 2 equivalent of the
Python 3str()built-in. Of course, usingrepr()on any
pythondialog object should return a byte string when run under
Python 2, because this is how therepr()API works in Python 2.
The same holds true forstr(), but this one is not supported by
the Python 2 backport of pythondialog: it is superseded, as already
explained, by the much more powerfulunicode().Before taking potentially expensive decisions, you should realize that
Unicode support ismuch, much better in Python 3 than in Python 2,
even though the basic types are largely the same (Unicode string in
Python 2, native string in Python 3). In Python 3, native strings
(simply called “strings” in the Python documentation) are natural and
ubiquitous. They can be read and written from/to the standard I/O
streams with sane encoding defaults.str()andrepr()return
native strings, as do all standard library calls whenever expected
(i.e., when the return value is text, as opposed to binary data).
Python 3 strings are both powerful and easy to use.By contrast, in Python 2, you always have to be very careful about
what you manipulate: byte strings or Unicode strings. Most library
calls in your code are a potential source of bug. Usually, this kind
of bug only pops up when user data or input introduces non-ASCII
characters in a byte string that is then either combined with an
Unicode string, or used in a context where the expected encoding is
different. This means that some users get annoyed by “crappy”
software, while the responsible developers are often not aware of any
problem—until a bug report is filed, if ever.Want to usetraceback.format_exc()for instance? What does it
return, byte string or Unicode string? Experiment. Answer: byte
string. Then, how does it deal with, e.g., accented characters in anOSErrorexception message? Experiment. Answer: it outputs therepr()representation of an Unicode string that uses backslash
escapes for the non-ASCII characters, all of this inside the returned
byte string. Conclusion: the messages seen by users will be very ugly
and more or less undecipherable for many of them. Does it behave this
way in all cases? Tough question. Use the source, Luke…With other library calls, you might get non-ASCII characters in a byte
string. Then, the question would be: what encoding has been used to
encode them, and is there a reliable way to detect it? In many cases,
this is not documented and/or depends on parameters under user
control, such as the locale settings. Again, you have to waste time
figuring out the encoding, and often can’t be sure whether your answer
is correct in all cases.Bottom line:There are good reasons why the Python developers broke compatibility
at such a fundamental level as string management between Python 2
and Python 3. Getting Unicode support completely right in Python 2
may require more work than porting your code to Python 3. Besides,
future maintainance and evolutions of your program will definitely
be easier once it is written in Python 3. Think about it.DocumentationImportant:be sure to read theBackport-specific notesabove.The pythondialog ManualThe pythondialog Manual is written inreStructuredTextformat for theSphinxdocumentation generator. The HTML documentation for the latest
version of pythondialog as rendered by Sphinx should be available at:http://pythondialog.sourceforge.net/doc/The sources for the pythondialog Manual are located in thedoctop-level directory of the pythondialog distribution, but the
documentation build process pulls many parts fromdialog.py(mainly
docstrings).Note:Generation of the pythondialog Manual withSphinxhas only been
tested, and is only supported with the reference implementation of
pythondialog (i.e., currently, on Python 3). As a consequence, the
package containing this file may be fine to read or grep through the.rstfiles; however, if compilation of said.rstfiles withSphinxon Python 2 doesn’t work, it is not considered a
bug—simply download the reference implementation if you want to do
that.To generate the documentation yourself fromdialog.pyand the
sources in thedocdirectory, first make sure you haveSphinxandMakeinstalled. Then, you can go to thedocdirectory and type,
for instance:make htmlYou will then find the output in the_build/htmlsubdirectory ofdoc.Sphinxcan build the documentation in many other formats.
For instance, if you haveLaTeXinstalled, you can generate the
pythondialog Manual in PDF format using:make latexpdfYou can runmakefrom thedocdirectory to see a list of the
available formats. Runmake cleanto clean up after the
documentation build process.For those who have installedSphinxbut notMake, it is still
possible to build the documentation with a command such as:sphinx-build -b html . _build/htmlrun from thedocdirectory. Please refer tosphinx-buildfor more
details.Reading the docstrings from an interactive Python interpreterIf 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 thepythondialog
Manualas generated bySphinx.Enabling Deprecation WarningsThere are a few places indialog.pythat send aDeprecationWarningto 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=. python2 -Wd examples/demo.py 2>/path/to/fileand 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.htmlTroubleshootingIf 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 toDialog.setup_debug(),
first available in pythondialog 2.12 (theexpand_file_optparameter
may be useful in versions 3.3 and later). An example of this can be
found indemo.pyfrom theexamplesdirectory.As of version 2.12, you can also enable this debugging facility fordemo.pyby calling it with the--debugflag (possibly combined
with--debug-expand-file-optin pythondialog 3.3 and later, cf.demo.py--help).Using Xdialog instead of dialogAs far as I can tell,Xdialoghas not been ported toGTK+version
2 or later. It is not inDebianstable 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 fordialog(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 withXdialog, I don’t really support the latter. I test everything with
dialog, and nothing with Xdialog.That being said, here is theoldtext 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
(whichshouldbe found underhttp://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.Historypythondialog 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 theXdialogsupport. Florent Rougon
took over maintainership again starting from 2009…