# API util

class tango.ApiUtil

  This class allows you to access the tango synchronization 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

  static cleanup() → None

    cleanup () -> `None`

    Destroy the ApiUtil singleton instance. After calling cleanup(), any existing DeviceProxy, AttributeProxy, or Database objects become invalid and must be reconstructed.

    Returns:

      None

    New in PyTango 9.3.0

  get_asynch_cb_sub_model(self: tango._tango.ApiUtil) → tango._tango.cb_sub_model

    get_asynch_cb_sub_model (self) -> `cb_sub_model`

    Get the asynchronous callback sub-model.

    Returns:

      the active asynchronous callback sub-model

    Return type:

      cb_sub_model

    New in PyTango 7.1.3

  get_asynch_replies(*args, **kwargs)

    Overloaded function.

    1. get_asynch_replies(self: tango._tango.ApiUtil) -> None

    get_asynch_replies (self) -> `None`

    Fire callback methods for all asynchronous requests (command and attribute) which already have arrived replies. Returns immediately if no replies arrived or there are no asynchronous requests.

    Returns:

      None

    Throws:

      None, all errors are reported via the callback’s err/errors fields.

    New in PyTango 7.1.3

    2. get_asynch_replies(self: tango._tango.ApiUtil, timeout: typing.SupportsInt) -> None

    get_asynch_replies (self, timeout: int) -> `None`

    Fire callback methods for all asynchronous requests (command and attributes) with already arrived replies. Wait up to timeout milliseconds if some replies haven’t arrived yet. If timeout=0, waits until all requests receive a reply.

    Parameters:

      timeout (int) – timeout in milliseconds

    Returns:

      None

    Throws:

      `AsynReplyNotArrived` if some replies did not arrive in time. Other errors are reported via the callback’s err/errors fields.

    New in PyTango 7.1.3

  static get_env_var(name: str) → object

    get_env_var (name) -> `str`

    Return the environment variable for the given name.

    Parameters:

      name (str) – Environment variable name

    Returns:

      The value of the environment variable

    Return type:

      str

  get_ip_from_if(self: tango._tango.ApiUtil, interface_name: tango._tango.StdStringVector) → None

    get_ip_from_if (self, interface_name: str) -> `str`

    Get the IP address for the given network interface name.

    Parameters:

      interface_name (str) – The name of the network interface

    Returns:

      IP address associated to that interface

    Return type:

      str

  get_user_connect_timeout(self: tango._tango.ApiUtil) → int

    get_user_connect_timeout (self) -> `int`

    Get the user connect timeout (in milliseconds).

    Returns:

      The timeout in milliseconds

    Return type:

      int

  in_server(self: tango._tango.ApiUtil) → bool

    in_server () -> `bool`

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

    Returns:

      True if running in a server, otherwise False

    Return type:

      bool

    Added in version 10.0.0.

  static instance() → tango._tango.ApiUtil

    instance () -> `ApiUtil`

    Returns the ApiUtil singleton instance.

    Returns:

      (ApiUtil) a reference to the ApiUtil singleton object.

    New in PyTango 7.1.3

  is_notifd_event_consumer_created(self: tango._tango.ApiUtil) → bool

    is_notifd_event_consumer_created (self) -> `bool`

    Check if the notifd event consumer was created.

    Returns:

      True if created, False otherwise

    Return type:

      bool

  is_zmq_event_consumer_created(self: tango._tango.ApiUtil) → bool

    is_zmq_event_consumer_created (self) -> `bool`

    Check if the ZMQ event consumer was created.

    Returns:

      True if created, False otherwise

    Return type:

      bool

  pending_asynch_call(self: tango._tango.ApiUtil, req: tango._tango.asyn_req_type) → int

    pending_asynch_call (self, req) -> `int`

    Return the number of asynchronous pending requests (any device). The input parameter is an enumeration with three values: - POLLING - CALL_BACK - ALL_ASYNCH

    Parameters:

      req (asyn_req_type) – asynchronous request type

    Returns:

      the number of pending requests for the given type

    Return type:

      int

    New in PyTango 7.1.3

  set_asynch_cb_sub_model(self: tango._tango.ApiUtil, model: tango._tango.cb_sub_model) → None

    set_asynch_cb_sub_model (self, model) -> `None`

    Set the asynchronous callback sub-model between PULL_CALLBACK or PUSH_CALLBACK.

    Parameters:

      model (cb_sub_model) – the callback sub-model

    Returns:

      None

    New in PyTango 7.1.3

