mutaprops 0.6.3

Simple UI, autogenerated from your classes.

mutaprops
=========


.. image:: https://img.shields.io/pypi/v/mutaprops.svg
:target: https://pypi.python.org/pypi/mutaprops

.. image:: https://img.shields.io/travis/JNevrly/mutaprops.svg
:target: https://travis-ci.org/calcite/mutaprops

.. image:: https://readthedocs.org/projects/pip/badge/
:target: https://readthedocs.org/projects/pip/badge/
:alt: Documentation Status

.. image:: https://pyup.io/repos/github/calcite/mutaprops/shield.svg
:target: https://pyup.io/repos/github/calcite/mutaprops/
:alt: Updates


Mutated Properties - a simple HTML5 property-configuration UI,
autogenerated from your classes.

It's great if you need a quick'n'dirty UI with minimal
effort and without changing much of the existing codebase. Mutaprops also thrive
on headless systems when usual UI solutions like tkinter_ doesn't make sense.

However, the customization possibilities are limited, so if you are looking for
some framework for building a full-fledged attractive GUI, better look
elsewhere.

.. * Free software: MIT license
.. * Documentation: https://mutaprops.readthedocs.io.


Features
--------

* Generate a self-documented web UI directly from your objects with simple decorators
* UI state automatically updated with object state changes (through websockets)
* Supports multiple UI sessions on the same object, synchronized through
websockets
* Supports clustering of UI's from multiple machines
* UI look and feel can be customized with your own stylesheet
* Add any widget you like with direct HTML support
* HTML5 log console capturing all your Python logging
* Asyncio support (and also a requirement ;))

The simplest example
--------------------

Imagine a normal Python class:

.. code-block:: python

class Hoovercraft:

MAX_EELS = 40

def __init__(self, number_of_eels=20, speed=0, direction='North'):
self._eel_count = number_of_eels
self._speed = speed
self._direction = direction
self._engine_running = False
self._steering_locked = True

@property
def eels(self):
return self._eel_count

@eels.setter
def eels(self, value):
self._eel_count = value
if self._eel_count >= self.MAX_EELS:
logger.warning("The hoovercraft is full of eels!")

def drop_all_eels(self):
self.eels = 0
logger.info("Eels are goooone!")

Now, to turn this into an UI, one just has to decorate it like this:

.. code-block:: python

from mutaprops import *

@mutaprop_class("Hoovercraft UI")
class Hoovercraft:

MAX_EELS = 40

def __init__(self, number_of_eels=20, speed=0, direction='North'):
self._eel_count = number_of_eels
self._speed = speed
self._direction = direction
self._engine_running = False
self._steering_locked = True

@mutaproperty("Number of eels", MutaTypes.INT, min_val=0,
max_val=MAX_EELS)
def eels(self):
return self._eel_count

@eels.setter
def eels(self, value):
self._eel_count = value
if self._eel_count >= self.MAX_EELS:
logger.warning("The hoovercraft is full of eels!")

@mutaprop_action("Drop all eels!")
def drop_all_eels(self):
self.eels = 0
logger.info("Eels are goooone!")

And then run it like this:


.. code-block:: python

if __name__ == '__main__':

test = Hoovercraft()
test.muta_init("Hoovercraft instance #1")
man = HttpMutaManager("Hoovercraft manager", proxy_log=logger)
man.add_object(test)
man.run(port=9000)

Et voila, here's the UI:

.. image:: docs/img/screenshot-simple.png

Other examples
--------------

The ``examples/`` folder contains several other examples:

* `simple_example.py`_ is the extension of the example above, including more
data types and also shows how to work with docstrings and ``mutasources``

* `advanced_example.py`_ demonstrates grouping of parameters, style
customizations, raw HTML features and asyncio integration.

Full documentation
------------------

The complete documentation is available at https://mutaprops.readthedocs.io

Using the UI
------------

Simple explanation how to use the UI is
`here <http://mutaprops.readthedocs.io/en/latest/usage.html#using-the-ui>`_.


Credits
-------

The default logo created with the Chlorinar_ font.

The JavaScript frontend created with the fantastic `Vue.js`_.

The widgets and styling are based on `Bootstrap 3`_.

The toggle widget is the `Bootstrap toggle`_.

Hoovercraft logo used in `advanced_example.py`_ was created by Theresa Stoodley
from the Noun Project. Licensed under Creative Commons 3.0 license.

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _`simple_example.py`: examples/simple_example.py
.. _`advanced_example.py`: examples/advanced_example.py
.. _Chlorinar: http://www.dafont.com/chlorinar.font
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _tkinter: https://docs.python.org/3.6/library/tkinter.html
.. _`Vue.js`: https://vuejs.org
.. _`Bootstrap 3`: https://getbootstrap.com/docs/3.3/
.. _`Bootstrap toggle`: http://www.bootstraptoggle.com/



=======
History
=======

Latest releases
+++++++++++++++

0.6.3 (2017-10-16)
------------------
* Fixed bug with step setting.

0.6.0 (2017-08-30)
------------------
* Added css separation
* Added documentation
* Minor bug fixes

Older releases
++++++++++++++

0.5.7 (2017-08-25)
------------------
Added the forgoten JS build...

0.5.6 (2017-08-25)
------------------
Fixed various UI bugs (read-only settings, responsive design, title).
Actions now can have read-only setting.

0.5.5 (2017-04-26)
------------------
Fixed incompatibility with Python 3.4.2.

0.5.4 (2017-04-25)
------------------
Fixed debug print of properties.

0.5.3 (2017-04-21)
------------------
Fixed bug with log messages formatting on the Web UI.

0.5.2 (2017-04-20)
------------------
Fixed bug with Bool-type props help panels not uncollapsing.

0.5.1 (2017-03-06)
------------------
Fixed error message when object was not selected in an one-object list.

0.5.0 (2017-02-15)
------------------
* Large internal rework - introduced update-dependencies for values and
selected meta-values (selects, minimums, maximums, steps etc).
* Added MutaSources as non-UI MutaProps for supporting internal dependencies
* Added HTML type of value (read-only)
* JS client now works with single state-store (Vuex)
* MutaSelects removed - this functionality is now replaced by more general
update-dependencies through MutaSources. This breaks compatibility with 0.4.x

0.4.1 (2016-12-06)
------------------
* Fixed bug with displaying first prop in hierarchy panel.

0.4.0 (2016-12-06)
------------------
* One level hierarchy (panels) and experimental support of toggle buttons instead of checkboxes.

0.3.0 (2016-11-03)
------------------
* Allowed HTML in help blocks
* Allowed local files/local dir

0.2.2 (2016-11-03)
------------------
* Fixed path problem on linux

0.2.1 (2016-11-03)
------------------
* Added ALPS logo

0.2.0 (2016-11-03)
------------------

* HTTP manager chaining.
* UI bugfixes.

0.1.0 (2016-11-03)
------------------

* First (internal) release.