High level server API

Server helper classes for writing Tango device servers.

Device attribute command pipe

device_property class_property run() server_run()

This module provides a high level device server API. It implements TEP1. It exposes an easier API for developing a Tango device server.

Here is a simple example on how to write a Clock device server using the high level API:

import time
from tango.server import run
from tango.server import Device, DeviceMeta
from tango.server import attribute, command


class Clock(Device):
    __metaclass__ = DeviceMeta

    time = attribute()

    def read_time(self):
        return time.time()

    @command(din_type=str, dout_type=str)
    def strftime(self, format):
        return time.strftime(format)


if __name__ == "__main__":
    run((Clock,))

Here is a more complete example on how to write a PowerSupply device server using the high level API. The example contains:

1. a read-only double scalar attribute called voltage
2. a read/write double scalar expert attribute current
3. a read-only double image attribute called noise
4. a ramp command
5. a host device property
6. a port class property

from time import time
from numpy.random import random_sample

from tango import AttrQuality, AttrWriteType, DispLevel, server_run
from tango.server import Device, DeviceMeta, attribute, command
from tango.server import class_property, device_property

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    voltage = attribute()

    current = attribute(label="Current", dtype=float,
                        display_level=DispLevel.EXPERT,
                        access=AttrWriteType.READ_WRITE,
                        unit="A", format="8.4f",
                        min_value=0.0, max_value=8.5,
                        min_alarm=0.1, max_alarm=8.4,
                        min_warning=0.5, max_warning=8.0,
                        fget="get_current", fset="set_current",
                        doc="the power supply current")

    noise = attribute(label="Noise", dtype=((float,),),
                      max_dim_x=1024, max_dim_y=1024,
                      fget="get_noise")

    host = device_property(dtype=str)
    port = class_property(dtype=int, default_value=9788)

    def read_voltage(self):
        self.info_stream("get voltage(%s, %d)" % (self.host, self.port))
        return 10.0

    def get_current(self):
        return 2.3456, time(), AttrQuality.ATTR_WARNING

    def set_current(self, current):
        print("Current set to %f" % current)

    def get_noise(self):
        return random_sample((1024, 1024))

    @command(dtype_in=float)
    def ramp(self, value):
        print("Ramping up...")

if __name__ == "__main__":
    server_run((PowerSupply,))

Pretty cool, uh?

Note

the __metaclass__ statement is mandatory due to a limitation in the boost-python library used by PyTango.

If you are using python 3 you can write instead:

class PowerSupply(Device, metaclass=DeviceMeta)
    pass

Data types

When declaring attributes, properties or commands, one of the most important information is the data type. It is given by the keyword argument dtype. In order to provide a more pythonic interface, this argument is not restricted to the CmdArgType options.

For example, to define a SCALAR DevLong attribute you have several possibilities:

1. int
2. ‘int’
3. ‘int32’
4. ‘integer’
5. tango.CmdArgType.DevLong
6. ‘DevLong’
7. numpy.int32

To define a SPECTRUM attribute simply wrap the scalar data type in any python sequence:

• using a tuple: (:obj:`int`,) or
• using a list: [:obj:`int`] or
• any other sequence type

To define an IMAGE attribute simply wrap the scalar data type in any python sequence of sequences:

• using a tuple: ((:obj:`int`,),) or
• using a list: [[:obj:`int`]] or
• any other sequence type

Below is the complete table of equivalences.

