.. _pytango-news:

###########
What's new?
###########

The sections below will give you the most relevant news from the PyTango releases.
For help moving to a new release, or for the complete list of changes, see the
following links:

.. toctree::
    :maxdepth: 1

    migration/index
    History of changes <revision>

****************************
What's new in PyTango 9.5.0?
****************************

Date: 2023-10-26 9.5.0rc1

Type: major release

Changed
=======

- PyTango requires at least `cppTango`_ 9.5.0. See the :ref:`migration guide <to9.5_deps_install>`.
- When using the asyncio green mode, a :class:`~tango.PyTangoUserWarning` will be emitted during the
  :meth:`~tango.server.Device.init_device` call, if the user's :class:`~tango.server.Device` methods are not
  coroutines (i.e., defined with ``async def``).
- Use ``127.0.0.1`` as the default host for (Multi)DeviceTestContext instead of trying to find an external IP.
  This allows tests to work on systems that only have a loopback interface, and also reduces firewall warnings
  when running tests (at least on macOS).  If using it from the command line like,
  ``python -m tango.test_context MyDS.MyDevice``, an external IP is still the default.
- All warnings generated by PyTango are now instances of :class:`~tango.PyTangoUserWarning`, which
  inherits from Python's :class:`UserWarning`.
- Some of the dependencies packaged with the binary wheels on PyPI have changed.  The bundled versions are:

+------------------------+----------+---------+---------+
| Dependency             | Linux    | Windows | MacOS   |
+========================+==========+=========+=========+
| cpptango               |    9.5.0 |   9.5.0 |   9.5.0 |
+------------------------+----------+---------+---------+
| omniorb / omniorb-libs |    4.3.1 |   4.3.0 |   4.3.1 |
+------------------------+----------+---------+---------+
| libzmq / zeromq        |    4.3.5 | 4.0.5-2 |   4.3.5 |
+------------------------+----------+---------+---------+
| cppzmq                 |  4.10.0  |   4.7.1 |  4.10.0 |
+------------------------+----------+---------+---------+
| libjpeg-turbo          |    3.0.0 |   2.0.3 |   3.0.0 |
+------------------------+----------+---------+---------+
| tango-idl              |    5.1.1 |   5.1.2 |   5.1.2 |
+------------------------+----------+---------+---------+
| boost                  |  1.82.0  |  1.83.0 |  1.82.0 |
+------------------------+----------+---------+---------+

Added
=====

- Short-name access can be used for (Multi)DeviceTestContext devices.  See :ref:`migration guide <to9.5_short_name_test_access>`
- *Experimental feature:*  use Python type hints to declare Device more easily.
  Read more in the new section: :ref:`type hint`.
- :meth:`~tango.WAttribute.set_write_value` now supports IMAGE attributes.
- Forwarded attributes are *partially* supported in the (Multi)DeviceTestContext.  We say *partially*, because
  a cppTango limitation (at least version 9.5.0) means root attributes on devices running in "nodb" mode
  (like those in launched by the TestContext) don't work. However, it does work if the test device accesses a root
  attribute on a Tango device running with a Tango database.
- Support for :class:`~tango.EncodedAttribute` in high-level API devices.
- Added ``free_it`` and ``clean_db`` arguments to :meth:`tango.server.Device.remove_attribute` and
  :meth:`tango.LatestDeviceImpl.remove_attribute` methods.
- Support Tango server debugging with PyCharm, PyDev and VS Code.  Breakpoints now work for command and attribute
  handler methods, as well as other standard :class:`~tango.server.Device` methods, when running through a debugger that
  is based on `pydevd <https://pypi.org/project/pydevd>`_.  However, it doesn't currently work with dynamic attributes
  and commands.  If necessary, the feature can be disabled by setting the environment variable
  ``PYTANGO_DISABLE_DEBUG_TRACE_PATCHING=1``.
- Added support for Python 3.12.

Fixed
=====

- Fixed various issues with :class:`~tango.DeviceProxy` with non-synchronous green mode devices launched with
  :class:`~tango.test_context.DeviceTestContext` and :class:`~tango.test_context.MultiDeviceTestContext`.
  This also fixes support for tests decorated with ``@pytest.mark.asyncio``.

