MTPPy2.0 0.1.5__py3-none-any.whl

utils/resolve_unit/unit_lib_test.py

@@ -0,0 +1,36 @@
+"""Tests for the unit catalog enum."""
+
+from enum import Enum
+from typing import Any
+
+from utils.resolve_unit.unit_lib import Units
+
+
+def test_kelvin_metadata():
+    kelvin: Any = getattr(Units, "KELVIN")
+    assert kelvin.code == 1000
+    assert kelvin.name == "KELVIN"
+    assert kelvin.symbol == "K"
+
+
+def test_unit_is_enum():
+    assert issubclass(Units, Enum)
+    assert Units(1000) is getattr(Units, "KELVIN")
+
+
+def test_unit_is_accessible_as_attribute():
+    assert Units.DEGREE_CELSIUS.code == 1001
+    assert Units.DEGREE_CELSIUS.symbol == "°C"
+    assert Units.DEGREE_CELSIUS.name == "DEGREE_CELSIUS"
+    assert Units.DEGREE_CELSIUS.de == "Grad Celsius"
+    assert Units.DEGREE_CELSIUS.en == "Degrees Celsius"
+
+
+def test_unit_names_are_explicit_and_stable():
+    assert getattr(Units, "DEGREE_CELSIUS").name == "DEGREE_CELSIUS"
+    assert getattr(Units, "SQUARE_METER").name == "SQUARE_METER"
+    assert getattr(Units, "NAUTICAL_MILE").name == "NAUTICAL_MILE"
+    assert getattr(Units, "MICROMETER").name == "MICROMETER"
+    assert getattr(Units, "PER_SECOND").name == "PER_SECOND"
+    assert all(unit.name.isidentifier() for unit in Units)
+    assert len({unit.name for unit in Units}) == len(Units)

utils/type_conversion.py

