python-wofi


Namepython-wofi JSON
Version 0.2.2 PyPI version JSON
download
home_pagehttps://github.com/cristobaltapia/python-wofi
SummaryCreate simple GUIs using the Wofi application
upload_time2020-10-27 21:43:38
maintainer
docs_urlNone
authorCristóbal Tapia Camú
requires_python>=3.6,<4.0
licenseMIT
keywords wofi
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ===========
python-wofi
===========

A Python module to make simple GUIs using Wofi_.
(forked from the original `python-rofi`_ module)

.. _`python-rofi`: https://github.com/bcbnz/python-rofi

.. _Wofi: https://hg.sr.ht/~scoopta/wofi


What is Wofi?
=============


Wofi is a launcher/menu program for wlroots based wayland compositors such as
sway. Its basic operation is to display a list of options and let the user
pick one. The following screenshot is shamelessly hotlinked from the wofi
website (which you should probably visit if you want actual details about
wofi!).

.. image:: https://f.cloudninja.pw/Scaled_4.png
   :alt: A screenshot of Wofi.

.. _Wofi: https://hg.sr.ht/~scoopta/wofi


What is this module?
====================

It simplifies making simple GUIs using Wofi. It provides a class with a number
of methods for various GUI actions (show messages, pick one of these options,
enter some text / a number). These are translated to the appropriate Wofi
command line options, and then the standard subprocess_ module is used to run
Wofi. Any output is then processed and returned to you to do whatever you like
with.

.. _subprocess: https://docs.python.org/3/library/subprocess.html


Examples
--------

Data entry
~~~~~~~~~~

The simplest example is to create a Wofi instance and prompt the user to enter
a piece of text::

    from wofi import Wofi
    r = Wofi()
    name = r.text_entry('What is your name? ')

There are also entry methods for integers, floating-point numbers, and decimal
numbers::

    age = r.integer_entry('How old are you? ')
    height = r.float_entry('How tall are you? ')
    price = r.decimal_entry('How much are you willing to spend? ')

All of these return the corresponding Python type. Dates and times can also be
requested::

    dob = r.date_entry('What is your date of birth? ')
    start = r.time_entry('When do you start work? ')
    reminder = r.datetime_entry('When do you want to be alerted? ')

Again, these return the corresponding Python type. By default, they expect the
user to enter something in the appropriate format for the current locale. You
can override this by providing a list of format specifiers to any of these
functions. The available specifiers are detailed in the Python documentation
for the datetime_ module. For example::

    start = r.time_entry('When do you start work? ', formats=['%H:%M'])

All of these entry methods are specialisations of the ``generic_entry()``
method. You can use this to create your own entry types. All you need to do is
create a validator function which takes the text entered by the user, and
returns either the Python object or an error message. For example, to enforce a
minimum length on an entered piece of text::

    validator = lambda s: (s, None) if len(s) > 6 else (None, "Too short!")
    r.generic_entry('Enter a 7-character or longer string: ', validator)

Note that all of these methods return ``None`` if the dialog is cancelled.

.. _datetime: https://docs.python.org/3/library/datetime.html

Errors
~~~~~~

To show an error message to the user::

    r.error('I cannot let you do that.')
    r.exit_with_error('I cannot let you do that.')

The latter shows the error message and then exits.

Selections
~~~~~~~~~~

To give the user a list of things to select from, and return the index of the
option they chose::

    options = ['Red', 'Green', 'Blue', 'White', 'Silver', 'Black', 'Other']
    index, key = r.select('What colour car do you drive?', options)

The returned ``key`` value tells you what key the user pressed. For Enter, the
value is 0, while -1 indicates they cancelled the dialog. You can also specify
custom key bindings::

    index, key = r.select('What colour car do you drive?', options, key5=('Alt+n', "I don't drive"))

In this case, the returned ``key`` will be 5 if they press Alt+n.

Status
~~~~~~

To display a status message to the user::

    r.status("I'm working on that...")

This is the only non-blocking method (all the others wait for the user to
finish before returning control to your script). To close the status message::

    r.close()

