variables

Описание

Модуль variables работает с переменными в рамках текущего тенанта (client_id).

Он определяет следующие функции и классы ошибок:

1class BadParamsError(Exception):
2    pass
3
4class VariableNotFoundError(Exception):
5    pass
6
7class UnknownError(Exception):
8    pass
9
10
11def get(name: str) -> Variable:
12    pass
13
14def create(name: str, value: Any, value_type: Types, timestamp: datetime, ttl: int) -> Variable:
15    pass
16
17def set(name: str, value: Any, value_type: Types, create: bool, force: bool, timestamp: datetime, ttl: int) -> Variable:
18    pass
19
20def increment(name: str, delta: Any, value_type: Types, ttl=None, default_value=0, create=False) -> Variable:
21    pass
22
23def decrement(name: str, delta: Any, value_type: Types, ttl=None, default_value=0, create=False) -> Variable:
24    pass
25
26def delete(name: str):
27    pass
28
29def exists(name: str) -> bool:
30    pass

Доступ к переменной в рамках тенанта осуществляется по уникальному имени, которое может содержать только английские буквы и цифры, а также символы _ и -.

1class Variable:
2	name:  str
3	type:  str
4	value: Any
5    timestamp:  int
6    expires_at: int
7
8    def set(self, value: Any, timestamp: datetime, ttl=None, create=False, force=False) -> 'Variable':
9        pass
10
11    def increment(self, delta: Any, ttl=None, default_value=0, create=False) -> 'Variable':
12        pass
13
14    def decrement(self, delta: Any, ttl=None, default_value=0, create=False) -> 'Variable':
15        pass
16
17    def delete(self):
18        pass
19
20    def exists(self) -> bool:
21            pass

Переменная содержит следующие поля:

name — уникальное имя;
type — тип значения переменной;
value — значение переменной (не может быть null);
timestamp — временная метка последнего изменения;
expires_at — временная метка до которой будет существовать переменная, по умолчанию переменная будет жить 30 дней с момента последнего обновления.

Переменная может иметь следующие типы значений:

integer;
float;
string;
boolean;
timestamp — временная отметка с точностью до микросекунд;
location — объект с ключами lat и lng.

Типы значений:

1class Types(str, Enum):
2    Integer = "integer"
3    Float = "float"
4    Timestamp = "timestamp"
5    String = "string"
6    Boolean = "boolean"
7    Location = "location"
8
9class Location(NamedTuple):
10    lat: float
11    lng: float

Значение переменной может содержать только значение указанного типа.

Создание

Переменная может быть создана методом create модуля variables:

1def create(name: str, value: Any, value_type: Types, timestamp: datetime, ttl: int) -> 'Variable':
2    pass
3
4
5ttl - время жизни переменной в хранилище в микросекундах
6Пример создания переменных:
7
8from datetime import datetime
9from coiiot_sdk import variables, user_logs
10
11ts=datetime.now()
12
13logger = user_logs.get_logger()
14
15# ttl=3600000000 - время жизни переменной 1 час
16create_int = variables.create(name='create_int', value=123, value_type=variables.Types.Integer, timestamp=ts, ttl=3600000000)
17logger.info(f'{create_int.value}')
18
19create_float = variables.create(name='create_float', value=123.45, value_type=variables.Types.Float, timestamp=ts, ttl=3600000000)
20logger.info(f'{create_float.value}')
21
22create_bool = variables.create(name='create_bool', value=True, value_type=variables.Types.Boolean, timestamp=ts, ttl=3600000000)
23logger.info(f'{create_bool.value}')
24
25create_string = variables.create(name='create_string', value="true", value_type=variables.Types.String, timestamp=ts, ttl=3600000000)
26logger.info(f'{create_string.value}')
27
28create_location = variables.create(name='create_location', value=variables.Location(48.89364, 2.33739), value_type=variables.Types.Location, timestamp=ts, ttl=3600000000)
29logger.info(f'{create_location.value}')
30logger.info(f'{create_location.value["lat"]} {create_location.value["lng"]}')
31
32create_timestamp = variables.create(name='create_timestamp', value=1234567890000000, value_type=variables.Types.Timestamp, timestamp=ts, ttl=3600000000)
33logger.info(f'{create_timestamp.value}')

Возвращается новое значение переменной.

Получение

Получить переменную из хранилища можно методом get модуля variables:

1def get(name: str) -> Variable:
2    pass

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4ts=datetime.now()
5
6logger = user_logs.get_logger()
7
8create_int = variables.create(name='create_int', value=123, value_type=variables.Types.Integer, timestamp=ts, ttl=3600000000)
9
10v1 = variables.get("create_int")
11if v1 is not None:
12    logger.info(f'{v1.name}')
13    logger.info(f'{v1.type}')
14    logger.info(f'{v1.value}')
15    logger.info(f'{v1.timestamp}')
16    logger.info(f'{v1.expires_at}')

Установка значений

Модифицировать переменную можно методом set модуля variables:

1def set(name: str, value: Any, value_type: Types, create: bool, force: bool, timestamp: datetime, ttl: int) -> 'Variable':
2    pass

Также доступна модификация переменной через метод set объекта переменной Variable:

1class Variable:
2    ...
3    def set(self, value: Any, timestamp: datetime, ttl=None, create=False, force=False) -> 'Variable':
4        pass

В обоих вариантах возвращается новое значение переменной.

При модификации значения переменной должна передаваться временная отметка операции. Эта отметка будет использоваться для разрешения конфликтных ситуаций при конкурентном обновлении значения. В общем случае если операция содержит более старую метку, чем текущее значение переменной, то модификации переменной не произойдет.

