Commit f452490b authored by Cyril Guilloud's avatar Cyril Guilloud
Browse files

added Settings usages examples

parent 31e6b66e
# Beacon settings
## Settings
*Beacon settings* are helper classes to store data in the Redis database at
runtime from Python code, using BLISS.
......@@ -8,67 +10,184 @@ Use cases for settings:
* on top of static configuration parameters
- motor velocity, acceleration, limits
- auto-gain on a Keithley
* to keep (or share) information across executions (or across processes)
* to persistency keep (or share) information across executions (or
across processes)
- selected counter for plot
- enabled loggers, log level
- scan saving path, file template...
## Settings classes
!!! note
To access to the redis database:
`redis-cli -s /tmp/redis.sock -n 0`
BLISS provides different classes for different kinds of settings.
### SimpleSetting
## SimpleSetting
The `SimpleSetting` class is used to save a *scalar value*:
The `SimpleSetting` class is used to store a *scalar value*:
* int
* float
* string
* bool
The typical usages are:
* to create the setting with a default value:
`sss = SimpleSetting(<key>, default_value=<value>)`
* to set a value to store: `sss.set()`
* to read the stored value: `sss.get()`)
* to reset the value to the default one: `sss.clear()`
Example:
```py
```python
from bliss.config import settings
magicNumber = 63825363
iii = settings.SimpleSetting('myIntkey', default_value=magicNumber)
assert iii.get() == magicNumber
iii.set(42)
assert iii.get() == 42
assert isinstance(iii.get(), int)
sss = settings.SimpleSetting('myIntkey', default_value=magicNumber)
print(sss)
# <SimpleSetting name=myIntkey value=None>
print(sss.get())
# 63825363 # this is the default value.
sss.set(42)
print(sss)
# <SimpleSetting name=myIntkey value=b'42'>
print(sss.get())
# 42
sss.clear()
print(sss.get())
# 63825363
sss.set(3.14)
```
`redis-cli` can be used to inspect the redis database:
```
% redis-cli -s /tmp/redis.sock -n 0
redis /tmp/redis.sock> keys my*
1) "myHkey"
2) "myIntkey"
redis /tmp/redis.sock> get myIntkey
"3.14"
```
After a restart of the session (or from another session):
```python
from bliss.config import settings
sss = settings.SimpleSetting('myIntkey')
print(sss.get())
# 3.14
```
The `default_value` is returned by the `SimpleSetting` object until it
has been set or after a `clear()`. Once the object has been set, the
value is persisted in redis.
Note that `default_value` can be `None`, but a `SimpleSetting` cannot
be set to `None`.
After a `.clear()`, the key is removed from Redis database:
```python
sss.clear()
```
```
redis /tmp/redis.sock> keys myIntkey
(empty list or set)
```
## BaseHashSetting and HashSetting
The `BaseHashSetting` class is used to represent a *dictionary* of
scalar values. `HashSetting` simply adds a kwarg `default_values` that
is a dictionary containing values taken as a fallback.
```python
from bliss.config import settings
myDict = {"key1":"value1", "key2":"value2"}
hs = settings.HashSetting('myHkey', default_values=myDict)
# note the 's' in default_values
# 'hs' acts now as a dictionary.
print(hs["key1"])
# value1
print(hs["key2"])
# value2
hs["key1"]=3333
print(hs["key1"])
# 3333
```
The `default_value` is returned by the `SimpleSetting` object until it has been
set. Once the object has been set, the value is persisted in redis.
Redis stores only key/value pairs that have changed:
### BaseHashSetting and HashSetting
```
% redis-cli -s /tmp/redis.sock -n 0
redis /tmp/redis.sock> hgetall myHkey
1) "key1"
2) "3333"
```
After a `.clear()`, the key is removed from Redis database.
A key can be added and removed:
bliss session:
```python
hs["newKey"]=45
```
The `BaseHashSetting` class is used to represent a dictionary of scalar values,
`HashSetting` simply adds a kwarg `default_values` that is a dictionary containing
values taken as a fallback.
redis:
```
hgetall myHkey
1) "key1"
2) "3333"
3) "newKey"
4) "45"
```
bliss session:
```python
hs.remove("newKey")
```
```py
myDict = {"C1":"riri", "C2":"fifi"}
shs = settings.HashSetting('myHkey', default_values=myDict) # note the s :)
redis:
```
redis /tmp/redis.sock> hgetall myHkey
1) "key1"
2) "3333"
```
### QueueSetting
## QueueSetting
The `QueueSetting` class is used to represent a list of scalar values:
```py
```python
>>> myList = ["a", "b", "c", "d"]
>>> sqs = settings.QueueSetting('myQkey')
>>> sqs.set(myList)
```
### ParametersWardrobe
## ParametersWardrobe
`ParametersWardrobe` are more advanced objects -- it is used to group
simple settings, and to be able to switch from one set of values for
the parameters to another:
```py
```python
>>> from bliss.config.settings import ParametersWardrobe
>>> p = ParametersWardrobe("my_params")
>>> p.add("test", 42)
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment