# Taurus 3.x to 4.x migration guide

Taurus 4 was released in July 2016 with the main goal of making Taurus scheme-agnostic (i.e. not relying on Tango for its core functionalities).

Being a major version change, it is not fully backwards-compatible with the previous taurus 3.x versions.

However, a design goal for the 4.x series was to smooth the transition from 3.x as much as possible, and a backwards-compatibility layer which will mark old taurus code as deprecated but otherwise attempt to transparently support it in Taurus4 whenever that is possible.

Thanks to this compatibility layer, a Taurus 3 application is likely to run on taurus 4 after minimal or even no changes (but typically producing deprecation warnings and possibly with some functionality slightly altered).

A good strategy for migrating a taurus 3 application or widget to taurus 4 is to attempt to run it as-is with taurus 4 and then try to remove any deprecation warnings one by one. Most changes will be related to one of the following:

- renamed methods and APIs (see the API changes section below),

- differences between Tango states and Taurus states (see the Working with States section below)

- Use of quantities for values (see the Working with quantities section below)

Note

The main sources of information regarding the changes introduced in Taurus 4 are the following two Enhancement proposals:

> - TEP3

> - TEP14

These changes are also treated in the Taurus 4 slides

## API Changes

The following is a table of Taurus 3.x public members (classes, methods, attributes, etc) that became deprecated in Taurus 4

This list is a best-effort to document changes, but it may not be 100% complete (please feel free to suggest changes)

IMPORTANT: in some cases, the proposed alternative can be used as a drop-in replacement of the deprecated code, but in some others the code may need some adaptation.

Member | Alternative(s)
--- | ---
TaurusConfigValue | TaurusAttribute / TaurusAttrValue
TaurusConfigurationProxy | TaurusAttribute
TaurusConfiguration | TaurusAttribute
Configuration (helper) | Attribute (helper)
Database (helper) | Authority (helper)
TaurusManager.{g,s}etOperationMode | –
xxxAttrValue.<foo> (where <foo> is any config option) | xxxAttribute.<foo>
xxxAttribute.value | xxxAttribute.rvalue
xxxAttribute.w_value | xxxAttribute.wvalue
xxxAttribute.has_failed | xxxAttribute.error
TangoAttribute.{g,s}etDescription | TangoAttribute.description
TangoAttribute.isInformDeviceOfErrors | –
TangoAttribute.displayValue | str
TangoAttribute.getDisplayValue | TangoAttribute.getLabel
TangoAttribute.getDisplayUnit | TangoAttribute.rvalue.units
TangoAttribute.getStandardUnit | TangoAttribute.rvalue.units
TangoAttribute.getUnit | TangoAttribute.rvalue.units
TangoAttribute.unit | TangoAttribute.rvalue.units
TangoAttribute.getDisplayWriteValue | –
TangoAttribute.getWritable | TangoAttribute.isWritable
TangoAttribute.is{Scalar,Spectrum,Image} | TangoAttribute.data_format
TangoAttribute.getMaxDim{X,Y} | TangoAttribute.getMaxDim
TangoAttribute.getShape | introspect the value shape if applicable
TangoAttribute.getParam | TangoAttribute.getAttributeInfoEx
TangoAttribute.setParam | use PyTango
TangoAttribute.getConfig | self (merged)
TangoAttribute.getCRanges | TangoAttribute .range + .alarms + .warnings
TangoAttribute.getCLimits | TangoAttribute.range
TangoAttribute.getMinValue | TangoAttribute.range
TangoAttribute.getMaxValue | TangoAttribute.range
TangoAttribute.climits | TangoAttribute.range
TangoAttribute.getCAlarms | TangoAttribute.alarms
TangoAttribute.getMinAlarm | TangoAttribute.alarms
TangoAttribute.getMaxAlarm | TangoAttribute.alarms
TangoAttribute.min_alarm | TangoAttribute.alarms
TangoAttribute.max_alarm | TangoAttribute.alarms
TangoAttribute.calarms | TangoAttribute.alarms
TangoAttribute.getCWarnings | TangoAttribute.warnings
TangoAttribute.getMinWarning | TangoAttribute.warnings
TangoAttribute.getMaxWarning | TangoAttribute.warnings
TangoAttribute.min_warning | TangoAttribute.warnings
TangoAttribute.max_warning | TangoAttribute.warnings
TangoAttribute.cwarnings | TangoAttribute.warnings
TangoDevice.getState | TangoDevice.stateObj.read().rvalue tango or .state agnostic
TangoDevice.state() PyTango.DeviceProxy API | TangoDevice.stateObj.read(cache=False).rvalue tango or .state agnostic
TangoDevice.getStateObj | TangoDevice.stateObj tango or .factory.getAttribute(state_full_name) agnostic
TangoDevice.getSWState | TangoDevice.state
TangoDevice.getValueObj | TangoDevice.stateObj.read tango or .state agnostic
TangoDevice.getDisplayValue | TangoDevice.stateObj.read().rvalue.name tango or .state.name agnostic
TangoDevice.getHWObj | TangoDevice.getDeviceProxy
TangoDevice.isValidDev | (TangoDevice.getDeviceProxy() is not None)
TangoDevice.getDescription | TangoDevice.description
TangoDatabase | TangoAuthority
TangoAuthority.getHWObj | TangoAuthority.getDeviceProxy
TangoAuthority.getValueObj | TangoAuthority.getTangoDB
TangoAuthority.getDisplayValue | TangoAuthority.getFullName
TangoAuthority.getDescription | TangoAuthority.description
TangoFactory.getAttributeInfo | TangoFactory.getAttribute
TangoFactory.getConfiguration | TangoFactory.getAttribute
TangoDevice.{g,s}etOperationMode | –

