Merge pull request #99 from ska-sa/doc-sensor-type-force

Document changes to sensor value coercion

doc/changelog.rst

@@ -1,6 +1,27 @@
 Changelog
 =========
 
+.. rubric:: Development version
+
+**Breaking changes:**
+
+- When setting the value of a sensor, it is coerced to
+  an instance of the sensor type (see :ref:`sensor-value-coercion`). Reading
+  back the sensor value will give this coerced object instead of the original.
+  This only applies if the value was not already of the expected type.
+
+- Setting a sensor value to an object of an unsupported type will now raise
+  :exc:`TypeError`. Previously it was silently accepted, and clients querying
+  the sensor would either get a value of the wrong type, or the query would
+  fail.
+
+- The :class:`Address` constructor now raises :exc:`TypeError`
+  if the first argument is not an IP address object.
+
+Other changes:
+
+- Use :func:`typing.get_args` instead of an undocumented API.
+
 .. rubric:: Version 1.10.0
 
 - Use `katcp-codec`_ to provide the low-level encoding and decoding of

doc/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "aiokatcp"
-copyright = "2017-2023, National Research Foundation (SARAO)"
+copyright = "2017-2024, National Research Foundation (SARAO)"
 author = "Bruce Merry"
 
 version = aiokatcp.minor_version()
@@ -32,6 +32,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -45,6 +46,10 @@
 autodoc_member_order = "bysource"
 napoleon_custom_sections = [("Informs", "params_style")]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/server/tutorial.rst

@@ -199,6 +199,28 @@ The :attr:`.DeviceServer.sensors` attribute implements both a dictionary-like
 and a set-like interface to allow sensors to be added and removed. Sensor
 metadata (such as the name or type) should not be mutated after creation.
 
+.. _sensor-value-coercion:
+
+Sensor value coercion
+^^^^^^^^^^^^^^^^^^^^^
+When setting the value of a sensor, the value being set might not match the
+declared type of the sensor. For convenience, this is allowed in some cases,
+and the value will be coerced to the sensor type (by using it as a function).
+For example, one can set the value of an integer sensor using a numpy integer
+scalar, and it will automatically be converted to a Python integer.
+
+The table below lists these special cases. In all other cases, the value must
+be an instance of the sensor type (possibly a subclass). Using an unsupported
+type when setting the value will raise :exc:`TypeError`.
+
+====================   ==========================
+Sensor type            Value type
+====================   ==========================
+:class:`int`           :class:`numbers.Integral`
+:class:`float`         :class:`numbers.Real`
+:class:`~.Timestamp`   :class:`numbers.Real`
+====================   ==========================
+
 Automatic status
 ^^^^^^^^^^^^^^^^
 In many cases the status of a sensor (nominal, warn or error) is determined