Calling a display or entry method will also close any status message currently
displayed.

Messages
~~~~~~~~

Any of the entry methods and the select method have an optional argument
``message``. This is a string which is displayed below the prompt. The string
can contain Pango_ markup::

    r.text_entry('What are your goals for this year? ', message='Be <b>bold</b>!')

If you need to escape a string to avoid it being mistaken for markup, use the
``Wofi.escape()`` class method::

    msg = Wofi.escape('Format: <firstname> <lastname>')
    r.text_entry('Enter your name: ', message=msg)

.. _Pango:  https://developer.gnome.org/pango/stable/PangoMarkupFormat.html

Customisation
~~~~~~~~~~~~~

There are a number of options available to customise the display. These can be
set in the initialiser to apply to every dialog displayed, or you can pass them
to any of the display methods to change just that dialog. See the Wofi
documentation for full details of these parameters.

* ``lines``: The maximum number of lines to show before scrolling.

* ``fixed_lines``: Keep a fixed number of lines visible.

* ``width``: If positive but not more than 100, this is the percentage of the
  screen's width the window takes up. If greater than 100, it is the width in
  pixels. If negative, it estimates the width required for the corresponding
  number of characters, i.e., -30 would set the width so approximately 30
  characters per row would show.

* ``fullscreen``: If True, use the full height and width of the screen.

* ``location``:  The position of the window on the screen.

* You can also pass in arbitrary arguments to wofi through the ``wofi_args``
  parameter. These have to be passed in as a list of strings, with every
  argument in a seperate string. For example, to make a selection case
  insensitive::
    
    r = Wofi()
    r.select('Choose one', ['option 1', 'option 2', 'option 3'],
        wofi_args=['-i'])
  
  or, to choose a different style for an instance of ``Wofi``::

    r = Wofi(wofi_args=['-theme', 'path/to/theme.rasi'])
    r.status('Stuff is happening, please wait...')




Requirements
============

You need to have the ``wofi`` executable available on the system path (i.e.,
install Wofi!). Everything else that python-wofi needs is provided by the
Python standard libraries.


What Python versions are supported?
===================================

It *should* work with any version of Python from 2.7 onwards. It may work with
older versions, though no specific support for them will be added. It is
developed on Python 2.7 and Python 3.6 -- the latest versions of the Python 2
and 3 branches respectively.


What license does it use?
=========================

The MIT license, the same as python-wofi.


Bug reports
===========

The project is developed on GitHub_. Please file any bug reports or feature
requests on the Issues_ page there.