## Working with quantities

One of the most visible changes in Taurus 4 is its use of quantities for the values of numeric attributes.

In Taurus 4 all the values of numeric (float or integer) attributes and their associated properties (such as limits, warning levels, etc.) are `pint.Quantity` objects provided by the `pint` python module. A Quantity is essentially the combination of a magnitude and a unit. In taurus 3.x all values were just “magnitudes”, and their units were either implicit or loosely described as a free string property, but not enforced in any way.

By using Quantities Taurus 4 can automatically verify the dimensional validity of operations and provide support for I/O using user-preferred units.

Taurus 3 applications use .value or .w_value to get the read or write magnitude of a taurus value, respectively. In taurus 4 these would be equivalent to .rvalue.magnitude and .wvalue.magnitude, but the recommended way to adapt a Taurus 3 application is to use the Quantity objects, not their magnitudes (i.e., rvalue and wvalue) and refactor the code if necessary.

For example, given the following taurus 3 code where we assume that ampli is in meters:

    v = taurus.Attribute('sys/tg_test/1/ampli').read()
    foo = 5 + v.value  # here "5" is implicitly assumed to mean "5 meters"

a lazy conversion to avoid deprecation warnings in taurus 4 would be:

    v = taurus.Attribute('sys/tg_test/1/ampli').read()
    foo = 5 + v.rvalue.magnitude

…which is a very direct translation (and exactly what the automated backwards compatibility layer already does for you). However, the recommended conversion should use Quantities rather than magnitudes, e.g:

    from taurus.core.units import UR  # import the taurus unit registry
    v = taurus.Attribute('sys/tg_test/1/ampli').read()
    foo = 5 * UR.meters + v.value  # use explicit units

Or, using the Quantity constructor instead of the Unit Registry:

    from taurus.core.units import Q_  # import the taurus Quantity factory
    v = taurus.Attribute('sys/tg_test/1/ampli').read()
    foo = Q_("5 meters")  + v.value

Finally, note that when using Quantities, you do not need to care about matching the units, as long as they are dimensionally compatible:

    foo = Q_("15 feet") + v.value

## Working with Device states

Taurus 4 is all about being “scheme-agnostic”. This means that the taurus core (and ideally the main widgets as well) should not assume that the model objects (attributes, devices, authorities) are of one specific source type (Tango, Epics, Evaluation…)

This implies that the APIs should be scheme-agnostic. In Taurus 3, the concept of device state is completely “tango-centric” and it has been replaced in Taurus 4 by a much more generic one where the devices are either “ready” or “not ready” (this is of course much less informative, but it is generic enough to accomodate schemes where the sources of data may not even be hardware-related).

In Taurus 4, the Taurus device states are defined in the taurus.core.TaurusDevState enumeration, and the tango device states are supported by the tango scheme in taurus.core.tango.DevState enumeration, which is a numerically-compatible translation of PyTango.DevState

Some taurus 3.x applications may implement logic that depends on Tango states, or maybe display information based on the rich palette of Tango state colors. In these cases, when converting the application to Taurus 4 one needs to decide if the simple Taurus states are enough (in which case one should refactor the logic and use device.state to get the Taurus device state) or if the richer tango states are required to the point of sacrificing the scheme-agnosticism of the application (in which case one can use device.stateObj.read().rvalue to obtain the Tango device state)