.. currentmodule:: PyTango

.. _pytango-data-types:

Data types
==========

This chapter describes the mapping of data types between Python and Tango.

Tango has more data types than Python which is more dynamic. The input and
output values of the commands are translated according to the array below.
Note that if PyTango is compiled with :py:mod:`numpy` support the numpy type
will be the used for the input arguments. Also, it is recomended to use numpy
arrays of the appropiate type for output arguments as well, as they tend to be
much more efficient.

**For scalar types (SCALAR)**

+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|   Tango data type       |              Python 2.x type                                              |              Python 3.x type (*New in PyTango 8.0*)                       |
+=========================+===========================================================================+===========================================================================+
|          DEV_VOID       |                    No data                                                |                    No data                                                |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|       DEV_BOOLEAN       | :py:obj:`bool`                                                            | :py:obj:`bool`                                                            |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|         DEV_SHORT       | :py:obj:`int`                                                             | :py:obj:`int`                                                             |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|         DEV_LONG        | :py:obj:`int`                                                             | :py:obj:`int`                                                             |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|        DEV_LONG64       | - :py:obj:`long` (on a 32 bits computer)                                  | :py:obj:`int`                                                             |
|                         | - :py:obj:`int` (on a 64 bits computer)                                   |                                                                           |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|         DEV_FLOAT       | :py:obj:`float`                                                           | :py:obj:`float`                                                           |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|       DEV_DOUBLE        | :py:obj:`float`                                                           | :py:obj:`float`                                                           |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|        DEV_USHORT       | :py:obj:`int`                                                             | :py:obj:`int`                                                             |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|        DEV_ULONG        | :py:obj:`int`                                                             | :py:obj:`int`                                                             |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|        DEV_ULONG64      | * :py:obj:`long` (on a 32 bits computer)                                  | :py:obj:`int`                                                             |
|                         | * :py:obj:`int` (on a 64 bits computer)                                   |                                                                           |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|        DEV_STRING       | :py:obj:`str`                                                             | :py:obj:`str` (decoded with *latin-1*, aka *ISO-8859-1*)                  |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | sequence of two elements:                                                 | sequence of two elements:                                                 |
| DEV_ENCODED             |                                                                           |                                                                           |
| (*New in PyTango 8.0*)  | 0. :py:obj:`str`                                                          | 0. :py:obj:`str` (decoded with *latin-1*, aka *ISO-8859-1*)               |
|                         | 1. :py:obj:`bytes` (for any value of *extract_as*)                        | 1. :py:obj:`bytes` (for any value of *extract_as*, except String.         |
|                         |                                                                           |    In this case it is :py:obj:`str` (decoded with default python          |
|                         |                                                                           |    encoding *utf-8*))                                                     |
+-------------------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+

**For array types (SPECTRUM/IMAGE)**

