vortexpy 6.2.3__tar.gz → 6.3.0__tar.gz

vortexpy-6.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2016-2026 Flying Ion Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

{vortexpy-6.2.3 → vortexpy-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortexpy
-Version: 6.2.3
+Version: 6.3.0
 Summary: Flying Ion's observable, routable, data serialisation and transport code.
 Author-email: Flying Ion Pty Ltd <contact@flyingion.com>
 License: MIT

{vortexpy-6.2.3 → vortexpy-6.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortexpy"
-version = "6.2.3"
+version = "6.3.0"
 license = {text = "MIT"}
 authors = [{name = "Flying Ion Pty Ltd", email = "contact@flyingion.com"}]
 description = "Flying Ion's observable, routable, data serialisation and transport code."

{vortexpy-6.2.3 → vortexpy-6.3.0}/vortex/Jsonable.py

@@ -9,10 +9,9 @@
 import logging
 import traceback
 import typing
+from _collections import defaultdict
 from copy import copy, deepcopy
 from json import JSONEncoder
-from typing import List
-from _collections import defaultdict
 
 logger = logging.getLogger(__name__)
 
@@ -27,15 +26,15 @@ JSONEncoder.item_separator = ","
 JSONEncoder.key_separator = ":"
 
 
-class Jsonable(object):
+class Jsonable:
     """Xmlable
     Inherit from this class if you want to serialise to XML.
     """
 
-    __fieldNames__: List[str] = None
+    __fieldNames__: list[str] = None
     __rapuiSerialiseType__ = T_GENERIC_CLASS
 
-    __rawJonableFields__: List[str] = None
+    __rawJonableFields__: list[str] = None
 
     JSON_CLASS_TYPE = "_ct"
     JSON_CLASS = "_c"
@@ -52,9 +51,7 @@ class Jsonable(object):
         cls.__memoryLoggingEnabled = True
 
     @classmethod
-    def memoryLoggingDump(
-        cls, top=10, over=100
-    ) -> List[typing.Tuple[str, int]]:
+    def memoryLoggingDump(cls, top=10, over=100) -> list[tuple[str, int]]:
         if not Jsonable.__memoryLoggingRefs:
             return []
 
@@ -67,10 +64,10 @@ class Jsonable(object):
         return list(filter(lambda x: x[1] >= over, data))[:top]
 
     def __memLoggingKey(self):
-        if getattr(self, "__rapuiSerialiseType__") == T_RAPUI_TUPLE:
-            key = "Tuple: " + getattr(self, "__tupleType__")
+        if self.__rapuiSerialiseType__ == T_RAPUI_TUPLE:
+            key = "Tuple: " + self.__tupleType__
 
-        elif getattr(self, "__rapuiSerialiseType__") == T_RAPUI_PAYLOAD:
+        elif self.__rapuiSerialiseType__ == T_RAPUI_PAYLOAD:
             assert hasattr(self, "filt"), "Payload is missing filt"
             if "key" in self.filt:
                 key = "Payload: key=" + self.filt["key"]
@@ -78,7 +75,7 @@ class Jsonable(object):
                 key = "Payload: " + str(self.filt)
 
         else:
-            key = "Jsonable: " + getattr(self, "__rapuiSerialiseType__")
+            key = "Jsonable: " + self.__rapuiSerialiseType__
 
         return key
 
@@ -100,9 +97,7 @@ class Jsonable(object):
         from .Tuple import TupleField
 
         if isinstance(value, TupleField):
-            value = (
-                None if value.defaultValue == None else copy(value.defaultValue)
-            )
+            value = None if value.defaultValue == None else copy(value.defaultValue)
 
         try:
             valueType = V_NULL if value is None else toRapuiType(value)
@@ -316,6 +311,54 @@ class Jsonable(object):
             ):
                 value = enumClass(value)
 
+            # Reconstruct Tuple subclasses for fields annotated with a Tuple
+            # type. Serialised tuples may arrive as plain dicts (no _ct/_c
+            # markers) when the sender has no Tuple class for the value; the
+            # receiving class's annotation drives the coercion.
+            value = self._coerceValueToTypeHint(value, hints.get(name))
+
             setattr(self, name, value)
 
         return self
+
+    def _coerceValueToTypeHint(
+        self, value: typing.Any, typeHint: typing.Any
+    ) -> typing.Any:
+        """Coerce a plain JSON value into the type declared by *typeHint*.
+
+        Currently handles ``vortex.Tuple`` subclasses (and lists of them);
+        other hints pass through unchanged. Plain dicts are validated:
+        unknown keys raise ``KeyError``. Values that are neither a dict nor
+        ``None`` for a Tuple-typed field raise ``ValueError``.
+        """
+        from .Tuple import Tuple
+
+        tupleClass = utilTupleClassFromTypeHint(typeHint)
+        if tupleClass is not None:
+            if isinstance(value, tupleClass):
+                return value
+            if isinstance(value, dict):
+                extraKeys = set(value) - set(tupleClass.__fieldNames__)
+                if extraKeys:
+                    raise KeyError(
+                        f"Unexpected keys for {tupleClass.__name__}:"
+                        f" {sorted(extraKeys)}"
+                    )
+                return Tuple.restfulJsonDictToTupleWithValidation(value, tupleClass)
+            if value is None:
+                return None
+            raise ValueError(
+                f"Expected dict for {tupleClass.__name__}, got {type(value).__name__}"
+            )
+
+        origin = typing.get_origin(typeHint)
+        if origin is list and isinstance(value, list):
+            args = typing.get_args(typeHint)
+            if args:
+                elementClass = utilTupleClassFromTypeHint(args[0])
+                if elementClass is not None:
+                    return [
+                        self._coerceValueToTypeHint(item, args[0]) for item in value
+                    ]
+
+        return value

vortexpy-6.3.0/vortex/Jsonable_tuple_dict_coercion_test.py

@@ -0,0 +1,144 @@
+# ruff: noqa: C408, N999
+# Copyright (c) 2016-2026 Flying Ion Pty Ltd
+#
+# This software is open source; the MIT license applies.
+# See LICENSE for the full license text.
+
+"""Tests for Jsonable.fromJsonDict coercion of plain dicts into Tuple fields."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+
+import pytest
+
+from vortex.SerialiseUtil import ISO8601
+from vortex.Tuple import Tuple, TupleField, addTupleType
+
+
+class _ColorE(StrEnum):
+    RED = "red"
+    BLUE = "blue"
+
+
+@addTupleType
+class _InnerTuple(Tuple):
+    __tupleType__ = "flyingion.vortex.JsonableCoercionInnerTuple"
+    fieldMap: dict[str, str] = TupleField()
+    color: _ColorE = TupleField()
+
+
+@addTupleType
+class _OuterTuple(Tuple):
+    __tupleType__ = "flyingion.vortex.JsonableCoercionOuterTuple"
+    inner: _InnerTuple = TupleField()
+    inners: list[_InnerTuple] = TupleField()
+    optInner: _InnerTuple | None = TupleField()
+
+
+@addTupleType
+class _DatetimeInnerTuple(Tuple):
+    __tupleType__ = "flyingion.vortex.JsonableCoercionDatetimeInnerTuple"
+    when: datetime = TupleField()
+
+
+@addTupleType
+class _DatetimeOuterTuple(Tuple):
+    __tupleType__ = "flyingion.vortex.JsonableCoercionDatetimeOuterTuple"
+    inner: _DatetimeInnerTuple = TupleField()
+
+
+def test_from_json_dict_coerces_nested_tuple_field() -> None:
+    data = dict(
+        inner=dict(fieldMap=dict(payload="body"), color="blue"),
+        inners=[dict(fieldMap=dict(x="y"), color="red")],
+        optInner=None,
+    )
+    result = _OuterTuple().fromJsonDict(data)
+
+    assert isinstance(result.inner, _InnerTuple), (
+        "plain dict inner must coerce to declared Tuple type"
+    )
+    assert result.inner.fieldMap == dict(payload="body"), (
+        "fieldMap must coerce nested dict values"
+    )
+    assert result.inner.color == _ColorE.BLUE, (
+        "enum field must coerce from string value"
+    )
+    assert isinstance(result.inners, list), "inners must be a list"
+    assert len(result.inners) == 1, "inners must contain one item"
+    assert isinstance(result.inners[0], _InnerTuple), (
+        "list item must coerce to declared Tuple type"
+    )
+    assert result.inners[0].color == _ColorE.RED, (
+        "list item enum must coerce from string value"
+    )
+    assert result.optInner is None, "optInner None must be preserved"
+
+
+def test_from_json_dict_coerces_optional_nested_tuple_field() -> None:
+    data = dict(
+        inner=dict(fieldMap=dict(), color="red"),
+        inners=[],
+        optInner=dict(fieldMap=dict(k="v"), color="blue"),
+    )
+    result = _OuterTuple().fromJsonDict(data)
+
+    assert isinstance(result.optInner, _InnerTuple), (
+        "optional inner dict must coerce to declared Tuple type"
+    )
+    assert result.optInner.color == _ColorE.BLUE, (
+        "optional inner enum must coerce from string value"
+    )
+
+
+def test_from_json_dict_coerces_nested_tuple_with_iso_datetime() -> None:
+    when = datetime(2024, 6, 15, 10, 30, 45, 123456, tzinfo=UTC)
+    data = dict(
+        inner=dict(when=when.strftime(ISO8601)),
+    )
+    result = _DatetimeOuterTuple().fromJsonDict(data)
+
+    assert isinstance(result.inner.when, datetime), (
+        "nested tuple datetime field must decode to datetime"
+    )
+    assert result.inner.when == when, "nested tuple datetime field must preserve value"
+
+
+def test_from_json_dict_enum_inside_nested_tuple_reconstructs() -> None:
+    data = dict(inner=dict(fieldMap=dict(), color="blue"), inners=[], optInner=None)
+    result = _OuterTuple().fromJsonDict(data)
+
+    assert result.inner.color == _ColorE.BLUE, (
+        "nested enum field must reconstruct from string"
+    )
+    assert isinstance(result.inner.color, _ColorE), (
+        "nested enum field must be the enum type"
+    )
+
+
+def test_from_json_dict_missing_required_key_raises_validation_error() -> None:
+    data = dict(
+        inner=dict(fieldMap=dict(payload="body")),  # missing color
+        inners=[],
+        optInner=None,
+    )
+    with pytest.raises((KeyError, TypeError)):
+        _OuterTuple().fromJsonDict(data)
+
+
+def test_from_json_dict_extra_key_raises_validation_error() -> None:
+    data = dict(
+        inner=dict(fieldMap=dict(), color="red", extra=1),
+        inners=[],
+        optInner=None,
+    )
+    with pytest.raises((KeyError, TypeError)):
+        _OuterTuple().fromJsonDict(data)
+
+
+def test_from_json_dict_non_dict_for_tuple_typed_field_raises() -> None:
+    data = dict(inner="not-a-dict", inners=[], optInner=None)
+    with pytest.raises(ValueError):
+        _OuterTuple().fromJsonDict(data)

{vortexpy-6.2.3 → vortexpy-6.3.0}/vortex/PayloadResponse.py

@@ -16,6 +16,8 @@ from uuid import uuid4
 import pytz
 from twisted.internet import reactor
 from twisted.internet.defer import Deferred
+from twisted.internet.defer import TimeoutError
+from twisted.internet.interfaces import IDelayedCall
 from twisted.python.failure import Failure
 
 from vortex.PayloadEndpoint import PayloadEndpoint
@@ -68,6 +70,7 @@ class PayloadResponse(Deferred):
         timeout: Optional[float] = None,
         resultCheck=True,
         logTimeoutException=True,
+        retries: Optional[int] = None,
     ) -> None:
         """Constructor
 
@@ -83,9 +86,16 @@ class PayloadResponse(Deferred):
                     it errback will be called.
         :param logTimeoutException: When True, payload timeouts log at ERROR.
                     When False, timeouts log at DEBUG with neutral wording.
+        :param retries: The number of times to resend the payload envelope
+                    when the response times out; None sends once with no
+                    retries. Requires destVortexName or destVortexUuid.
         """
         Deferred.__init__(self)
 
+        assert retries is None or (destVortexName or destVortexUuid), (
+            "retries requires destVortexName or destVortexUuid to resend"
+        )
+
         if not timeout:
             timeout = self.TIMEOUT
 
@@ -99,6 +109,11 @@ class PayloadResponse(Deferred):
         payloadEnvelope.filt[self.MESSAGE_ID_KEY] = self._messageId
         self._filt = copy(payloadEnvelope.filt)
         self._destVortexName = destVortexName
+        self._destVortexUuid = destVortexUuid
+        self._payloadEnvelope = payloadEnvelope
+        self._timeout = timeout
+        self._retries: Optional[int] = retries
+        self._timeoutDelayedCall: Optional[IDelayedCall] = None
 
         self._status = self.PROCESSING
         self._date = datetime.now(pytz.utc)
@@ -107,23 +122,49 @@ class PayloadResponse(Deferred):
             self._filt, self._process, requiredPermissions=frozenset()
         )
 
-        if destVortexName or destVortexUuid:
-            d: Deferred = payloadEnvelope.toVortexMsgDefer()
-            d.addCallback(
-                VortexFactory.sendVortexMsg,
-                destVortexName=destVortexName,
-                destVortexUuid=destVortexUuid,
-            )
-            d.addErrback(self.errback)
+        self._sendVortexMsg()
 
         try:
             raise Exception()
         except:
             self._stack = sys.exc_info()[2]
 
-        # noinspection PyTypeChecker
-        self.addTimeout(timeout, reactor)
-        self.addErrback(self._timedOut)
+        if retries is None:
+            # noinspection PyTypeChecker
+            self.addTimeout(timeout, reactor)
+            self.addErrback(self._timedOut)
+        else:
+            self._armTimeout()
+
+    def _sendVortexMsg(self) -> None:
+        if not (self._destVortexName or self._destVortexUuid):
+            return
+
+        d: Deferred = self._payloadEnvelope.toVortexMsgDefer()
+        d.addCallback(
+            VortexFactory.sendVortexMsg,
+            destVortexName=self._destVortexName,
+            destVortexUuid=self._destVortexUuid,
+        )
+        d.addErrback(self.errback)
+
+    def _armTimeout(self) -> None:
+        self._timeoutDelayedCall = reactor.callLater(  # type: ignore[attr-defined]  # pyright: ignore[reportAttributeAccessIssue]
+            self._timeout, self._onTimeout
+        )
+
+    def _onTimeout(self) -> None:
+        self._timeoutDelayedCall = None
+
+        if self._retries:
+            self._retries -= 1
+            self._sendVortexMsg()
+            self._armTimeout()
+            return
+
+        failure = Failure(TimeoutError("timed out"))
+        self._timedOut(failure)
+        self.errback(failure)
 
     @classmethod
     def isResponsePayloadEnvelope(cls, payloadEnvelope: PayloadEnvelope):
@@ -162,6 +203,12 @@ class PayloadResponse(Deferred):
             self._endpoint.shutdown()
             self._endpoint = None
 
+        if self._timeoutDelayedCall is not None:
+            # zope Interface methods omit self, which static analysis cannot bind
+            if self._timeoutDelayedCall.active():  # pyright: ignore[reportAttributeAccessIssue]
+                self._timeoutDelayedCall.cancel()  # pyright: ignore[reportAttributeAccessIssue]
+            self._timeoutDelayedCall = None
+
         if self._destVortexName and vortexName != self._destVortexName:
             logger.debug(
                 "Received response from a vortex other than the dest vortex, "
@@ -175,14 +222,10 @@ class PayloadResponse(Deferred):
             logger.error("Received response after timeout for %s" % self._filt)
             return
 
-        if self._resultCheck and not payloadEnvelope.result in (None, True):
+        if self._resultCheck and payloadEnvelope.result not in (None, True):
             self._status = self.FAILED
             self.errback(
-                Failure(
-                    Exception(payloadEnvelope.result).with_traceback(
-                        self._stack
-                    )
-                )
+                Failure(Exception(payloadEnvelope.result).with_traceback(self._stack))
             )
 
         else:

vortexpy-6.3.0/vortex/PayloadResponse_test.py

@@ -0,0 +1,161 @@
+import unittest
+from unittest.mock import MagicMock, patch
+
+from twisted.internet.defer import TimeoutError
+from twisted.internet.defer import succeed
+from twisted.python.failure import Failure
+
+from vortex.PayloadEnvelope import PayloadEnvelope
+from vortex.PayloadResponse import PayloadResponse
+
+
+class _FakeDelayedCall:
+    def __init__(self, callback) -> None:
+        self.callback = callback
+        self.cancelled = False
+
+    def active(self) -> bool:
+        return not self.cancelled
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+    def fire(self) -> None:
+        self.callback()
+
+
+class _FakeReactor:
+    def __init__(self) -> None:
+        self.delayedCalls: list[_FakeDelayedCall] = []
+
+    def callLater(self, _seconds: float, callback) -> _FakeDelayedCall:
+        call = _FakeDelayedCall(callback)
+        self.delayedCalls.append(call)
+        return call
+
+
+class PayloadResponseLoggingTest(unittest.TestCase):
+    @patch("vortex.PayloadResponse.VortexFactory.sendVortexMsg")
+    @patch("vortex.PayloadResponse.logger")
+    def testTimeoutLogsDebugWhenLogTimeoutExceptionFalse(
+        self, mockLogger: MagicMock, _mockSend: MagicMock
+    ) -> None:
+        pr = PayloadResponse(
+            PayloadEnvelope(filt={"key": "example"}),
+            timeout=30.0,
+            logTimeoutException=False,
+        )
+        pr._timedOut(Failure(TimeoutError("timed out")))
+        mockLogger.error.assert_not_called()
+        mockLogger.debug.assert_called_once()
+
+    @patch("vortex.PayloadResponse.VortexFactory.sendVortexMsg")
+    @patch("vortex.PayloadResponse.logger")
+    def testTimeoutLogsErrorWhenLogTimeoutExceptionTrue(
+        self, mockLogger: MagicMock, _mockSend: MagicMock
+    ) -> None:
+        pr = PayloadResponse(
+            PayloadEnvelope(filt={"key": "example"}),
+            timeout=30.0,
+            logTimeoutException=True,
+        )
+        pr._timedOut(Failure(TimeoutError("timed out")))
+        mockLogger.debug.assert_not_called()
+        mockLogger.error.assert_called_once()
+
+
+class PayloadResponseRetryTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.fakeReactor = _FakeReactor()
+        patch("vortex.PayloadResponse.reactor", self.fakeReactor).start()
+        self.mockSend: MagicMock = patch(
+            "vortex.PayloadResponse.VortexFactory.sendVortexMsg"
+        ).start()
+        patch(
+            "vortex.PayloadEnvelope.PayloadEnvelope.toVortexMsgDefer",
+            return_value=succeed(b"{}"),
+        ).start()
+        self.addCleanup(patch.stopall)
+
+    def testTimeoutResendsPayloadAndSucceedsOnLateResponse(self) -> None:
+        pr = PayloadResponse(
+            PayloadEnvelope(filt={"key": "example"}),
+            destVortexName="destVortex",
+            timeout=30.0,
+            retries=1,
+        )
+
+        self.assertEqual(self.mockSend.call_count, 1)
+        self.assertEqual(len(self.fakeReactor.delayedCalls), 1)
+
+        # First attempt times out, the payload is resent and re-armed
+        self.fakeReactor.delayedCalls[0].fire()
+
+        self.assertEqual(self.mockSend.call_count, 2)
+        self.assertEqual(len(self.fakeReactor.delayedCalls), 2)
+        self.assertEqual(pr.status, PayloadResponse.PROCESSING)
+
+        # The resent payload receives a response
+        results = []
+        pr.addCallback(results.append)
+        response = PayloadEnvelope(filt={"key": "example"})
+        pr._process(response, "vortexUuid", "destVortex")
+
+        self.assertEqual(pr.status, PayloadResponse.SUCCESS)
+        self.assertEqual(results, [response])
+        self.assertTrue(self.fakeReactor.delayedCalls[1].cancelled)
+
+    def testExhaustedRetriesErrbackWithTimedOut(self) -> None:
+        pr = PayloadResponse(
+            PayloadEnvelope(filt={"key": "example"}),
+            destVortexName="destVortex",
+            timeout=30.0,
+            retries=1,
+        )
+
+        failures = []
+        pr.addErrback(failures.append)
+
+        self.fakeReactor.delayedCalls[0].fire()
+        self.assertEqual(self.mockSend.call_count, 2)
+        self.assertEqual(pr.status, PayloadResponse.PROCESSING)
+
+        self.fakeReactor.delayedCalls[1].fire()
+
+        self.assertEqual(self.mockSend.call_count, 2)
+        self.assertEqual(pr.status, PayloadResponse.TIMED_OUT)
+        self.assertEqual(len(failures), 1)
+        self.assertIsInstance(failures[0].value, TimeoutError)
+
+    def testRetriesRequiresDestinationVortex(self) -> None:
+        with self.assertRaises(AssertionError):
+            PayloadResponse(
+                PayloadEnvelope(filt={"key": "example"}),
+                timeout=30.0,
+                retries=1,
+            )
+
+    def testDefaultTimeoutPathDoesNotResend(self) -> None:
+        pr = PayloadResponse(
+            PayloadEnvelope(filt={"key": "example"}),
+            destVortexName="destVortex",
+            timeout=30.0,
+        )
+
+        failures = []
+        pr.addErrback(failures.append)
+
+        self.assertEqual(self.mockSend.call_count, 1)
+        self.assertEqual(len(self.fakeReactor.delayedCalls), 1)
+
+        # addTimeout cancels the deferred, which errbacks with TimeoutError
+        self.fakeReactor.delayedCalls[0].fire()
+
+        self.assertEqual(self.mockSend.call_count, 1)
+        self.assertEqual(pr.status, PayloadResponse.TIMED_OUT)
+        self.assertEqual(len(failures), 1)
+        self.assertIsInstance(failures[0].value, TimeoutError)
+
+
+if __name__ == "__main__":
+    unittest.main()

{vortexpy-6.2.3 → vortexpy-6.3.0}/vortex/SerialiseUtil.py

@@ -12,9 +12,9 @@ import functools
 import logging
 import types
 import typing
-from base64 import b64encode, b64decode
+from base64 import b64decode, b64encode
 from collections import defaultdict
-from datetime import UTC, datetime, date
+from datetime import UTC, date, datetime
 
 import pytz
 from sqlalchemy.orm.collections import InstrumentedList
@@ -114,15 +114,15 @@ def convertFromWkbElement(value):
 
 
 def serialiseWkb(wkb: WKBElement) -> str:
-    from geoalchemy2.shape import to_shape
     import shapely
+    from geoalchemy2.shape import to_shape
 
     return b64encode(shapely.wkb.dumps(to_shape(wkb))).decode()
 
 
 def deserialiseWkb(wkbB64Data: str) -> WKBElement:
-    from geoalchemy2.shape import from_shape
     import shapely
+    from geoalchemy2.shape import from_shape
 
     return from_shape(shapely.wkb.loads(b64decode(wkbB64Data)))
 
@@ -253,9 +253,7 @@ def fromStr(val: str, typeName: str):
     if typeName == T_DATETIME:
         # TODO: Check with ISO8601_JS_REGEXP
         if len(val) == len("2017-06-06T09:40:37.097Z"):
-            return datetime.strptime(val, ISO8601_JS_FORMAT).replace(
-                tzinfo=pytz.UTC
-            )
+            return datetime.strptime(val, ISO8601_JS_FORMAT).replace(tzinfo=pytz.UTC)
 
         if len(val) <= len("2017-06-06 09:40:37.097068"):
             raise ValueError(
@@ -286,7 +284,7 @@ def fromRapuiType(typeName: str):
     return TYPE_MAP_RAPUI_TO_PY[typeName]
 
 
-@functools.lru_cache(maxsize=None)
+@functools.cache
 def utilTypeHintsForClass(cls: type) -> dict[str, typing.Any]:
     """Resolved type hints for a class, cached per class.
 
@@ -328,6 +326,29 @@ def utilEnumClassFromTypeHint(typeHint: typing.Any) -> type[enum.Enum] | None:
     return None
 
 
+def utilTupleClassFromTypeHint(typeHint: typing.Any) -> type | None:
+    """The ``vortex.Tuple`` subclass for a field type hint, or None.
+
+    Handles bare ``SomeTuple``, ``SomeTuple | None`` and
+    ``Optional[SomeTuple]``; every other hint returns None.
+    """
+    from vortex.Tuple import Tuple
+
+    if typeHint is None:
+        return None
+
+    if isinstance(typeHint, type) and issubclass(typeHint, Tuple):
+        return typeHint
+
+    origin = typing.get_origin(typeHint)
+    if origin in (typing.Union, types.UnionType):
+        for arg in typing.get_args(typeHint):
+            if isinstance(arg, type) and issubclass(arg, Tuple):
+                return arg
+
+    return None
+
+
 def toRapuiType(value):
     if value is None:
         return V_NULL