API util

class tango.ApiUtil(*args, **kwargs)

This class allows you to access the tango syncronization model API. It is designed as a singleton. To get a reference to the singleton object you must do:

import tango
apiutil = tango.ApiUtil.instance()

New in PyTango 7.1.3

cleanup() → None

Destroy the ApiUtil singleton instance. After cleanup() all references to DeviceProxy, AttributeProxy or Database objects in the current process become invalid and these objects need to be reconstructed.

Parameters:

None

Return:

None

New in PyTango 9.3.0

get_asynch_cb_sub_model(self) → cb_sub_model

Get the asynchronous callback sub-model.

Parameters:

None

Return:

(cb_sub_model) the active asynchronous callback sub-model.

New in PyTango 7.1.3

get_asynch_replies(self) → None

Fire callback methods for all (any device) asynchronous requests (command and attribute) with already arrived replied. Returns immediately if there is no replies already arrived or if there is no asynchronous requests.

Parameters:

None

Return:

None

Throws:

None, all errors are reported using the err and errors fields of the parameter passed to the callback method.

New in PyTango 7.1.3

get_asynch_replies (self) -> None

Fire callback methods for all (any device) asynchronous requests (command and attributes) with already arrived replied. Wait and block the caller for timeout milliseconds if they are some device asynchronous requests which are not yet arrived. Returns immediately if there is no asynchronous request. If timeout is set to 0, the call waits until all the asynchronous requests sent has received a reply.

Parameters:

timeout:

(int) timeout (milliseconds)

Return:

None

Throws:

AsynReplyNotArrived. All other errors are reported using the err and errors fields of the object passed to the callback methods.

New in PyTango 7.1.3

in_server() → bool

Returns True if current process is a running Tango device server.

Returns:

running in server

Return type:

bool

New in version 10.0.0.

instance() → ApiUtil

Returns the ApiUtil singleton instance.

Parameters:

None

Return:

(ApiUtil) a reference to the ApiUtil singleton object.

New in PyTango 7.1.3

pending_asynch_call(self, req) → int

Return number of asynchronous pending requests (any device). The input parameter is an enumeration with three values which are:

• POLLING: Return only polling model asynchronous request number

• CALL_BACK: Return only callback model asynchronous request number

• ALL_ASYNCH: Return all asynchronous request number

Parameters:

req:

(asyn_req_type) asynchronous request type

Return:

(int) the number of pending requests for the given type

New in PyTango 7.1.3

set_asynch_cb_sub_model(self, model) → None

Set the asynchronous callback sub-model between the pull and push sub-model. The cb_sub_model data type is an enumeration with two values which are:

• PUSH_CALLBACK: The push sub-model

• PULL_CALLBACK: The pull sub-model

Parameters:

model:

(cb_sub_model) the callback sub-model

Return:

None

New in PyTango 7.1.3

Information classes

See also Event configuration information

Attribute

class tango.AttributeAlarmInfo(*args, **kwargs)

A structure containing available alarm information for an attribute with the following members:

• min_alarm : (str) low alarm level

• max_alarm : (str) high alarm level

• min_warning : (str) low warning level

• max_warning : (str) high warning level

• delta_t : (str) time delta

• delta_val : (str) value delta

• extensions : (StdStringVector) extensions (currently not used)

class tango.AttributeDimension(*args, **kwargs)

A structure containing x and y attribute data dimensions with the following members:

• dim_x : (int) x dimension

• dim_y : (int) y dimension

class tango.AttributeInfo(*args, **kwargs)

A structure (inheriting from DeviceAttributeConfig) containing available information for an attribute with the following members:

• disp_level : (DispLevel) display level (OPERATOR, EXPERT)

Inherited members are:

• name : (str) attribute name

• writable : (AttrWriteType) write type (R, W, RW, R with W)

• data_format : (AttrDataFormat) data format (SCALAR, SPECTRUM, IMAGE)

• data_type : (int) attribute type (float, string,..)

• max_dim_x : (int) first dimension of attribute (spectrum or image attributes)

• max_dim_y : (int) second dimension of attribute(image attribute)

• description : (int) attribute description

