You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To provide a getter-setter (& deleter) method is optional. If none given, when the property is set/written, the value
53
-
is stored inside the instance's `__dict__` under the name `<given property name >_param_value`
54
-
(for example, `serial_number_param_value` for `serial_number`). In layman's terms,
55
-
`__dict__` is the internal map where the attributes of the object are stored by python.
51
+
To provide a getter-setter (& deleter) method is optional.
56
52
57
-
When a value assignment was never called on the property, `default` is returned when reading the value. This is the purpose of the `default` argument. If a setter/deleter is given, getter is mandatory. In this case, `default` is also ignored & the getter is always executed.
53
+
If none given, when the property is set/written, the value is stored inside the instance's `__dict__` under the name `<given property name>_param_value`
54
+
(for example, `serial_number_param_value` for `serial_number`). In layman's terms, `__dict__` is the internal map where the attributes of the object are stored by python.
55
+
56
+
When a value assignment was never called on the property, `default` is returned when reading the value. If a setter/deleter is given, getter is mandatory. In this case, `default` is also ignored & the getter is always executed.
If default is desirable, one has to return it manually in the getter method by accessing the property [descriptor object directly](../#__codelineno-2-15).
@@ -82,12 +80,12 @@ instead of instance's `__dict__` (instance's attribute).
82
80
Custom getter-setter-deleter are not compatible with this option currently. `class_member` takes precedence over fget-fset-fdel,
`class_member` can still be used with a default value if there is no custom fget-fset-fdel.
@@ -96,57 +94,60 @@ which in turn has precedence over `default`.
96
94
97
95
setting `remote` to False makes the inaccessible to a client but accessible to the object locally. This is still useful to type-restrict python attributes to provide an interface to other developers using your class, for example, when someone else inherits your `Thing`. For example, the `Thing`'s `logger` is implemented in this fashion:
This is also currently applicable only when set operations are called by clients. Local set operations are always executed irrespective of the state machine state. A get operation is always executed as well even from the clients irrespective of the state.
125
+
This is also currently applicable only when set operations are called by clients. Local set operations are always executed irrespective of the state machine state. A get operation is always executed even from the clients irrespective of the state.
125
126
126
127
## `observable`
127
128
128
129
Observable properties push change events when the property is set or read. This is useful when one wants to monitor the
129
130
property for changes without polling from the client. The payload of the change event is the new value of the property.
`metadata` is a dictionary that allows storing arbitrary metadata about the property. For example, one can store units of the physical
139
+
`metadata` is a free-flow dictionary that allows storing arbitrary metadata about the property. For example, one can store units of the physical
139
140
quantity.
140
141
141
142
## `db_init`, `db_commit` & `db_persist`
142
143
143
-
Properties can be stored in a file or a database and loaded from them when the `Thing` is stopped and restarted. This is useful especially to preserve the settings of the hardware when the server undergoes a restart, either through system restart or any other reason.
144
+
Properties can be stored in a file or a database and loaded from them when the `Thing` is stopped and restarted. This is useful especially to preserve the settings of the hardware when the server undergoes a restart, either through system restart, server crash or any other reason.
144
145
145
-
-`db_init` only loads a property from database, when the value is changed, its not written back to the database.
146
+
-`db_init` only loads a property from database. When the property value is changed, its not written back to the database.
146
147
For this option, the value has to be pre-created in the database in some other fashion.
147
148
148
-
-`db_commit` only writes the value into the database when an assignment is called.
149
+
-`db_commit` only writes the value into the database when an assignment/write operation is called.
149
150
150
-
-`db_persist`both stores and loads the property from the database.
151
+
-`db_persist` stores and loads the property from the database. property value is assigned after `__init__()` method, therefore its recommended to ensure that the device connection is established at `__init__()` itself. Other, errors should be expected.
151
152
152
153
Supported databases are MySQL, Postgres & SQLite currently. Look at database how-to for supply database configuration.
Basically, check the types, manipulate your data if necessary and pass it to the parent. It is necessary to use the `instance_descriptor` decorator as shown above to allow `class_member` option to function correctly. If the `Property` will not be a `class_member`, this decorator can be skipped.
19
+
- check metadata options like `readonly`, `constant` etc.
20
+
- check the type of the input value
21
+
- manipulate your data if necessary
22
+
- pass it to the parent.
20
23
21
-
Further, the parent class [`Property` takes care](https://github.com/VigneshVSV/hololinked/blob/main/hololinked/server/property.py) of allocating an instance variable, checking `constant`, `readonly`, pushing change events, writing the value to the database etc. To avoid double checking of certain options like `readonly` and `constant`, its better to carry out the validation and coercion within the method `validate_and_adapt()` instead of `__set__`:
24
+
It is necessary to use the `instance_descriptor` decorator as shown above to allow `class_member` option to function correctly. If the `Property` will not be a `class_member`, this decorator can be skipped.
25
+
26
+
Further, the parent class [`Property` takes care](https://github.com/VigneshVSV/hololinked/blob/main/hololinked/core/property.py) of allocating an instance variable, checking `constant`, `readonly`, pushing change events, writing the value to the database etc. Therefore, to avoid redundancy, its recommended to implement a `validate_and_adapt()` method instead of `__set__`:
22
27
23
28
```py title='Validation and Adaption' linenums="1"
In this particular example, since we dont want the `JPEG` to be set externally by a client, we create a local `Property` which carries out the image manipulation and an externally visible `readonly` Property that can fetch the processed image.
41
+
In this particular example, since we dont want the `JPEG` to be set externally by a client, we create a local `Property` which carries out the image manipulation and an externally visible `readonly` Property that can supply the processed image to the client.
37
42
38
43
The difference between using a custom setter/`fset` method and overloading the `Property` is that, one can accept certain options specific to the `Property` in the `__init__` of the
The value of the property must be serializable to be read by the clients. Read the [serializer section](#serialization) for further details & customization. To make a property only locally accessible, set `remote=False`, i.e. such a property will not accessible on the network.
42
+
The value of the property must be serializable to be read by the clients. Read the [serializer section](#serialization) for further details & customization. To make a property only locally accessible, set `remote=False`, i.e. such a property will not accessible on the network nevertheless the descriptor behaviour can still be leveraged.
43
43
44
44
### Predefined Typed Properties
45
45
@@ -73,20 +73,20 @@ An example:
73
73
```
74
74
75
75
For typed properties, before the setter is invoked, the value is internally validated.
76
-
The return value of getter method is never validated and is left to the developer's or the client object's caution.
76
+
The return value of getter method is never validated and is left to the developer's or the client's caution.
77
77
78
78
## Schema Constrained Property
79
79
80
80
For complicated data structures, one can use `pydantic` or JSON schema based type definition and validation. Set the `model` argument to define the type:
81
81
82
82
=== "pydantic"
83
83
84
-
```py title="Properties Using Schema - pydantic" linenums="1" hl_lines="7 42-43"
0 commit comments