fix: deprecate RangeBearingSensor's animate kwarg instead of erroring (#599)

animate was silently renamed to plot in 68292ae/93be21f9 (2023) with
no back-compat shim, so existing scripts using the old name hit an
unexplained TypeError from SensorBase.__init__ instead of a clear
deprecation warning. A stray comment at the old call site
("TODO change plot option to animate, but RVC3 uses plot") shows this
was known and only partially addressed.

Author: petercorke

src/roboticstoolbox/mobile/sensors.py

@@ -1,4 +1,5 @@
 from abc import ABC
+import warnings
 import numpy as np
 import scipy as sp
 from math import pi, sin, cos
@@ -56,6 +57,7 @@ def __init__(
         delay=0.1,
         seed=0,
         verbose=False,
+        **kwargs,
     ):
         """Sensor.Sensor Sensor object constructor
         %
@@ -73,6 +75,12 @@ def __init__(
         # - Animation shows a ray from the vehicle position to the selected
         #   landmark.
         """
+        if kwargs:
+            raise TypeError(
+                f"SensorBase.__init__() got unexpected keyword argument(s): "
+                f"{', '.join(kwargs)}"
+            )
+
         self._robot = robot
         self._map = map
         self._every = every
@@ -266,9 +274,19 @@ def __init__(
             >>> print(sensor)
 
         :seealso: :class:`~roboticstoolbox.mobile.LandmarkMap` :class:`~roboticstoolbox.mobile.EKF`
+
+        .. deprecated:: the ``animate`` keyword is deprecated, use ``plot``
+            instead.
         """
 
-        # TODO change plot option to animate, but RVC3 uses plot
+        animate = kwargs.pop("animate", None)
+        if animate is not None:
+            warnings.warn(
+                "animate is deprecated, use plot instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            plot = animate
 
         # call the superclass constructor
         super().__init__(robot, map, **kwargs)

tests/test_mobile.py

@@ -108,6 +108,15 @@ def test_init(self):
 
         self.assertIsInstance(str(self.rs), str)
 
+    def test_animate_deprecated(self):
+
+        with self.assertWarns(DeprecationWarning):
+            rs = RangeBearingSensor(self.veh, self.map, animate=True)
+        self.assertTrue(rs._animate)
+
+        with self.assertRaises(TypeError):
+            RangeBearingSensor(self.veh, self.map, bogus_kwarg=True)
+
     def test_reading(self):
 
         z, lm_id = self.rs.reading()