+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|    Tango data type      |   ExtractAs     |                          Data type (Python 2.x)                           |             Data type (Python 3.x) (*New in PyTango 8.0*)                 |
+=========================+=================+===========================================================================+===========================================================================+
| DEVVAR_CHARARRAY        | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint8`)                  | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint8`)                  |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`int`>                                          | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`int`>                                         | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_SHORTARRAY       | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint16`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint16`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_SHORT + SPECTRUM)  | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_SHORT + IMAGE)     | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`int`>                                          | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`int`>                                         | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_LONGARRAY        | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint32`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint32`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_LONG + SPECTRUM)   | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_LONG + IMAGE)      | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`int`>                                          | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`int`>                                         | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_LONG64ARRAY      | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint64`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint64`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_LONG64 + SPECTRUM) | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_LONG64 + IMAGE)    | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <int (64 bits) / long (32 bits)>                         | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <int (64 bits) / long (32 bits)>                        | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_FLOATARRAY       | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float32`)                | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float32`)                |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_FLOAT + SPECTRUM)  | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_FLOAT + IMAGE)     | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`float`>                                        | :py:class:`list` <:py:obj:`float`>                                        |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`float`>                                       | :py:class:`tuple` <:py:obj:`float`>                                       |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_DOUBLEARRAY      | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float64`)                | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float64`)                |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_DOUBLE + SPECTRUM) | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_DOUBLE + IMAGE)    | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`float`>                                        | :py:class:`list` <:py:obj:`float`>                                        |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`float`>                                       | :py:class:`tuple` <:py:obj:`float`>                                       |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_USHORTARRAY      | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint16`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint16`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_USHORT + SPECTRUM) | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_USHORT + IMAGE)    | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`int`>                                          | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`int`>                                         | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_ULONGARRAY       | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint32`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint32`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_ULONG + SPECTRUM)  | Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_ULONG + IMAGE)     | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <:py:obj:`int`>                                          | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <:py:obj:`int`>                                         | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_ULONG64ARRAY     | Numpy           | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint64`)                 | :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.uint64`)                 |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_ULONG64 + SPECTRUM)| Bytes           | :py:obj:`bytes` (which is in fact equal to :py:obj:`str`)                 | :py:obj:`bytes`                                                           |
| or                      +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| (DEV_ULONG64 + IMAGE)   | ByteArray       | :py:obj:`bytearray`                                                       | :py:obj:`bytearray`                                                       |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | String          | :py:obj:`str`                                                             | String    :py:obj:`str` (decoded with default python encoding *utf-8*!!!) |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | List            | :py:class:`list` <int (64 bits) / long (32 bits)>                         | :py:class:`list` <:py:obj:`int`>                                          |
|                         +-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         | Tuple           | :py:class:`tuple` <int (64 bits) / long (32 bits)>                        | :py:class:`tuple` <:py:obj:`int`>                                         |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
| DEVVAR_STRINGARRAY      |                 | sequence<:py:obj:`str`>                                                   | sequence<:py:obj:`str`>                                                   |
| or                      |                 |                                                                           | (decoded with *latin-1*, aka *ISO-8859-1*)                                |
| (DEV_STRING + SPECTRUM) |                 |                                                                           |                                                                           |
| or                      |                 |                                                                           |                                                                           |
| (DEV_STRING + IMAGE)    |                 |                                                                           |                                                                           |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         |                 | sequence of two elements:                                                 | sequence of two elements:                                                 |
|  DEV_LONGSTRINGARRAY    |                 |                                                                           |                                                                           |
|                         |                 | 0. :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.int32`) or            | 0. :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.int32`) or            |
|                         |                 |    sequence<:py:obj:`int`>                                                |    sequence<:py:obj:`int`>                                                |
|                         |                 | 1. sequence<:py:obj:`str`>                                                | 1.  sequence<:py:obj:`str`> (decoded with *latin-1*, aka *ISO-8859-1*)    |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+
|                         |                 | sequence of two elements:                                                 | sequence of two elements:                                                 |
|  DEV_DOUBLESTRINGARRAY  |                 |                                                                           |                                                                           |
|                         |                 | 0. :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float64`) or          | 0. :py:class:`numpy.ndarray` (dtype= :py:obj:`numpy.float64`) or          |
|                         |                 |    sequence<:py:obj:`int`>                                                |    sequence<:py:obj:`int`>                                                |
|                         |                 | 1. sequence<:py:obj:`str`>                                                | 1. sequence<:py:obj:`str`> (decoded with *latin-1*, aka *ISO-8859-1*)     |
+-------------------------+-----------------+---------------------------------------------------------------------------+---------------------------------------------------------------------------+

For SPECTRUM and IMAGES the actual sequence object used depends on the context 
where the tango data is used, and the availability of :py:mod:`numpy`.

1. for properties the sequence is always a :py:class:`list`. Example::
    
    >>> import PyTango
    >>> db = PyTango.Database()
    >>> s = db.get_property(["TangoSynchrotrons"])
    >>> print type(s)
    <type 'list'>

2. for attribute/command values
    - :py:class:`numpy.ndarray` if PyTango was compiled with :py:mod:`numpy`
      support (default) and :py:mod:`numpy` is installed.
    - :py:class:`list` otherwise