• label : (str) attribute label (Voltage, time, …)

• unit : (str) attribute unit (V, ms, …)

• standard_unit : (str) standard unit

• display_unit : (str) display unit

• format : (str) how to display the attribute value (ex: for floats could be ‘%6.2f’)

• min_value : (str) minimum allowed value

• max_value : (str) maximum allowed value

• min_alarm : (str) low alarm level

• max_alarm : (str) high alarm level

• writable_attr_name : (str) name of the writable attribute

• extensions : (StdStringVector) extensions (currently not used)

class tango.AttributeInfoEx(*args, **kwargs)

A structure (inheriting from AttributeInfo) containing available information for an attribute with the following members:

• alarms : object containing alarm information (see AttributeAlarmInfo).

• events : object containing event information (see AttributeEventInfo).

• sys_extensions : StdStringVector

Inherited members are:

• name : (str) attribute name

• writable : (AttrWriteType) write type (R, W, RW, R with W)

• data_format : (AttrDataFormat) data format (SCALAR, SPECTRUM, IMAGE)

• data_type : (int) attribute type (float, string,..)

• max_dim_x : (int) first dimension of attribute (spectrum or image attributes)

• max_dim_y : (int) second dimension of attribute(image attribute)

• description : (int) attribute description

• label : (str) attribute label (Voltage, time, …)

• unit : (str) attribute unit (V, ms, …)

• standard_unit : (str) standard unit

• display_unit : (str) display unit

• format : (str) how to display the attribute value (ex: for floats could be ‘%6.2f’)

• min_value : (str) minimum allowed value

• max_value : (str) maximum allowed value

• min_alarm : (str) low alarm level

• max_alarm : (str) high alarm level

• writable_attr_name : (str) name of the writable attribute

• extensions : (StdStringVector) extensions (currently not used)

• disp_level : (DispLevel) display level (OPERATOR, EXPERT)

see also AttributeInfo

class tango.DeviceAttributeConfig(*args, **kwargs)

A base structure containing available information for an attribute with the following members:

• name : (str) attribute name

• writable : (AttrWriteType) write type (R, W, RW, R with W)

• data_format : (AttrDataFormat) data format (SCALAR, SPECTRUM, IMAGE)

• data_type : (int) attribute type (float, string,..)

• max_dim_x : (int) first dimension of attribute (spectrum or image attributes)

• max_dim_y : (int) second dimension of attribute(image attribute)

• description : (int) attribute description

• label : (str) attribute label (Voltage, time, …)

• unit : (str) attribute unit (V, ms, …)

• standard_unit : (str) standard unit

• display_unit : (str) display unit

• format : (str) how to display the attribute value (ex: for floats could be ‘%6.2f’)

• min_value : (str) minimum allowed value

• max_value : (str) maximum allowed value

• min_alarm : (str) low alarm level

• max_alarm : (str) high alarm level

• writable_attr_name : (str) name of the writable attribute

• extensions : (StdStringVector) extensions (currently not used)

Command

class tango.DevCommandInfo(*args, **kwargs)

A device command info with the following members:

• cmd_name : (str) command name

• cmd_tag : command as binary value (for TACO)

• in_type : (CmdArgType) input type

• out_type : (CmdArgType) output type

• in_type_desc : (str) description of input type

• out_type_desc : (str) description of output type

New in PyTango 7.0.0

class tango.CommandInfo(*args, **kwargs)

A device command info (inheriting from DevCommandInfo) with the following members:

• disp_level : (DispLevel) command display level

Inherited members are (from DevCommandInfo):

• cmd_name : (str) command name

• cmd_tag : (str) command as binary value (for TACO)

• in_type : (CmdArgType) input type

• out_type : (CmdArgType) output type

• in_type_desc : (str) description of input type

• out_type_desc : (str) description of output type

Other

class tango.DeviceInfo(*args, **kwargs)

A structure containing available information for a device with the” following members:

• dev_class : (str) device class

• server_id : (str) server ID

• server_host : (str) host name

• server_version : (str) server version

• doc_url : (str) document url

• version_info : (dict<str, str>) version info dict

Changed in version 10.0.0: Added version_info field

