High level server API

Server helper classes for writing Tango device servers.

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
from tango.server import attribute, command


class Clock(Device):

    time = attribute()

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

    @command(dtype_in=str, dtype_out=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

 1from time import time
 2from numpy.random import random_sample
 3
 4from tango import AttrQuality, AttrWriteType, DispLevel
 5from tango.server import Device, attribute, command
 6from tango.server import class_property, device_property
 7
 8class PowerSupply(Device):
 9
10    voltage = attribute()
11
12    current = attribute(label="Current", dtype=float,
13                        display_level=DispLevel.EXPERT,
14                        access=AttrWriteType.READ_WRITE,
15                        unit="A", format="8.4f",
16                        min_value=0.0, max_value=8.5,
17                        min_alarm=0.1, max_alarm=8.4,
18                        min_warning=0.5, max_warning=8.0,
19                        fget="get_current", fset="set_current",
20                        doc="the power supply current")
21
22    noise = attribute(label="Noise", dtype=((float,),),
23                      max_dim_x=1024, max_dim_y=1024,
24                      fget="get_noise")
25
26    host = device_property(dtype=str)
27    port = class_property(dtype=int, default_value=9788)
28
29    def read_voltage(self):
30        self.info_stream("get voltage(%s, %d)" % (self.host, self.port))
31        return 10.0
32
33    def get_current(self):
34        return 2.3456, time(), AttrQuality.ATTR_WARNING
35
36    def set_current(self, current):
37        print("Current set to %f" % current)
38
39    def get_noise(self):
40        return random_sample((1024, 1024))
41
42    @command(dtype_in=float)
43    def ramp(self, value):
44        print("Ramping up...")
45
46if __name__ == "__main__":
47    PowerSupply.run_server()

Pretty cool, uh?

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. ‘int64’

  4. tango.CmdArgType.DevLong64

  5. ‘DevLong64’

  6. numpy.int64

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

'int32'

DevLong

DevLong

DevLong

'DevLong'

DevLong

numpy.int32

DevLong

'uint32'

DevULong

DevULong

DevULong

'DevULong'

DevULong

numpy.uint32

DevULong

int

DevLong64

'int'

DevLong64

'int64'

DevLong64

DevLong64

DevLong64

'DevLong64'

DevLong64

numpy.int64

DevLong64

'uint'

DevULong64

'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

class tango.server.Device(cl, name)

Bases: tango.server.BaseDevice

Device class for the high-level API.

All device specific classes should inherit from this class.

add_attribute(self, attr, r_meth=None, w_meth=None, is_allo_meth=None) Attr

Add a new attribute to the device attribute list.

Please, note that if you add an attribute to a device at device creation time, this attribute will be added to the device class attribute list. Therefore, all devices belonging to the same class created after this attribute addition will also have this attribute.

Parameters
  • attr (Attr or AttrData) – the new attribute to be added to the list.

  • r_meth (callable) – the read method to be called on a read request

  • w_meth (callable) – the write method to be called on a write request (if attr is writable)

  • is_allo_meth (callable) – the method that is called to check if it is possible to access the attribute or not

Returns

the newly created attribute.

Return type

Attr

Raises

DevFailed

add_command(self, cmd, device_level=True) cmd

Add a new command to the device command list.

Parameters
  • cmd – the new command to be added to the list

  • device_level – Set this flag to true if the command must be added for only this device

Returns

The command to add

Return type

Command

Raises

DevFailed

always_executed_hook()

Tango always_executed_hook. Default implementation does nothing

append_status(self, status, new_line=False)

Appends a string to the device status.

Parameters
  • status (str) – the string to be appened to the device status

  • new_line (bool) – If true, appends a new line character before the string. Default is False

check_command_exists(self)

Check that a command is supported by the device and does not need input value.

The method throws an exception if the command is not defined or needs an input value.

Parameters

cmd_name (str) – the command name

Raises
  • DevFailed

  • API_IncompatibleCmdArgumentType

  • API_CommandNotFound

New in PyTango 7.1.2

debug_stream(self, msg, *args)

Sends the given message to the tango debug stream.

Since PyTango 7.1.3, the same can be achieved with:

print(msg, file=self.log_debug)
Parameters

msg (str) – the message to be sent to the debug stream

delete_device(self)

Delete the device.

dev_state(self) DevState

Get device state.

Default method to get device state. The behaviour of this method depends on the device state. If the device state is ON or ALARM, it reads the attribute(s) with an alarm level defined, check if the read value is above/below the alarm and eventually change the state to ALARM, return the device state. For all th other device state, this method simply returns the state This method can be redefined in sub-classes in case of the default behaviour does not fullfill the needs.

Returns

the device state

Return type

DevState

Raises

DevFailed – If it is necessary to read attribute(s) and a problem occurs during the reading

dev_status(self) str

Get device status.

Default method to get device status. It returns the contents of the device dev_status field. If the device state is ALARM, alarm messages are added to the device status. This method can be redefined in sub-classes in case of the default behaviour does not fullfill the needs.

Returns

the device status

Return type

str

Raises

DevFailed – If it is necessary to read attribute(s) and a problem occurs during the reading

error_stream(self, msg, *args)

Sends the given message to the tango error stream.

Since PyTango 7.1.3, the same can be achieved with:

print(msg, file=self.log_error)
Parameters

msg (str) – the message to be sent to the error stream

fatal_stream(self, msg, *args)

Sends the given message to the tango fatal stream.

Since PyTango 7.1.3, the same can be achieved with:

print(msg, file=self.log_fatal)
Parameters

msg (str) – the message to be sent to the fatal stream

get_attr_min_poll_period(self) Sequence[str]

Returns the min attribute poll period

Returns

the min attribute poll period

Return type

Sequence[str]

New in PyTango 7.2.0

get_attr_poll_ring_depth(self, attr_name) int

Returns the attribute poll ring depth.

Parameters

attr_name (str) – the attribute name

Returns

the attribute poll ring depth

Return type

int

New in PyTango 7.1.2

get_attribute_config(self, attr_names) list[DeviceAttributeConfig]

Returns the list of AttributeConfig for the requested names

Parameters

attr_names (list[str]) – sequence of str with attribute names

Returns

tango.DeviceAttributeConfig for each requested attribute name

Return type

list[tango.DeviceAttributeConfig]

get_attribute_config_2(self, attr_names) list[AttributeConfig_2]

Returns the list of AttributeConfig_2 for the requested names

Parameters

attr_names (list[str]) – sequence of str with attribute names

Returns

list of tango.AttributeConfig_2 for each requested attribute name

Return type

list[tango.AttributeConfig_2]

get_attribute_config_3(self, attr_name) list[AttributeConfig_3]

Returns the list of AttributeConfig_3 for the requested names

Parameters

attr_names (list[str]) – sequence of str with attribute names

Returns

list of tango.AttributeConfig_3 for each requested attribute name

Return type

list[tango.AttributeConfig_3]

get_attribute_poll_period(self, attr_name) int

Returns the attribute polling period (ms) or 0 if the attribute is not polled.

Parameters

attr_name (str) – attribute name

Returns

attribute polling period (ms) or 0 if it is not polled

Return type

int

New in PyTango 8.0.0

get_cmd_min_poll_period(self) Sequence[str]

Returns the min command poll period.

Returns

the min command poll period

Return type

Sequence[str]

New in PyTango 7.2.0

get_cmd_poll_ring_depth(self, cmd_name) int

Returns the command poll ring depth.

Parameters

cmd_name (str) – the command name

Returns

the command poll ring depth

Return type

int

New in PyTango 7.1.2

get_command_poll_period(self, cmd_name) int

Returns the command polling period (ms) or 0 if the command is not polled.

Parameters

cmd_name (str) – command name

Returns

command polling period (ms) or 0 if it is not polled

Return type

int

New in PyTango 8.0.0

get_dev_idl_version(self) int

Returns the IDL version.

Returns

the IDL version

Return type

int

New in PyTango 7.1.2

get_device_attr(self) MultiAttribute

Get device multi attribute object.

Returns

the device’s MultiAttribute object

Return type

MultiAttribute

get_device_class(self)

Get device class singleton.

Returns

the device class singleton (device_class field)

Return type

DeviceClass

get_device_properties(self, ds_class=None)

Utility method that fetches all the device properties from the database and converts them into members of this DeviceImpl.

Parameters

ds_class (DeviceClass) – the DeviceClass object. Optional. Default value is None meaning that the corresponding DeviceClass object for this DeviceImpl will be used

Raises

DevFailed

get_exported_flag(self) bool

Returns the state of the exported flag

Returns

the state of the exported flag

Return type

bool

New in PyTango 7.1.2

get_logger(self) Logger

Returns the Logger object for this device

Returns

the Logger object for this device

Return type

Logger

get_min_poll_period(self) int

Returns the min poll period.

Returns

the min poll period

Return type

int

New in PyTango 7.2.0

get_name(self)

Get a COPY of the device name.

Returns

the device name

Return type

str

get_non_auto_polled_attr(self) Sequence[str]

Returns a COPY of the list of non automatic polled attributes

Returns

a COPY of the list of non automatic polled attributes

Return type

Sequence[str]

New in PyTango 7.1.2

get_non_auto_polled_cmd(self) Sequence[str]

Returns a COPY of the list of non automatic polled commands

Returns

a COPY of the list of non automatic polled commands

Return type

Sequence[str]

New in PyTango 7.1.2

get_poll_old_factor(self) int

Returns the poll old factor

Returns

the poll old factor

Return type

int

New in PyTango 7.1.2

get_poll_ring_depth(self) int

Returns the poll ring depth

Returns

the poll ring depth

Return type

int

New in PyTango 7.1.2

get_polled_attr(self) Sequence[str]

Returns a COPY of the list of polled attributes

Returns

a COPY of the list of polled attributes

Return type

Sequence[str]

New in PyTango 7.1.2

get_polled_cmd(self) Sequence[str]

Returns a COPY of the list of polled commands

Returns

a COPY of the list of polled commands

Return type

Sequence[str]

New in PyTango 7.1.2

get_prev_state(self) DevState

Get a COPY of the device’s previous state.

Returns

the device’s previous state

Return type

DevState

get_state(self) DevState

Get a COPY of the device state.

Returns

Current device state

Return type

DevState

get_status(self) str

Get a COPY of the device status.

Returns

the device status

Return type

str

info_stream(self, msg, *args)

Sends the given message to the tango info stream.

Since PyTango 7.1.3, the same can be achieved with:

print(msg, file=self.log_info)
Parameters

msg (str) – the message to be sent to the info stream

init_device()

Tango init_device method. Default implementation calls get_device_properties()

init_logger(self) None

Setups logger for the device. Called automatically when device starts.

initialize_dynamic_attributes()

Method executed at initializion phase to create dynamic attributes. Default implementation does nothing. Overwrite when necessary.

is_attribute_polled(self, attr_name) bool

True if the attribute is polled.

Parameters

attr_name (str) – attribute name

Returns

True if the attribute is polled

Return type

bool

is_command_polled(self, cmd_name) bool

True if the command is polled.

Parameters

cmd_name (str) – attribute name

Returns

True if the command is polled

Return type

bool

is_device_locked(self) bool

Returns if this device is locked by a client.

Returns

True if it is locked or False otherwise

Return type

bool

New in PyTango 7.1.2

is_polled(self) bool

Returns if it is polled

Returns

True if it is polled or False otherwise

Return type

bool

New in PyTango 7.1.2

is_there_subscriber(self, att_name, event_type) bool

Check if there is subscriber(s) listening for the event.

This method returns a boolean set to true if there are some subscriber(s) listening on the event specified by the two method arguments. Be aware that there is some delay (up to 600 sec) between this method returning false and the last subscriber unsubscription or crash…

The device interface change event is not supported by this method.

Parameters
  • att_name (str) – the attribute name

  • event_type (EventType) – the event type

Returns

True if there is at least one listener or False otherwise

Return type

bool

poll_attribute(self, attr_name, period) None

Add an attribute to the list of polled attributes.

Parameters
  • attr_name (str) – attribute name

  • period (int) – polling period in milliseconds

Returns

None

Return type

None

poll_command(self, cmd_name, period) None

Add a command to the list of polled commands.

Parameters
  • cmd_name (str) – attribute name

  • period (int) – polling period in milliseconds

Returns

None

Return type

None

push_archive_event(self, attr_name)
push_archive_event(self, attr_name, except)
push_archive_event(self, attr_name, data, dim_x=1, dim_y=0)
push_archive_event(self, attr_name, str_data, data)
push_archive_event(self, attr_name, data, time_stamp, quality, dim_x=1, dim_y=0)
push_archive_event(self, attr_name, str_data, data, time_stamp, quality)

Push an archive event for the given attribute name.

The event is pushed to the notification daemon.

Parameters
  • attr_name (str) – attribute name

  • data – the data to be sent as attribute event data. Data must be compatible with the attribute type and format. for SPECTRUM and IMAGE attributes, data can be any type of sequence of elements compatible with the attribute type

  • str_data (str) – special variation for DevEncoded data type. In this case ‘data’ must be a str or an object with the buffer interface.

  • except (DevFailed) – Instead of data, you may want to send an exception.

  • dim_x (int) – the attribute x length. Default value is 1

  • dim_y (int) – the attribute y length. Default value is 0

  • time_stamp (double) – the time stamp

  • quality (AttrQuality) – the attribute quality factor

Raises

DevFailed – If the attribute data type is not coherent.

push_att_conf_event(self, attr)

Push an attribute configuration event.

Parameters

attr (Attribute) – the attribute for which the configuration event will be sent.

New in PyTango 7.2.1

push_change_event(self, attr_name)
push_change_event(self, attr_name, except)
push_change_event(self, attr_name, data, dim_x=1, dim_y=0)
push_change_event(self, attr_name, str_data, data)
push_change_event(self, attr_name, data, time_stamp, quality, dim_x=1, dim_y=0)
push_change_event(self, attr_name, str_data, data, time_stamp, quality)

Push a change event for the given attribute name.

The event is pushed to the notification daemon.

Parameters
  • attr_name (str) – attribute name

  • data – the data to be sent as attribute event data. Data must be compatible with the attribute type and format. for SPECTRUM and IMAGE attributes, data can be any type of sequence of elements compatible with the attribute type

  • str_data (str) – special variation for DevEncoded data type. In this case ‘data’ must be a str or an object with the buffer interface.

  • except (DevFailed) – Instead of data, you may want to send an exception.

  • dim_x (int) – the attribute x length. Default value is 1

  • dim_y (int) – the attribute y length. Default value is 0

  • time_stamp (double) – the time stamp

  • quality (AttrQuality) – the attribute quality factor

Raises

DevFailed – If the attribute data type is not coherent.

push_data_ready_event(self, attr_name, counter=0)

Push a data ready event for the given attribute name.

The event is pushed to the notification daemon.

The method needs only the attribue name and an optional “counter” which will be passed unchanged within the event

Parameters
  • attr_name (str) – attribute name

  • counter (int) – the user counter

Raises

DevFailed – If the attribute name is unknown.

push_event(self, attr_name, filt_names, filt_vals)
push_event(self, attr_name, filt_names, filt_vals, data, dim_x=1, dim_y=0)
push_event(self, attr_name, filt_names, filt_vals, str_data, data)
push_event(self, attr_name, filt_names, filt_vals, data, time_stamp, quality, dim_x=1, dim_y=0)
push_event(self, attr_name, filt_names, filt_vals, str_data, data, time_stamp, quality)

Push a user event for the given attribute name.

The event is pushed to the notification daemon.

Parameters
  • attr_name (str) – attribute name

  • filt_names (Sequence[str]) – the filterable fields name

  • filt_vals (Sequence[double]) – the filterable fields value

  • data – the data to be sent as attribute event data. Data must be compatible with the attribute type and format. for SPECTRUM and IMAGE attributes, data can be any type of sequence of elements compatible with the attribute type

  • str_data (str) – special variation for DevEncoded data type. In this case ‘data’ must be a str or an object with the buffer interface.

  • dim_x (int) – the attribute x length. Default value is 1

  • dim_y (int) – the attribute y length. Default value is 0

  • time_stamp (double) – the time stamp

  • quality (AttrQuality) – the attribute quality factor

Raises

DevFailed – If the attribute data type is not coherent.

push_pipe_event(self, blob)

Push an pipe event.

Parameters

blob – the blob which pipe event will be send.

New in PyTango 9.2.2

read_attr_hardware(self, attr_list)

Read the hardware to return attribute value(s).

Default method to implement an action necessary on a device to read the hardware involved in a read attribute CORBA call. This method must be redefined in sub-classes in order to support attribute reading

Parameters

attr_list (Sequence[int]) – list of indices in the device object attribute vector of an attribute to be read.

Raises

DevFailed – This method does not throw exception but a redefined method can.

register_signal(self, signo)

Register a signal.

Register this device as device to be informed when signal signo is sent to to the device server process

Parameters

signo (int) – signal identifier

remove_attribute(self, attr_name)

Remove one attribute from the device attribute list.

Parameters

attr_name (str) – attribute name

Raises

DevFailed

remove_command(self, attr_name)

Remove one command from the device command list.

Parameters
  • cmd_name (str) – command name to be removed from the list

  • free_it (bool) – set to true if the command object must be freed.

  • clean_db – Clean command related information (included polling info if the command is polled) from database.

Raises

DevFailed

classmethod run_server(args=None, **kwargs)

Run the class as a device server. It is based on the tango.server.run method.

The difference is that the device class and server name are automatically given.

Args:
args (iterable): args as given in the tango.server.run method

without the server name. If None, the sys.argv list is used

kwargs: the other keywords argument are as given

in the tango.server.run method.

set_archive_event(self, attr_name, implemented, detect=True)

Set an implemented flag for the attribute to indicate that the server fires archive events manually, without the polling to be started.

If the detect parameter is set to true, the criteria specified for the archive event are verified and the event is only pushed if they are fullfilled. If detect is set to false the event is fired without any value checking!

Parameters
  • attr_name (str) – attribute name

  • implemented (bool) – True when the server fires change events manually.

  • detect (bool) – Triggers the verification of the change event properties when set to true. Default value is true.

set_attribute_config_3(self, new_conf) None

Sets attribute configuration locally and in the Tango database

Parameters

new_conf (list[tango.AttributeConfig_3]) – The new attribute(s) configuration. One AttributeConfig structure is needed for each attribute to update

Returns

None

Return type

None

set_change_event(self, attr_name, implemented, detect=True)

Set an implemented flag for the attribute to indicate that the server fires change events manually, without the polling to be started.

If the detect parameter is set to true, the criteria specified for the change event are verified and the event is only pushed if they are fullfilled. If detect is set to false the event is fired without any value checking!

Parameters
  • attr_name (str) – attribute name

  • implemented (bool) – True when the server fires change events manually.

  • detect (bool) – Triggers the verification of the change event properties when set to true. Default value is true.

set_state(self, new_state)

Set device state.

Parameters

new_state (DevState) – the new device state

set_status(self, new_status)

Set device status.

Parameters

new_status (str) – the new device status

signal_handler(self, signo)

Signal handler.

The method executed when the signal arrived in the device server process. This method is defined as virtual and then, can be redefined following device needs.

Parameters

signo (int) – the signal number

Raises

DevFailed – This method does not throw exception but a redefined method can.

start_logging(self) None

Starts logging

stop_logging(self) None

Stops logging

stop_poll_attribute(self, attr_name) None

Remove an attribute from the list of polled attributes.

Parameters

attr_name (str) – attribute name

Returns

None

Return type

None

stop_poll_command(self, cmd_name) None

Remove a command from the list of polled commands.

Parameters

cmd_name (str) – cmd_name name

Returns

None

Return type

None

stop_polling(self)
stop_polling(self, with_db_upd)

Stop all polling for a device. if the device is polled, call this method before deleting it.

Parameters

with_db_upd (bool) – Is it necessary to update db?

New in PyTango 7.1.2

unregister_signal(self, signo)

Unregister a signal.

Unregister this device as device to be informed when signal signo is sent to to the device server process

Parameters

signo (int) – signal identifier

warn_stream(self, msg, *args)

Sends the given message to the tango warn stream.

Since PyTango 7.1.3, the same can be achieved with:

print(msg, file=self.log_warn)
Parameters

msg (str) – the message to be sent to the warn stream

write_attr_hardware(self)

Write the hardware for attributes.

Default method to implement an action necessary on a device to write the hardware involved in a write attribute. This method must be redefined in sub-classes in order to support writable attribute

Parameters

attr_list (Sequence[int]) – list of indices in the device object attribute vector of an attribute to be written.

Raises

DevFailed – This method does not throw exception but a redefined method can.

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):

    voltage = attribute()

    def read_voltage(self):
        return 999.999

The same can be achieved with:

class PowerSupply(Device):

    @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

fisallowed

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.

forwarded

bool

False

the attribute should be forwarded if True

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):

    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):

    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):

    @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):

    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):

    @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

fisallowed

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):

    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):

    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='', mandatory=False, 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):

    host = device_property(dtype=str)
    port = device_property(dtype=int, mandatory=True)
Parameters
  • dtype – Data type (see Data types)

  • doc – property documentation (optional)

  • (optional (mandatory) – default is False)

  • 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):

    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, raises=False)

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):
    pass

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):
    pass

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

  • raises (bool) – Disable error handling and propagate exceptions from the server

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]

Changed in version 9.2.2: raises argument has been added

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.