taurus 5.3.2__tar.gz → 5.4.0.dev0__tar.gz

{taurus-5.3.2 → taurus-5.4.0.dev0}/CHANGELOG.md

@@ -13,6 +13,23 @@ develop branch) won't be reflected in this file.
 
 ## Unreleased
 
+### Added
+- Support for Tango `EventSubMode` in attribute event subscriptions. This enables
+  selecting the subscription mode (`Sync`, `SyncRead`, `Async`, `AsyncRead`, `Stateless`)
+  when subscribing to attribute events (!1358).
+- Asynchronous modes (`Async`, `AsyncRead`) handle initial subscription notifications,
+  allowing the client to distinguish between successful subscriptions and cases where
+  a polling fallback is required.
+- First-time attribute reads during client initialization. Attributes can be read
+  once before event subscriptions for attribute with events with "no read" modes
+  (`Sync`, `Async`) to ensure cached values are initialized.
+- Ability to change or disable Tango event subscriptions from Taurus custom settings,
+  CLI, or programmatically through the `TangoFactory` API.
+
+### Changed
+- Default subscription mode is now `AsyncRead` when `EventSubMode` is available (Tango >= 10.1).
+  To retain the previous Taurus behavior, `SyncRead` can be selected via Taurus custom settings.
+
 ## [5.3.2] - 2025-11-28
 Patch release with bug fixes.
 
@@ -31,13 +48,16 @@ IMPORTANT: This patch release has not undergone the usual cross-platform manual
 - Avoid `Qt.ItemFlags` instantiation to prevent `AttributeError` with PyQt6 by returning the combined flags directly (!1385).
 
 ### Changed
-- Replaced Black and Flake8 with Ruff for formatting and linting, and updated Taurus code to comply with Ruff rules (!1359)
+- Replaced Black and Flake8 with Ruff for formatting and linting, and updated Taurus
+  code to comply with Ruff rules (!1359)
 
 ## [5.3.1] - 2025-09-15
 Hotfix to fix #1442
 
 ### Fixed
