Clarify Coder API examples

Author: SiboVG

docs/coder-api.md

@@ -28,13 +28,14 @@ steps.
 ## Basic Script
 
 This script lowers the moving assembly by 10 mm, waits 5 seconds, then raises it by 10 mm.
+The examples use keyword arguments so the distance, speed, and acceleration units stay clear.
 
 ```python
 self.enable_motor()
 
-self.move_down(10, 5)
-self.sleep(5)
-self.move_up(10, 2)
+self.move_down(distance_mm=10, speed_mm_s=5)
+self.sleep(seconds=5)
+self.move_up(distance_mm=10, speed_mm_s=2)
 
 self.disable_motor()
 ```
@@ -66,8 +67,8 @@ self.move_down(distance_mm, speed_mm_s, acceleration_mm_s2=None)
 Examples:
 
 ```python
-self.move_down(10, 5)
-self.move_down(10, 5, 10)
+self.move_down(distance_mm=10, speed_mm_s=5)
+self.move_down(distance_mm=10, speed_mm_s=5, acceleration_mm_s2=10)
 ```
 
 The first example lowers the moving assembly by 10 mm at 5 mm/s. The second also sets acceleration to 10 mm/s^2.
@@ -81,8 +82,8 @@ self.move_up(distance_mm, speed_mm_s, acceleration_mm_s2=None)
 Examples:
 
 ```python
-self.move_up(10, 5)
-self.move_up(10, 5, 10)
+self.move_up(distance_mm=10, speed_mm_s=5)
+self.move_up(distance_mm=10, speed_mm_s=5, acceleration_mm_s2=10)
 ```
 
 ### Home the Motor
@@ -109,9 +110,9 @@ self.move_to_position(position_mm, speed_mm_s=None, acceleration_mm_s2=None)
 Examples:
 
 ```python
-self.move_to_position(10)
-self.move_to_position(10, 5)
-self.move_to_position(10, 5, 10)
+self.move_to_position(position_mm=10)
+self.move_to_position(position_mm=10, speed_mm_s=5)
+self.move_to_position(position_mm=10, speed_mm_s=5, acceleration_mm_s2=10)
 ```
 
 ### Wait
@@ -123,7 +124,7 @@ self.sleep(seconds)
 Example:
 
 ```python
-self.sleep(5)
+self.sleep(seconds=5)
 ```
 
 ## Example: Simple Dip Cycle
@@ -132,13 +133,13 @@ self.sleep(5)
 self.enable_motor()
 
 # Move into the liquid.
-self.move_down(20, 4)
+self.move_down(distance_mm=20, speed_mm_s=4)
 
 # Wait while submerged.
-self.sleep(10)
+self.sleep(seconds=10)
 
 # Withdraw slowly.
-self.move_up(20, 1)
+self.move_up(distance_mm=20, speed_mm_s=1)
 
 self.disable_motor()
 ```
@@ -149,10 +150,10 @@ self.disable_motor()
 self.enable_motor()
 
 for cycle in range(3):
-    self.move_down(15, 4)
-    self.sleep(5)
-    self.move_up(15, 2)
-    self.sleep(10)
+    self.move_down(distance_mm=15, speed_mm_s=4)
+    self.sleep(seconds=5)
+    self.move_up(distance_mm=15, speed_mm_s=2)
+    self.sleep(seconds=10)
 
 self.disable_motor()
 ```

src/dip_coater/code_editor_init_content.py

@@ -19,12 +19,12 @@
 self.enable_motor()
 
 # == MOVE DOWN ==
-self.move_down(distance_down, speed_down)
+self.move_down(distance_mm=distance_down, speed_mm_s=speed_down)
 
 # == WAIT ==
-self.sleep(wait_time)
+self.sleep(seconds=wait_time)
 
 # == MOVE UP ==
-self.move_up(distance_up, speed_up)
+self.move_up(distance_mm=distance_up, speed_mm_s=speed_up)
 
 self.disable_motor()

src/dip_coater/coder_API.md

