Property side-effects with @lt.on_set by rwb27 · Pull Request #331 · labthings/labthings-fastapi

rwb27 · 2026-05-05T22:33:19Z

This adds basic side-effects to properties, along with some tests.

Methods may be decorated with @lt.on_set. The method will then be run whenever the property is set.

To-do:

Add to public API docs
Add to conceptual docs on data properties, and link from functional properties
Test this against DataSetting as well as properties
Add at least one example to a feature branch in the OFM codebase

This is intended to allow for basic validation or synchronisation, where the full power of a functional property is not needed. It runs before validation (if enabled), to allow coercion and to catch None in case someone's forgotten to return a value from on_set. This could become configurable in the future.

It may be desirable to also allow a similar decorator to add a validator to the Pydantic model, but that might require more thought, and is not for this PR.

Closes #237

barecheck · 2026-05-05T22:34:47Z

Barecheck - Code coverage report

Total: 97.03%

Your code coverage diff: 0.03% ▴

Uncovered files and lines

File	Lines
src/labthings_fastapi/properties.py	485, 503, 583, 1019, 1023, 1119, 1142, 1558

rwb27 · 2026-05-06T08:29:29Z

From @julianstirling out-of-band:

Simulation camera updates the canvas on certain propery changes
Also when we have mapping thingslots we check if the key is available in the mapping when we change our selectors

This adds basic side-effects to properties, along with some tests.

Running the `on_set` function before validating the property (if enabled) has a few advantages: * If the user has forgotten to return a value, it's more likely to catch the `None` if it's invalid. * It allows user code

This adds `on_set` to the public API docs and to the conceptual page on properties. It also tidies up a couple of decorators in the public API docs.

This now matches the test code. I've also improved testing and error checking, so that naming errors give a custom exception, and said exception should happen earlier with a stack trace pointing to the problematic method. I've added tests of the on_set descriptor's __get__ method too, to ensure it works as expected.

bprobert97 · 2026-06-01T08:50:51Z

+    See the description at :ref:`properties_on_set` for an example.
+
+    This decorator causes a method to be called whenever a property
+    is set. The method must return the value (and may modify it), but


Suggested change

is set. The method must return the value (and may modify it), but

is set. The method must return the value (and may modify it), or raise an exception, but

bprobert97 · 2026-06-01T08:54:21Z

+            # Note: this is also checked in __set_name__, but it raises a more helpful
+            # error if it's checked here.
+            msg = f"On-set function '{property_name}' overwrites its property: "
+            msg += "rename it."


Why is this separate from the rest of the msg?

bprobert97 · 2026-06-01T08:55:24Z

+        prop = getattr(owner, self.property_name, None)
+        if not isinstance(prop, DataProperty):
+            msg = "On-set functions may only be attached to data properties. "
+            msg += f"'{self.property_name}' is not a data property"


Why is this separate from the rest of the msg?

bprobert97 · 2026-06-01T08:58:15Z

+    class Example(lt.Thing):
+        intprop: int = prop_or_setting(default=0)
+
+        shadow: int = lt.property(default=0)


Can we add a comment explaining what shadow is?

bprobert97 · 2026-06-01T09:01:02Z

+    with pytest.raises(ValueError, match="Can't be negative"):
+        thing.intprop = -1


Could we then test that thing.intprop and thing.shadow are still 42? If an error is raised, the previous value should remain

bprobert97 · 2026-06-01T09:02:06Z

+    assert thing._on_set_intprop.args == (thing,)
+
+
+def test_bad_on_set_definitions():


Adding some comments within each of the sub-tests here would be useful

bprobert97 · 2026-06-01T09:04:22Z

+
+There are a few important points to note when using `lt.on_set` in your code:
+
+* Your function *must* return a value, which will be used as the property's value. This allows `lt.on_set` to coerce values to valid ones.


Are any errors or warning messages raised if the function doesn't return a value in the on_set function?
Might be helpful to a user, and we can write a test for it

julianstirling · 2026-06-01T11:38:42Z

+* Your function will run every time the property is set, meaning it should complete quickly. If this function takes longer than a second, it is likely to cause HTTP timeouts.
+* It's ok to communicate with hardware, but you are likely to need to acquire any locks you need manually.
+* If global locking is enabled, the global lock will already have been acquired when your function is run: there's no need to acquire it again.
+* You do not need to "remember" the value as you would for a regular Python property - the data property already takes care of that.


I don't understand what this bullet point is trying to say?

rwb27 · 2026-06-01T14:00:37Z

Very helpful suggestion from @julianstirling: we should define (and implement, and test) what happens if an exception is raised by on_set.

rwb27 force-pushed the side-effects-for-properties branch from 0c864e0 to 1d8bd1c Compare May 6, 2026 10:35

rwb27 added this to the v0.3.0 milestone May 7, 2026

rwb27 force-pushed the side-effects-for-properties branch 2 times, most recently from 2e460ba to 3045760 Compare May 26, 2026 13:15

rwb27 added 5 commits May 27, 2026 13:42

First implementation of @lt.on_set

0529ec9

This adds basic side-effects to properties, along with some tests.

Run on_set before validating.

832c3ea

Running the `on_set` function before validating the property (if enabled) has a few advantages: * If the user has forgotten to return a value, it's more likely to catch the `None` if it's invalid. * It allows user code

Add documentation

93a3671

This adds `on_set` to the public API docs and to the conceptual page on properties. It also tidies up a couple of decorators in the public API docs.

Parametrize test for on_set to add settings.

7e4535d

rwb27 force-pushed the side-effects-for-properties branch from c7834cf to 7e4535d Compare May 27, 2026 12:42

rwb27 mentioned this pull request May 28, 2026

Better event handling #256

Open

bprobert97 requested changes Jun 1, 2026

View reviewed changes

julianstirling reviewed Jun 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Property side-effects with @lt.on_set#331

Property side-effects with @lt.on_set#331
rwb27 wants to merge 5 commits into
mainfrom
side-effects-for-properties

rwb27 commented May 5, 2026 •

edited

Loading

Uh oh!

barecheck Bot commented May 5, 2026 •

edited

Loading

Uh oh!

rwb27 commented May 6, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

bprobert97 Jun 1, 2026

Uh oh!

julianstirling Jun 1, 2026

Uh oh!

rwb27 commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	is set. The method must return the value (and may modify it), but
	is set. The method must return the value (and may modify it), or raise an exception, but

		with pytest.raises(ValueError, match="Can't be negative"):
		thing.intprop = -1

		assert thing._on_set_intprop.args == (thing,)


		def test_bad_on_set_definitions():


		There are a few important points to note when using `lt.on_set` in your code:

		* Your function must return a value, which will be used as the property's value. This allows `lt.on_set` to coerce values to valid ones.

Conversation

rwb27 commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

barecheck Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Barecheck - Code coverage report

Uh oh!

rwb27 commented May 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rwb27 commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rwb27 commented May 5, 2026 •

edited

Loading

barecheck Bot commented May 5, 2026 •

edited

Loading