Removed
=======

- Breaking change to the API: the :class:`~tango.CmdArgType.DevInt` data type
  was removed, due to its removal from `cppTango`_. See the :ref:`migration guide <to9.5_dev_int>`.
- Deprecated signature, :meth:`~tango.WAttribute.get_write_value(self, lst)`, was removed.


****************************
What's new in PyTango 9.4.2?
****************************

Date: 2023-07-27

Type: minor release

Changed
=======

- New python and NumPy :ref:`version policy <pytango-version-policy>` is implemented.

Added
=====

- Correct code coverage of server's methods can be obtained
- server_init_hook was added to high-level and low-level API
- macOS wheels now are provided

Fixed
=====

- DevEncoded attributes and commands read methods are now segfault safe
- DevEncoded attributes and commands now decoded with utf-8
- DevEncoded attributes and commands can be extracted and written as str, bytes and bytesarray
- If string encoding with Latin-1 fails, UnicodeError will be raised instead of segfaulting
- When user gives empty spectrum properties to the DeviceTestContext,
  they will be patched with one space symbol " " for each element
- In case patching failed or any other problems with FileDatabase, instead of crash PyTango will raise an exception
  and print out generated file
- Regression when applying additional decorators on attribute accessor functions.  Method calls
  would have the wrong signature and fail.

Removed
=======

- Support for Python < 3.9. See :ref:`version policy <pytango-version-policy>`

****************************
What's new in PyTango 9.4.1?
****************************

Date: 2023-03-15

Type: major release (breaking changes compared to 9.4.0)

Changed
=======

- Removed additional function signatures for high-level attribute read/write/is_allowed
  methods that were added in 9.4.0 resulting in a regression.  For example, the high-level
  write method API for dynamic attributes of the form ``write_method(self, attr, value)``
  has been removed, leaving only ``write_method(self, attr)``.  Similarly, unbound functions
  that could be used without a reference to the device object, like ``read_function()``, are no
  longer supported - only ``read_function(device)``.
  See the :ref:`migration guide <to9.4_non_bound_user_funcs>`.
- The dependencies packaged with the binary PyPI wheels are as follows:
    - Linux:
        - cpptango: 9.4.1
        - omniorb: 4.2.5  (changed since PyTango 9.4.0)
        - libzmq: v4.3.4
        - cppzmq: v4.7.1
        - libjpeg-turbo: 2.0.9
        - tango-idl: 5.1.1
        - boost: 1.80.0 (with patch for Python 3.11 support)
    - Windows:
        - cpptango: 9.4.1
        - omniorb: 4.2.5
        - libzmq: v4.0.5-2
        - cppzmq: v4.7.1
        - libjpeg-turbo: 2.0.3
        - tango-idl: 5.1.2
        - boost: 1.73.0

Fixed
=====

- Regression for undecorated read attribute accessor functions in derived device classes.  E.g., if we
  have ``class A(Device)`` with attribute reading via method ``A.read_my_attribute``, then
  reading ``my_attribute`` from ``class B(A)`` would fail.  More generally, repeated wrapping
  of methods related to attributes, commands and standard methods (like ``init_device``) is now
  avoided.
- Regression when applying additional decorators on attribute accessor functions.  Method calls
  would have the wrong signature and fail.

****************************
What's new in PyTango 9.4.0?
****************************

Date: 2023-02-15

Type: major release

.. warning:: significant regressions - use newer release!

Changed
=======

- PyTango requires at least `cppTango`_ 9.4.1.  See the :ref:`migration guide <to9.4_deps_install>`.
- Breaking change to the API when using empty spectrum and image attributes.  Clients reading an empty
  attribute will get an empty sequence (list/tuple/numpy array) instead of a :obj:`None` value.  Similarly,
  devices that have an empty sequence written will receive that in the write method instead of a :obj:`None`
  value.  See the migration guide on :ref:`empty attributes <to9.4_empty_attrs>` and
  :ref:`extract as <to9.4_extract_as>`.