dtype argument	converts to tango type
None	DevVoid
'None'	DevVoid
DevVoid	DevVoid
'DevVoid'	DevVoid
DevState	DevState
'DevState'	DevState
bool	DevBoolean
'bool'	DevBoolean
'boolean'	DevBoolean
DevBoolean	DevBoolean
'DevBoolean'	DevBoolean
numpy.bool_	DevBoolean
'char'	DevUChar
'chr'	DevUChar
'byte'	DevUChar
chr	DevUChar
DevUChar	DevUChar
'DevUChar'	DevUChar
numpy.uint8	DevUChar
'int16'	DevShort
DevShort	DevShort
'DevShort'	DevShort
numpy.int16	DevShort
'uint16'	DevUShort
DevUShort	DevUShort
'DevUShort'	DevUShort
numpy.uint16	DevUShort
int	DevLong
'int'	DevLong
'int32'	DevLong
DevLong	DevLong
'DevLong'	DevLong
numpy.int32	DevLong
'uint'	DevULong
'uint32'	DevULong
DevULong	DevULong
'DevULong'	DevULong
numpy.uint32	DevULong
'int64'	DevLong64
DevLong64	DevLong64
'DevLong64'	DevLong64
numpy.int64	DevLong64
'uint64'	DevULong64
DevULong64	DevULong64
'DevULong64'	DevULong64
numpy.uint64	DevULong64
DevInt	DevInt
'DevInt'	DevInt
'float32'	DevFloat
DevFloat	DevFloat
'DevFloat'	DevFloat
numpy.float32	DevFloat
float	DevDouble
'double'	DevDouble
'float'	DevDouble
'float64'	DevDouble
DevDouble	DevDouble
'DevDouble'	DevDouble
numpy.float64	DevDouble
str	DevString
'str'	DevString
'string'	DevString
'text'	DevString
DevString	DevString
'DevString'	DevString
bytearray	DevEncoded
'bytearray'	DevEncoded
'bytes'	DevEncoded
DevEncoded	DevEncoded
'DevEncoded'	DevEncoded
DevVarBooleanArray	DevVarBooleanArray
'DevVarBooleanArray'	DevVarBooleanArray
DevVarCharArray	DevVarCharArray
'DevVarCharArray'	DevVarCharArray
DevVarShortArray	DevVarShortArray
'DevVarShortArray'	DevVarShortArray
DevVarLongArray	DevVarLongArray
'DevVarLongArray'	DevVarLongArray
DevVarLong64Array	DevVarLong64Array
'DevVarLong64Array'	DevVarLong64Array
DevVarULong64Array	DevVarULong64Array
'DevVarULong64Array'	DevVarULong64Array
DevVarFloatArray	DevVarFloatArray
'DevVarFloatArray'	DevVarFloatArray
DevVarDoubleArray	DevVarDoubleArray
'DevVarDoubleArray'	DevVarDoubleArray
DevVarUShortArray	DevVarUShortArray
'DevVarUShortArray'	DevVarUShortArray
DevVarULongArray	DevVarULongArray
'DevVarULongArray'	DevVarULongArray
DevVarStringArray	DevVarStringArray
'DevVarStringArray'	DevVarStringArray
DevVarLongStringArray	DevVarLongStringArray
'DevVarLongStringArray'	DevVarLongStringArray
DevVarDoubleStringArray	DevVarDoubleStringArray
'DevVarDoubleStringArray'	DevVarDoubleStringArray
DevPipeBlob	DevPipeBlob
'DevPipeBlob'	DevPipeBlob

tango.server.Device

class tango.server.attribute(fget=None, **kwargs)

Declares a new tango attribute in a Device. To be used like the python native property function. For example, to declare a scalar, tango.DevDouble, read-only attribute called voltage in a PowerSupply Device do:

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    voltage = attribute()

    def read_voltage(self):
        return 999.999

The same can be achieved with:

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    @attribute
    def voltage(self):
        return 999.999

It receives multiple keyword arguments.

