MTPPy2.0 0.1.5__py3-none-any.whl

tools/inspect_mtp.py

@@ -0,0 +1,110 @@
+"""Read MTP-file and inspect aspects like services, data_assemblies and opcua-nodes.
+
+This module provides functionality to read MTP files (-f <filename>) and inspect
+various aspects including services (-s), data assemblies (-d), and OPC UA node (-n).
+
+The two most import CLI attributes are -k <regexp> that allows to filter services and
+data assemblies by their system names and -a <regexp> that allows to filter on
+the attribute level of data assemblies.
+
+Example:
+    ```python -m tools.inspect_mtp -f minimal.mtp -d -n -k upper -a RefB```
+    would give the RefBaseSystemUnitPath of DataAssembly upper_bound and the
+    list of node-ids
+"""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import argparse
+
+from mtppy.pea.data_assembly_factory import DataAssemblyFactory
+from mtppy.utils.mtp_file_handling.mtp_reader.mtp_reader import MtpReader
+
+
+def parseargs() -> argparse.Namespace:
+    """Parse CLI arguments.
+
+    Returns:
+        argparse.Namespace: Parsed arguments namespace.
+    """
+    p = argparse.ArgumentParser("test MtpReader")
+    p.add_argument(
+        "-k",
+        "--key",
+        default=".+",
+        help="regular expression for filtering by key",
+    )
+    p.add_argument(
+        "-a",
+        "--attribute",
+        default=".+",
+        help="regular expression for filtering by attribute",
+    )
+    p.add_argument(
+        "-c",
+        "--create",
+        action="store_true",
+        help="create data assemblies (only in conjunction with -d)",
+    )
+    p.add_argument("-f", "--filename", help="filename")
+    p.add_argument("-n", "--nodeid", action="store_true", help="node id s")
+    p.add_argument("-s", "--service", action="store_true", help="print services")
+    p.add_argument(
+        "-d",
+        "--dataassembly",
+        action="store_true",
+        help="print data assemblies",
+    )
+    return p.parse_args()
+
+
+def main():
+    """Main function to execute the MTP inspection tool."""
+    import re
+    from pprint import pprint
+
+    args = parseargs()
+
+    reader = MtpReader(args.filename)
+
+    if args.dataassembly:
+        print(f'\n{"- " * 20} data assemblies')
+        pprint(
+            {
+                k: {
+                    inner_k: inner_v
+                    for inner_k, inner_v in v.items()
+                    if re.match(args.attribute, inner_k)
+                }
+                for k, v in reader.data_assemblies.items()
+                if re.match(args.key, k)
+            },
+        )
+        if args.create:
+            DataAssemblyFactory.create_data_assemblies(reader.data_assemblies)
+
+    if args.nodeid:
+        print(f'\n{"- " * 20} nodeids')
+        pprint(
+            {
+                k: reader.alias_opcua_map[k]
+                for k in reader.alias_opcua_map
+                if re.match(args.key, k)
+            },
+        )
+    if args.service:
+        print(f'\n{"- " * 20} services')
+        pprint(
+            reader.services,
+            compact=True,
+            indent=2,
+        )
+
+    print("- " * 20)
+
+
+if __name__ == "__main__":
+    main()

utils/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

utils/file_handling/__init__.py

@@ -0,0 +1,4 @@
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"

utils/file_handling/cleanup_folder.py

@@ -0,0 +1,9 @@
+"""This module provides a utility function to clean up a folder by removing it and all its contents.
+"""
+from os.path import isdir
+from shutil import rmtree
+
+
+def cleanup_folder(path):
+    if isdir(path):
+        rmtree(path)

utils/file_handling/get_utc_foldername_with_ms.py

@@ -0,0 +1,15 @@
+"""utility function to get a UTC folder name with milliseconds."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import datetime
+
+from datetime import UTC
+
+
+def get_utc_foldername_with_ms():
+    dt = datetime.datetime.now(tz=UTC)
+    return dt.strftime("%Y-%m-%d_%H-%M-%S") + f"-{dt.microsecond // 1000:03d}Z"

utils/file_handling/get_work_dir.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from utils.file_handling.get_utc_foldername_with_ms import get_utc_foldername_with_ms
+
+
+def get_work_dir(base: str = "out"):
+    path = Path(base) / get_utc_foldername_with_ms()
+    path.mkdir(parents=True, exist_ok=True)
+    return path.resolve()

utils/file_handling/is_valid_path_for_json.py

@@ -0,0 +1,11 @@
+"""utility function to check if a path points to a valid JSON file.
+"""
+__copyright__ = "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+__license__ = "MIT"
+
+from pathlib import Path
+
+
+def is_valid_path_for_json(path):
+    path_object = Path(path)
+    return path_object.suffix == ".json"

utils/file_handling/is_valid_path_to_json.py

@@ -0,0 +1,17 @@
+"""utility function to check if a path points to a valid JSON file."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from pathlib import Path
+
+from utils.file_handling.is_valid_path_for_json import is_valid_path_for_json
+
+
+def is_valid_path_to_json(path):
+    path_object = Path(path)
+    return (
+        path_object.exists() and path_object.is_file() and is_valid_path_for_json(path)
+    )