@@ -5,23 +5,23 @@ self.disable_motor()        # Disarm the motor
 # Move the motor down by distance_mm at speed_mm_s speed and (optional) acceleration_mm_s acceleration
 self.move_down(distance_mm, speed_mm_s, acceleration_mm_s2=None)
 ### Examples:
-self.move_down(10, 5)       # Move the coater down by 10 mm at 5 mm/s
-self.move_down(10, 5, 10)   # Move the coater down by 10 mm at 5 mm/s and 10 mm/s^2 acceleration
+self.move_down(distance_mm=10, speed_mm_s=5)
+self.move_down(distance_mm=10, speed_mm_s=5, acceleration_mm_s2=10)
 
 # Move the motor up by distance_mm at <speed_mm_s> speed and (optional) <acceleration_mm_s> acceleration
-self.move_down(distance_mm, speed_mm_s, acceleration_mm_s2=None)
+self.move_up(distance_mm, speed_mm_s, acceleration_mm_s2=None)
 ### Examples:
-self.move_up(10, 5)         # Move the coater up by 10 mm at 5 mm/s
-self.move_up(10, 5, 10)     # Move the coater up by 10 mm at 5 mm/s and 10 mm/s^2 acceleration
+self.move_up(distance_mm=10, speed_mm_s=5)
+self.move_up(distance_mm=10, speed_mm_s=5, acceleration_mm_s2=10)
 
 # Home the motor (needed to move to motor to absolute positions)
 self.home_motor(home_up=True)    # Home the motor. If home_up is True, the motor will move up until the top limit switch is triggered. If home_up is False, the motor will move down until the bottom limit switch is triggered.
 
 # Move the motor to an absolute position (in mm)
-self.move_to_position(self, position_mm, speed_mm_s=None, acceleration_mm_s2=None, home_up=True)
+self.move_to_position(position_mm, speed_mm_s=None, acceleration_mm_s2=None)
 ### Examples:
-self.move_to_position(10)           # Move the coater to 10 mm, using the last set speed and acceleration
-self.move_to_position(10, 5)        # Move the coater to 10 mm at 5 mm/s
+self.move_to_position(position_mm=10)
+self.move_to_position(position_mm=10, speed_mm_s=5)
 
-self.sleep(5)               # Sleep for 5 seconds
-```
+self.sleep(seconds=5)       # Sleep for 5 seconds
+```

src/dip_coater/help.md

@@ -62,21 +62,20 @@ You can create custom control routines using the coder in the `Coder` tab. To do
 following functions (the so-called 'Coder API'):
 - `self.enable_motor()`: arm the motor
 - `self.disable_motor()`: disarm the motor
-- `self.move_down(distance_mm, speed_mm_s, acceleration_mm_s=None)`: move the motor down by supplying the following parameters:
+- `self.move_down(distance_mm, speed_mm_s, acceleration_mm_s2=None)`: move the motor down by supplying the following parameters:
   - `distance_mm`: the distance in mm to move down
   - `speed_mm_s`: the speed in mm/s to move down
-  - `acceleration_mm_s`: (optional) the acceleration in mm/s^2 to move down (leave empty for default acceleration)
-- `self.move_up(distance_mm, speed_mm_s, acceleration_mm_s=None)`: move the motor up by supplying the following parameters:
+  - `acceleration_mm_s2`: (optional) the acceleration in mm/s^2 to move down (leave empty for default acceleration)
+- `self.move_up(distance_mm, speed_mm_s, acceleration_mm_s2=None)`: move the motor up by supplying the following parameters:
   - `distance_mm`: the distance in mm to move up
   - `speed_mm_s`: the speed in mm/s to move up
-  - `acceleration_mm_s`: (optional) the acceleration in mm/s^2 to move up (leave empty for default acceleration)
+  - `acceleration_mm_s2`: (optional) the acceleration in mm/s^2 to move up (leave empty for default acceleration)
 - `self.home_motor(home_up=True)`: home the motor, necessary for moving to absolute positions
   - `home_up` (optional) if the motor was homed at the top limit switch, set to `True`, if homed using the bottom limit switch, set `False`
