Use a _set_ prefix on property setters.

docs/source/properties.rst

@@ -83,11 +83,15 @@ Functional properties may also have a "setter" method, which is called when the
             return self.my_property * 2
 
         @twice_my_property.setter
-        def twice_my_property(self, value: int):
+        def _set_twice_my_property(self, value: int):
             """Set the value of twice_my_property."""
             self.my_property = value // 2
 
-Adding a setter makes the property read-write (if only a getter is present, it must be read-only). 
+Adding a setter makes the property read-write (if only a getter is present, it must be read-only).
+
+.. note::
+
+    The setter method for regular Python properties is usually named the same as the property itself (e.g. ``def twice_my_property(self, value: int)``). Unfortunately, doing this with LabThings properties causes problems for static type checkers such as `mypy`\ . We therefore recommend you prefix setters with ``_set_`` (e.g. ``def _set_twice_my_property(self, value: int)``). This is optional, and doesn't change the way the property works - but it is useful if you need `mypy` to work on your code, and don't want to ignore every property setter.
 
 It is possible to make a property read-only for clients by setting its ``readonly`` attribute: this has the same behaviour as for data properties.
 
@@ -105,7 +109,7 @@ It is possible to make a property read-only for clients by setting its ``readonl
             return self.my_property * 2
 
         @twice_my_property.setter
-        def twice_my_property(self, value: int):
+        def _set_twice_my_property(self, value: int):
             """Set the value of twice_my_property."""
             self.my_property = value // 2
 
@@ -143,7 +147,7 @@ We can modify the previous example to show how to add constraints to both data a
             return self._humidity
 
         @humidity.setter
-        def humidity(self, value: float):
+        def _set_humidity(self, value: float):
             """Set the current humidity percentage."""
             self._humidity = value
 

src/labthings_fastapi/base_descriptor.py

@@ -124,7 +124,7 @@ def prop4(self):
                 return True
 
             @prop4.setter
-            def set_prop4(self, val):
+            def _set_prop4(self, val):
                 "A setter for prop4 that is not named prop4."
                 pass
 

src/labthings_fastapi/properties.py

@@ -27,7 +27,7 @@
             return self.target - self.count
 
         @remaining.setter
-        def remaining(self, value: int) -> None:
+        def _set_remaining(self, value: int) -> None:
             self.target = self.count + value
 
 The first two properties are simple variables: they may be read and assigned
@@ -686,11 +686,11 @@
         self._fget: ValueGetter = fget
         self._type = return_type(self._fget)
         if self._type is None:
             msg = (
                 f"{fget} does not have a valid type. "
                 "Return type annotations are required for property getters."
             )
             raise MissingTypeError(msg)
         self._fset: ValueSetter | None = None
         self.readonly: bool = True
 
@@ -713,10 +713,10 @@
         :param fget: The new getter function.
         :return: this descriptor (i.e. ``self``). This allows use as a decorator.
         """
         self._fget = fget
         self._type = return_type(self._fget)
         self.__doc__ = fget.__doc__
         return self
 
     def setter(self, fset: ValueSetter) -> Self:
         r"""Set the setter function of the property.
@@ -740,7 +740,7 @@
                     return self._myprop
 
                 @myprop.setter
-                def set_myprop(self, val: int) -> None:
+                def _set_myprop(self, val: int) -> None:
                     self._myprop = val
 
                 myprop.readonly = True  # Prevent client code from setting it
@@ -753,7 +753,7 @@
             ``mypy`` raising an error that the getter has been redefined with a
             different type. The behaviour is identical whether the setter and getter
             have the same name or not. The only difference is that the `.Thing`
-            will have an additional method called ``set_myprop`` in the example
+            will have an additional method called ``_set_myprop`` in the example
             above.
 
         :param fset: The new setter function.
@@ -788,7 +788,7 @@
             # Don't return the descriptor if it's named differently.
             # see typing notes in docstring.
             return fset  # type: ignore[return-value]
         return self
 
     def instance_get(self, obj: Thing) -> Value:
         """Get the value of the property.
@@ -807,7 +807,7 @@
         :raises ReadOnlyPropertyError: if the property cannot be set.
         """
         if self.fset is None:
             raise ReadOnlyPropertyError(f"Property {self.name} of {obj} has no setter.")
         self.fset(obj, value)
 
 