utils/file_handling/load_json_file.py

@@ -0,0 +1,18 @@
+"""utility function to load JSON data from a file."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import json
+
+from utils.file_handling.is_valid_path_to_json import is_valid_path_to_json
+
+
+def load_json_file(file_path):
+    """Load and return JSON content from file."""
+    if not is_valid_path_to_json(file_path):
+        raise FileNotFoundError(f"Invalid path: {file_path}")
+    with open(file_path) as f:
+        return json.load(f)

utils/file_handling/read_file_from_file_archive.py

@@ -0,0 +1,43 @@
+"""utility function to read a specific file from a zip archive."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import logging
+import zipfile
+
+logger = logging.getLogger(__name__)
+
+
+def read_file_from_file_archive(archive_path, filename):
+    """Read a specific file from a zip archive and returns its contents as a string.
+
+    Args:
+        archive_path: Path to the file archive.
+        filename: Name of the file to read inside the archive (case-sensitive).
+
+    Returns:
+        Contents of the file as a string, or None if not found.
+    """
+    try:
+        with zipfile.ZipFile(archive_path, "r") as zip_ref:
+            # List all files in the zip
+            file_list = zip_ref.namelist()
+
+            if filename in file_list:
+                with zip_ref.open(filename) as file:
+                    return file.read().decode(
+                        "utf-8"
+                    )  # You can change encoding if needed
+            else:
+                logger.info(f"'{filename}' not found in the archive.")
+                return None
+
+    except zipfile.BadZipFile:
+        logger.error("The file is not a valid zip archive.")
+        return None
+    except (ValueError, NotImplementedError, RuntimeError) as e:
+        logger.error(f"error while reading '{filename}': {e}")
+        return None

utils/file_handling/read_file_string.py

@@ -0,0 +1,10 @@
+import chardet
+
+
+def read_file_string(filename):
+    with open(filename, "rb") as f:
+        result = chardet.detect(f.read())
+        encoding = result["encoding"]
+    with open(filename, encoding=encoding) as f:
+        content = f.readlines()
+    return content

utils/file_handling/validate_json_data.py

@@ -0,0 +1,28 @@
+"""utility function to validate JSON data against a schema."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import logging
+
+from jsonschema import ValidationError, validate
+
+from utils.file_handling.is_valid_path_to_json import is_valid_path_to_json
+from utils.file_handling.load_json_file import load_json_file
+
+logger = logging.getLogger(__name__)
+
+
+def validate_json_data(data, schema_path):
+    try:
+        if not is_valid_path_to_json(schema_path):
+            raise FileNotFoundError(f"Invalid schema path: {schema_path}")
+        schema = load_json_file(schema_path)
+        validate(instance=data, schema=schema)
+        logger.info(f"Json data validation successful for {schema_path}.")
+        return True
+    except ValidationError as e:
+        logger.error(f"error validating {schema_path}: {e.message}")
+        return False

utils/file_handling/write_json_file.py

@@ -0,0 +1,23 @@
+"""utility function to write data to a JSON file."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+
+import json
+
+from utils.file_handling.is_valid_path_for_json import is_valid_path_for_json
+
+
+def write_json_file(data, output_path):
+
+    if is_valid_path_for_json(output_path):
+        try:
+            with open(output_path, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=4)
+        except OSError as e:
+            raise OSError(f"Failed to write JSON output: {e}")
+    else:
+        raise TypeError("Invalid path to write JSON output!")

utils/get_uuid.py

