sift_py.ingestion.config.yaml.spec
Formal specification of the types that sift_py expects when loading a telemetry config from a YAML file.
1""" 2Formal specification of the types that `sift_py` expects when loading a telemetry config from a YAML file. 3""" 4 5from __future__ import annotations 6 7from typing import Dict, List 8 9from typing_extensions import NotRequired, TypedDict 10 11import sift_py.yaml.channel as channel_yaml 12import sift_py.yaml.rule as rule_yaml 13 14RuleYamlSpec = rule_yaml.RuleYamlSpec 15NamedExpressionYamlSpec = rule_yaml.NamedExpressionYamlSpec 16ChannelConfigYamlSpec = channel_yaml.ChannelConfigYamlSpec 17ChannelEnumTypeYamlSpec = channel_yaml.ChannelEnumTypeYamlSpec 18ChannelBitFieldElementYamlSpec = channel_yaml.ChannelBitFieldElementYamlSpec 19 20 21class TelemetryConfigYamlSpec(TypedDict): 22 """ 23 Formal spec that defines what the telemetry config should look like in YAML. 24 25 `asset_name`: The name of the asset to telemeter. 26 `ingestion_client_key`: Optional user-defined string-key that uniquely identifies this telemetry config. 27 `organization_id`: Optional ID of user's organization. Required if user belongs to multiple orgs. 28 `channels`: Sensors that send the data. 29 `rules`: Rules that, when evaluated to a true, will perform some sort of acction. 30 `flows`: A list of named groups of channels that send data together. 31 """ 32 33 asset_name: str 34 ingestion_client_key: NotRequired[str] 35 organization_id: NotRequired[str] 36 channels: Dict[str, ChannelConfigYamlSpec] 37 rules: NotRequired[List[RuleYamlSpec]] 38 flows: NotRequired[List[FlowYamlSpec]] 39 40 41class FlowYamlSpec(TypedDict): 42 """ 43 Formal spec that defines what a flow should look like in YAML. 44 """ 45 46 name: str 47 channels: List[ChannelConfigYamlSpec] 48 49 50class YamlConfigError(Exception): 51 """ 52 When the YAML config has missing or invalid properties. 53 """ 54 55 message: str 56 57 def __init__(self, message: str): 58 super().__init__(message)
260class RuleYamlSpec(TypedDict): 261 """ 262 The formal definition of what a single rule looks like in YAML. 263 264 `name`: Name of the rule. 265 `rule_client_key`: User-defined string-key that uniquely identifies this rule config. 266 `description`: Description of rule. 267 `expression`: 268 Either an expression-string or a `sift_py.ingestion.config.yaml.spec.NamedExpressionYamlSpec` referencing a named expression. 269 `type`: Determines the action to perform if a rule gets evaluated to true. 270 `assignee`: If `type` is `review`, determines who to notify. Expects an email. 271 `tags`: Tags to associate with the rule. 272 `channel_references`: A list of channel references that maps to an actual channel. More below. 273 `contextual_channels`: A list of channel configs that provide context but aren't directly used in the expression. 274 `sub_expressions`: A list of sub-expressions which is a mapping of place-holders to sub-expressions. Only used if using named expressions. 275 `asset_names`: A list of asset names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config. 276 `tag_names`: A list of tag names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config. 277 278 Channel references: 279 A channel reference is a string containing a numerical value prefixed with "$". Examples include "$1", "$2", "$11", and so on. 280 The channel reference is mapped to an actual channel config. In YAML it would look something like this: 281 282 ```yaml 283 channel_references: 284 - $1: *vehicle_state_channel 285 - $2: *voltage_channel 286 contextual_channels: 287 - name: log 288 ``` 289 290 Sub-expressions: 291 A sub-expression is made up of two components: A reference and the actual sub-expression. The sub-expression reference is 292 a string with a "$" prepended to another string comprised of characters in the following character set: `[a-zA-Z0-9_]`. 293 This reference should be mapped to the actual sub-expression. For example, say you have kinematic equations in `kinematics.yml`, 294 and the equation you're interested in using looks like the following: 295 296 ```yaml 297 kinetic_energy_gt: 298 0.5 * $mass * $1 * $1 > $threshold 299 ``` 300 301 To properly use `kinetic_energy_gt` in your rule, it would look like the following: 302 303 ```yaml 304 rules: 305 - name: kinetic_energy 306 description: Tracks high energy output while in motion 307 type: review 308 assignee: bob@example.com 309 expression: 310 name: kinetic_energy_gt 311 channel_references: 312 - $1: *velocity_channel 313 sub_expressions: 314 - $mass: 10 315 - $threshold: 470 316 tags: 317 - nostromo 318 ``` 319 """ 320 321 name: str 322 rule_client_key: NotRequired[str] 323 description: NotRequired[str] 324 expression: Union[str, NamedExpressionYamlSpec] 325 type: Union[Literal["phase"], Literal["review"]] 326 assignee: NotRequired[str] 327 tags: NotRequired[List[str]] 328 channel_references: NotRequired[List[Dict[str, ChannelConfigYamlSpec]]] 329 contextual_channels: NotRequired[List[str]] 330 sub_expressions: NotRequired[List[Dict[str, str]]] 331 asset_names: NotRequired[List[str]] 332 tag_names: NotRequired[List[str]]
The formal definition of what a single rule looks like in YAML.
name: Name of the rule.
rule_client_key: User-defined string-key that uniquely identifies this rule config.
description: Description of rule.
expression:
Either an expression-string or a sift_py.ingestion.config.yaml.spec.NamedExpressionYamlSpec referencing a named expression.
type: Determines the action to perform if a rule gets evaluated to true.
assignee: If type is review, determines who to notify. Expects an email.
tags: Tags to associate with the rule.
channel_references: A list of channel references that maps to an actual channel. More below.
contextual_channels: A list of channel configs that provide context but aren't directly used in the expression.
sub_expressions: A list of sub-expressions which is a mapping of place-holders to sub-expressions. Only used if using named expressions.
asset_names: A list of asset names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config.
tag_names: A list of tag names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config.
Channel references: A channel reference is a string containing a numerical value prefixed with "$". Examples include "$1", "$2", "$11", and so on. The channel reference is mapped to an actual channel config. In YAML it would look something like this:
channel_references:
- $1: *vehicle_state_channel
- $2: *voltage_channel
contextual_channels:
- name: log
Sub-expressions:
A sub-expression is made up of two components: A reference and the actual sub-expression. The sub-expression reference is
a string with a "$" prepended to another string comprised of characters in the following character set: [a-zA-Z0-9_].
This reference should be mapped to the actual sub-expression. For example, say you have kinematic equations in kinematics.yml,
and the equation you're interested in using looks like the following:
kinetic_energy_gt:
0.5 * $mass * $1 * $1 > $threshold
To properly use kinetic_energy_gt in your rule, it would look like the following:
rules:
- name: kinetic_energy
description: Tracks high energy output while in motion
type: review
assignee: bob@example.com
expression:
name: kinetic_energy_gt
channel_references:
- $1: *velocity_channel
sub_expressions:
- $mass: 10
- $threshold: 470
tags:
- nostromo
335class NamedExpressionYamlSpec(TypedDict): 336 """ 337 A named expression. This class is the formal definition of what a named expression 338 should look like in YAML. The value of `name` may contain a mix of channel references 339 and channel identifiers. 340 341 For a formal definition of channel references and channel identifiers see the following: 342 `sift_py.ingestion.config.yaml.spec.RuleYamlSpec`. 343 """ 344 345 name: str
A named expression. This class is the formal definition of what a named expression
should look like in YAML. The value of name may contain a mix of channel references
and channel identifiers.
For a formal definition of channel references and channel identifiers see the following:
sift_py.ingestion.config.yaml.spec.RuleYamlSpec.
177class ChannelConfigYamlSpec(TypedDict): 178 """ 179 Formal spec that defines what a channel should look like in YAML. 180 181 `name`: Name of channel. 182 `description`: Optional channel description. 183 `unit`: Unit of measurement. 184 `component`: Name of component that channel belongs to. 185 `data_type`: Type of the data associated with the channel. 186 `enum_types`: Required if `data_type` is `enum. 187 `bit_field_elements`: Required if `data_type` is `bit_field`. 188 """ 189 190 name: str 191 description: NotRequired[str] 192 unit: NotRequired[str] 193 component: NotRequired[str] 194 data_type: Union[ 195 Literal["double"], 196 Literal["string"], 197 Literal["enum"], 198 Literal["bit_field"], 199 Literal["bool"], 200 Literal["float"], 201 Literal["int32"], 202 Literal["int64"], 203 Literal["uint32"], 204 Literal["uint64"], 205 ] 206 enum_types: NotRequired[List[ChannelEnumTypeYamlSpec]] 207 bit_field_elements: NotRequired[List[ChannelBitFieldElementYamlSpec]]
Formal spec that defines what a channel should look like in YAML.
name: Name of channel.
description: Optional channel description.
unit: Unit of measurement.
component: Name of component that channel belongs to.
data_type: Type of the data associated with the channel.
enum_types: Required if data_type is enum.
bit_field_elements: Required ifdata_typeisbit_field`.
210class ChannelEnumTypeYamlSpec(TypedDict): 211 """ 212 Formal spec that defines what a channel enum type should look like in YAML. 213 """ 214 215 name: str 216 key: int
Formal spec that defines what a channel enum type should look like in YAML.
219class ChannelBitFieldElementYamlSpec(TypedDict): 220 """ 221 Formal spec that defines what a bit-field element should look like in YAML. 222 """ 223 224 name: str 225 index: int 226 bit_count: int
Formal spec that defines what a bit-field element should look like in YAML.
22class TelemetryConfigYamlSpec(TypedDict): 23 """ 24 Formal spec that defines what the telemetry config should look like in YAML. 25 26 `asset_name`: The name of the asset to telemeter. 27 `ingestion_client_key`: Optional user-defined string-key that uniquely identifies this telemetry config. 28 `organization_id`: Optional ID of user's organization. Required if user belongs to multiple orgs. 29 `channels`: Sensors that send the data. 30 `rules`: Rules that, when evaluated to a true, will perform some sort of acction. 31 `flows`: A list of named groups of channels that send data together. 32 """ 33 34 asset_name: str 35 ingestion_client_key: NotRequired[str] 36 organization_id: NotRequired[str] 37 channels: Dict[str, ChannelConfigYamlSpec] 38 rules: NotRequired[List[RuleYamlSpec]] 39 flows: NotRequired[List[FlowYamlSpec]]
Formal spec that defines what the telemetry config should look like in YAML.
asset_name: The name of the asset to telemeter.
ingestion_client_key: Optional user-defined string-key that uniquely identifies this telemetry config.
organization_id: Optional ID of user's organization. Required if user belongs to multiple orgs.
channels: Sensors that send the data.
rules: Rules that, when evaluated to a true, will perform some sort of acction.
flows: A list of named groups of channels that send data together.
42class FlowYamlSpec(TypedDict): 43 """ 44 Formal spec that defines what a flow should look like in YAML. 45 """ 46 47 name: str 48 channels: List[ChannelConfigYamlSpec]
Formal spec that defines what a flow should look like in YAML.
51class YamlConfigError(Exception): 52 """ 53 When the YAML config has missing or invalid properties. 54 """ 55 56 message: str 57 58 def __init__(self, message: str): 59 super().__init__(message)
When the YAML config has missing or invalid properties.
Inherited Members
- builtins.BaseException
- with_traceback
- args