@@ -940,7 +940,7 @@
 
         :raises NotImplementedError: this method should be implemented in subclasses.
         """
         raise NotImplementedError("This method should be implemented in subclasses.")
 
 
 class DataSetting(DataProperty[Value], BaseSetting[Value], Generic[Value]):

tests/old_dependency_tests/test_dependency_metadata.py

@@ -25,7 +25,7 @@ def a(self):
         return self._a
 
     @a.setter
-    def a(self, value):
+    def _set_a(self, value):
         self._a = value
 
     @property

tests/test_base_descriptor.py

@@ -266,13 +266,13 @@ def prop1(self):
                 return False
 
             @prop1.setter
-            def set_prop1(self, val):
+            def _set_prop1(self, val):
                 pass
 
     # The exception occurs at the end of the class definition, so check we include
     # the property names.
     assert "prop1" in str(excinfo.value)
-    assert "set_prop1" in str(excinfo.value)
+    assert "_set_prop1" in str(excinfo.value)
 
     # For good measure, check reuse across classes is also prevented.
     class FirstExampleClass:

tests/test_properties.py

@@ -44,7 +44,7 @@ def floatprop(self) -> float:
         return self._float
 
     @floatprop.setter
-    def floatprop(self, value: float):
+    def _set_floatprop(self, value: float):
         self._float = value
 
     @lt.action
@@ -82,7 +82,7 @@ def constrained_functional_int(self) -> int:
         return self._constrained_functional_int
 
     @constrained_functional_int.setter
-    def set_constrained_functional_int(self, value: int):
+    def _set_constrained_functional_int(self, value: int):
         self._constrained_functional_int = value
 
     constrained_functional_int.constraints = {"ge": 0, "le": 10}
@@ -92,7 +92,7 @@ def constrained_functional_str_setting(self) -> str:
         return self._constrained_functional_str_setting
 
     @constrained_functional_str_setting.setter
-    def set_constrained_functional_str_setting(self, value: str):
+    def _set_constrained_functional_str_setting(self, value: str):
         self._constrained_functional_str_setting = value
 
     constrained_functional_str_setting.constraints = {

tests/test_property.py

@@ -271,14 +271,14 @@ def prop(self) -> bool:
             """An example getter."""
 
         @prop.setter
-        def set_prop(self, val: bool) -> None:
+        def _set_prop(self, val: bool) -> None:
             """A setter named differently."""
             pass
 
     assert isinstance(Example.prop, FunctionalProperty)
     assert Example.prop.name == "prop"
-    assert not isinstance(Example.set_prop, FunctionalProperty)
-    assert callable(Example.set_prop)
+    assert not isinstance(Example._set_prop, FunctionalProperty)
+    assert callable(Example._set_prop)
 
 
 def test_premature_api_and_affordance(mocker):

tests/test_settings.py

@@ -36,7 +36,7 @@ def floatsetting(self) -> float:
         return self._floatsetting
 
     @floatsetting.setter
-    def floatsetting(self, value: float):
+    def _set_floatsetting(self, value: float):
         self._floatsetting = value
 
     @lt.setting
@@ -50,7 +50,7 @@ def localonlysetting(self) -> str:
         return self._localonlysetting
 
     @localonlysetting.setter
-    def localonlysetting(self, value: str):
+    def _set_localonlysetting(self, value: str):
         self._localonlysetting = value
 
     localonlysetting.readonly = True

tests/test_websocket.py

@@ -31,7 +31,7 @@ def funcprop(self) -> int:
         return 0
 
     @funcprop.setter
-    def set_funcprop(self, val: int) -> None:
+    def _set_funcprop(self, val: int) -> None:
         pass
 
     @lt.action

typing_tests/thing_properties.py

@@ -217,7 +217,7 @@ def intprop2(self) -> int:
         return 0
 
     @intprop2.setter
-    def set_intprop2(self, value: int) -> None:
+    def _set_intprop2(self, value: int) -> None:
         """Setter for intprop2."""
         pass
 
@@ -232,7 +232,7 @@ def intprop3(self) -> int:
         return 0
 
     @intprop3.setter
-    def set_intprop3(self, value: str) -> None:
+    def _set_intprop3(self, value: str) -> None:
         """Setter for intprop3. It's got the wrong type so should fail."""
         pass
 
@@ -246,7 +246,7 @@ def fprop(self) -> int:
         return 0
 
     @fprop.setter
-    def set_fprop(self, value: int) -> None:
+    def _set_fprop(self, value: int) -> None:
         """Setter for fprop. Type checking should pass."""
         pass