Доступные флаги:

force - если true, установить новое значение переменной игнорируя временную метку текущего значения;
create - если true, атомарно создать переменную (если не существует);
value_type - если переменная создается, то этим флагом можно задать тип значения для этой переменной.

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4logger = user_logs.get_logger()
5
6create_int_2 = variables.create(name='create_int_2', value=12345, value_type=variables.Types.Integer)
7logger.info(f'{create_int_2.value}')
8
9set_int_2 = variables.set(name='create_int_2', value=1234567, value_type=variables.Types.Integer)
10logger.info(f'{set_int_2.value}')
11
12create_int = create_int.set(2, timestamp=datetime.now())
13logger.info(f'{create_int.value}')
14 
15v2 = variables.set(name="my-cool-var2", value=21.3, force=True, create=True, value_type=variables.Types.Float)
16logger.info(f'{v2.value}')

Инкрементация значений

Инкрементировать значение переменной можно методом increment модуля variables:

1def increment(name: str, delta: Any, value_type: Types, ttl=None, default_value=0, create=False) -> 'Variable':
2    pass

Также доступна инкрементация значения переменной через метод increment объекта переменной Variable:

1class Variable:
2    ...
3    def increment(self, delta: Any, ttl=None, default_value=0, create=False) -> 'Variable':
4            pass

В обоих вариантах возвращается новое значение переменной.

increment — атомарная операция value += delta над числовыми типами данных (integer, float, timestamp), временная метка не передается.

Доступные флаги:

create - если true, создать переменную (если не существует);
value_type - если переменная создается, то этим флагом можно задать тип значения для этой переменной;
default_value - если переменная создается, то этим флагом можно задать начальное значение переменной перед применением операции (по умолчанию 0).

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4logger = user_logs.get_logger()
5
6v2 = variables.set(name="my-cool-var2", value=21.3, force=True, create=True, value_type=variables.Types.Float)
7logger.info(f'{v2.value}')
8
9v2 = v2.increment(100)
10logger.info(f'{v2.value}')
11
12v3 = variables.increment(name="my-cool-var3", delta=7.01, default_value=14.02, create=True, value_type=variables.Types.Float)
13logger.info(f'{v3.value}')

Декрементация значений

Декрементировать значение переменной можно методом decrement модуля variables:

1def decrement(name: str, delta: Any, value_type: Types, ttl=None, default_value=0, create=False) -> 'Variable':
2    pass

Также доступна декрементация значения переменной через метод decrement объекта переменной Variable:

1class Variable:
2    ...
3    def decrement(self, delta: Any, ttl=None, default_value=0, create=False) -> 'Variable':
4            pass

В обоих вариантах возвращается новое значение переменной.

decrement - атомарная операция value -= delta над числовыми типами данных (integer, float, timestamp), временная метка не передается.

Доступные флаги:

create - если true, то создать переменную (если не существует);
value_type - если переменная создается, то этим флагом можно задать тип значения для этой переменной;
default_value - если переменная создается, то этим флагом можно задать начальное значение переменной перед применением операции (по умолчанию 0).

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4logger = user_logs.get_logger()
5
6v2 = variables.set(name="my-cool-var2", value=21.3, force=True, create=True, value_type=variables.Types.Float)
7logger.info(f'{v2.value}')
8
9v2 = v2.decrement(50)
10logger.info(f'{v2.value}')
11
12v3 = variables.decrement(name="my-cool-var3", delta=8.95, default_value=21.3, create=True, value_type=variables.Types.Float)
13logger.info(f'{v3.value}')

Удаление

Проверить удаление переменной из хранилища можно с помощью метода:

1def delete(name: str):
2    pass

Также доступно удаление переменной через метод delete объекта переменной Variable:

1class Variable:
2    ...
3    def delete(self):
4        pass

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4logger = user_logs.get_logger()
5
6v2 = variables.set(name="my-cool-var2", value=123.45, force=True, create=True, value_type=variables.Types.Float)
7logger.info(f'{v2.value}')
8
9v3 = variables.decrement(name="my-cool-var3", delta=8.95, default_value=21.3, create=True, value_type=variables.Types.Float)
10logger.info(f'{v3.value}')
11
12if v2.exists():
13    v2.delete()
14
15exists = v2.exists()
16logger.info(f'{exists}')
17
18if variables.exists(name="my-cool-var3"):
19    variables.delete(name="my-cool-var3")

Проверка

Проверить наличие переменной в хранилище можно с помощью метода:

1def exists(name: str) -> bool:
2    pass

Также доступна проверка наличия переменной через метод exists объекта переменной Variable:

1class Variable:
2    ...
3    def exists(self) -> bool:
4        pass

В обоих вариантах возвращается значение типа bool.

Пример:

1from datetime import datetime
2from coiiot_sdk import variables, user_logs
3
4logger = user_logs.get_logger()
5
6v2 = variables.set(name="my-cool-var2", value=123.45, force=True, create=True, value_type=variables.Types.Float)
7logger.info(f'{v2.value}')
8
9v3 = variables.decrement(name="my-cool-var3", delta=8.95, default_value=21.3, create=True, value_type=variables.Types.Float)
10logger.info(f'{v3.value}')
11
12if v2.exists():
13    v2.delete()
14
15exists = v2.exists()
16logger.info(f'{exists}')
17
18if variables.exists(name="my-cool-var3"):
19    variables.delete(name="my-cool-var3")
20
21exists = variables.exists(name="my-cool-var3")
22logger.info(f'{exists}')

Не нашли ответа? Напишите нам