class tango.LockerInfo(*args, **kwargs)

A structure with information about the locker with the following members:

• ll : (tango.LockerLanguage) the locker language

• li : (pid_t / UUID) the locker id

• locker_host : (str) the host

• locker_class : (str) the class

pid_t should be an int, UUID should be a tuple of four numbers.

New in PyTango 7.0.0

class tango.PollDevice(*args, **kwargs)

A structure containing PollDevice information with the following members:

• dev_name : (str) device name

• ind_list : (sequence<int>) index list

New in PyTango 7.0.0

Storage classes

Attribute: DeviceAttribute

class tango.DeviceAttribute(*args, **kwargs)

This is the fundamental type for RECEIVING data from device attributes.

It contains several fields. The most important ones depend on the ExtractAs method used to get the value. Normally they are:

• value : Normal scalar value or numpy array of values.

• w_value : The write part of the attribute.

See other ExtractAs for different possibilities. There are some more fields, these really fixed:

• name : (str)

• data_format : (AttrDataFormat) Attribute format

• quality : (AttrQuality)

• time : (TimeVal)

• dim_x : (int) attribute dimension x

• dim_y : (int) attribute dimension y

• w_dim_x : (int) attribute written dimension x

• w_dim_y : (int) attribute written dimension y

• r_rimension : (tuple) Attribute read dimensions.

• w_dimension : (tuple) Attribute written dimensions.

• nb_read : (int) attribute read total length

• nb_written : (int) attribute written total length

And two methods:

• get_date

• get_err_stack

class ExtractAs

Defines what will go into value field of DeviceAttribute, or what will Attribute.get_write_value() return… Not all the possible values are valid in all the cases.

Valid possible values are:

• Numpy : Value will be stored in [value, w_value]. If the attribute is an scalar, they will contain a value. If it’s an SPECTRUM or IMAGE it will be exported as a numpy array.

• Tuple : Value will be stored in [value, w_value]. If the attribute is an scalar, they will contain a value. If it’s an SPECTRUM or IMAGE it will be exported as a tuple or tuple of tuples.

• List : Value will be stored in [value, w_value]. If the attribute is an scalar, they will contain a value. If it’s an SPECTRUM or IMAGE it will be exported as a list or list of lists

• String : The data will be stored ‘as is’, the binary data as it comes from TangoC++ in ‘value’.

• Nothing : The value will not be extracted from DeviceAttribute

get_date(self) → TimeVal

Get the time at which the attribute was read by the server.

Note: It’s the same as reading the “time” attribute.

Parameters:

None

Return:

(TimeVal) The attribute read timestamp.

get_err_stack(self) → sequence<DevError>

Returns the error stack reported by the server when the attribute was read.

Parameters:

None

Return:

(sequence<DevError>)

set_w_dim_x(self, val) → None

Sets the write value dim x.

Parameters:

val:

(int) new write dim x

Return:

None

New in PyTango 8.0.0

set_w_dim_y(self, val) → None

Sets the write value dim y.

Parameters:

val:

(int) new write dim y

Return:

None

New in PyTango 8.0.0

Command: DeviceData

Device data is the type used internally by Tango to deal with command parameters and return values. You don’t usually need to deal with it, as command_inout will automatically convert the parameters from any other type and the result value to another type.

You can still use them, using command_inout_raw to get the result in a DeviceData.

You also may deal with it when reading command history.

class tango.DeviceData(*args, **kwargs)

This is the fundamental type for sending and receiving data from device commands. The values can be inserted and extracted using the insert() and extract() methods.

extract(self) → any

Get the actual value stored in the DeviceData.

Parameters:

None

Return:

Whatever is stored there, or None.

get_type(self) → CmdArgType

This method returns the Tango data type of the data inside the DeviceData object.

Parameters:

None

Return:

The content arg type.

insert(self, data_type, value) → None

Inserts a value in the DeviceData.

Parameters:

data_type:

value:

(any) The value to insert

Return:

Whatever is stored there, or None.

is_empty(self) → bool

It can be used to test whether the DeviceData object has been initialized or not.

Parameters:

None

Return:

True or False depending on whether the DeviceData object contains data or not.

