Merge remote-tracking branch 'upstream/develop' into issue1433

.travis.yml

@@ -0,0 +1,67 @@
+group: deprecated-2017Q4
+
+language: python
+
+sudo: required
+
+services:
+  - docker
+
+python:
+  - "3.5"
+
+env:
+  global:
+    # Doctr deploy key for sardana-org/sardana-doc
+    - secure: "p/0UgVZzPKJQqcvQ/97qMgo9kPCE0cZ6vI+308YEJ2o9xj4a3FsfHCZ/vWtjdsrp1sQbtKVDesx+xmK4CLDzQeC2+Xskv8OZDjaG2jYkHcVosZEM3EGW8rLVKzoDWLr6cTy2wexLgjHPCsmrjukPs49/i5p+WU0no64YoLlZdp9TT+gvWSQJLIk6R4eqt4FHMszPybLv0pvb1SEiCzimlX1WM1pBrE0LHgchd2ZBYSUWTTwe+Koi4HCS4Bads8j20K2e3fFKcmR2u9DfmU+7Mf5HRJsj1LYJgBUF76lUG2/fZfpoDe8sWi+eUewTa3zNM4bhRLpV+pmG0ypplM4pIcdvwiHV03nGSGu6XK6OGQ/Mgsw0fmud4JR4f5g9DgEfERlyJKI4A9mPZQ327OmEwOOl33x2AFJAL05Qvm0yXCkf1dwgYXnZl44SQbAczY1NHFL90t6xbHtmTitJrE2Xb+4BLzMe3OOZj6j/0QeiXA4z1FnZr1s8UoAsm68iW194IuFg1RRG9FTISFWaBew5wzwvAJak0DxkpG0k43VkHiVC7sPHqr5CxXMXO/MuaptK2ti6iLK9xBAEUpO9HluOkeJq5WDIIxBiBS9tPi0i3vIpq87RjHkdw5n7pdIqnuJ1nXUjpWsuUyV3fLkY12fFxSbZgqmNhIE5/o9c5VP/69Y="
+
+  matrix:
+  # - TEST="flake8"
+  - TEST="testsuite" DOCKER_IMG=reszelaz/sardana-test
+  - TEST="doc" DOCKER_IMG=reszelaz/sardana-test
+
+
+before_install:
+  # install flake8 to perform python code style check in the script part
+  # install it using pip in order to get the newest version
+  - if [ $TEST == "flake8" ]; then sudo apt-get update -qq ; fi
+  - if [ $TEST == "flake8" ]; then sudo apt-get install -qq python3-pip; fi
+  - if [ $TEST == "flake8" ]; then sudo pip3 install flake8; fi
+
+install:
+  # run reszelaz/sardana-test docker container (Debian8 with sardana-deps)
+  - if [ $TEST != "flake8" ]; then docker pull $DOCKER_IMG; fi
+  - if [ $TEST != "flake8" ]; then docker run -d --name=sardana-test -h sardana-test --volume=`pwd`:/sardana $DOCKER_IMG; fi
+
+  # wait approx. 10 s (supervisor starts mysql and Tango DB)
+  - if [ $TEST == "testsuite" ]; then sleep 10; fi
+
+  # install sardana in order to create the launcher scripts for servers
+  - if [ $TEST == "testsuite" ]; then docker exec sardana-test bash -c "cd /sardana && python3 setup.py install"; fi
+
+  # start Pool and MacroServer necessary for macro tests
+  - if [ $TEST == "testsuite" ]; then docker exec sardana-test supervisorctl start Pool; fi
+  - if [ $TEST == "testsuite" ]; then docker exec sardana-test supervisorctl start MacroServer; fi
+
+script:
+  # make the script fail if a line fails
+  - set -e
+  # run flake8 check on all python files in the project
+  - if [ $TEST == "flake8" ]; then ci/flake8_diff.sh; fi
+  # run the full testsuite
+  - if [ $TEST == "testsuite" ]; then docker exec sardana-test xvfb-run -s '-screen 0 1920x1080x24' /bin/bash -c "pytest /usr/local/lib/python3.5/dist-packages/sardana-*.egg/sardana"; fi
+  # build docs
+  - if [ $TEST == "doc" ]; then docker exec -t sardana-test /bin/bash -c "cd /sardana ; sphinx-build -W doc/source/ build/sphinx/html" ; fi
+  - if [ $TEST == "doc" ]; then docker exec -t sardana-test /bin/bash -c "touch /sardana/build/sphinx/html/.nojekyll" ; fi
+
+deploy:
+  - provider: pages
+    local_dir: build/sphinx/html
+    repo: sardana-org/sardana-doc
+    skip_cleanup: true
+    github_token: $GITHUB_TOKEN  # Set in the settings page of your repository, as a secure variable
+    keep_history: true
+    fqdn: sardana-controls.org  # Set custom domain
+    on:
+      branch: develop
+      condition: "$TEST == doc"