.. _GitHub: https://github.com/cristobaltapia/python-wofi
.. _Issues: https://github.com/cristobaltapia/python-wofi/issues

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/cristobaltapia/python-wofi",
    "name": "python-wofi",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6,<4.0",
    "maintainer_email": "",
    "keywords": "wofi",
    "author": "Crist\u00f3bal Tapia Cam\u00fa",
    "author_email": "crtapia@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/65/d7/802146e1046fcbeea914ae9746d0161e1f0e359c92de36392da1d4c6148d/python-wofi-0.2.2.tar.gz",
    "platform": "",
    "description": "===========\npython-wofi\n===========\n\nA Python module to make simple GUIs using Wofi_.\n(forked from the original `python-rofi`_ module)\n\n.. _`python-rofi`: https://github.com/bcbnz/python-rofi\n\n.. _Wofi: https://hg.sr.ht/~scoopta/wofi\n\n\nWhat is Wofi?\n=============\n\n\nWofi is a launcher/menu program for wlroots based wayland compositors such as\nsway. Its basic operation is to display a list of options and let the user\npick one. The following screenshot is shamelessly hotlinked from the wofi\nwebsite (which you should probably visit if you want actual details about\nwofi!).\n\n.. image:: https://f.cloudninja.pw/Scaled_4.png\n   :alt: A screenshot of Wofi.\n\n.. _Wofi: https://hg.sr.ht/~scoopta/wofi\n\n\nWhat is this module?\n====================\n\nIt simplifies making simple GUIs using Wofi. It provides a class with a number\nof methods for various GUI actions (show messages, pick one of these options,\nenter some text / a number). These are translated to the appropriate Wofi\ncommand line options, and then the standard subprocess_ module is used to run\nWofi. Any output is then processed and returned to you to do whatever you like\nwith.\n\n.. _subprocess: https://docs.python.org/3/library/subprocess.html\n\n\nExamples\n--------\n\nData entry\n~~~~~~~~~~\n\nThe simplest example is to create a Wofi instance and prompt the user to enter\na piece of text::\n\n    from wofi import Wofi\n    r = Wofi()\n    name = r.text_entry('What is your name? ')\n\nThere are also entry methods for integers, floating-point numbers, and decimal\nnumbers::\n\n    age = r.integer_entry('How old are you? ')\n    height = r.float_entry('How tall are you? ')\n    price = r.decimal_entry('How much are you willing to spend? ')\n\nAll of these return the corresponding Python type. Dates and times can also be\nrequested::\n\n    dob = r.date_entry('What is your date of birth? ')\n    start = r.time_entry('When do you start work? ')\n    reminder = r.datetime_entry('When do you want to be alerted? ')\n\nAgain, these return the corresponding Python type. By default, they expect the\nuser to enter something in the appropriate format for the current locale. You\ncan override this by providing a list of format specifiers to any of these\nfunctions. The available specifiers are detailed in the Python documentation\nfor the datetime_ module. For example::\n\n    start = r.time_entry('When do you start work? ', formats=['%H:%M'])\n\nAll of these entry methods are specialisations of the ``generic_entry()``\nmethod. You can use this to create your own entry types. All you need to do is\ncreate a validator function which takes the text entered by the user, and\nreturns either the Python object or an error message. For example, to enforce a\nminimum length on an entered piece of text::\n\n    validator = lambda s: (s, None) if len(s) > 6 else (None, \"Too short!\")\n    r.generic_entry('Enter a 7-character or longer string: ', validator)\n\nNote that all of these methods return ``None`` if the dialog is cancelled.\n\n.. _datetime: https://docs.python.org/3/library/datetime.html\n\nErrors\n~~~~~~\n\nTo show an error message to the user::\n\n    r.error('I cannot let you do that.')\n    r.exit_with_error('I cannot let you do that.')\n\nThe latter shows the error message and then exits.\n\nSelections\n~~~~~~~~~~\n\nTo give the user a list of things to select from, and return the index of the\noption they chose::\n\n    options = ['Red', 'Green', 'Blue', 'White', 'Silver', 'Black', 'Other']\n    index, key = r.select('What colour car do you drive?', options)\n\nThe returned ``key`` value tells you what key the user pressed. For Enter, the\nvalue is 0, while -1 indicates they cancelled the dialog. You can also specify\ncustom key bindings::\n\n    index, key = r.select('What colour car do you drive?', options, key5=('Alt+n', \"I don't drive\"))\n\nIn this case, the returned ``key`` will be 5 if they press Alt+n.\n\nStatus\n~~~~~~\n\nTo display a status message to the user::\n\n    r.status(\"I'm working on that...\")\n\nThis is the only non-blocking method (all the others wait for the user to\nfinish before returning control to your script). To close the status message::\n\n    r.close()\n\nCalling a display or entry method will also close any status message currently\ndisplayed.\n\nMessages\n~~~~~~~~\n\nAny of the entry methods and the select method have an optional argument\n``message``. This is a string which is displayed below the prompt. The string\ncan contain Pango_ markup::\n\n    r.text_entry('What are your goals for this year? ', message='Be <b>bold</b>!')\n\nIf you need to escape a string to avoid it being mistaken for markup, use the\n``Wofi.escape()`` class method::\n\n    msg = Wofi.escape('Format: <firstname> <lastname>')\n    r.text_entry('Enter your name: ', message=msg)\n\n.. _Pango:  https://developer.gnome.org/pango/stable/PangoMarkupFormat.html\n\nCustomisation\n~~~~~~~~~~~~~\n\nThere are a number of options available to customise the display. These can be\nset in the initialiser to apply to every dialog displayed, or you can pass them\nto any of the display methods to change just that dialog. See the Wofi\ndocumentation for full details of these parameters.\n\n* ``lines``: The maximum number of lines to show before scrolling.\n\n* ``fixed_lines``: Keep a fixed number of lines visible.\n\n* ``width``: If positive but not more than 100, this is the percentage of the\n  screen's width the window takes up. If greater than 100, it is the width in\n  pixels. If negative, it estimates the width required for the corresponding\n  number of characters, i.e., -30 would set the width so approximately 30\n  characters per row would show.\n\n* ``fullscreen``: If True, use the full height and width of the screen.\n\n* ``location``:  The position of the window on the screen.\n\n* You can also pass in arbitrary arguments to wofi through the ``wofi_args``\n  parameter. These have to be passed in as a list of strings, with every\n  argument in a seperate string. For example, to make a selection case\n  insensitive::\n    \n    r = Wofi()\n    r.select('Choose one', ['option 1', 'option 2', 'option 3'],\n        wofi_args=['-i'])\n  \n  or, to choose a different style for an instance of ``Wofi``::\n\n    r = Wofi(wofi_args=['-theme', 'path/to/theme.rasi'])\n    r.status('Stuff is happening, please wait...')\n\n\n\n\nRequirements\n============\n\nYou need to have the ``wofi`` executable available on the system path (i.e.,\ninstall Wofi!). Everything else that python-wofi needs is provided by the\nPython standard libraries.\n\n\nWhat Python versions are supported?\n===================================\n\nIt *should* work with any version of Python from 2.7 onwards. It may work with\nolder versions, though no specific support for them will be added. It is\ndeveloped on Python 2.7 and Python 3.6 -- the latest versions of the Python 2\nand 3 branches respectively.\n\n\nWhat license does it use?\n=========================\n\nThe MIT license, the same as python-wofi.\n\n\nBug reports\n===========\n\nThe project is developed on GitHub_. Please file any bug reports or feature\nrequests on the Issues_ page there.\n\n.. _GitHub: https://github.com/cristobaltapia/python-wofi\n.. _Issues: https://github.com/cristobaltapia/python-wofi/issues\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Create simple GUIs using the Wofi application",
    "version": "0.2.2",
    "split_keywords": [
        "wofi"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "f12e518908dc2207e68fb3e85f4c6cec",
                "sha256": "a0a6f62778b3fd91a3b8db50a6f006f67118e0868a8fff4920da684273212635"
            },
            "downloads": -1,
            "filename": "python_wofi-0.2.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f12e518908dc2207e68fb3e85f4c6cec",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6,<4.0",
            "size": 13116,
            "upload_time": "2020-10-27T21:43:39",
            "upload_time_iso_8601": "2020-10-27T21:43:39.428318Z",
            "url": "https://files.pythonhosted.org/packages/de/c9/fb6ac7170c42cae4d9217e98a0e70b823a4c2ef5c79c08461b2e391cd3c8/python_wofi-0.2.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "bc3ef87b4d51a52b9bfebccfb70d2715",
                "sha256": "96ae2a6b8f7e0be367d0bc5e79b50c9129dd14ddde47225b96cd27d53bf21173"
            },
            "downloads": -1,
            "filename": "python-wofi-0.2.2.tar.gz",
            "has_sig": false,
            "md5_digest": "bc3ef87b4d51a52b9bfebccfb70d2715",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6,<4.0",
            "size": 14457,
            "upload_time": "2020-10-27T21:43:38",
            "upload_time_iso_8601": "2020-10-27T21:43:38.176560Z",
            "url": "https://files.pythonhosted.org/packages/65/d7/802146e1046fcbeea914ae9746d0161e1f0e359c92de36392da1d4c6148d/python-wofi-0.2.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-10-27 21:43:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "cristobaltapia",
    "error": "Could not fetch GitHub repository",
    "lcname": "python-wofi"
}
        
Elapsed time: 0.14423s