# Information classes

See also [Event configuration information]

## Attribute

class tango.AttributeAlarmInfo

  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

  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

  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

  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

  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

  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

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

  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

  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(da=None)

  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_dimension : (`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(*values)

    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

    List = 4
    Numpy = 0
    String = 5
    Tuple = 3
  class except_flags(*values)
  get_date(self: tango._tango.DeviceAttribute) → tango._tango.TimeVal

    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: tango._tango.DeviceAttribute) → list[DevError]

    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: tango._tango.DeviceAttribute, val: SupportsInt) → None

    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: tango._tango.DeviceAttribute, val: SupportsInt) → None

    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

  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.

  class except_flags(*values)
  extract(self: object, extract_as: tango._tango.ExtractAs = ExtractAs.Numpy) → object

    extract (self) -> `any`

    Get the actual value stored in the DeviceData.

    Parameters:

      None

    Return:

      Whatever is stored there, or None.

  get_type(self: tango._tango.DeviceData) → tango._tango.CmdArgType

    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: tango._tango.DeviceData, data_type: SupportsInt, value: object) → None

    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: tango._tango.DeviceData) → bool

    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
  property argout

    (DeviceAttribute) The attribute value

  property attr_names

    (sequence<str>) The attribute name list

  property device

    (DeviceProxy) The DeviceProxy object on which the call was executed

  property err

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

  property errors

    (sequence<DevError>) The error stack

class tango.AttrWrittenEvent
  property attr_names

    (sequence<str>) The attribute name list

  property device

    (DeviceProxy) The DeviceProxy object on which the call was executed

  property err

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

  property errors

    (sequence<DevError>) The error stack

class tango.CmdDoneEvent

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

  property argout

    The command argout

  property cmd_name

    (str) The command name

  property device

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

  property err

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

  property errors

    (sequence<DevError>) The error stack

# Event related classes

## Event configuration information

class tango.AttributeEventInfo

  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

  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

  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

  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 subscription structures

class tango.EventSubMode(*values)

  An enumeration representing the sub mode used when subscribing to events.

  - `EventSubMode.SyncRead` - synchronous subscription including attribute read (raises exception on failure), first callback immediately with current value.

  - `EventSubMode.AsyncRead` - asynchronous subscription and asynchronous attribute read (no exception on failure, retries automatically), first callback “soon” after read with current value.

  - `EventSubMode.Sync` - synchronous subscription without reading attribute (raises exception on failure), no callback on subscription (only on next event).

  - `EventSubMode.Async` - asynchronous subscription without reading attribute (no exception on failure, retries automatically), first callback with no value when subscription completed.

  - `EventSubMode.Stateless` - synchronous subscription including attribute read (no exception on failure, retries automatically) - equivalent to old stateless=True option, first callback immediately with current value. Consider `AsyncRead` instead.

  The table below summarises this:

  Event Subscription Modes
  EventSubMode | Tries subscription before returning | Raises on subscription failure | Reads entity | First callback
  --- | --- | --- | --- | ---
  SyncRead | Yes | Yes | Yes, during subscription | Immediately, with data
  AsyncRead | No | No | Yes, after subscription | After read, with data
  Sync | Yes | Yes | No | Only on next event
  Async | No | No | No | After subscription, no data
  Stateless | Yes | No | Yes, during subscription | Immediately, with data

  See `tango.DeviceProxy.subscribe_event()`.

  Added in version 10.1.0.

## Event arrived structures

class tango.EventData

  This class is used to pass data to the callback method when an event related to attribute data 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 type name

  > - event_reason : (`EventReason`) The reason for the event

  > - attr_value : (`DeviceAttribute`) 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`)

  Note

  The `attr_value` field may be `None`. E.g., if `err` is True, or when subscribing in `EventSubMode.Async` mode and the initial callback is received with `EventReason.SubSuccess`.

  get_date(self: tango._tango.EventData) → tango._tango.TimeVal

    get_date (self) -> `TimeVal`

    Returns the timestamp of the event.

    Returns:

      the timestamp of the event

    Return type:

      TimeVal

    New in PyTango 7.0.0