parameter	type	default value	description
name	str	class member name	alternative attribute name
dtype	object	DevDouble	data type (see Data type equivalence)
dformat	AttrDataFormat	SCALAR	data format
max_dim_x	int	1	maximum size for x dimension (ignored for SCALAR format)
max_dim_y	int	0	maximum size for y dimension (ignored for SCALAR and SPECTRUM formats)
display_level	DispLevel	OPERATOR	display level
polling_period	int	-1	polling period
memorized	bool	False	attribute should or not be memorized
hw_memorized	bool	False	write method should be called at startup when restoring memorize value (dangerous!)
access	AttrWriteType	READ	read only/ read write / write only access
fget (or fread)	str or callable	‘read_<attr_name>’	read method name or method object
fset (or fwrite)	str or callable	‘write_<attr_name>’	write method name or method object
is_allowed	str or callable	‘is_<attr_name>_allowed’	is allowed method name or method object
label	str	‘<attr_name>’	attribute label
enum_labels	sequence	None	the list of enumeration labels (enum data type)
doc (or description)	str	‘’	attribute description
unit	str	‘’	physical units the attribute value is in
standard_unit	str	‘’	physical standard unit
display_unit	str	‘’	physical display unit (hint for clients)
format	str	‘6.2f’	attribute representation format
min_value	str	None	minimum allowed value
max_value	str	None	maximum allowed value
min_alarm	str	None	minimum value to trigger attribute alarm
max_alarm	str	None	maximum value to trigger attribute alarm
min_warning	str	None	minimum value to trigger attribute warning
max_warning	str	None	maximum value to trigger attribute warning
delta_val	str	None
delta_t	str	None
abs_change	str	None	minimum value change between events that causes event filter to send the event
rel_change	str	None	minimum relative change between events that causes event filter to send the event (%)
period	str	None
archive_abs_change	str	None
archive_rel_change	str	None
archive_period	str	None
green_mode	GreenMode	None	green mode for read and write. None means use server green mode.
read_green_mode	GreenMode	None	green mode for read. None means use server green mode.
write_green_mode	GreenMode	None	green mode for write. None means use server green mode.

Note

avoid using dformat parameter. If you need a SPECTRUM attribute of say, boolean type, use instead dtype=(bool,).

Example of a integer writable attribute with a customized label, unit and description:

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    current = attribute(label="Current", unit="mA", dtype=int,
                        access=AttrWriteType.READ_WRITE,
                        doc="the power supply current")

    def init_device(self):
        Device.init_device(self)
        self._current = -1

    def read_current(self):
        return self._current

    def write_current(self, current):
        self._current = current

The same, but using attribute as a decorator:

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    def init_device(self):
        Device.init_device(self)
        self._current = -1

    @attribute(label="Current", unit="mA", dtype=int)
    def current(self):
        """the power supply current"""
        return 999.999

    @current.write
    def current(self, current):
        self._current = current

In this second format, defining the write implicitly sets the attribute access to READ_WRITE.

New in version 8.1.7: added green_mode, read_green_mode and write_green_mode options

tango.server.command(f=None, dtype_in=None, dformat_in=None, doc_in='', dtype_out=None, dformat_out=None, doc_out='', display_level=None, polling_period=None, green_mode=None)

Declares a new tango command in a Device. To be used like a decorator in the methods you want to declare as tango commands. The following example declares commands:

• void TurnOn(void)
• void Ramp(DevDouble current)
• DevBool Pressurize(DevDouble pressure)

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    @command
    def TurnOn(self):
        self.info_stream('Turning on the power supply')

    @command(dtype_in=float)
    def Ramp(self, current):
        self.info_stream('Ramping on %f...' % current)

    @command(dtype_in=float, doc_in='the pressure to be set',
             dtype_out=bool, doc_out='True if it worked, False otherwise')
    def Pressurize(self, pressure):
        self.info_stream('Pressurizing to %f...' % pressure)
        return True

Note

avoid using dformat parameter. If you need a SPECTRUM attribute of say, boolean type, use instead dtype=(bool,).

Parameters:

