# The Utilities API

class `PyTango.utils.``EventCallBack`(format='{date} {dev_name} {name} {type} {value}', fd=<open file '<stdout>', mode 'w'>, max_buf=100)

  Useful event callback for test purposes

  Usage:

      >>> dev = PyTango.DeviceProxy(dev_name)
      >>> cb = PyTango.utils.EventCallBack()
      >>> id = dev.subscribe_event("state", PyTango.EventType.CHANGE_EVENT, cb, [])
      2011-04-06 15:33:18.910474 sys/tg_test/1 STATE CHANGE [ATTR_VALID] ON

  Allowed format keys are:

  > - date (event timestamp)
  > - reception_date (event reception timestamp)
  > - type (event type)
  > - dev_name (device name)
  > - name (attribute name)
  > - value (event value)

  New in PyTango 7.1.4

  `get_events`()

    Returns the list of events received by this callback

    Returns: | the list of events received by this callback
    Return type: | sequence<obj>

  `push_event`(evt)

    Internal usage only

`PyTango.utils.``is_pure_str`(obj)

  Tells if the given object is a python string.

  In python 2.x this means any subclass of basestring. In python 3.x this means any subclass of str.

  Parameters: | obj (`object`) – the object to be inspected
  Returns: | True is the given obj is a string or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_seq`(obj)

  Tells if the given object is a python sequence.

  It will return True for any collections.Sequence (list, tuple, str, bytes, unicode), bytearray and (if numpy is enabled) numpy.ndarray

  Parameters: | obj (`object`) – the object to be inspected
  Returns: | True is the given obj is a sequence or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_non_str_seq`(obj)

  Tells if the given object is a python sequence (excluding string sequences).

  It will return True for any collections.Sequence (list, tuple (and bytes in python3)), bytearray and (if numpy is enabled) numpy.ndarray

  Parameters: | obj (`object`) – the object to be inspected
  Returns: | True is the given obj is a sequence or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_integer`(obj)

  Tells if the given object is a python integer.

  It will return True for any int, long (in python 2) and (if numpy is enabled) numpy.integer

  Parameters: | obj (`object`) – the object to be inspected
  Returns: | True is the given obj is a python integer or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_number`(obj)

  Tells if the given object is a python number.

  It will return True for any numbers.Number and (if numpy is enabled) numpy.number

  Parameters: | obj (`object`) – the object to be inspected
  Returns: | True is the given obj is a python number or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_bool`(tg_type, inc_array=False)

  Tells if the given tango type is boolean

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is boolean or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_scalar_type`(tg_type)

  Tells if the given tango type is a scalar

  Parameters: | tg_type (`PyTango.CmdArgType`) – tango type
  Returns: | True if the given tango type is a scalar or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_array_type`(tg_type)

  Tells if the given tango type is an array type

  Parameters: | tg_type (`PyTango.CmdArgType`) – tango type
  Returns: | True if the given tango type is an array type or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_numerical_type`(tg_type, inc_array=False)

  Tells if the given tango type is numerical

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is a numerical or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_int_type`(tg_type, inc_array=False)

  Tells if the given tango type is integer

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is integer or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_float_type`(tg_type, inc_array=False)

  Tells if the given tango type is float

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is float or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_bool_type`(tg_type, inc_array=False)

  Tells if the given tango type is boolean

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is boolean or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_bin_type`(tg_type, inc_array=False)

  Tells if the given tango type is binary

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is binary or False otherwise
  Return type: | `bool`

`PyTango.utils.``is_str_type`(tg_type, inc_array=False)

  Tells if the given tango type is string

  Parameters:

  - tg_type (`PyTango.CmdArgType`) – tango type
  - inc_array (`bool`) – (optional, default is False) determines if include array in the list of checked types

  Returns: | True if the given tango type is string or False otherwise
  Return type: | `bool`

`PyTango.utils.``obj_2_str`(obj, tg_type=None)

  Converts a python object into a string according to the given tango type

  Parameters:

  - obj (`object`) – the object to be converted
  - tg_type (`PyTango.CmdArgType`) – tango type

  Returns: | a string representation of the given object
  Return type: | `str`

`PyTango.utils.``seqStr_2_obj`(seq, tg_type, tg_format=None)

  Translates a sequence<str> to a sequence of objects of give type and format

  Parameters:

  - seq (sequence<str>) – the sequence
  - tg_type (`PyTango.CmdArgType`) – tango type
  - tg_format (`PyTango.AttrDataFormat`) – (optional, default is None, meaning SCALAR) tango format

  Returns: | a new sequence

`PyTango.utils.``scalar_to_array_type`(tg_type)

  Gives the array tango type corresponding to the given tango scalar type. Example: giving DevLong will return DevVarLongArray.

  Parameters: | tg_type (`PyTango.CmdArgType`) – tango type
  Returns: | the array tango type for the given scalar tango type
  Return type: | `PyTango.CmdArgType`
  Raises: | ValueError – in case the given dtype is not a tango scalar type

`PyTango.utils.``get_home`()

  Find user’s home directory if possible. Otherwise raise error.

  Returns: | user’s home directory
  Return type: | `str`

  New in PyTango 7.1.4

`PyTango.utils.``requires_pytango`(min_version=None, conflicts=(), software_name='Software')

  Determines if the required PyTango version for the running software is present. If not an exception is thrown. Example usage:

      from PyTango import requires_pytango

      requires_pytango('7.1', conflicts=['8.1.1'], software='MyDS')

  Parameters:

  - min_version (None, str, `LooseVersion`) – minimum PyTango version [default: None, meaning no minimum required]. If a string is given, it must be in the valid version number format (see: `LooseVersion`)
  - conflics (seq<str|LooseVersion>) – a sequence of PyTango versions which conflict with the software using it
  - software_name (str) – software name using PyTango. Used in the exception message

  Raises: | Exception – if the required PyTango version is not met

  New in PyTango 8.1.4

`PyTango.utils.``requires_tango`(min_version=None, conflicts=(), software_name='Software')

  Determines if the required Tango version for the running software is present. If not an exception is thrown. Example usage:

      from Tango import requires_tango

      requires_tango('7.1', conflicts=['8.1.1'], software='MyDS')

  Parameters:

  - min_version (None, str, `LooseVersion`) – minimum Tango version [default: None, meaning no minimum required]. If a string is given, it must be in the valid version number format (see: `LooseVersion`)
  - conflics (seq<str|LooseVersion>) – a sequence of Tango versions which conflict with the software using it
  - software_name (str) – software name using Tango. Used in the exception message

  Raises: | Exception – if the required Tango version is not met

  New in PyTango 8.1.4