sift-stack-py 0.3.2__py3-none-any.whl

sift_py/yaml/_rule_test.py

@@ -0,0 +1,207 @@
+import pytest
+
+from sift_py.ingestion.config.yaml.error import YamlConfigError
+from sift_py.yaml import rule
+
+
+def test__validate_sub_expression():
+    rule._validate_sub_expression({"$mass": 10})
+    rule._validate_sub_expression({"$m": 10})
+
+    with pytest.raises(YamlConfigError, match="Invalid sub-expression key"):
+        rule._validate_sub_expression({"mass": 10})
+
+    with pytest.raises(YamlConfigError, match="Invalid sub-expression key"):
+        rule._validate_sub_expression({"$!mass": 10})
+
+    with pytest.raises(YamlConfigError, match="Invalid sub-expression key"):
+        rule._validate_sub_expression({"$$mass": 10})
+
+
+def test__validate_rule():
+    rule._validate_rule(
+        {
+            "name": "overheat_rule",
+            "description": "some_description",
+            "expression": "$1 > 10 && $2 > 10",
+            "type": "review",
+            "assignee": "homer@example.com",
+            "tags": ["foo", "bar"],
+            "channel_references": [
+                {"$1": {"name": "voltage", "data_type": "double"}},
+                {"$2": {"name": "vehicle_state", "data_type": "double"}},
+            ],
+            "rule_client_key": "overheat_rule_key",
+        }
+    )
+
+    # Rule with tag and asset names
+    rule._validate_rule(
+        {
+            "name": "overheat_rule",
+            "description": "some_description",
+            "expression": "$1 > 10 && $2 > 10",
+            "type": "review",
+            "assignee": "homer@example.com",
+            "tags": ["foo", "bar"],
+            "channel_references": [
+                {"$1": {"name": "voltage", "data_type": "double"}},
+                {"$2": {"name": "vehicle_state", "data_type": "double"}},
+            ],
+            "asset_names": ["NostromoLV426"],
+            "tag_names": ["vehicle"],
+            "rule_client_key": "overheat_rule_key",
+        }
+    )
+
+    with pytest.raises(YamlConfigError, match="Expected 'name' to be <str> but it is <int>"):
+        rule._validate_rule(
+            {
+                "name": 0,
+                "description": "some_description",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "review",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Expected 'description' to be <str> but it is <int>"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": 0,
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "review",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(
+        YamlConfigError, match="Expected 'expression' to be <<class 'str'> | <class 'dict'>>"
+    ):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "some_description",
+                "expression": 123,
+                "type": "review",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(
+        YamlConfigError, match="Expected 'type' to be <review | phase> but it is <str>"
+    ):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "foobar",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "not_valid_type",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Expected 'tags' to be"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "foobar",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "phase",
+                "assignee": "homer@example.com",
+                "tags": 123,
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Invalid channel reference key"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "foobar",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "phase",
+                "assignee": "homer@example.com",
+                "channel_references": [
+                    {"$foo": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Invalid sub-expression key"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "foobar",
+                "expression": {"name": "kinetic_energy_gt"},
+                "type": "phase",
+                "assignee": "homer@example.com",
+                "channel_references": [
+                    {"$1": {"name": "velocity", "data_type": "double"}},
+                ],
+                "sub_expressions": [
+                    {"mass": None},
+                ],
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Expected 'asset_names' to be"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "some_description",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "review",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+                "rule_client_key": "overheat_rule_key",
+                "asset_names": 123,
+            }
+        )
+
+    with pytest.raises(YamlConfigError, match="Expected 'tag_names' to be"):
+        rule._validate_rule(
+            {
+                "name": "overheat_rule",
+                "description": "some_description",
+                "expression": "$1 > 10 && $2 > 10",
+                "type": "review",
+                "assignee": "homer@example.com",
+                "tags": ["foo", "bar"],
+                "channel_references": [
+                    {"$1": {"name": "voltage", "data_type": "double"}},
+                    {"$2": {"name": "vehicle_state", "data_type": "double"}},
+                ],
+                "rule_client_key": "overheat_rule_key",
+                "tag_names": 123,
+            }
+        )

sift_py/yaml/channel.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Literal, Union, cast
+
+from typing_extensions import NotRequired, TypedDict
+
+from sift_py.ingestion.channel import ChannelDataTypeStrRep
+from sift_py.ingestion.config.yaml.error import YamlConfigError
+from sift_py.yaml.utils import _type_fqn
+
+_CHANNEL_REFERENCE_REGEX = re.compile(r"^\$\d+$")
+
+
+def _validate_channel_anchor(val: Any):
+    if not isinstance(val, str):
+        raise YamlConfigError._invalid_property(
+            val,
+            "<str>",
+            "&str",
+            ["channels"],
+        )
+
+
+def _validate_channel(val: Any):
+    channel = cast(Dict[Any, Any], val)
+
+    name = channel.get("name")
+
+    if not isinstance(name, str):
+        raise YamlConfigError._invalid_property(name, "- name", "str", ["channels"])
+
+    description = channel.get("description")
+
+    if description is not None and not isinstance(description, str):
+        raise YamlConfigError._invalid_property(description, "- description", "str", ["channels"])
+
+    unit = channel.get("unit")
+
+    if unit is not None and not isinstance(unit, str):
+        raise YamlConfigError._invalid_property(unit, "- unit", "str", ["channels"])
+
+    component = channel.get("component")
+
+    if component is not None and not isinstance(component, str):
+        raise YamlConfigError._invalid_property(component, "- component", "str", ["channels"])
+
+    data_type = channel.get("data_type")
+    valid_data_type_values = [v.value for v in ChannelDataTypeStrRep]
+
+    if not data_type in valid_data_type_values:
+        raise YamlConfigError._invalid_property(
+            data_type,
+            "- data_type",
+            " | ".join(valid_data_type_values),
+            ["channels"],
+        )
+
+    if data_type == ChannelDataTypeStrRep.ENUM.value:
+        enum_types = channel.get("enum_types")
+
+        if not isinstance(enum_types, list):
+            raise YamlConfigError._invalid_property(
+                enum_types,
+                "- enum_types",
+                f"List<{_type_fqn(ChannelEnumTypeYamlSpec)}>",
+                ["channels"],
+            )
+
+        for enum_type in cast(List[Any], enum_types):
+            _validate_enum_type(enum_type)
+
+    elif data_type == ChannelDataTypeStrRep.BIT_FIELD.value:
+        bit_field_elements = channel.get("bit_field_elements")
+
+        if not isinstance(bit_field_elements, list):
+            raise YamlConfigError._invalid_property(
+                bit_field_elements,
+                "- bit_field_elements",
+                f"List<{_type_fqn(ChannelBitFieldElementYamlSpec)}>",
+            )
+
+        for bit_field_element in cast(List[Any], bit_field_elements):
+            _validate_bit_field_element(bit_field_element)
+
+    else:
+        enum_types = channel.get("enum_types")
+
+        if enum_types is not None:
+            raise YamlConfigError(
+                f"Channel of data-type '{data_type}' should not have 'enum_types' set."
+            )
+
+        bit_field_elements = channel.get("bit_field_elements")
+
+        if bit_field_elements is not None:
+            raise YamlConfigError(
+                f"Channel of data-type '{data_type}' should not have 'bit_field_elements' set."
+            )
+
+
+def _validate_enum_type(val: Any):
+    enum_type = cast(Dict[Any, Any], val)
+
+    name = enum_type.get("name")
+
+    if not isinstance(name, str):
+        raise YamlConfigError._invalid_property(
+            name,
+            "- name",
+            "str",
+            ["channels", "- enum_type"],
+        )
+
+    key = enum_type.get("key")
+
+    if not isinstance(key, int):
+        raise YamlConfigError._invalid_property(
+            key,
+            "- key",
+            "int",
+            ["channels", "- enum_type"],
+        )
+
+
+def _validate_bit_field_element(val: Any):
+    bit_field_element = cast(Dict[Any, Any], val)
+
+    name = bit_field_element.get("name")
+
+    if not isinstance(name, str):
+        raise YamlConfigError._invalid_property(
+            name, "- name", "str", ["channels", "- bit_field_elements"]
+        )
+
+    index = bit_field_element.get("index")
+
+    if not isinstance(index, int):
+        raise YamlConfigError._invalid_property(
+            name, "- index", "int", ["channels", "- bit_field_elements"]
+        )
+
+    bit_count = bit_field_element.get("bit_count")
+
+    if not isinstance(bit_count, int):
+        raise YamlConfigError._invalid_property(
+            name, "- bit_count", "int", ["channels", "- bit_field_elements"]
+        )
+
+
+def _validate_channel_reference(val: Any):
+    channel_reference = cast(Dict[Any, Any], val)
+
+    for key, value in channel_reference.items():
+        if not isinstance(key, str):
+            raise YamlConfigError._invalid_property(
+                channel_reference,
+                "- <str>",
+                f"Dict[str, {_type_fqn(ChannelConfigYamlSpec)}]",
+                ["rules", "- channel_references"],
+            )
+
+        if _CHANNEL_REFERENCE_REGEX.match(key) is None:
+            raise YamlConfigError(
+                f"Invalid channel reference key '{key}'. Expected an integer prefixed with '$' e.g. '$1', '$2', and so on."
+            )
+
+        if isinstance(value, dict):  # Do this for YamlConfigChannelSpec but not str
+            try:
+                _validate_channel(value)
+            except YamlConfigError as err:
+                raise YamlConfigError(f"Rule '{key}' contains an invalid channel reference:\n{err}")
+
+
+class ChannelConfigYamlSpec(TypedDict):
+    """
+    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 if `data_type` is `bit_field`.
+    """
+
+    name: str
+    description: NotRequired[str]
+    unit: NotRequired[str]
+    component: NotRequired[str]
+    data_type: Union[
+        Literal["double"],
+        Literal["string"],
+        Literal["enum"],
+        Literal["bit_field"],
+        Literal["bool"],
+        Literal["float"],
+        Literal["int32"],
+        Literal["int64"],
+        Literal["uint32"],
+        Literal["uint64"],
+    ]
+    enum_types: NotRequired[List[ChannelEnumTypeYamlSpec]]
+    bit_field_elements: NotRequired[List[ChannelBitFieldElementYamlSpec]]
+
+
+class ChannelEnumTypeYamlSpec(TypedDict):
+    """
+    Formal spec that defines what a channel enum type should look like in YAML.
+    """
+
+    name: str
+    key: int
+
+
+class ChannelBitFieldElementYamlSpec(TypedDict):
+    """
+    Formal spec that defines what a bit-field element should look like in YAML.
+    """
+
+    name: str
+    index: int
+    bit_count: int

sift_py/yaml/report_templates.py

@@ -0,0 +1,73 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, cast
+
+import yaml
+from typing_extensions import NotRequired, TypedDict
+
+from sift_py.ingestion.config.yaml.error import YamlConfigError
+from sift_py.report_templates.config import ReportTemplateConfig
+from sift_py.yaml.utils import _handle_subdir
+
+
+def load_report_templates(paths: List[Path]) -> List[ReportTemplateConfig]:
+    """
+    Takes in a list of paths to YAML files which contains report templates and processes them into a list of
+    `ReportTemplateConfig` objects. For more information on report templates see
+    `sift_py.report_templates.config.ReportTemplateConfig`.
+    """
+    report_templates: List[ReportTemplateConfig] = []
+
+    def update_report_templates(path: Path):
+        report_templates.extend(_read_report_template_yaml(path))
+
+    for path in paths:
+        if path.is_dir():
+            _handle_subdir(path, update_report_templates)
+        elif path.is_file():
+            update_report_templates(path)
+    return report_templates
+
+
+def _read_report_template_yaml(path: Path) -> List[ReportTemplateConfig]:
+    report_templates = []
+    with open(path, "r") as f:
+        report_templates_yaml = cast(Dict[str, Any], yaml.safe_load(f.read()))
+
+        report_template_list = report_templates_yaml.get("report_templates")
+        if not isinstance(report_template_list, list):
+            raise YamlConfigError(
+                f"Expected 'report_templates' to be a list in report template yaml: '{path}'"
+            )
+
+        for report_template in report_template_list:
+            try:
+                report_template_config = ReportTemplateConfig(**report_template)
+                report_templates.append(report_template_config)
+            except Exception as e:
+                raise YamlConfigError(f"Error parsing report template '{report_template}'") from e
+
+        return report_templates
+
+
+class ReportTemplateYamlSpec(TypedDict):
+    """
+    Formal spec for a report template.
+
+    `name`: Name of the report template.
+    `template_client_key`: Unique client key to identify the report template.
+    `organization_id`: Organization ID that the report template belongs to.
+    `tags`: Tags to associate with the report template.
+    `description`: Description of the report template.
+    `rule_client_keys`: List of rule client keys associated with the report template.
+    `archived_date`: Date when the report template was archived. Setting this field
+      will archive the report template, and unsetting it will unarchive the report template.
+    """
+
+    name: str
+    template_client_key: str
+    organization_id: NotRequired[str]
+    tags: NotRequired[List[str]]
+    description: NotRequired[str]
+    rule_client_keys: List[str]
+    archived_date: NotRequired[datetime]