Add public method docstrings.

tests/test_dummy_server.py

@@ -31,6 +31,7 @@ camera_stage_mapping.DEFAULT_SETTLING_TIME = 0  # skip the settling time for tes
 
 @pytest.fixture
 def thing_server():
+    """Yield a server with a very basic configuration."""
     temp_folder = tempfile.TemporaryDirectory()
     server = lt.ThingServer(settings_folder=temp_folder.name)
     server.add_thing(
@@ -43,36 +44,46 @@ def thing_server():
     server.add_thing(AutofocusThing(), "/autofocus/")
     server.add_thing(CameraStageMapper(), "/camera_stage_mapping/")
     assert os.path.exists(os.path.join(temp_folder.name, "camera/"))
-    # NB yield is important: otherwise, the temp folder gets deleted before the test runs
+    # Note: yield is important. If return is used the temp folder gets deleted
+    # before the test runs
     yield server
 
 
 @pytest.fixture
 def client(thing_server):
+    """Yield a FastAPI TestClient for the server."""
     with TestClient(thing_server.app) as client:
         yield client
 
 
 @pytest.fixture
 def slower_client(thing_server):
+    """Yield a FastAPI TestClient for the server with a slower moving stage.
+
+    The step time for the stage is 100 microseconds rather than
+    1 microsecond.
+    """
     thing_server.things["/stage/"].step_time = 0.0001
     with TestClient(thing_server.app) as client:
         yield client
 
 
 def test_autofocus(slower_client):
+    """Test Fast Autofocus can run doesn't raise an exception."""
     client = slower_client
     autofocus = lt.ThingClient.from_url("/autofocus/", client)
     _ = autofocus.fast_autofocus()
 
 
 def test_grab_jpeg(client):
+    """Check that grab_jpeg returns a blob that can be opened."""
     camera = lt.ThingClient.from_url("/camera/", client)
     blob = camera.grab_jpeg()
     _image = Image.open(blob.open())
 
 
 def test_capture_jpeg_metadata(client):
+    """Check that the position is encoded into the image metadata."""
     camera = lt.ThingClient.from_url("/camera/", client)
     blob = camera.capture_jpeg()
     image = Image.open(blob.open())
@@ -83,6 +94,7 @@ def test_capture_jpeg_metadata(client):
 
 
 def test_stage(client):
+    """Test moving th stage forwards and backwards."""
     stage = lt.ThingClient.from_url("/stage/", client)
     start = stage.position
     move = {"x": 1, "y": 2, "z": 3}
@@ -97,12 +109,13 @@ def test_stage(client):
 
 
 def test_capture_array(client):
+    """Capture array from simulation and check the size is as expected."""
     camera = lt.ThingClient.from_url("/camera/", client)
     array = np.asarray(camera.capture_array())
     assert array.shape == (240, 320, 3)
 
 
-# Currently this fails, not yet sure why.
 def test_camera_stage_mapping_calibration(client):
+    """Check that camera stage mapping can run without an exception."""
     camera_stage_mapping = lt.ThingClient.from_url("/camera_stage_mapping/", client)
     camera_stage_mapping.calibrate_xy()

tests/test_scan_planners.py

@@ -12,6 +12,7 @@ from .utilities import scan_test_helpers
 
 
 def test_enforce_xy_tuple():
+    """Check that 2 value tuples (or ValueErrors) are always returned."""
     bad_len_vals = [[1], [], (1,), (2, 4, 4), [1, 4, 5, 7]]
     bad_type_vals = ["hi", 1, {"this": "that"}, {1, 2}]
     for value in bad_len_vals + bad_type_vals:
@@ -23,6 +24,7 @@ def test_enforce_xy_tuple():
 
 
 def test_enforce_xyz_tuple():
+    """Check that 3 value tuples (or ValueErrors) are always returned."""
     bad_len_vals = [[1], [], (1,), (2, 4), [1, 4, 5, 7]]
     bad_type_vals = ["hi!", 1, {"this": "that"}, {1, 2, 3}]
     for value in bad_len_vals + bad_type_vals:
@@ -34,12 +36,14 @@ def test_enforce_xyz_tuple():
 
 
 def test_base_class_not_implemented():
+    """Check NotImplementedError is raised when initialising ScanPlanner directly."""
     intial_position = (100, 50)
     with pytest.raises(NotImplementedError):
         scan_planners.ScanPlanner(intial_position=intial_position)
 
 
 def test_v_basic_smart_spiral():
+    """Check that a SmartSpiral where the first image is not sample completes."""
     intial_position = (100, 50)
     planner_settings = {"dx": 50, "dy": 50, "max_dist": 10000}
     planner = scan_planners.SmartSpiral(
@@ -71,6 +75,7 @@ def test_v_basic_smart_spiral():
 
 
 def test_bad_smart_spiral_settings():
+    """Check that KeyError is raised when SmartSpiral is given bad settings."""
     intial_position = (100, 50)
 
     # Class init should raise error if no planner_settings dictionary set
@@ -195,6 +200,7 @@ def test_smart_spiral_first_few_pos():
 
 
 def test_smart_spiral_stops_on_max_dist():
+    """Test that if max distance is reached smart spiral really does stop."""
     intial_position = (0, 0)
     planner_settings = {"dx": 100, "dy": 100, "max_dist": 1000}
     # Create a planner