Add a default attribute to properties

[rwb27]

This PR adds a default attribute to properties, where it can be defined. Currently, this applies only to DataProperty and DataSetting as we don't have a neat way to define a default for functional properties. The default may be accessed in two ways:

1. As thing.properties['name'].default (from Python)
2. As the default key in the PropertyAffordance in the Thing Description.

I have also added a reset method, which resets the property to that value, if it exists.

If you attempt to reset or get the default of a FunctionalProperty we raise a new FeatureNotAvailable exception which I hope makes it clear.

The last step is to add a way to reset properties over HTTP. I am minded to make that a separate PR, because:

• The current (standard compliant) PR already makes it possible to reset, because the default value is exposed in the TD.
• There's no WoT standard way to reset properties to default, as far as I know.

I can see three sensible ways to expose resetting over HTTP:

• Add an extra POST endpoint: POST http://my.server:5000/my_thing/my_property/reset
• Add a DELETE endpoint at the property URL DELETE http://my.server:5000/my_thing/my_property
• Add an action that takes the property name as a parameter: POST http://my.server:5000/my_thing/reset_property with payload my_property.

Of these, I think we discussed DELETE before and nobody liked it. I think the first one is clearest if we ignore WoT standards. The action is fine, but feels ugly, and currently it involves a lot more HTTP requests than it really needs, as the action would need polling to completion to find out whether it was successful.

I'd be happy to merge this in its present state (i.e. without extra endpoints to reset) and we can discuss what to do about resetting. If we get a consensus quickly, I have also written the code to do resets, but not yet tested it.

Closes #257

[barecheck]

Barecheck - Code coverage report

Total: 96.35%

Your code coverage diff: 0.01% ▴

Uncovered files and lines

File	Lines
src/labthings_fastapi/properties.py	504, 794, 798, 821-824, 896, 915, 1166

[julianstirling]

I've tried to go through it. I think it is going to be annoying to have some property resetable and others not so I would really prefer FunctionalProperties to be resettable as quote a few of our properties have side effects and are still functional.

This being said it isn't too clear to me how the extra methods for a descriptor are defined hence some of the questions that go deeper.

[julianstirling]

It would be nice if FunctionalProperty could allow setting a reset method as:

@myprop.reset
def _reset_myprop(self):
    """Resetting my property."""
    self._myprop = 1066

or even

myprop.default = 1066

[julianstirling]

Actually would it be possible to pass an an argument to the decorator?

_my_property=1066

@lt.property(default=1066):
def my_property(self):
    ...

I suppose could even then be:

_my_property=1066

@lt.property(default=_my_property):
def my_property(self):
    ...

[rwb27]

Having a reset function for a functional property makes sense to me, and I've deliberately left it so that this should be quite simple to implement. I was trying to keep this PR, so I've not added that feature in here, though if I'm adding more commits to add a reset endpoint, I could also add resetting for functional properties.

That said, if you've already reviewed this, it would be not unreasonable to merge it, and then add reset for functional properties in a future one.

Having a default for functional properties feels slightly odd to me, though as I write it I can't fully explain why. I think it's because the default for a DataProperty is the value it starts at - the same isn't necessarily true for a FunctionalProperty.

I really need to add side-effects! But that is an entirely separate PR...

[julianstirling]

Created #297. It would be good to get it in for the same release as a feature asymmetry for functional properties makes it hard to adopt the feature for a consistent UI.

[rwb27]

Actually would it be possible to pass an an argument to the decorator?

I think this would be nasty to implement. I'm not saying a hard no, but I would be strongly in favour of providing a different syntax. The problem is that lt.property(default=<whatever>) is the same signature we use to create a DataProperty descriptor, so it would then require us to add a __call__ method to DataProperty such that the same class can function either as a decorator or a descriptor. That bakes my brain quite badly.

I think it would be absolutely fine to allow:

class MyThing(lt.Thing):
    @lt.property
    def myprop(self) -> int:
        return 42

    myprop.default=42

default_factory could be done the same way, or exposed as a decorator - with perhaps a little thought as to whether the default factory ought to have access to self or not. Perhaps we'd actually want to suggest something like @myprop.default_factory_method to be explicit about that.

Similarly, @myprop.resetter would be a reasonable decorator to allow a reset operation.