Callback related classes

If you subscribe a callback in a DeviceProxy, it will be run with a parameter. This parameter depends will be of one of the following classes depending on the callback type.

class tango.AttrReadEvent(*args, **kwargs)

This class is used to pass data to the callback method in asynchronous callback model for read_attribute(s) execution.

It has the following members:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed

• attr_names : (sequence<str>) The attribute name list

• argout : (DeviceAttribute) The attribute value

• err : (bool) A boolean flag set to true if the command failed. False otherwise

• errors : (sequence<DevError>) The error stack

• ext :

class tango.AttrWrittenEvent(*args, **kwargs)

This class is used to pass data to the callback method in asynchronous callback model for write_attribute(s) execution

It has the following members:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed

• attr_names : (sequence<str>) The attribute name list

• err : (bool) A boolean flag set to true if the command failed. False otherwise

• errors : (NamedDevFailedList) The error stack

• ext :

class tango.CmdDoneEvent(*args, **kwargs)

This class is used to pass data to the callback method in asynchronous callback model for command execution.

It has the following members:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed.

• cmd_name : (str) The command name

• argout_raw : (DeviceData) The command argout

• argout : The command argout

• err : (bool) A boolean flag set to true if the command failed. False otherwise

• errors : (sequence<DevError>) The error stack

• ext :

Event related classes

Event configuration information

class tango.AttributeEventInfo(*args, **kwargs)

A structure containing available event information for an attribute with the following members:

• ch_event : (ChangeEventInfo) change event information

• per_event : (PeriodicEventInfo) periodic event information

• arch_event : (ArchiveEventInfo) archiving event information

class tango.ArchiveEventInfo(*args, **kwargs)

A structure containing available archiving event information for an attribute with the following members:

• archive_rel_change : (str) relative change that will generate an event

• archive_abs_change : (str) absolute change that will generate an event

• archive_period : (str) archive period

• extensions : (sequence<str>) extensions (currently not used)

class tango.ChangeEventInfo(*args, **kwargs)

A structure containing available change event information for an attribute with the following members:

• rel_change : (str) relative change that will generate an event

• abs_change : (str) absolute change that will generate an event

• extensions : (StdStringVector) extensions (currently not used)

class tango.PeriodicEventInfo(*args, **kwargs)

A structure containing available periodic event information for an attribute with the following members:

• period : (str) event period

• extensions : (StdStringVector) extensions (currently not used)

Event arrived structures

class tango.EventData(*args, **kwargs)

This class is used to pass data to the callback method when an event is sent to the client. It contains the following public fields:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed.

• attr_name : (str) The attribute name

• event : (str) The event name

• attr_value : (DeviceAttribute) The attribute data (DeviceAttribute)

• err : (bool) A boolean flag set to true if the request failed. False otherwise

• errors : (sequence<DevError>) The error stack

• reception_date: (TimeVal)

class tango.AttrConfEventData(*args, **kwargs)

This class is used to pass data to the callback method when a configuration event is sent to the client. It contains the following public fields:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed

• attr_name : (str) The attribute name

• event : (str) The event name

• attr_conf : (AttributeInfoEx) The attribute data

• err : (bool) A boolean flag set to true if the request failed. False otherwise

• errors : (sequence<DevError>) The error stack

• reception_date: (TimeVal)

class tango.DataReadyEventData(*args, **kwargs)

This class is used to pass data to the callback method when an attribute data ready event is sent to the clien. It contains the following public fields:

• device : (DeviceProxy) The DeviceProxy object on which the call was executed

• attr_name : (str) The attribute name

• event : (str) The event name

• attr_data_type : (int) The attribute data type

• ctr : (int) The user counter. Set to 0 if not defined when sent by the server

• err : (bool) A boolean flag set to true if the request failed. False otherwise

• errors : (sequence<DevError>) The error stack

• reception_date: (TimeVal)

New in PyTango 7.0.0

History classes

class tango.DeviceAttributeHistory(*args, **kwargs)

Bases:

See DeviceAttribute.

class tango.DeviceDataHistory(*args, **kwargs)

Bases:

See DeviceData.