• dtype_in – a data type describing the type of parameter. Default is None meaning no parameter.
• dformat_in (AttrDataFormat) – parameter data format. Default is None.
• doc_in (str) – parameter documentation
• dtype_out – a data type describing the type of return value. Default is None meaning no return value.
• dformat_out (AttrDataFormat) – return value data format. Default is None.
• doc_out (str) – return value documentation
• display_level (DispLevel) – display level for the command (optional)
• polling_period (int) – polling period in milliseconds (optional)
• green_mode – set green mode on this specific command. Default value is None meaning use the server green mode. Set it to GreenMode.Synchronous to force a non green command in a green server.

New in version 8.1.7: added green_mode option

New in version 9.2.0: added display_level and polling_period optional argument

class tango.server.pipe(fget=None, **kwargs)

Declares a new tango pipe in a Device. To be used like the python native property function.

Checkout the pipe data types to see what you should return on a pipe read request and what to expect as argument on a pipe write request.

For example, to declare a read-only pipe called ROI (for Region Of Interest), in a Detector Device do:

class Detector(Device):
    __metaclass__ = DeviceMeta

    ROI = pipe()

    def read_ROI(self):
        return ('ROI', ({'name': 'x', 'value': 0},
                        {'name': 'y', 'value': 10},
                        {'name': 'width', 'value': 100},
                        {'name': 'height', 'value': 200}))

The same can be achieved with (also showing that a dict can be used to pass blob data):

class Detector(Device):
    __metaclass__ = DeviceMeta

    @pipe
    def ROI(self):
        return 'ROI', dict(x=0, y=10, width=100, height=200)

It receives multiple keyword arguments.

parameter	type	default value	description
name	str	class member name	alternative pipe name
display_level	DispLevel	OPERATOR	display level
access	PipeWriteType	READ	read only/ read write access
fget (or fread)	str or callable	‘read_<pipe_name>’	read method name or method object
fset (or fwrite)	str or callable	‘write_<pipe_name>’	write method name or method object
is_allowed	str or callable	‘is_<pipe_name>_allowed’	is allowed method name or method object
label	str	‘<pipe_name>’	pipe label
doc (or description)	str	‘’	pipe description
green_mode	GreenMode	None	green mode for read and write. None means use server green mode.
read_green_mode	GreenMode	None	green mode for read. None means use server green mode.
write_green_mode	GreenMode	None	green mode for write. None means use server green mode.

The same example with a read-write ROI, a customized label and description:

class Detector(Device):
    __metaclass__ = DeviceMeta

    ROI = pipe(label='Region Of Interest', doc='The active region of interest',
               access=PipeWriteType.PIPE_READ_WRITE)

    def init_device(self):
        Device.init_device(self)
        self.__roi = 'ROI', dict(x=0, y=10, width=100, height=200)

    def read_ROI(self):
        return self.__roi

    def write_ROI(self, roi):
        self.__roi = roi

The same, but using pipe as a decorator:

class Detector(Device):
    __metaclass__ = DeviceMeta

    def init_device(self):
        Device.init_device(self)
        self.__roi = 'ROI', dict(x=0, y=10, width=100, height=200)

    @pipe(label="Region Of Interest")
    def ROI(self):
        """The active region of interest"""
        return self.__roi

    @ROI.write
    def ROI(self, roi):
        self.__roi = roi

In this second format, defining the write / setter implicitly sets the pipe access to READ_WRITE.

New in version 9.2.0.

class tango.server.device_property(dtype, doc='', default_value=None, update_db=False)

Declares a new tango device property in a Device. To be used like the python native property function. For example, to declare a scalar, tango.DevString, device property called host in a PowerSupply Device do:

from tango.server import Device, DeviceMeta
from tango.server import device_property

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    host = device_property(dtype=str)

Parameters:

• dtype – Data type (see Data types)
• doc – property documentation (optional)
• default_value – default value for the property (optional)
• update_db (bool) – tells if set value should write the value to database. [default: False]

New in version 8.1.7: added update_db option

class tango.server.class_property(dtype, doc='', default_value=None, update_db=False)

