===============================================================================
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.
.. _dialog: https://invisible-island.net/dialog/dialog.html
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.
.. _short example: https://pythondialog.sourceforge.io/#example
.. _screenshots: https://pythondialog.sourceforge.io/gallery.html
.. _summary of the recent changes:
https://pythondialog.sourceforge.io/news.html
.. _documentation: https://pythondialog.sourceforge.io/doc/
.. _Git repository: https://sourceforge.net/p/pythondialog/code/
.. _mailing list: https://sourceforge.net/p/pythondialog/mailman/
.. _issue tracker: https://sourceforge.net/p/pythondialog/_list/tickets
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.
.. _ncurses: https://invisible-island.net/ncurses/ncurses.html
.. _blessings: https://github.com/erikrose/blessings
.. _Urwid Python library: http://excess.org/urwid/
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
<https://bugs.debian.org/990043>`_; 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`_.
.. _pythondialog home page: https://pythondialog.sourceforge.io/
* 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 <https://pypi.org/project/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
<https://pip.pypa.io/>`_.
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/
.. _pythondialog Manual: https://pythondialog.sourceforge.io/doc/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _LaTeX: https://www.latex-project.org/
.. _Make: https://www.gnu.org/software/make/
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.
.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
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!).
.. _Xdialog: http://xdialog.free.fr/
.. _GTK+: https://www.gtk.org/
.. _Debian: https://www.debian.org/
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...
..
# Local Variables:
# coding: utf-8
# fill-column: 72
# End:
Raw data
{
"_id": null,
"home_page": "https://pythondialog.sourceforge.io/",
"name": "pythondialog",
"maintainer": "Florent Rougon",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "f.rougon@free.fr",
"keywords": "dialog,ncurses,Xdialog,text-mode interface,terminal",
"author": "Robb Shecter",
"author_email": "robb@acm.org",
"download_url": "https://files.pythonhosted.org/packages/4e/40/5c84d79f7d536ca2c3722af521eff4faafe54a93797f08c72eb72e68fb68/pythondialog-3.5.3.tar.gz",
"platform": "Unix",
"description": "===============================================================================\nPython wrapper for the UNIX \"dialog\" utility\n===============================================================================\nEasy writing of graphical interfaces for terminal-based applications\n-------------------------------------------------------------------------------\n\nOverview\n--------\n\npythondialog is a Python wrapper for the UNIX dialog_ utility\noriginally written by Savio Lam and later rewritten by Thomas E. Dickey.\nIts purpose is to provide an easy to use, pythonic and as complete as\npossible interface to dialog_ from Python code.\n\n.. _dialog: https://invisible-island.net/dialog/dialog.html\n\npythondialog is free software, licensed under the GNU LGPL (GNU Lesser\nGeneral Public License). Its home page is located at:\n\n https://pythondialog.sourceforge.io/\n\nand contains a `short example`_, screenshots_, a `summary of the recent\nchanges`_, links to the `documentation`_, the `Git repository`_, the\n`mailing list`_, the `issue tracker`_, etc.\n\n.. _short example: https://pythondialog.sourceforge.io/#example\n.. _screenshots: https://pythondialog.sourceforge.io/gallery.html\n.. _summary of the recent changes:\n https://pythondialog.sourceforge.io/news.html\n.. _documentation: https://pythondialog.sourceforge.io/doc/\n.. _Git repository: https://sourceforge.net/p/pythondialog/code/\n.. _mailing list: https://sourceforge.net/p/pythondialog/mailman/\n.. _issue tracker: https://sourceforge.net/p/pythondialog/_list/tickets\n\nIf you want to get a quick idea of what this module allows one to do,\nyou can download a release tarball and run ``demo.py``::\n\n PYTHONPATH=. python3 examples/demo.py\n\n\nWhat is pythondialog good for? What are its limitations?\n--------------------------------------------------------\n\nAs you might infer from the name, dialog is a high-level program that\ngenerates dialog boxes. So is pythondialog. They allow you to build nice\ninterfaces quickly and easily, but you don't have full control over the\nwidgets, nor can you create new widgets without modifying dialog itself.\nIf you need to do low-level stuff, you should have a look at `ncurses`_\n(cf.\u00a0the ``curses`` module in the Python standard library), `blessings`_\nor slang instead. For sophisticated text-mode interfaces, the `Urwid\nPython library`_ looks rather interesting, too.\n\n.. _ncurses: https://invisible-island.net/ncurses/ncurses.html\n.. _blessings: https://github.com/erikrose/blessings\n.. _Urwid Python library: http://excess.org/urwid/\n\n\nRequirements\n------------\n\n* As of version 2.12, pythondialog requires Python 3.0 or later in the 3.x\n series. pythondialog 3.5.3 has been tested with Python 3.9.\n\n* dialog_ version 1.3-20201126-1 (the version shipped in Debian stable\n and unstable in November 2021) is `broken\n <https://bugs.debian.org/990043>`_; don't waste your time with that\n version. dialog_ 1.3-20210621 works fine.\n\n* Versions of pythondialog up to and including 3.5.1 had a backport to\n Python\u00a02, however this outdated Python dialect isn't supported\n anymore. You may find pointers to the old packages with Python\u00a02\n support on the `pythondialog home page`_.\n\n .. _pythondialog home page: https://pythondialog.sourceforge.io/\n\n* Apart from that, pythondialog requires the dialog_ program (or a\n drop-in replacement for dialog). You can download dialog from:\n\n https://invisible-island.net/dialog/dialog.html\n\n Note that some features of pythondialog may require recent versions of\n dialog.\n\n\nQuick installation instructions\n-------------------------------\n\nIf you have a working `pip <https://pypi.org/project/pip/>`_ setup,\nyou should be able to install pythondialog with::\n\n pip install pythondialog\n\nWhen doing so, make sure that your ``pip`` executable runs with the\nPython\u00a03 installation you want to install pythondialog for.\n\nFor more detailed instructions, you can read the ``INSTALL`` file from a\nrelease tarball. You may also want to consult the `pip documentation\n<https://pip.pypa.io/>`_.\n\n\nDocumentation\n-------------\n\nThe pythondialog Manual\n^^^^^^^^^^^^^^^^^^^^^^^\n\nThe pythondialog Manual is written in `reStructuredText`_ format for the\n`Sphinx`_ documentation generator. The HTML documentation for the latest\nversion of pythondialog as rendered by Sphinx should be available at:\n\n https://pythondialog.sourceforge.io/doc/\n\n.. _pythondialog Manual: https://pythondialog.sourceforge.io/doc/\n.. _reStructuredText: http://docutils.sourceforge.net/rst.html\n.. _Sphinx: https://www.sphinx-doc.org/en/master/\n.. _LaTeX: https://www.latex-project.org/\n.. _Make: https://www.gnu.org/software/make/\n\nThe sources for the pythondialog Manual are located in the ``doc``\ntop-level directory of the pythondialog distribution, but the\ndocumentation build process pulls many parts from ``dialog.py`` (mainly\ndocstrings).\n\nTo generate the documentation yourself from ``dialog.py`` and the\nsources in the ``doc`` directory, first make sure you have `Sphinx`_ and\n`Make`_ installed. Then, you can go to the ``doc`` directory and type,\nfor instance::\n\n make html\n\nYou will then find the output in the ``_build/html`` subdirectory of\n``doc``. `Sphinx`_ can build the documentation in many other formats.\nFor instance, if you have `LaTeX`_ installed, you can generate the\npythondialog Manual in PDF format using::\n\n make latexpdf\n\nYou can run ``make`` from the ``doc`` directory to see a list of the\navailable formats. Run ``make clean`` to clean up after the\ndocumentation build process.\n\nFor those who have installed `Sphinx`_ but not `Make`_, it is still\npossible to build the documentation with a command such as::\n\n sphinx-build -b html . _build/html\n\nrun from the ``doc`` directory. Please refer to `sphinx-build`_ for more\ndetails.\n\n.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html\n\n\nReading the docstrings from an interactive Python interpreter\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf you have already installed pythondialog, you may consult its\ndocstrings in an interactive Python interpreter this way::\n\n >>> import dialog; help(dialog)\n\nbut only parts of the documentation are available using this method, and\nthe result is much less convenient to use than the `pythondialog\nManual`_ as generated by `Sphinx`_.\n\n\nEnabling Deprecation Warnings\n-----------------------------\n\nThere are a few places in ``dialog.py`` that send a\n``DeprecationWarning`` to warn developers about obsolete features.\nHowever, because of:\n\n - the dialog output to the terminal;\n - the fact that such warnings are silenced by default since Python 2.7\n and 3.2;\n\nyou have to do two things in order to see them:\n\n - redirect the standard error stream to a file;\n - enable the warnings for the Python interpreter.\n\nFor instance, to see the warnings produced when running the demo, you\ncan do::\n\n PYTHONPATH=. python3 -Wd examples/demo.py 2>/path/to/file\n\nand examine ``/path/to/file``. This can also help you to find files that\nare still open when your program exits.\n\n**Note:**\n\n If your program is terminated by an unhandled exception while stderr\n is redirected as in the preceding command, you won't see the traceback\n until you examine the file stderr was redirected to. This can be\n disturbing, as your program may exit with no apparent reason in such\n conditions.\n\nFor more explanations and other methods to enable deprecation warnings,\nplease refer to:\n\n https://docs.python.org/3/whatsnew/2.7.html\n\n\nTroubleshooting\n---------------\n\nIf you have a problem with a pythondialog call, you should read its\ndocumentation and the dialog(1) manual page. If this is not enough, you\ncan enable logging of shell command-line equivalents of all dialog calls\nmade by your program with a simple call to ``Dialog.setup_debug()``,\nfirst available in pythondialog 2.12 (the ``expand_file_opt`` parameter\nmay be useful in versions 3.3 and later). An example of this can be\nfound in ``demo.py`` from the ``examples`` directory.\n\nAs of version 2.12, you can also enable this debugging facility for\n``demo.py`` by calling it with the ``--debug`` flag (possibly combined\nwith ``--debug-expand-file-opt`` in pythondialog 3.3 and later, cf.\n``demo.py --help``).\n\n\nUsing Xdialog instead of dialog\n-------------------------------\n\nAs far as I can tell, `Xdialog`_ has not been ported to `GTK+`_ version\n2 or later. It is not in `Debian`_ stable nor unstable (November 30, 2019).\nIt is not installed on my system (because of the GTK+ 1.2 dependency),\nand according to the Xdialog-specific patches I received from Peter\n\u00c5strand in 2004, was not a drop-in replacement for `dialog`_ (in\nparticular, Xdialog seemed to want to talk to the caller through stdout\ninstead of stderr, grrrrr!).\n\n.. _Xdialog: http://xdialog.free.fr/\n.. _GTK+: https://www.gtk.org/\n.. _Debian: https://www.debian.org/\n\nAll this to say that, even though I didn't remove the options to use\nanother backend than dialog, nor did I remove the handful of little,\nnon-invasive modifications that help pythondialog work better with\n`Xdialog`_, I don't really support the latter. I test everything with\ndialog, and nothing with Xdialog.\n\nThat being said, here is the *old* text of this section (from 2004), in\ncase you are still interested:\n\n Starting with 2.06, there is an \"Xdialog\" compatibility mode that you\n can use if you want pythondialog to run the graphical Xdialog program\n (which *should* be found under http://xdialog.free.fr/) instead of\n dialog (text-mode, based on the ncurses library).\n\n The primary supported platform is still dialog, but as long as only\n small modifications are enough to make pythondialog work with Xdialog,\n I am willing to support Xdialog if people are interested in it (which\n turned out to be the case for Xdialog).\n\n The demo.py from pythondialog 2.06 has been tested with Xdialog 2.0.6\n and found to work well (barring Xdialog's annoying behaviour with the\n file selection dialog box).\n\n\nWhiptail, anyone?\n-----------------\n\nWell, pythondialog seems not to work very well with whiptail. The reason\nis that whiptail is not compatible with dialog anymore. Although you can\ntell pythondialog the program you want it to invoke, only programs that\nare mostly dialog-compatible are supported.\n\n\nHistory\n-------\n\npythondialog was originally written by Robb Shecter. Sultanbek Tezadov\nadded some features to it (mainly the first gauge implementation, I\nguess). Florent Rougon rewrote most parts of the program to make it more\nrobust and flexible so that it can give access to most features of the\ndialog program. Peter \u00c5strand took over maintainership between 2004 and\n2009, with particular care for the `Xdialog`_ support. Florent Rougon\ntook over maintainership again starting from 2009...\n\n.. \n # Local Variables:\n # coding: utf-8\n # fill-column: 72\n # End:\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python interface to the UNIX dialog utility and mostly-compatible programs",
"version": "3.5.3",
"project_urls": {
"Documentation": "https://pythondialog.sourceforge.io/doc/",
"Git repository": "https://sourceforge.net/p/pythondialog/code/",
"Homepage": "https://pythondialog.sourceforge.io/",
"Issue tracker": "https://sourceforge.net/p/pythondialog/_list/tickets",
"Mailing list": "https://sourceforge.net/p/pythondialog/mailman/",
"SourceForge project page": "https://sourceforge.net/projects/pythondialog"
},
"split_keywords": [
"dialog",
"ncurses",
"xdialog",
"text-mode interface",
"terminal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69f0b3c431610753aa5687384e67cb92fbc2d531eb86f1ce32a8cb9735f9b0b7",
"md5": "e73ace4d799d0e3b8f92e1800c393b54",
"sha256": "b9ac084a1ba5db75242ef623ea6a770f0e74aa634869151be15a2d1c50daaab2"
},
"downloads": -1,
"filename": "pythondialog-3.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e73ace4d799d0e3b8f92e1800c393b54",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 54746,
"upload_time": "2021-11-26T13:21:35",
"upload_time_iso_8601": "2021-11-26T13:21:35.007671Z",
"url": "https://files.pythonhosted.org/packages/69/f0/b3c431610753aa5687384e67cb92fbc2d531eb86f1ce32a8cb9735f9b0b7/pythondialog-3.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e405c84d79f7d536ca2c3722af521eff4faafe54a93797f08c72eb72e68fb68",
"md5": "94a9236e427de783fa3ee8288834f7f1",
"sha256": "b2a34a8af0a6625ccbdf45cd343b854fc6c1a85231dadc80b8805db836756323"
},
"downloads": -1,
"filename": "pythondialog-3.5.3.tar.gz",
"has_sig": false,
"md5_digest": "94a9236e427de783fa3ee8288834f7f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 1509854,
"upload_time": "2021-11-26T13:21:54",
"upload_time_iso_8601": "2021-11-26T13:21:54.795069Z",
"url": "https://files.pythonhosted.org/packages/4e/40/5c84d79f7d536ca2c3722af521eff4faafe54a93797f08c72eb72e68fb68/pythondialog-3.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-11-26 13:21:54",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pythondialog"
}
JSON