-- `self.move_to_position(self, position_mm, speed_mm_s=None, acceleration_mm_s2=None, home_up=True)`: move the motor to an absolute position in mm
+- `self.move_to_position(position_mm, speed_mm_s=None, acceleration_mm_s2=None)`: move the motor to an absolute position in mm
   - `position_mm`: the absolute position in mm to move to
   - `speed_mm_s`: (optional) the speed in mm/s to move to the absolute position (leave empty to use the last set speed)
   - `acceleration_mm_s2`: (optional) the acceleration in mm/s^2 to move to the absolute position (leave empty to use the last set acceleration)
-  - `home_up`: (optional) if the motor was homed at the top limit switch, set to `True`, if homed using the bottom limit switch, set `False`
 - `self.sleep(seconds)`: wait for a number of seconds
 
 For example, to move the motor down by 10 mm at a speed of 5 mm/s, then wait 5 seconds, and then move up by 10 mm at 2 mm/s,
@@ -87,13 +86,13 @@ you can write the following code in the `Coder` tab:
 self.enable_motor()
 
 # Move down
-self.move_down(10, 5)
+self.move_down(distance_mm=10, speed_mm_s=5)
 
 # Wait for 5 seconds
-self.sleep(5)
+self.sleep(seconds=5)
 
 # Move up
-self.move_up(10, 2)
+self.move_up(distance_mm=10, speed_mm_s=2)
 
 # Disarm the motor
 self.disable_motor()

src/dip_coater/widgets/coder.py

@@ -288,7 +288,7 @@ def home_motor(self, home_up: bool = None):
     def move_to_position(
         self,
         position_mm: float,
-        speed_mm_s: float,
+        speed_mm_s: float = None,
         acceleration_mm_s2: float = None,
         home_up: bool = None,
     ):

src/test/test_coder.py

@@ -1,4 +1,5 @@
 import asyncio
+import inspect
 from types import SimpleNamespace
 
 import pytest
@@ -51,6 +52,12 @@ def test_coder_api_refuses_new_commands_after_stop_request():
     assert motor_controls.moves == []
 
 
+def test_coder_move_to_position_allows_default_speed():
+    signature = inspect.signature(Coder.move_to_position)
+
+    assert signature.parameters["speed_mm_s"].default is None
+
+
 def test_coder_builds_python_highlighted_editor():
     editor = Coder.build_code_editor('def coat():\n    print("Hello, World!")\n')
 

src/test/test_docs_content.py

@@ -35,6 +35,31 @@ def test_coder_docs_explain_trusted_scripts_and_stop_button():
     assert "between Coder API calls" in coder_docs
 
 
+def test_coder_examples_use_explicit_keyword_arguments():
+    root = Path(__file__).parents[2]
+    docs_coder = (root / "docs" / "coder-api.md").read_text()
+    bundled_coder = (root / "src" / "dip_coater" / "coder_API.md").read_text()
+    help_docs = (root / "src" / "dip_coater" / "help.md").read_text()
+    initial_code = (
+        root / "src" / "dip_coater" / "code_editor_init_content.py"
+    ).read_text()
+
+    assert "self.move_down(distance_mm=10, speed_mm_s=5)" in docs_coder
+    assert (
+        "self.move_down(distance_mm=10, speed_mm_s=5, acceleration_mm_s2=10)"
+        in docs_coder
+    )
+    assert "self.move_up(distance_mm=10, speed_mm_s=5)" in bundled_coder
+    assert "self.move_to_position(position_mm=10, speed_mm_s=5)" in bundled_coder
+    assert "self.move_down(distance_mm=10, speed_mm_s=5)" in help_docs
+    assert (
+        "self.move_down(distance_mm=distance_down, speed_mm_s=speed_down)"
+        in initial_code
+    )
+    assert "self.move_down(10, 5)" not in docs_coder
+    assert "self.move_up(10, 2)" not in help_docs
+
+
 def test_run_docs_explain_session_log_file():
     run_docs = (Path(__file__).parents[2] / "docs" / "run-the-app.md").read_text()