Declares a new tango class property in a Device. To be used like the python native property function. For example, to declare a scalar, tango.DevString, class property called port in a PowerSupply Device do:

from tango.server import Device, DeviceMeta
from tango.server import class_property

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

    port = class_property(dtype=int, default_value=9788)

Parameters:

• dtype – Data type (see Data types)
• doc – property documentation (optional)
• default_value – default value for the property (optional)
• update_db (bool) – tells if set value should write the value to database. [default: False]

New in version 8.1.7: added update_db option

tango.server.run(classes, args=None, msg_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, verbose=False, util=None, event_loop=None, post_init_callback=None, green_mode=None)

Provides a simple way to run a tango server. It handles exceptions by writting a message to the msg_stream.

The classes parameter can be either a sequence of:

• : class:~tango.server.Device or
• a sequence of two elements DeviceClass, DeviceImpl or
• a sequence of three elements DeviceClass, DeviceImpl, tango class name (str)

or a dictionary where:

• key is the tango class name

• value is either:

  • a : class:~tango.server.Device class or
  • a sequence of two elements DeviceClass, DeviceImpl or
  • a sequence of three elements DeviceClass, DeviceImpl, tango class name (str)

The optional post_init_callback can be a callable (without arguments) or a tuple where the first element is the callable, the second is a list of arguments (optional) and the third is a dictionary of keyword arguments (also optional).

Note

the order of registration of tango classes defines the order tango uses to initialize the corresponding devices. if using a dictionary as argument for classes be aware that the order of registration becomes arbitrary. If you need a predefined order use a sequence or an OrderedDict.

Example 1: registering and running a PowerSupply inheriting from Device:

from tango.server import Device, DeviceMeta, run

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

run((PowerSupply,))

Example 2: registering and running a MyServer defined by tango classes MyServerClass and MyServer:

from tango import Device_4Impl, DeviceClass
from tango.server import run

class MyServer(Device_4Impl):
    pass

class MyServerClass(DeviceClass):
    pass

run({'MyServer': (MyServerClass, MyServer)})

Example 3: registering and running a MyServer defined by tango classes MyServerClass and MyServer:

from tango import Device_4Impl, DeviceClass
from tango.server import Device, DeviceMeta, run

class PowerSupply(Device):
    __metaclass__ = DeviceMeta

class MyServer(Device_4Impl):
    pass

class MyServerClass(DeviceClass):
    pass

run([PowerSupply, [MyServerClass, MyServer]])
# or: run({'MyServer': (MyServerClass, MyServer)})

Parameters:

• classes (sequence or dict) – a sequence of Device classes or a dictionary where keyword is the tango class name and value is a sequence of Tango Device Class python class, and Tango Device python class
• args (list) – list of command line arguments [default: None, meaning use sys.argv]
• msg_stream – stream where to put messages [default: sys.stdout]
• util (Util) – PyTango Util object [default: None meaning create a Util instance]
• event_loop (callable) – event_loop callable
• post_init_callback (callable or tuple (see description above)) – an optional callback that is executed between the calls Util.server_init and Util.server_run

Returns:

The Util singleton object

Return type:

Util

New in version 8.1.2.

Changed in version 8.1.4: when classes argument is a sequence, the items can also be a sequence <TangoClass, TangoClassClass>[, tango class name]

tango.server.server_run(classes, args=None, msg_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, verbose=False, util=None, event_loop=None, post_init_callback=None, green_mode=None)

Since PyTango 8.1.2 it is just an alias to run(). Use run() instead.

New in version 8.0.0.

Changed in version 8.0.3: Added util keyword parameter. Returns util object

Changed in version 8.1.1: Changed default msg_stream from stderr to stdout Added event_loop keyword parameter. Returns util object

Changed in version 8.1.2: Added post_init_callback keyword parameter

Deprecated since version 8.1.2: Use run() instead.