class tango.AttrConfEventData

  This class is used to pass data to the callback method when an attribute configuration event (`tango.EventType.ATTR_CONF_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 type name

  > - event_reason : (`EventReason`) The reason for the event

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

  get_date(self: tango._tango.AttrConfEventData) → tango._tango.TimeVal

    get_date (self) -> `TimeVal`

    Returns the timestamp of the event.

    Returns:

      the timestamp of the event

    Return type:

      TimeVal

    New in PyTango 7.0.0

class tango.DataReadyEventData

  This class is used to pass data to the callback method when an attribute data ready event (`tango.EventType.DATA_READY_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 type name

  > - event_reason : (`EventReason`) The reason for the event

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

  get_date(self: tango._tango.DataReadyEventData) → tango._tango.TimeVal

    get_date (self) -> `TimeVal`

    Returns the timestamp of the event.

    Returns:

      the timestamp of the event

    Return type:

      TimeVal

    New in PyTango 7.0.0

class tango.DevIntrChangeEventData

  This class is used to pass data to the callback method when a device interface changed event (`tango.EventType.INTERFACE_CHANGE_EVENT`) is sent to the client. It contains the following public fields:

  > - device : (`DeviceProxy`) The DeviceProxy object on which the call was executed

  > - event : (`str`) The event type name

  > - event_reason : (`EventReason`) The reason for the event

  > - device_name : (`str`) Tango device name

  > - dev_started : (`bool`) True when event sent due to device being (re)started and with only a possible, but not certain, interface change

  > - att_list : (`AttributeInfoListEx`) List of attribute details (only available in callback)

  > - cmd_list : (`CommandInfoList`) List of command details (only available in callback)

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

  > - errors : (sequence<`DevError`>) The error stack

  > - reception_date: (`TimeVal`)

  get_date(self: tango._tango.DevIntrChangeEventData) → tango._tango.TimeVal

    get_date (self) -> `TimeVal`

    Returns the timestamp of the event.

    Returns:

      the timestamp of the event

    Return type:

      TimeVal

class tango.EventReason(*values)

  An enumeration representing the reason for an event.

  - `EventReason.SubSuccess` - initial subscription was successful. Note: Event data will not have a value for EventSubMode.Async subscription. Not emitted for EventSubMode.Sync.

  - `EventReason.Update` - new event available. Device has pushed a new event, or re-subscription after loosing connection to device (e.g., after restart).

  - `EventReason.SubFail` - initial asynchronous subscription failed, or event system down (“Event channel is not responding anymore”).

  - `EventReason.Unknown` - unexpected - probably a bug in cppTango or PyTango.

  See `tango.EventSubMode`.

  Added in version 10.1.0.

# History classes

class tango.DeviceAttributeHistory

  Bases: `DeviceAttribute`

  has_failed(self: tango._tango.DeviceAttributeHistory) → bool

See `DeviceAttribute`.

class tango.DeviceDataHistory

  Bases: `DeviceData`

  get_date(self: tango._tango.DeviceDataHistory) → tango._tango.TimeVal

    get_date (self) -> `TimeVal`

    > Get record polling date

    Returns:

      the date when the device server polling thread has executed the command

    Return type:

      TimeVal

  get_err_stack(self: tango._tango.DeviceDataHistory) → list[DevError]

    get_err_stack (self) -> `DevErrorList`

    Get record error stack

    Returns:

      the error stack recorded by the device server polling thread in case of the command failed when it was invoked

    Return type:

      DevErrorList

  has_failed(self: tango._tango.DeviceDataHistory) → bool

    has_failed (self) -> `bool`

    Check if the record was a failure

    Returns:

      a boolean set to true if the record in the polling buffer was a failure

    Return type:

      bool

See `DeviceData`.