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`: 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: 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)
241class RuleYamlSpec(TypedDict): 242 """ 243 The formal definition of what a single rule looks like in YAML. 244 245 `name`: Name of the rule. 246 `rule_client_key`: User-defined string-key that uniquely identifies this rule config. 247 `description`: Description of rule. 248 `expression`: 249 Either an expression-string or a `sift_py.ingestion.config.yaml.spec.NamedExpressionYamlSpec` referencing a named expression. 250 `type`: Determines the action to perform if a rule gets evaluated to true. 251 `assignee`: If `type` is `review`, determines who to notify. Expects an email. 252 `tags`: Tags to associate with the rule. 253 `channel_references`: A list of channel references that maps to an actual channel. More below. 254 `sub_expressions`: A list of sub-expressions which is a mapping of place-holders to sub-expressions. Only used if using named expressions. 255 `asset_names`: A list of asset names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config. 256 `tag_names`: A list of tag names that this rule should be applied to. ONLY VALID if defining rules outside of a telemetry config. 257 258 Channel references: 259 A channel reference is a string containing a numerical value prefixed with "$". Examples include "$1", "$2", "$11", and so on. 260 The channel reference is mapped to an actual channel config. In YAML it would look something like this: 261 262 ```yaml 263 channel_references: 264 - $1: *vehicle_state_channel 265 - $2: *voltage_channel 266 ``` 267 268 Sub-expressions: 269 A sub-expression is made up of two components: A reference and the actual sub-expression. The sub-expression reference is 270 a string with a "$" prepended to another string comprised of characters in the following character set: `[a-zA-Z0-9_]`. 271 This reference should be mapped to the actual sub-expression. For example, say you have kinematic equations in `kinematics.yml`, 272 and the equation you're interested in using looks like the following: 273 274 ```yaml 275 kinetic_energy_gt: 276 0.5 * $mass * $1 * $1 > $threshold 277 ``` 278 279 To properly use `kinetic_energy_gt` in your rule, it would look like the following: 280 281 ```yaml 282 rules: 283 - name: kinetic_energy 284 description: Tracks high energy output while in motion 285 type: review 286 assignee: bob@example.com 287 expression: 288 name: kinetic_energy_gt 289 channel_references: 290 - $1: *velocity_channel 291 sub_expressions: 292 - $mass: 10 293 - $threshold: 470 294 tags: 295 - nostromo 296 ``` 297 """ 298 299 name: str 300 rule_client_key: NotRequired[str] 301 description: NotRequired[str] 302 expression: Union[str, NamedExpressionYamlSpec] 303 type: Union[Literal["phase"], Literal["review"]] 304 assignee: NotRequired[str] 305 tags: NotRequired[List[str]] 306 channel_references: NotRequired[List[Dict[str, ChannelConfigYamlSpec]]] 307 sub_expressions: NotRequired[List[Dict[str, str]]] 308 asset_names: NotRequired[List[str]] 309 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.
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
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
312class NamedExpressionYamlSpec(TypedDict): 313 """ 314 A named expression. This class is the formal definition of what a named expression 315 should look like in YAML. The value of `name` may contain a mix of channel references 316 and channel identifiers. 317 318 For a formal definition of channel references and channel identifiers see the following: 319 `sift_py.ingestion.config.yaml.spec.RuleYamlSpec`. 320 """ 321 322 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`: 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: 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: 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