@@ -0,0 +1,18 @@
+"""**get_uuid** wraps uuid.uuid4."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import uuid
+
+
+def get_uuid() -> str:
+    """Generate random uuid v4 for different elements.
+
+    Returns:
+        return: uuid v4 as string
+
+    """
+    return str(uuid.uuid4())

utils/get_uuid_test.py

@@ -0,0 +1,17 @@
+import pytest
+
+from utils.get_uuid import get_uuid
+
+
+def test_get_uuid():
+    random_id = get_uuid()
+    parts = random_id.split("-")
+    assert len(parts) == 5
+
+    expected_lengths = [8, 4, 4, 4, 12]
+    for i, expected_len in zip(parts, expected_lengths):
+        assert len(i) == expected_len
+
+
+if __name__ == "__main__":
+    pytest.main(["test_get_uuid.py", "-s"])

utils/logging.py

@@ -0,0 +1,100 @@
+"""provides a custom logger with support for custom info logging levels."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import logging
+from collections.abc import Mapping
+from typing import Any, Final
+
+OPCUA_LEVEL: Final = logging.INFO + 1
+MTP_LEVEL: Final = logging.INFO + 2
+APP_LEVEL: Final = logging.INFO + 4
+POL_LEVEL: Final = logging.INFO + 6
+
+CUSTOM_LEVELS: Final[dict[str, int]] = {
+    "opcua": OPCUA_LEVEL - logging.INFO,
+    "mtp": MTP_LEVEL - logging.INFO,
+    "app": APP_LEVEL - logging.INFO,
+    "pol": POL_LEVEL - logging.INFO,
+}
+
+_LOGGER_FORMAT: Final = (
+    "%(asctime)s.%(msecs)03d [%(levelname)s] "
+    "%(thread)s::%(module)s.%(funcName)s: %(message)s"
+)
+
+logging.basicConfig(
+    format=_LOGGER_FORMAT,
+    datefmt="%Y-%m-%d %H:%M:%S",
+    level=logging.DEBUG,
+)
+
+for _name, _offset in CUSTOM_LEVELS.items():
+    logging.addLevelName(logging.INFO + _offset, _name.upper())
+
+
+class CustomLogger(logging.Logger):
+    """Custom logger class that allows adding custom logging levels.
+
+    The levels are between the standard logging levels INFO and WARNING.
+    The logger is configured to display the timestamp, log level, thread, module,
+    function name, and message in the log output.
+
+    Example:
+        ```python
+        from utils.logging import CustomLogger
+        logging.setLoggerClass(CustomLogger)
+        logger = logging.getLogger("MTPPy2.0Logger")
+        logger.add_custom_levels({"opcua": 1, "mtp": 2, "app": 4, "pol": 6})
+        ```
+    """
+
+    def __init__(self, name: str, level: int = logging.NOTSET) -> None:
+        """Initialize a logger with the standard logging constructor."""
+        super().__init__(name, level)
+
+    def add_custom_levels(self, custom_levels: Mapping[str, int]) -> None:
+        """Register level names using offsets from ``logging.INFO``.
+
+        The logger methods are explicit and are not generated dynamically. This
+        keeps the framework API visible to static type checkers.
+        """
+        for level_name, offset in custom_levels.items():
+            if not level_name or not isinstance(offset, int):
+                raise ValueError("custom level names must have integer offsets")
+            logging.addLevelName(logging.INFO + offset, level_name.upper())
+
+    def opcua(self, msg: str, *args: object, **kwargs: object) -> None:
+        """Log a message at the OPC UA level."""
+        self._log_custom_level(msg, OPCUA_LEVEL, args, kwargs)
+
+    def mtp(self, msg: str, *args: object, **kwargs: object) -> None:
+        """Log a message at the MTP level."""
+        self._log_custom_level(msg, MTP_LEVEL, args, kwargs)
+
+    def app(self, msg: str, *args: object, **kwargs: object) -> None:
+        """Log a message at the application level."""
+        self._log_custom_level(msg, APP_LEVEL, args, kwargs)
+
+    def pol(self, msg: str, *args: object, **kwargs: object) -> None:
+        """Log a message at the POL level."""
+        self._log_custom_level(msg, POL_LEVEL, args, kwargs)
+
+    def _log_custom_level(
+        self,
+        msg: str,
+        level: int,
+        args: tuple[object, ...],
+        kwargs: dict[str, Any],
+    ) -> None:
+        if self.isEnabledFor(level):
+            self._log(level, msg, args, stacklevel=2, **kwargs)
+
+    def add_custom_level(self, level_name: str, level_value: int) -> None:
+        """Register one custom level name without modifying the logger API."""
+        if not level_name or not isinstance(level_value, int):
+            raise ValueError("custom level names must have integer values")
+        logging.addLevelName(level_value, level_name.upper())

utils/logging_test.py