@@ -0,0 +1,236 @@
+"""**type_conversion** collects utility functions that cast values to basic types used
+in automation.
+
+OPC UA, MTP, IEC 61131 and other automation standards have quite
+specialized data types, which are not always directly supported by
+Python, for instance signed/unsigned integer types of different
+sizes (UNSIGNED SHORT != SHORT, INT != SHORT), or strings with a
+maximum length.
+
+The collected functions help to convert/cast values to the
+appropriate python types, ensuring compatibility with these standards.
+"""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from typing import (
+    LiteralString,
+    SupportsBytes,
+    SupportsFloat,
+    SupportsIndex,
+    SupportsInt,
+)
+from numbers import Real
+
+STRING_TYPE = str | bytes
+NUMERIC_TYPE = SupportsFloat | SupportsBytes | SupportsInt | LiteralString
+ANY_TYPE = STRING_TYPE | NUMERIC_TYPE
+
+# Define general constants for integer clamps
+INT8_MIN = -(2**7)  # -128
+INT8_MAX = (2**7) - 1  # 127
+UINT8_MAX = (2**8) - 1  # 255
+
+INT16_MIN = -(2**15)  # -32768
+INT16_MAX = (2**15) - 1  # 32767
+UINT16_MAX = (2**16) - 1  # 65535
+
+INT32_MIN = -(2**31)  # -2147483648
+INT32_MAX = (2**31) - 1  # 2147483647
+UINT32_MAX = (2**32) - 1  # 4294967295
+
+INT64_MIN = -(2**63)  # -9223372036854775808
+INT64_MAX = (2**63) - 1  # 9223372036854775807
+UINT64_MAX = (2**64) - 1  # 18446744073709551615
+
+
+def cast_to_string(
+    value: object,
+    max_len: SupportsIndex | None = None,
+) -> str:
+    """Casts a value to a string, optionally truncating it to a maximum length.
+
+    Args:
+        value: The value to be cast to a string.
+        max_len: The maximum length of the resulting string.
+
+    Returns:
+        The string representation of the value, optionally truncated.
+
+    """
+    s = str(value)
+    if max_len is not None:
+        s = s[: int(max_len)]
+    return s
+
+
+def cast_to_bool(value: object) -> bool:
+    """Casts canonical boolean values without treating arbitrary strings as true."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, Real):
+        return bool(value)
+    if isinstance(value, str):
+        normalized_value = value.strip().lower()
+        if normalized_value in ("true", "1"):
+            return True
+        if normalized_value in ("false", "0"):
+            return False
+    raise ValueError(f"Invalid boolean value: {value!r}")
+
+
+def cast_to_int(value: SupportsInt) -> int:
+    """Casts a value to an integer.
+
+    Args:
+        value: The value to be cast to an integer.
+
+    Returns:
+        The integer representation of the value.
+
+    """
+    int_value = int(value)
+    return max(INT32_MIN, min(INT32_MAX, int_value))
+
+
+def cast_to_uint(value: SupportsInt) -> int:
+    """Casts a value to an unsigned integer, ensuring it falls within the range of 0 to
+    4294967295.
+
+    Args:
+        value: The value to be cast to an unsigned integer.
+
+    Returns:
+        The unsigned integer representation, clamped to the valid range.
+
+    """
+    int_value = int(value)
+    return max(0, min(UINT32_MAX, int_value))
+
+
+def cast_to_short(value: SupportsInt) -> int:
+    """Casts a value to a short integer, ensuring it falls within the range of -32768
+    to 32767.
+
+    Args:
+        value: The value to be cast to a short integer.
+
+    Returns:
+        The signed short integer representation of the value, clamped to the valid
+        range.
+
+    """
+    int_value = cast_to_int(value)
+    return max(INT16_MIN, min(INT16_MAX, int_value))
+
+
+def cast_to_ushort(value: SupportsInt) -> int:
+    """Casts value to unsigned short integer, ensuring it falls within the range of
+    0 to 65535.
+
+    Args:
+        value: The value to be cast to an unsigned short integer.
+
+    Returns:
+        The unsigned short integer representation, clamped to the valid range.
+
+    """
+    int_value = cast_to_int(value)
+    return max(0, min(UINT16_MAX, int_value))
+
+
+def cast_to_long(value: SupportsInt) -> int:
+    """Casts value to long integer, ensuring it falls within the range of
+    INT64_MIN to INT64_MAX (-9223372036854775808 to 9223372036854775807).
+
+    Args:
+        value: The value to be cast to a long integer.
+
+    Returns:
+        The signed integer representation of the value, clamped to the valid range.
+
+    """
+    int_value = int(value)
+    return max(INT64_MIN, min(INT64_MAX, int_value))
+
+
+def cast_to_ulong(value: SupportsInt) -> int:
+    """Casts value to unsigned long integer, ensuring it falls within the range of
+    0 to UINT64_MAX (18446744073709551615).
+
+    Args:
+        value: The value to be cast to an unsigned long integer.
+
+    Returns:
+        The unsigned long integer representation, clamped to the valid range.
+
+    """
+    int_value = int(value)
+    return max(0, min(UINT64_MAX, int_value))
+
+
+def cast_to_byte(value: SupportsInt) -> int:
+    """Casts value to byte, ensuring it falls within the range of
+    INT8_MIN to INT8_MAX (-128 to 127).
+
+    Args:
+        value: The value to be cast to a byte.
+
+    Returns:
+        The byte representation of the value, clamped to the valid range.
+
+    """
+    int_val = int(value)
+    return max(INT8_MIN, min(INT8_MAX, int_val))
+
+
+def cast_to_ubyte(value: SupportsInt) -> int:
+    """Casts value to unsigned byte, ensuring it falls within the range of
+    0 to UINT8_MAX (255).
+
+    Args:
+        value: The value to be cast to an unsigned byte.
+
+    Returns:
+        The unsigned byte representation of the value, clamped to the valid range.
+
+    """
+    int_val = int(value)
+    return max(0, min(UINT8_MAX, int_val))
+
+
+def clamp(
+    value: float,
+    limit: tuple[float, float],
+    reset: tuple[float, float] | None = None,
+) -> float:
+    """Clamp a value between a lower and an upper bound.
+
+    When ``value`` is below the lower bound or above the upper bound, it is
+    replaced by the corresponding element of ``reset``. If ``reset`` is not
+    provided, the bounds themselves are used as the replacement values.
+
+    Args:
+        value: The value to clamp.
+        limit: A ``(min, max)`` pair defining the inclusive bounds.
+        reset: An optional ``(min, max)`` pair returned when
+            ``value`` is outside the bounds. Defaults to ``limit``.
+
+    Returns:
+        The clamped value, or the matching fallback bound.
+
+    Example:
+        clamp(value,[0,100],[0,0]) - generates a saw-tooth when fed with a ramp
+        clamp(value,[0,0]) - clamps the value between upper and lower bound
+
+    """
+    if not reset:
+        reset = limit
+    if value < limit[0]:
+        return reset[0]
+    if value > limit[1]:
+        return reset[1]
+    return value

utils/type_conversion_test.py

@@ -0,0 +1,114 @@
+"""Test suite for type conversion helpers."""
+
+import pytest
+
+from utils import type_conversion as tc
+
+
+def test_cast_to_string():
+    assert tc.cast_to_string(123) == "123"
+    assert tc.cast_to_string(b"value") == "b'value'"
+    assert tc.cast_to_string("abcdef", max_len=3) == "abc"
+    assert tc.cast_to_string("abcdef", max_len=None) == "abcdef"
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (True, True),
+        (False, False),
+        (1, True),
+        (0, False),
+        (" true ", True),
+        ("FALSE", False),
+        ("1", True),
+        ("0", False),
+    ],
+)
+def test_cast_to_bool_accepts_canonical_values(value, expected):
+    assert tc.cast_to_bool(value) is expected
+
+
+@pytest.mark.parametrize("value", ["yes", "no", "", None])
+def test_cast_to_bool_rejects_non_canonical_values(value):
+    with pytest.raises(ValueError, match="Invalid boolean value"):
+        tc.cast_to_bool(value)
+
+
+@pytest.mark.parametrize(
+    ("converter", "value", "expected"),
+    [
+        (tc.cast_to_int, 12.9, 12),
+        (tc.cast_to_uint, 12, 12),
+        (tc.cast_to_short, 12, 12),
+        (tc.cast_to_ushort, 12, 12),
+        (tc.cast_to_long, 12, 12),
+        (tc.cast_to_ulong, 12, 12),
+        (tc.cast_to_byte, 12, 12),
+        (tc.cast_to_ubyte, 12, 12),
+    ],
+)
+def test_integer_converters_accept_normal_values(converter, value, expected):
+    assert converter(value) == expected
+
+
+@pytest.mark.parametrize(
+    ("converter", "value", "expected"),
+    [
+        (tc.cast_to_int, tc.INT32_MIN - 1, tc.INT32_MIN),
+        (tc.cast_to_int, tc.INT32_MAX + 1, tc.INT32_MAX),
+        (tc.cast_to_uint, -1, 0),
+        (tc.cast_to_uint, tc.UINT32_MAX + 1, tc.UINT32_MAX),
+        (tc.cast_to_short, tc.INT16_MIN - 1, tc.INT16_MIN),
+        (tc.cast_to_short, tc.INT16_MAX + 1, tc.INT16_MAX),
+        (tc.cast_to_ushort, -1, 0),
+        (tc.cast_to_ushort, tc.UINT16_MAX + 1, tc.UINT16_MAX),
+        (tc.cast_to_long, tc.INT64_MIN - 1, tc.INT64_MIN),
+        (tc.cast_to_long, tc.INT64_MAX + 1, tc.INT64_MAX),
+        (tc.cast_to_ulong, -1, 0),
+        (tc.cast_to_ulong, tc.UINT64_MAX + 1, tc.UINT64_MAX),
+        (tc.cast_to_byte, tc.INT8_MIN - 1, tc.INT8_MIN),
+        (tc.cast_to_byte, tc.INT8_MAX + 1, tc.INT8_MAX),
+        (tc.cast_to_ubyte, -1, 0),
+        (tc.cast_to_ubyte, tc.UINT8_MAX + 1, tc.UINT8_MAX),
+    ],
+)
+def test_integer_converters_clamp_out_of_range_values(converter, value, expected):
+    assert converter(value) == expected
+
+
+@pytest.mark.parametrize(
+    "converter",
+    [
+        tc.cast_to_int,
+        tc.cast_to_uint,
+        tc.cast_to_short,
+        tc.cast_to_ushort,
+        tc.cast_to_long,
+        tc.cast_to_ulong,
+        tc.cast_to_byte,
+        tc.cast_to_ubyte,
+    ],
+)
+def test_integer_converters_reject_non_numeric_strings(converter):
+    with pytest.raises(ValueError):
+        converter("not a number")
+
+
+def test_clamp_keeps_values_inside_limits():
+    assert tc.clamp(50, (0, 100)) == 50
+    assert tc.clamp(0, (0, 100)) == 0
+    assert tc.clamp(100, (0, 100)) == 100
+
+
+@pytest.mark.parametrize(
+    ("value", "limit", "reset", "expected"),
+    [
+        (-1, (0, 100), None, 0),
+        (101, (0, 100), None, 100),
+        (-1, (0, 100), (-10, 110), -10),
+        (101, (0, 100), (-10, 110), 110),
+    ],
+)
+def test_clamp_replaces_values_outside_limits(value, limit, reset, expected):
+    assert tc.clamp(value, limit, reset) == expected