Title: Use python Enum instead of taurus Enumeration
SEP: 12
State: CANDIDATE
Date: 2014-02-28
Drivers: Tiago Coutinho coutinho@esrf.fr
URL: https://sourceforge.net/p/sardana/wiki/SEP12
License: http://www.jclark.com/xml/copying.txt
Abstract:
Currently, taurus uses an internal private implementation of Enumeration.
This SEP suggests to replace the private Enumeration with the standard python Enum approved in python 3.4. Old python versions can use an official back-port.
Taurus can provide an internal implementation in case none of the previous is available.
Enums have been added to Python 3.4 (PEP 435). Official Enum implementation has lots of advantages when compared with taurus private implementation of Enumeration:
The official python enum module is only present since 3.4. Fortunately python enum has been back-ported to python >= 2.4 in a package called enum34.
Taurus code should access Enum class using the mechanism devised in [SEP11].
This mechanism will:
<if python >= 3.4> use python standard enum <elif enum34 back-port package is installed> use enum from enum34 <else> use private implementation of enum34 provided by taurus
The official back-port of enum34 is just a simple python module with the definition of the Enum
and IntEnum
classes. As a last resort (python < 3.4 and enum34 back-port not installed), taurus can provide a private implementation of enum34. Therefore, enum34 is an optional dependency of taurus.
This SEP proposes to change the internal taurus code to use the new Enum (directly or indirectly).
In order to maintain backward compatibility the taurus.core.util.enumeration
will still exist but its usage should be marked as deprecated.
These are the foreseen compatibility issues:
LockStatus["Locked"]
or LockStatus[2]
). Python Enum only supports dictionary access with key (which makes sense, of course)To solve problem 1, the SEP proposes to re-factor all calls to these methods with the python Enum equivalent code. Further, taurus enumerations that inherit from taurus.core.util.Enumeration
should inherit instead from a new taurus.core.util.Enum
which in turn inherits from enum.Enum
and implements the missing methods. This reduces the risk of backward incompatibility to a minimum.
Problem 2.1 is an improper usage of Enumeration. The SEP assumes that this specific improper usage is internal to taurus and it proposes that effort is spent to make sure this is fixed internally in taurus (Example of this improper usage in taurus.qt.qtgui.display.qled)
Problem 2.2 comes from a faulty design in the original Enumeration API. It seems to be technically impossible to simulate this behavior using the python Enum. It is actually against enumeration design to do this sort of thing. Taurus code is free from its usage so internally no change is required.
Although most enumerations are intended to be used only internally by taurus, and because of the dynamic nature of python, improper usage of taurus enumerations by third-party taurus applications can never be guaranteed. These applications, if they exist, would require changes to work with a new version of taurus. This is, in fact, a general statement that could be applied to any change in python code. This SEP considers important that it is mentioned explicitly anyway.
Copyright (c) 2014 Tiago Coutinho
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.
2014-03-05 tiagocoutinho
Changed state to CANDIDATE
2014-03-03 tiagocoutinho
Add internal implementation and backward compatibility details
2014-02-24 tiagocoutinho
Initial version
Wiki: SEP
Wiki: SEP11
Taurus: OLD Tickets: #43
Note: regarding to bck-compat:
__str__()
method should also be reimplemented to return the .name. e.g.:str(Cars.Citroen) --> 'Citroen'
(instead ofstr(Cars.Citroen) -->'Cars.Citroen')
In general, I think that all the bck-compat hacks to be implemented in taurus.core.util.Enum should be marked as deprecated, so that 3rd party code has some time to adapt, and eventually just remove the compatibility layer.