.. _howto-evaluated-models:

Work with evaluated models
==========================

The Taurus ``eval:`` scheme creates Taurus attributes whose values are computed
from Python expressions. It is useful for quick calculations, combining values
from other Taurus models, and prototyping data sources without implementing a
new scheme.

Use a Python expression
-----------------------

Create an evaluation attribute with :func:`taurus.Attribute`::

    import taurus

    attr = taurus.Attribute('eval:Q(rand(), "V")')
    print(attr.read().rvalue)

When no evaluation device is specified, Taurus uses its default evaluator,
which provides a selection of NumPy functions and other safe symbols.

Use values from other Taurus models
-----------------------------------

Enclose another model name in braces to use its value in an expression. For
example, the following form displays a Tango attribute and a value ten times
larger::

    taurus form \
        "tango:sys/tg_test/1/short_scalar" \
        "eval:{tango:sys/tg_test/1/short_scalar}*10"

Evaluation models can be used by normal Taurus widgets just like models from
other schemes. For example::

    taurus trend \
        "tango:sys/tg_test/1/short_scalar" \
        "eval:-{tango:sys/tg_test/1/short_scalar}"

Evaluations are also units-aware. For example::

    taurus form "eval:({eval:Q('3N')}/{eval:Q('2kg')}).to_base_units()"

This evaluates to ``1.5 m/s**2``.

Access Python modules
---------------------

The ``@module.*`` syntax creates an evaluation device exposing symbols from a
Python module. For example::

    taurus form 'eval:@datetime.*/date.today().isoformat()'

or::

    taurus form 'eval:@os.path.*/exists("/tmp")'

The module name may contain dots, as in the ``os.path`` example above.

Use a custom evaluation device
------------------------------

Evaluation devices derive from
:class:`taurus.core.util.safeeval.SafeEvaluator`. You can create a named
evaluator and add symbols programmatically::

    import taurus

    dev = taurus.Device('eval:@mydev')
    dev.addSafe({'message': 'hello world'})

    attr = taurus.Attribute('eval:@mydev/message.upper()')
    print(attr.read().rvalue)

This is useful for prototyping, but applications that expose a reusable data
source should normally consider implementing a dedicated Taurus scheme.

Further examples
----------------

The Taurus training material contains more advanced examples, including
accessing class instances and exposing writable Python properties as Taurus
attributes:

`Taurus training: Evaluation Scheme <https://gitlab.com/taurus-org/taurus-training/-/blob/main/current/eval_scheme.md>`_

See also
--------

- :mod:`taurus.core.evaluation`
- :doc:`Models and schemes <../explanation/models>`