Ts-salobj

------=

Backwards incompatible changes:

* `topics.RemoteCommand.set` and `topics.RemoteCommand.set_start` now start from a fresh data sample,
rather than using the parameters for the most recent command (``self.data``) as defaults.
This makes behavior easier to understand and avoids unpleasant surprises.
It should affect very little code, since most code specifies all parameters for each call.

Other changes:

* `current_tai` now uses the system TAI clock, if available (only on Linux) and if it gives a reasonable time.
Salobj logs a warning such as ``current_tai uses current_tai_from_utc; clock_gettime(CLOCK_TAI) is off by 37.0 seconds``
if CLOCK_TAI does not give a reasonable time.
This warning indicates that salobj is computing TAI from the standard UTC-ish system clock;
that time will be accurate on most days, but it will be off by up to a second on the day of a leap second.
* `set_summary_state` now accepts ``settingsToApply=None``.
Formerly it was not supported, but might work.
* Improved IO errors handling while accessing schema, labels and configuration
file in `ConfigurableCsc`.
* `ConfigurableCsc.get_default_config_dir` renamed to
`ConfigurableCsc._get_default_config_dir`.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)

------=

Backwards incompatible changes:

* Many methods of topics in `Remote`\ s now raise `RuntimeError` if the remote has not yet started.
This may cause some code (especially unit tests) to fail with a `RuntimeError`.
The fix is to make sure the code waits for `Remote.start_task` before trying to read data or issue commands.
In unit tests consider using ``async with salobj.Remote(...) as remote:``.
The methods that raise are:

* Data reading methods: `topics.ReadTopic.has_data`, `topics.ReadTopic.aget`, `topics.ReadTopic.get`,
`topics.ReadTopic.get_oldest`, and `topics.ReadTopic.next`.
* Command issuing methods: `topics.RemoteCommand.start` and `topics.RemoteCommand.set_start`.

Other changes:

* Fixed an error in `name_to_name_index`: it could not handle names that contained integers (DM-24933).
* Fixed an error in `BaseCscTestCase.make_csc`: ``log_level`` was ignored after the first call, and also ignored if the level was greater than (verbosity less than) WARNING.
* Improved `BaseCscTestCase.make_csc` to allow ``log_level=None`` (do not change the log level) and make that the default.
* Update `BaseScript.start` to wait for its remotes to start.
* Update `CscCommander` to include the received time as part of event and telemetry output.
* Improved the error message from `BaseCscTestCase.assert_next_sample` to specify which field failed.
* Improved tests/test_speed.py:

* Fixed a bug: the measurement "salobj.CreateClasses" was reported as the inverse of the correct value.
* Do not fail the read speed measurements if samples are lost; writing is faster than reading, so some loss is likely.
Instead, print the number of samples lost.
* Improve the measurement "salobj.ReadTest_logLevel" by ignoring an extra logLevel event output by `Controller`.
* Be more careful about shutting down the topic writer subprocess.
This eliminates a warning about an unclosed socket.
* Reduced the number of samples read and written, since it doesn't affect the measurements,
speeds up the test, and may reduce lost samples.
* Removed the combined read/write speed test because it is redundant with the tests added in v5.11.0.

* Minor improvements to ``test_salobj_to_either.py`` and ``test_salpy_to_either.py``,
including printing how long it takes to create the listeneners,
which is an upper limit (and decent approximation) of how long it waits for historical data.
* Made time limits in unit tests more generous and simpler.
This should help test robustness on computers that are slow or starved for resources.
* Fixed flake8 warnings about f strings with no {}.
* Removed deprecated ``sudo: false`` entry from ``.travis.yml``, in order to allow github checks to pass once again.
* Modified `assert_black_formatted` to ignore ``version.py``.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)

------=

Major changes:

* Update CscCommander to support custom commands and to run commands in the background.
* Add new speed tests for issuing commands, reading small and large topics, and writing small and large topics.
Results of the speed tests are uploaded to SQuaSH by Jenkins.
* Add new function `assert_black_formatted` to simplify making sure code remains formatted with ``black``,
and a unit test that calls the function.
* Increased the shutdown delay in `Controller` from 0.5 seconds to 1 second,
in order to give `Remote`\ s a bit more time to read final SAL/DDS messages.
This may require tweaking timeouts in unit tests that wait for a controller to quit.

Other changes:

* Update the CSC documentation to move the details for configurable CSCs to a new section.
* Change `SalInfo` to only set the log level if it is less verbose than `loggint.INFO`.
That makes it easier to set a more verbose level in unit tests.
* Update a unit test for compatibility with the pending release of ts_xml 5.2.
* Made ``test_salpy_to_either.py`` more robust by increasing the polling rate for messages.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)

------=

Major changes:

* Sped up DDS message read and write by a factor of 8, as reported by ``tests/test_speed.py``.
This was done by speeding up `tai_from_utc`, which turned out to be the bottleneck.
* Add function `tai_from_utc_unix`, which does most of the work for `tai_from_utc`.

Minor changes:

* Improved the Jenkins file handling for building and uploading the documentation.
If building the documentation fails then the Jenkins job fails.
If uploading the documentation fails then the Jenkins job is marked as unstable.

Notes:

* `tai_from_utc` and `astropy_time_from_tai_unix` will be deprecated once we upgrade to a version of AstroPy that supports TAI seconds directly.
That change has been committed to the AstroPy code base.
The new function `tai_from_utc_unix` will remain.
* salobj now uses a daemon thread to maintain an internal leap second table.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)

------

Backwards incompatible changes:

* The arguments have changed slightly for `AsyncS3Bucket.make_bucket_name` and `AsyncS3Bucket.make_key` and the returned values are quite different.
We changed our standards because it turns out that large numbers of buckets are a problem for Amazon Web Services (AWS).

Major changes:

* Add a ``timeout`` argument to `BaseCscTestCase.check_standard_state_transitions`.
* Update `BaseCsc.start` to output the ``softwareVersions`` event.
* Update `ConfigurableCsc` to output the ``settingsApplied`` event.

Minor changes:

* Allow the ``SALPY_Test`` library to be missing: skip the few necessary unit tests if the library is not found.
* The Jenkins job now builds and uploads the documentation (even if unit tests fail).
* Improve the reliability of ``tests/test_salobj_to_either.py`` by increasing a time limit.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)

------

Major changes:

* Improved `AsyncS3Bucket`:

* Read environment variable ``S3_ENDPOINT_URL`` to obtain the endpoint URL.
This allows use with non-AWS S3 servers.
* Added support for running a mock S3 server: a new ``domock`` constructor argument and `AsyncS3Bucket.stop_mock` method.
This is intended for CSCs running in simulation mode, and for unit tests.
* Added static method `AsyncS3Bucket.make_bucket_name`.
* Added static method `AsyncS3Bucket.make_key`.

* Improved `BaseCscTestCase`:

* Added argument ``skip_commands`` to `BaseCscTestCase.check_standard_state_transitions`.
* Added argument ``**kwargs`` to `BaseCscTestCase.make_csc` and `BaseCscTestCase.basic_make_csc`.
* Changed argument ``*cmdline_args`` to ``cmdline_args`` for `BaseCscTestCase.check_bin_script`, for clarity.

Other changes:

* Added a :ref:`lsst.ts.salobj-configuration` section to the documentation.
* Added missing unit test for `topics.QueueCapacityChecker`.
* Standardized the formatting for attributes documented in the Notes section for some classes.

Requirements:

* ts_idl 1
* ts_xml 4.7
* IDL files for Test, Script, and LOVE.
* SALPY_Test generated by ts_sal 4 (for unit tests)