@@ -0,0 +1,67 @@
+"""Tests for the reusable custom logging implementation."""
+
+import logging
+
+import pytest
+
+from utils.logging import (
+    APP_LEVEL,
+    CUSTOM_LEVELS,
+    MTP_LEVEL,
+    OPCUA_LEVEL,
+    POL_LEVEL,
+    CustomLogger,
+)
+
+
+@pytest.mark.parametrize(
+    ("method_name", "expected_level"),
+    [
+        ("opcua", OPCUA_LEVEL),
+        ("mtp", MTP_LEVEL),
+        ("app", APP_LEVEL),
+        ("pol", POL_LEVEL),
+    ],
+)
+def test_custom_logger_methods_emit_expected_levels(
+    caplog, method_name: str, expected_level: int
+) -> None:
+    logger = CustomLogger(f"test.custom.{method_name}")
+    logger.setLevel(logging.NOTSET)
+    logger.addHandler(caplog.handler)
+    logger.propagate = False
+
+    with caplog.at_level(logging.NOTSET):
+        getattr(logger, method_name)("message %s", method_name)
+
+    assert len(caplog.records) == 1
+    assert caplog.records[0].levelno == expected_level
+    assert caplog.records[0].levelname == method_name.upper()
+    assert caplog.records[0].message == f"message {method_name}"
+
+
+def test_custom_logger_registers_custom_level_names() -> None:
+    for name, offset in CUSTOM_LEVELS.items():
+        assert logging.getLevelName(logging.INFO + offset) == name.upper()
+
+
+def test_custom_logger_rejects_invalid_level_registration() -> None:
+    logger = CustomLogger("test.invalid-level")
+
+    with pytest.raises(ValueError):
+        logger.add_custom_level("", logging.INFO)
+    with pytest.raises(ValueError):
+        logger.add_custom_level("invalid", 1.5)  # type: ignore[arg-type]
+
+
+def test_custom_logger_does_not_emit_disabled_levels(caplog) -> None:
+    logger = CustomLogger("test.disabled")
+    logger.setLevel(APP_LEVEL)
+    logger.addHandler(caplog.handler)
+    logger.propagate = False
+
+    with caplog.at_level(logging.NOTSET):
+        logger.mtp("hidden")
+        logger.app("visible")
+
+    assert [record.message for record in caplog.records] == ["visible"]

utils/opcua/check_node.py

@@ -0,0 +1,79 @@
+"""utility function to check if a node exists on an OPC UA server.
+"""
+__copyright__ = "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+__license__ = "MIT"
+
+import logging
+from typing import Any
+
+from opcua import Client
+from opcua.ua.uaerrors import UaStatusCodeError
+
+logger = logging.getLogger(__name__)
+
+def check_node(server_info, node_info: list(dict[str, Any])):
+    """Checks, if a Node exists on the OPC UA Server.
+
+    Args:
+        server_info (dict): Information of the OPC UA Server according to JSON schema
+        node_info (dict): NodeInformation according to JSON schema
+
+    Returns:
+        bool: True if Node exists, else False
+    
+    Example of server_info and node_info:
+        {
+            "endpoint": "opc.tcp://localhost:4840",
+            "user": "",
+            "password": ""
+        }
+
+        {
+            "identifier": "1",
+            "contextualizedName": "TestTag",
+            "namespaceInfo": {
+                "type": "uri",
+                "namespaceUri": "https://semodia.com/ua/"
+            },
+            "nodeIdInfo": {
+                "type": "s",
+                "value": "Ti_V"
+            }
+        }
+
+    """
+    identifier = node_info["index"]
+    contextualized_name = node_info["contextualizedName"]
+    endpoint_url = server_info["endpoint"]
+    username = server_info.get("user", "")
+    password = server_info.get("password", "")
+
+    client = Client(endpoint_url)
+    try:
+        logger.info(f"Processing: {identifier}-{contextualized_name}")
+
+        if len(username) > 0:
+            client.set_user(username)
+            client.set_password(password)
+        client.connect()
+
+        namespace_info = node_info["namespaceInfo"]
+        namespace_type = namespace_info["type"]
+        namespace_index = None
+        if namespace_type == "uri":
+            namespace_index = client.get_namespace_index(namespace_info["namespaceUri"])
+        else:
+            namespace_index = namespace_info["namespaceIndex"]
+
+        node_id_info = node_info["nodeIdInfo"]
+        node = client.get_node("ns=" + str(namespace_index) + ";" + node_id_info["type"] + "=" + str(node_id_info["value"]))
+
+        # Access of the value to check if it's okay
+        value = node.get_value()
+        return (value is not None)
+    # TODO why this check doesn't work?
+    except UaStatusCodeError as uae:
+        logger.error(f"Node '{identifier}-{contextualized_name}' threw an error: {uae}")
+        return False
+    finally:
+        client.disconnect()

utils/resolve_unit/resolve_unit.py

@@ -0,0 +1,11 @@
+from typing import Any
+
+from utils.resolve_unit.unit_lib import Units
+
+
+def resolve_unit_symbol(identifier: int | None) -> str:
+    try:
+        unit: Any = Units(identifier)
+        return unit.symbol
+    except (TypeError, ValueError):
+        return ""