Title: core refactoring (quantities and configuration)
TEP: 14
State: ACCEPTED
Date: 2016-03-16
Drivers: Carlos Pascual-Izarra cpascual@cells.es, Carlos Falcon-Torres cfalcon@cells.es
URL: https://sourceforge.net/p/tauruslib/wiki/TEP14
License: http://www.jclark.com/xml/copying.txt
Abstract:
This proposal picks the tango.core refactoring from TEP3 and takes it a step further. While TEP3 eliminates the PyTango module dependencies, this TEP aims to get rid some of the most evident "tangoisms" still left in the code by TEP3. Among other things it implements support for Quantities and eliminates the attribute configuration classes
This TEP is a spin-off of [TEP3]. It proposes a refactoring of taurus.core to get rid of some tango-centric implementation details that were left by [TEP3]. The objective is to obtain a cleaner and more scheme-agnostic API for creation of new schemes. Several inter-related aspects of the taurus core are refactored:
An explicit objective of this TEP is to provide as much backwards-compatibility as possible. Some of the changes unavoidably break the backwards compatibility, but, whenever it is possible, a compatibility API is left in place which uses the new deprecation mechanisms to inform the developers of the new recommended alternative.
One of the main changes of this TEP involves the removal of the xxxConfiguration,
and xxxConfigurationValue classes, and their role being taken by xxxAttribute.
The resulting class relationships is then simplified, as seen in the following figure:
From the point of view of application code (e.g. widgets), this implies that:
Previous to this proposal, the API for xxxAttribute and xxxAttributeValue (as well the configuration API) was not defined, and the tango scheme was used as a loose reference by other schemes.
This proposal defines, via the TaurusAttributeValue and TaurusAttribute classes, a base API for all schemes to use, so that it can be relied upon when writing scheme-agnostic code.
Apart of defining standard members for common concepts (e.g. "range" for the min,max
tuple in which a value can vary), the types allowed for these members are also restricted by this TEP:
taurus.external.pint
module). Note that Quantity objects allow for both scalar and non-scalar magnitudes to be represented. See table below.from taurus.external.enum
(preferred) or Enumeration from (taurus.core.util.enumeration
)Schemes must use encode/decode methods to ensure that the common API is respected even if the scheme internally uses scheme-specific types. Of course, it is allowed for a scheme to extend the API with its own scheme-specific members which would not be subject to the rules defined here, but it should be kept in mind that those extensions will not be usable by scheme-agnostic code.
The following table summarizes the allowed types for the read/write values, limits, etc. depending on the type and format of the attribute:
DataType | _0D | _1D | _2D |
---|---|---|---|
Boolean | bool | ndarray<bool> | ndarray<bool> |
Integer, Float | Quantity | Quantity | Quantity |
String | str | seq<str> | seq<seq<str>> |
Bytes | bytes |
Some important remarks:
numpy.ndarray
imposes fixed lengths of its items. Instead, for strings we recomend using (nested) lists of str
.As explained before, the information previously available via the xxxConfiguration API is now part of the xxxAttribute scheme-agnostic API. However in order to avoid using tango-centric enumerations/concepts the new API relies on newly defined enumerations and/or standard python objects for some information that was previously encoded with tango-centric types:
PyTango.AttrDataFormat
, the dimensionality of a given attribute is now described by the taurus.DataFormat
enumeration, which currently defines _0D
, _1D
, and _2D
, corresponding to the scalars, spectrum and image types of Tango, respectively. More formats may eventually be added if support for them is introduced in taurus.PyTango.CmdArgType
, the data type of a given attribute is now described by the taurus.DataType
enumeration, which currently defines Boolean
, Integer
, Float
, String
and Bytes
types (plus some other deprecated types as well as a type for opaque objects). A map of Tango to Taurus data types can be found in taurus.core.tango.util.tango_taurus.FROM_TANGO_TO_TAURUS_TYPE
taurus.AttrQuality
enumeration instead of the PyTango.AttrQuality
PyTango.AttrWriteType
) is now described by a boolean stored in the writable
attribute/property of a xxxAttribute.Just as for xxxAttribute, this proposal defines, via the TaurusDevice class, a base API for all schemes to use, so that it can be relied upon when writing scheme-agnostic code.
Previous to this proposal the xxxDevice objects were heavily influenced by the TangoDevice implementation. In particular the concept of a "device state" was linked to the tango-centric assumption that all xxxDevices had at least one associated xxxAttribute called "state", which reflected the device's state using the PyTango.DevState
. Also, other tango-influenced enumerations were used by Taurus in relation to the state of the connection state/health of a device (TaurusDevSWState
, TaurusDevSWHealth
)
This TEP avoids those tango-specific assumptions and defines a simpler (albeit less informative) API for dealing with the device state: now "state" is an attribute/property of the xxxDevice which uses the taurus.TaurusDevState
enumeration to describe the device state in a scheme-agnostic way.
Note that each scheme is still alowed to provide its own specific API to handle richer state information but, of course, it will not be used by scheme-agnostic code (e.g., in a tango-specific context one could still get PyTango.DevState info by using TangoDevice.stateObj.read()
).
Note that this change is one of the possible sources of unavoidable backwards incompatibilities introduced by this TEP.
The concept of "Authority" models type was already introduced in [TEP3] to generalise the tango-centric "Database". This TEP defines a base API for xxxAuthority via the TaurusAuthority base class. This is the api that scheme-agnostic code can use for dealing with Authority models.
Since [TEP3], the concept of "URI fragments" was introduced in the model names (a model name may contain a "#" symbol followed by a fragment name). In TEP3 only a limited use was done of this syntax. This proposal generalises it:
For example, "tango:a/b/c/d" refers to the TangoAttribute object (which is a subclass of TaurusModel) representing the "a/b/c/d" Tango attribute, and "tango:a/b/c/d#label" refers to the object's "label" attribute.
It is important to note that the fragment name is not a part of the model name. In the Model-View-Controller pattern used in Taurus, the fragment name is only known by the view/controller parts, but not by the model.
Certain fragment names may be reserved in some or all model types to provide a common scheme-agnostic API (e.g., widgets will expect that suffixing "#label" to any attribute name will be interpreted as a reference to the "label" of the attribute).
Other fragment names may be used to access scheme-specific members of the given model object. For example, this will allow TaurusCommand button (which is for now actually a Tango-specific widget) to refer to methods of the TangoDevice object which execute Tango commands (it is easy to imagine that this could open the door to supporting the concept of "Taurus commands" in general).
Currently, the list of reserved fragment names corresponds to the public properties/attributes of the base model classes (TaurusAttribute, TaurusDevice, TaurusFactory):
Finally, note that dot-syntax is supported by the fragment mechanism: e.g. on can refer to the units of the read value of the "a/b/c/d" tango attribute using "tango:a/b/c/d#rvalue.units"
The deprecations introduced by this proposal can be identified in the code by the use of the @tep14_deprecation
decorator and the calls to the deprecated
function with the rel='tep14'
argument.
The [Taurus4-API_changes] document is an attempt to explicitly list all the changes (it is not considered part of this TEP because it is likely to be modified to include more comments or missing changes)
The proposed implementation was done for the most part internally at the ALBA synchrotron and therefore most of the discussion took place either offline or with internal mechanisms for which unfortunately no external access is available.
Some discussions/announcements about TEP14 were held on the tauruslib-devel and taurus-user mailing list:
A proposal of implementation was pushed to the taurus4-preview
branch at the official repository.
The mentioned branch also includes changes belonging to [TEP3], since that is the starting implementation point for TEP14. It also includes the minimal necessary changes in Taurus widgets in order for them to work with the changes of the core due to TEP14 (note that these changes in widgets are technically out of the scope of TEP14, but they are convenient in order to properly evaluate the implementation proposal).
Apart of the minimal changes just mentioned, the taurus widgets require further changes in order to take advantage of the new features provided by this TEP (e.g., plots currently use only the magnitude information from their model values, when they should use the units info as well). Another TEP (or feature-request-driven development) should be started for that.
The following copyright statement and license apply to SEP3 (this
document).
Copyright (c) 2015 CELLS / ALBA Synchrotron, Bellaterra, Spain
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
2015-04-28
cpascual First draft based on parts moved from [TEP3] and previous discussions with tiagocoutinho, cfalcon and zreszela
2015-11-23
cpascual Implementation proposal uploaded to taurus4-preview branch of official repo
2016-03-11
cpascual Completed missing sections, rewritted existing ones and passed to CANDIDATE
2016-03-16
cpascual Passing to ACCEPTED
Sardana: OLD Tickets: #452
Sardana: Wiki: SEP3
Wiki: TEP3
Wiki: Taurus4-API_changes
Wiki: priorities-may2015