CHANGELOG.md

@@ -3,6 +3,43 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 This file follows the formats and conventions from [keepachangelog.com]
 
+## [Unreleased] 
+
+### Added
+
+* *scan information* and *scan point* forms to the *showscan online* widget (#1386)
+* `ScanPlotWidget`, `ScanPlotWindow`, `ScanInfoForm`, `ScanPointForm` and `ScanWindow`
+  widget classes for easier composition of custom GUIs involving online scan plotting (#1386)
+* Include trigger/gate elements in the per-measurement preparation (#1432, #1443, #1468)
+  * Add `PrepareOne()` to TriggerGate controller.
+  * Call TriggerGate controller preparation methods in the _acquision action_
+* Add `ScanUser` environment variable (#1355)
+* Allow to programmatically disable *deterministic scan* optimization (#1426, #1427)
+* Initial delay in position domain to the synchronization description
+  in *ct* like continuous scans (#1428)
+* Avoid double printing of user units in PMTV: read widget and units widget (#1424)
+* Document how to properly deal with exceptions in macros in order to not interfer 
+  with macro stopping/aborting (#1461)
+* Documentation on how to start Tango servers on fixed IP - ORBendPoint (#1470)
+* Documentation example on how to more efficiently access Tango with PyTango
+  in macros/controllers (#1456)
+
+### Fixed
+
+* Execute per measurement preparation in `mesh` scan macro (#1437)
+* Continously read value references in hardware synchronized acquisition 
+  instead of reading only at the end (#1442, #1448)
+* Avoid problems when defining different, e.g. shape, standard attributes,
+  e.g. pseudo counter's value, in controllers (#1440, #1446)
+* Problems with macro id's when `sequencer` executes from _plain text_ files (#1215, #1216)
+* `sequencer` loading of plain text sequences in spock syntax with macro functions (#1422)
+* Allow running Spock without Qt bindings (#1462, #1463)
+* Recorders tests helpers (#1439)
+* Disable flake8 job in travis CI (#1455)
+* `createMacro()` and `prepareMacro()` docstring (#1460, #1444)
+* Make write of MeasurementGroup (Taurus extension) integration time more robust (#1473)
+* String formatting when rising exceptions in pseudomotors (#1469)
+
 ## [3.0.3] 2020-09-18
 
 ### Added

doc/source/devel/api/api_controller.rst

@@ -13,6 +13,7 @@ Controller API reference
     * :class:`ZeroDController` - 0D controller API
     * :class:`PseudoMotorController` - PseudoMotor controller API
     * :class:`PseudoCounterController` - PseudoCounter controller API
+    * :class:`TriggerGateController` - Trigger/Gate controller API
     * :class:`IORegisterController` - IORegister controller API
 
 .. _sardana-controller-data-type:

doc/source/devel/api/api_macro.rst

@@ -42,3 +42,23 @@ imacro decorator
     :members:
     :undoc-members:
 
+StopException
+-------------
+
+.. autoclass:: StopException
+    :members:
+    :undoc-members:
+
+AbortException
+--------------
+
+.. autoclass:: AbortException
+    :members:
+    :undoc-members:
+
+InterruptException
+------------------
+
+.. autoclass:: InterruptException
+    :members:
+    :undoc-members:

doc/source/devel/api/sardana/macroserver/scan.rst

@@ -26,8 +26,8 @@ GScan
     :show-inheritance:
     :members:
 
-GScan
------
+Scan
+----
 
 .. inheritance-diagram:: SScan
     :parts: 1

doc/source/devel/api/sardana/pool/controller.rst

@@ -44,6 +44,7 @@
     * :class:`OneDController`    
     * :class:`TwoDController`
     * :class:`PseudoCounterController`
+    * :class:`TriggerGateController`
     * :class:`IORegisterController`
 
 
@@ -216,6 +217,17 @@ Pseudo Counter Controller API
     :undoc-members:
 
 
+Trigger/Gate Controller API
+---------------------------
+
+.. inheritance-diagram:: TriggerGateController
+    :parts: 1
+
+.. autoclass:: TriggerGateController
+    :show-inheritance:
+    :members:
+    :undoc-members:
+
 IO Register Controller API
 ----------------------------
 

doc/source/devel/howto_controllers/howto_triggergatecontroller.rst

@@ -89,6 +89,18 @@ The state should be a member of :obj:`~sardana.sardanadefs.State` (For backward
 compatibility reasons, it is also supported to return one of
 :class:`PyTango.DevState`). The status could be any string.
 
+.. _sardana-TriggerGateController-howto-prepare:
+
+Prepare for measurement
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To prepare a trigger for a measurement you can use the
+:meth:`~sardana.pool.controller.TriggerGateController.PrepareOne` method which
+receives as an argument the number of starts of the whole measurement.
+This information may be used to prepare the hardware for generating
+multiple events (triggers or gates) in a complex measurement
+e.g. :ref:`sardana-macros-scanframework-determscan`.
+
 .. _sardana-TriggerGateController-howto-load:
 
 Load synchronization description

doc/source/devel/howto_macros/macros_general.rst

@@ -13,6 +13,10 @@ Writing macros
 This chapter provides the necessary information to write macros in sardana. The
 complete macro :term:`API` can be found :ref:`here <sardana-macro-api>`.
 
+.. contents:: Table of contents
+    :depth: 3
+    :backlinks: entry
+
 What is a macro
 ---------------
 
@@ -866,6 +870,55 @@ of user's interruption you must override the
     withing the :meth:`~sardana.macroserver.macro.Macro.on_stop` or
     :meth:`~sardana.macroserver.macro.Macro.on_abort`.
 
+.. _sardana-macro-exception-handling:
+
+Handling exceptions
+-------------------
+
+Please refer to the
+`Python Errors and Exceptions <https://docs.python.org/3/tutorial/errors.html>`_
+documentation on how to deal with exceptions in your macro code.
+
+.. important::
+    :ref:`sardana-macro-handling-macro-stop-and-abort` is internally implemented
+    using Python exceptions. So, your ``except`` clause can not simply catch any
+    exception type without re-raising it - this would ignore the macro stop/abort
+    request done in the ``try ... except`` block. If you still would like to
+    use the broad catching, you need to catch and raise the stop/abort exception
+    first:
+
+    .. code-block:: python
+        :emphasize-lines: 7
+
+        import time
+
+        from sardana.macroserver.macro import macro, StopException
+
+        @macro()
+        def exception_macro(self):
+            self.output("Starting stoppable process")
+            try:
+                for i in range(10):
+                    self.output("In iteration: {}".format(i))
+                    time.sleep(1)
+            except StopException:
+                raise
+            except Exception:
+                self.warning("Exception, but we continue")
+            self.output("After 'try ... except' block")
+
+    If you do not program lines 12-13 and you stop your macro within
+    the ``try ... except`` block then the macro will continue and print the
+    output from line 16.
+
+    You may choose to catch and re-raise:
+    `~sardana.macroserver.macro.StopException`,
+    `~sardana.macroserver.macro.AbortException` or
+    `~sardana.macroserver.macro.InterruptException`. The last one will
+    take care of stopping and aborting at the same time.
+
+
+
 .. _sardana-macro-adding-hooks-support:
 
 Adding hooks support
@@ -965,6 +1018,36 @@ simplified usage you should use Taurus. If you strive for very optimal access
 to Tango and don't need these benefits then most probably PyTango will work
 better for you.
 
+.. hint::
+    If you go for PyTango and wonder if creating a new `tango.DeviceProxy`
+    in frequent macro executions is inefficient from the I/O point of view you
+    should not worry about it cause Tango (more precisely CORBA) is taking
+    care about recycling the connection during a period of 120 s (default).
+
+    If you still would like to optimize your code in order to avoid creation
+    of a new `tango.DeviceProxy` you may consider using the
+    `functools.lru_cache` as a singleton cache mechanism::
+
+        import functools
+        import tango
+        from sardana.macroserver.macro import macro
+
+        Device = functools.lru_cache(maxsize=1024)(tango.DeviceProxy)
+
+        @macro()
+        def switch_states(self):
+            """Switch TangoTest device state"""
+            proxy = Device('sys/tg_test/1')
+            proxy.SwitchStates()
+
+    Here you don't need to worry about the opened connection to the
+    Tango device server in case you don't execute the macro for a while.
+    Again, Tango (more precisely CORBA) will take care about it.
+    See more details about the CORBA scavanger thread in:
+    `Tango client threading <https://tango-controls.readthedocs.io/en/latest/development/advanced/threading.html#client-process>`_
+    and `CORBA idle connection shutdown <http://omniorb.sourceforge.net/omni42/omniORB/omniORB006.html#sec%3AconnShutdown>`_.
+
+
 .. _sardana-macro-using-external-libraries:
 
 Using external python libraries

doc/source/devel/howto_macros/scan_framework.rst

@@ -195,6 +195,7 @@ the most basic features of a continuous scan:: ::
    (with more elaborated waypoint generator), see the code of 
    :class:`~sardana.macroserver.macros.scan.meshc`
 
+.. _sardana-macros-scanframework-determscan:
 
 Deterministic scans
 -------------------

doc/source/users/configuration/server.rst

@@ -7,25 +7,30 @@ Sardana system can
 :ref:`run as one or many Tango device servers<sardana-getting-started-running-server>`.
 Tango device servers listens on a TCP port for the CORBA requests. Usually
 it is fine to use the randomly assigned port (default behavior) but sometimes
-it may be necessary to use a fixed port number. For example, when the server
-needs to be accessed from another isolated network and we want to open
-connections only for the given ports.
+it may be necessary to use a fixed port number or even IP address.
+For example, when the server needs to be accessed from another isolated
+network and we want to open connections only for the given ports or IPs.
 
-There are three possibilities to assign the port explicitly (the order
-indicates the precedence):
+There are three possibilities to assign the IP and/or port in format of the
+ORBendPoint explicitly (the order indicates the precedence):
+
+.. note::
+    The ORBendPoint is in the following format: ``giop:tcp:<IP>:<port>``
+    and both IP and port are optional, so you could only fix the IP,
+    only fix the port, fix both of them or none of them.
 
 - using OS environment variable ``ORBendPoint`` e.g.
 
 .. code-block:: bash
 
-    $ export ORBendPoint=28366
-    $ Pool demo1 -ORBendPoint 28366
+    $ export ORBendPoint=giop:tcp:192.168.0.100:28366
+    $ Pool demo1
 
 - using Tango device server command line argument ``-ORBendPoint``
 
 .. code-block:: bash
 
-    $ Pool demo1 -ORBendPoint 28366
+    $ Pool demo1 -ORBendPoint giop:tcp:192.168.0.100:28366
 
 - using Tango DB free property with object name: ``ORBendPoint`` and property
   name: ``<server_name>/<instance_name>``)
@@ -34,7 +39,7 @@ indicates the precedence):
 
     import tango
     db = tango.Database()
-    db.put_property("ORBendPoint", {"Pool/demo1": 28366})
+    db.put_property("ORBendPoint", {"Pool/demo1": "giop:tcp:192.168.0.100:28366"})
 
 .. note::
 

doc/source/users/environment_variable_catalog.rst

@@ -308,7 +308,7 @@ ScanRecorder
 
 Its value may be either of type string or of list of strings. If
 ScanRecorder variable is defined, it explicitly indicates which recorder
-class should be used and for which file defined by ScanFile (based on the 
+class should be used and for which file defined by ScanFile (based on the
 order).
 
 Example 1:
@@ -381,6 +381,17 @@ For example::
        'min': 2.9802322387695312e-08,
        'minpos': 0.0}}}
 
+.. _scanuser:
+
+ScanUser
+~~~~~~~~
+*Not mandatory, set by user*
+
+Its value is of type string. Its value is delivered to the recorders which
+may use it, for example, as a user contact information. If not set, the OS
+user executing the Sardana server (which executes the scan) will be passed to
+the recorders instead.
+
 .. _sharedmemory:
 
 SharedMemory