- Python dependencies:  `numpy`_ is no longer optional - it is required.
  Other new requirements are `packaging <https://pypi.org/project/packaging>`_ and
  `psutil <https://pypi.org/project/psutil>`_.
- Binary wheels for more platforms, including Linux, are available on `PyPI`_.  Fast installation without compiling and
  figuring out all the dependencies!
- The dependencies packaged with the binary PyPI wheels are as follows:
    - Linux:
        - cpptango: 9.4.1
        - omniorb: 4.2.4
        - libzmq: v4.3.4
        - cppzmq: v4.7.1
        - libjpeg-turbo: 2.0.9
        - tango-idl: 5.1.1
        - boost: 1.80.0 (with patch for Python 3.11 support)
    - Windows:
        - cpptango: 9.4.1
        - omniorb: 4.2.5
        - libzmq: v4.0.5-2
        - cppzmq: v4.7.1
        - libjpeg-turbo: 2.0.3
        - tango-idl: 5.1.2
        - boost: 1.73.0
- When using the ``--port`` commandline option without ``--host``, the ``ORBendpoint`` for ``gio::tcp`` passed
  to cppTango will use ``"0.0.0.0"`` as the host instead of an empty string.  This is to workaround a
  `regression with cppTango 9.4.1 <https://gitlab.com/tango-controls/cppTango/-/issues/1055>`_.
  Note that if the ``--ORBendPoint`` commandline option is specified directly, it will not be modified.
  This will lead to a crash if an empty host is used, e.g., ``--ORBendPoint giop:tcp::1234``.

Added
=====

- User methods for attribute access (read/write/is allowed), and for commands (execute/is allowed)
  can be plain functions.  They don't need to be methods on the device class anymore.  There was some
  inconsistency with this previously, but now it is the same for static and dynamic attributes,
  and for commands.  Static and dynamic commands can also take an ``fisallowed`` keyword argument.
  See the :ref:`migration guide <to9.4_non_bound_user_funcs>`.
- Device methods for reading and writing dynamic attributes can use the high-level API instead of getting
  and setting values inside :class:`~tango.Attr` objects.  See the :ref:`migration guide <to9.4_hl_dynamic>`.
- High-level API support for accessing and creating DevEnum spectrum and image attributes.
  See the :ref:`migration guide <to9.4_hl_dev_enum>`.
- Developers can optionally allow Python attributes to be added to a :class:`~tango.DeviceProxy` instance
  by calling :meth:`~tango.DeviceProxy.unfreeze_dynamic_interface`.  The default behaviour is still
  to raise an exception when accessing unknown attributes.
  See the :ref:`migration guide <to9.4_optional_proxy_attrs>`.
- Attribute decorators have additional methods: :meth:`~tango.server.attribute.getter`,
  :meth:`~tango.server.attribute.read` and :meth:`~tango.server.attribute.is_allowed`.
  See the :ref:`migration guide <to9.4_attr_decorators>`.
- Python 3.11 support.
- MacOS support.  This is easiest installing from `Conda-forge`_.  Compiling locally is not recommended.
  See :ref:`Getting started <getting-started>`.
- Integrated development environment (IDE) autocompletion for methods inherited from
  :class:`tango.server.Device` and :class:`tango.LatestDeviceImpl`.  Attributes from the full class
  hierarchy are now more easily accessible directly in your editor.

Fixed
=====

- Log stream calls that include literal ``%`` symbols but no args now work properly without
  raising an exception.  E.g., ``self.debug_stream("I want to log a %s symbol")``.
  See the :ref:`migration guide <to9.4_logging_percent_sym>`.
- Writing a :obj:`numpy.array` to a spectrum attribute of type :obj:`str` no longer crashes.
- Reading an enum attribute with :class:`~tango.AttrQuality.ATTR_INVALID` quality via the high-level API
  now returns :obj:`None` instead of crashing.  This behaviour is consistent with the other data types.

Removed
=======

- Support for Python 2.7 and Python 3.5.
- The option to install PyTango without `numpy`_.