-- Restored dot-separated logger names to preserve parent/child hierarchy in Python logging. This ensures handler inheritance and log propagation. The issue was detected as missing output in Sardana Spock CLI (!1370, #1442)
+- Restored dot-separated logger names to preserve parent/child hierarchy in Python
+  logging. This ensures handler inheritance and log propagation. The issue was
+  detected as missing output in Sardana Spock CLI (!1370, #1442)
 
 ## [5.3.0] - 2025-08-24
 [Jul25 milestone](https://gitlab.com/taurus-org/taurus/-/milestones/21)
@@ -45,19 +65,30 @@ Hotfix to fix #1442
 Release adding Qt6 support and dropping support for python<3.7 and PyTango<9.2.0.
 
 ### Added
-- Qt6 compatibility across the codebase, including support for PyQt6 and PySide6, while retaining support for PyQt5 and PySide2. PyQt5 remains the default binding (!1300, #1299)
-- Support for custom Tango device state color policies via the TANGO_DEVICE_STATE_COLOR_POLICY setting. `Taurus` policy (default) preserves current colors, and a new `Tango` policy is available to match Tango ATK colors. More policies can be added in the future (!1361, #1391)
+- Qt6 compatibility across the codebase, including support for PyQt6 and PySide6,
+  while retaining support for PyQt5 and PySide2. PyQt5 remains the default binding
+  (!1300, #1299)
+- Support for custom Tango device state color policies via the
+  TANGO_DEVICE_STATE_COLOR_POLICY setting. `Taurus` policy (default) preserves
+  current colors, and a new `Tango` policy is available to match Tango ATK colors.
+  More policies can be added in the future (!1361, #1391)
 
 ### Changed
 - Increased minimum supported PyTango version to 9.2.0 (!1347)
 - Updated minimum Python version to 3.7 (!1364)
-- TaurusForm now uses `TaurusModelSelector` instead of `TaurusModelChooser` for model selection, enabling plugin discovery (!1294, #1353)
+- TaurusForm now uses `TaurusModelSelector` instead of `TaurusModelChooser` for model
+  selection, enabling plugin discovery (!1294, #1353)
 
 ### Fixed
-- Fixed incorrect pending operations display for Tango attributes pushing change events from code. This is caused due to `w_value` not being updated in the received event after write. Taurus now always uses `write_read_attribute()` to ensure consistency (!1360)
+- Fixed incorrect pending operations display for Tango attributes pushing change
+  events from code. This is caused due to `w_value` not being updated in the received
+  event after write. Taurus now always uses `write_read_attribute()` to ensure
+  consistency (!1360)
 - Avoid None on initial read state in Tango device (!1362)
-- Fix setting model in taurus form using the full Tango host when no `TANGO_HOST` variable is set (!1363, #1421)
-- Prevent TaurusValue to return a non-list result as default read widget and to destroy an unexisting widget (!1323, #1379)
+- Fix setting model in taurus form using the full Tango host when no `TANGO_HOST`
+  variable is set (!1363, #1421)
+- Prevent TaurusValue to return a non-list result as default read widget and to
+  destroy an unexisting widget (!1323, #1379)
 
 
 ## [5.2.4] - 2025-04-29
@@ -954,7 +985,7 @@ and several other places](https://sf.net/p/tauruslib/tickets/milestone/Jul15/)
 [TEP19]: http://www.taurus-scada.org/tep/?TEP19.md
 [TEP20]: http://www.taurus-scada.org/tep/?TEP20.md
 [Unreleased]: https://gitlab.com/taurus-org/taurus/-/tree/develop
-[5.3.1]: https://gitlab.com/taurus-org/taurus/-/tree/5.3.2
+[5.3.2]: https://gitlab.com/taurus-org/taurus/-/tree/5.3.2
 [5.3.1]: https://gitlab.com/taurus-org/taurus/-/tree/5.3.1
 [5.3.0]: https://gitlab.com/taurus-org/taurus/-/tree/5.3.0
 [5.2.4]: https://gitlab.com/taurus-org/taurus/-/tree/5.2.4
@@ -991,4 +1022,3 @@ and several other places](https://sf.net/p/tauruslib/tickets/milestone/Jul15/)
 [taurus_legacy_cli]: https://github.com/taurus-org/taurus_legacy_cli
 
 
-

{taurus-5.3.2/lib/taurus.egg-info → taurus-5.4.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taurus
-Version: 5.3.2
+Version: 5.4.0.dev0
 Summary: A framework for scientific/industrial CLIs and GUIs
 Home-page: http://www.taurus-scada.org
 Download-URL: http://pypi.python.org/packages/source/t/taurus

taurus-5.4.0.dev0/doc/source/devel/eventsubmode.rst

@@ -0,0 +1,105 @@
+===============================================================================
+Tango event subscription modes
+===============================================================================
+
+This work is part of `Taurus Performance Optimization`_ (TPO) project. It adapts
+taurus to the new event subscription modes that Tango introduces from 10.1.0.
+The two pillars here are:
+
+1. Selecting the **event subscription mode** (``EventSubMode``).
+2. A lightweight **first read** to initialize attribute values when needed.
+
+For background on Tango events and PyTango API see the official docs:
+`Tango Events`_ and `PyTango DeviceProxy API`_. PyTango exposes the
+``EventSubMode`` enum and adds ``EventReason`` in the ``EventData``
+structure (see documentation in `PyTango client API`_). 
+
+.. _Taurus Performance Optimization: http://www.taurus-scada.org/tep/?TEP21.md
+.. _Tango Events: https://tango-controls.readthedocs.io/en/latest/Explanation/event.html
+.. _PyTango DeviceProxy API: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/device_proxy.html
+.. _PyTango client API: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/miscellaneous.html
+
+EventSubMode in Taurus
+----------------------
+
+Taurus supports all event subscription modes that Tango >= 10.1.0 provides.
+Taurus functionality should not change between modes but depending on the
+nature of the attributes and devices, the performance when starting applications
+may be affected. 
+
+When available, Taurus uses ``AsyncRead`` as default ``EventSubMode``. Typically, 
+the mode should not be changed as ``AsyncRead`` resulted the best compromise between
+compatibility, simplicity and performance but Taurus offers the possibility to
+change modes via via :ref:`Taurus custom settings <EventModesCustomSettings>`  or 
+:ref:`Command-Line Interface <EventModesCLI>`.
+
+If you experience problems when starting applications, specially with values
+initialization, the mode can be changed to ``SyncRead`` to recover the previous
+Taurus (< 5.4) default behaviour.
+
+The following table (adapted from `PyTango EventSubMode`_) summarizes the available event 
+subscription modes:
+
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+| EventSubMode| Tries subscription before returning | Raises on subscription failure | Retries automatically      | Reads entity              | First callback                          |
++=============+=====================================+================================+============================+===========================+=========================================+
+| SyncRead    | Yes                                 | Yes                            | No                         | Yes, during subscription  | Immediately, with data                  |
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+| AsyncRead   | No                                  | No                             | Yes                        | Yes, after subscription   | After read, with data                   |
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+| Sync        | Yes                                 | Yes                            | No                         | No                        | Not on subscription. Only on next event |
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+| Async       | No                                  | No                             | Yes                        | No                        | After subscription, no data             |
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+| Stateless   | Yes                                 | No                             | Yes                        | Yes, during subscription  | Immediately, with data                  |
++-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
+
+.. _PyTango EventSubMode: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/miscellaneous.html#tango.EventSubMode
+
+First Read (client-side initialization)
+---------------------------------------
+
+Taurus now provides a one-shot read used when the chosen mode does not
+perform an initial read by itself (``Sync`` and ``Async``). This first read
+is performed asynchronously in a dedicated thread that finishes when 
+all attributes have been initialized.
+
+This feature ensures that the attribute has a value cached right after
+subscription setup, delegating to Taurus the responsibility for providing
+the initial attribute value.
+
+API involved in Taurus:
+
+- Factory helper to register a first-time read for a given attribute.
+- Attribute-side helper that delegates to the factory during initialization.
+ 
+ 
+.. _EventModesCustomSettings:
+
+Changing the default mode via Custom Settings
+---------------------------------------------
+
+You can set the **default EventSubMode** machine-wide using **Taurus Custom Settings**.
+See the official page: `Taurus custom settings`_.
+
+.. _Taurus custom settings: https://taurus-scada.org/devel/tauruscustomsettings.html
+
+.. _EventModesCLI:
+
+Command-Line Interface (CLI)
+----------------------------
+
+Taurus provides two CLI switches to control Tango event subscriptions at launch:
+
+- ``--disable-tango-event-subscription``
+  Disables Tango change-event subscriptions and forces polling.
+
+- ``--tango-event-sub-mode {Sync,SyncRead,Async,AsyncRead}``
+  Selects the subscription mode for change events for this run.
+
+Precedence:
+
+1. If events are disabled via CLI, polling is used regardless of of the selected mode.
+2. Otherwise, the mode is taken from CLI; if not set, from custom settings;
+   otherwise Taurus uses the project default (``AsyncRead`` in this branch).
+

{taurus-5.3.2 → taurus-5.4.0.dev0}/doc/source/devel/index.rst

@@ -6,7 +6,7 @@ Developer's Guide
 
 .. toctree::
     :maxdepth: 2
-    
+
     Taurus 3.x to Taurus 4.x migration guide <taurus3to4>
     Development guidelines <coding_guide>
     Creating GUIs with the TaurusGUI framework <taurusgui_newgui>
@@ -17,6 +17,7 @@ Developer's Guide
     Plotting guide <plotting_guide>
     Plugins <plugins>
     Taurus Custom Settings <tauruscustomsettings>
+    Tango EventSubMode <eventsubmode>
     Examples <examples>
     API <api/index>
-    
+

taurus-5.4.0.dev0/doc/source/tep/TEP21.md

@@ -0,0 +1,121 @@
+    Title: Taurus Startup and Polling Performance Optimization
+    TEP: 21
+    State: ACCEPTED
+    Date: 2023
+    Drivers: ALBA Synchrotron
+    URL: http://www.taurus-scada.org/tep/?TEP21.md
+    License: http://www.jclark.com/xml/copying.txt
+    Abstract: 
+      Taurus GUIs managing hundreds of attributes may suffer from long startup times and fragile polling, especially in the presence of slow or timeout-prone attributes. TEP21 defines a plan to optimize Taurus startup and polling performance by fixing core inefficiencies, introducing systematic benchmarking and improving event subscription strategies.
+
+## Motivation
+
+Taurus-based GUIs at accelerators and beamlines frequently manage hundreds of Tango attributes, many of them event-driven. Users have long reported slow startup times (20–30 s for typical control room applications), fragile polling performance and poor responsiveness in the presence of slow, timeout-prone or event-flooding attributes.
+Improving Taurus startup time and attribute subscription robustness would directly benefit all Taurus deployments, including large-scale GUIs at several facilities.
+
+This proposal describes a set of improvements collectively known as *Taurus Performance Optimization (TPO)*. The work started in 2023 and includes work directly in Taurus and additional work that will need to be coordinated with Tango Core.
+
+## Background
+
+Profiling and benchmarking work developed at the beginning of TPO identified several bottlenecks:
+
+- Unnecessary repetitive calls (`getElementAlias()`, `fqdn_no_alias()`).
+- Triple reads for attributes without events and double reads for attributes with events under specific conditions (ATTR_CONF_EVENT + polling expirations).
+- Polling thread creation bugs (thread created too early, entering sleep without work).
+- Synchronous read performed inside `DeviceProxy.subscribe_event()`, which can block up to 3 s per attribute in case of slow or timeout attributes.
+
+Benchmarking (fast/slow/timeout/exception attributes) demonstrated that Taurus startup can be significantly improved and that it does not scale well with increasing numbers of attributes, especially those with events.
+
+## Goals
+
+The objective of TEP21 is to address Taurus inefficiencies regarding the slow start of GUIs, and to improve the polling and event subscription mechanisms, providing:
+
+- Fast and scalable GUI startup.
+- Robust handling of slow, timeout and missing attributes during initialization.
+- A mechanism to guarantee that all attributes have an initial value within a reasonable time (e.g. within one polling cycle for attributes without events).
+- Clear benchmark coverage to avoid regressions.
+
+## Proposed Design and Roadmap
+
+The project will be divided into two phases, Taurus Core Optimizations (TPO1) and event subscription improvements (TPO2).
+
+### Core Taurus Optimizations (TPO1)
+
+- Removal of redundant method calls.
+- Fixes to polling thread lifecycle.
+- Improved read cache behavior.
+- Avoid reads during startup when subscription fails.
+- Addition of benchmark tests to measure startup times and detect regressions.
+
+### Event Subscription Improvements (TPO2)
+
+The main design motivation is avoiding the synchronous read performed by Tango during event subscription. Three approaches will be evaluated:
+
+#### Option A: Internal Taurus Async Subscriber (Delayed/AsyncSubscriber)
+
+Implement (or improve the existing `DelayedSubscriber` to be easier to use) a new background thread (we'll call it "subscribe thread" from now on) that will try to subscribe to change events in background.
+
+Currently, Taurus tries to subscribe to change events as soon as `setModel` is called. With the new approach:
+
+- The `setModel` will not immediately subscribe to change events. Instead, it will enable polling for all attributes as if the attribute doesn't send events.
+- Once the application is open, the subscribe thread will attempt to subscribe to events for all attributes.
+  - If an attribute does not send events, it will remain in polling mode and will be removed from the subscribe thread.
+  - If an attribute does send events, the thread will successfully subscribe. Then it will be removed from the subscribe thread and also from the polling thread.
+
+**Pros:**
+
+- No Tango changes required.
+
+**Cons:**
+
+- While this approach is functional, it's not ideal. It will take some time to try to subscribe to events for all attributes. So if an attribute is sending events every 0.5 s, it will be updated every 3 s (or the polling period set) until this subscribe thread subscribes to that specific attribute.
+
+#### Option B: Tango Event Subscription without Read
+
+Add a new argument to Tango `subscribe_event()` method, called `read_attr` (or alternatively `avoid_read`, `read_value`, etc.). By default, this argument will be set to `True`, preserving the current behavior. When set to `False`, `subscribe_event()` will return immediately with the event ID or raise an exception if the attribute doesn’t send events. Unlike the current behavior, it won’t trigger a `push_event` callback since no read is performed.
+
+In this scenario, it becomes the caller’s responsibility to retrieve the attribute value through other methods.
+
+Taurus logic:
+
+1. Attribute added temporarily to polling with a one-shot flag.
+2. Polling retrieves first value (≤ 3 s guaranteed).
+3. Attribute removed from polling once events start.
+
+For most attributes, this polling workflow won’t be necessary because the attribute would typically send an event within a few seconds. However, we want to ensure that every attribute will have a value within 3 seconds or less, even if the attribute only sends events infrequently (e.g., once a day).
+
+**Pros:**
+
+- Small Tango-side modification.
+- Good startup behavior.
+
+**Cons:**
+
+- Requires more work on the Taurus side.
+
+#### Option C: Tango asynchronous event subscription
+
+We propose a new `subscribe_event_asynch()` method, similar to `read_attributes_asynch()`. This method would return immediately with the event ID but perform the actual read asynchronously. Once the value is retrieved, it would trigger the `push_event` callback as usual.
+
+In Taurus, this would work as follows:
+
+1. `subscribe_event_asynch()` is called (attributes without events will still raise an exception).
+2. When the application opens, most attributes will already have a value.
+3. Within a maximum of 3 seconds, all attributes will have a value, even in the worst case (when the last subscribed attribute raises a timeout error, which will call the callback ~3 seconds after the application starts).
+
+**Pros:**
+
+- Best performance and scalability.
+- Clean Taurus implementation.
+- Guarantees fast startup and early availability of values.
+
+**Cons:**
+
+- Implementation effort on Tango core side.
+
+## Risks
+
+- behavior differences between devices with and without events.
+- Tango feature implementation delays.
+- Coordination for PyTango bindings.
+- Potential performance regressions if benchmark tests are not maintained and run regularly.

{taurus-5.3.2 → taurus-5.4.0.dev0}/doc/source/tep/index.md

@@ -26,8 +26,8 @@ Proposals list
   [TEP17][] | ACCEPTED  | Implement plots with pyqtgraph
   [TEP18][] | ACCEPTED  | Implement support for Qt5 in taurus
   [TEP19][] | ACCEPTED  | Moving taurus-org to Gitlab
-  [TEP20][] | ACCEPTED | multi-models API
-  TEP21     | DRAFT    | Improve Taurus performance
+  [TEP20][] | ACCEPTED  | multi-models API
+  [TEP21][] | ACCEPTED  | Taurus Startup and Polling Performance Optimization
 
 [TEP0]: http://www.taurus-scada.org/tep/?TEP0.md
 [TEP3]: http://www.taurus-scada.org/tep/?TEP3.md
@@ -46,3 +46,4 @@ Proposals list
 [TEP18]: http://www.taurus-scada.org/tep/?TEP18.md
 [TEP19]: http://www.taurus-scada.org/tep/?TEP19.md
 [TEP20]: http://www.taurus-scada.org/tep/?TEP20.md
+[TEP21]: http://www.taurus-scada.org/tep/?TEP21.md

{taurus-5.3.2 → taurus-5.4.0.dev0}/lib/taurus/_release.py

@@ -52,7 +52,7 @@ __docformat__ = "restructuredtext"
 # (https://github.com/peritus/bumpversion), except when adding/removing
 # extra numbers in the release segment (e.g. for hotfixes), which is done
 # manually.
-version = "5.3.2"
+version = "5.4.0.dev0"
 
 name = "taurus"
 

{taurus-5.3.2 → taurus-5.4.0.dev0}/lib/taurus/cli/cli.py

@@ -36,6 +36,7 @@ from . import common
 @common.serial_mode
 @common.default_formatter
 @common.disable_tango_event_subscription
+@common.tango_event_sub_mode
 @click.option(
     "--rconsole",
     "rconsole_port",
@@ -52,6 +53,7 @@ def taurus_cmd(
     serialization_mode,
     default_formatter,
     disable_tango_event_subscription,
+    tango_event_sub_mode,
     rconsole_port,
     settings_files,
 ):
@@ -101,6 +103,13 @@ def taurus_cmd(
             disable_tango_event_subscription
         )
 
+    if tango_event_sub_mode is not None:
+        setattr(
+            tauruscustomsettings,
+            "TANGO_EVENT_SUB_MODE",
+            tango_event_sub_mode.upper(),
+        )
+
 
 def register_subcommands():
     """Discover and add subcommands to taurus_cmd"""

{taurus-5.3.2 → taurus-5.4.0.dev0}/lib/taurus/cli/common.py

@@ -195,6 +195,15 @@ disable_tango_event_subscription = click.option(
     ),
 )
 
+tango_event_sub_mode = click.option(
+    "--tango-event-sub-mode",
+    "tango_event_sub_mode",
+    type=click.Choice(["Sync", "SyncRead", "Async", "AsyncRead", "Stateless"]),
+    default=None,
+    show_default=True,
+    help="Tango subscription mode to use for change events",
+)
+
 list_alternatives = click.option(
     "--ls-alt",
     is_flag=True,