feat: support multi-target transitions in Transition class

The `target` parameter now accepts `State | List[State] | None`,
enabling SCXML parallel region entry where a single transition
targets multiple states. Internally stores as `_targets` list with
backward-compatible `target` property (returns first target) and
new `targets` property (returns full list).

Author: fgmacedo

statemachine/transition.py

@@ -1,5 +1,6 @@
 from copy import deepcopy
 from typing import TYPE_CHECKING
+from typing import List
 
 from .callbacks import CallbackGroup
 from .callbacks import CallbackPriority
@@ -17,7 +18,9 @@ class Transition:
 
     Args:
         source (State): The origin state of the transition.
-        target (State): The target state of the transition.
+        target: The target state(s) of the transition. Can be a single ``State``, a list of
+            states (for multi-target transitions, e.g. SCXML parallel region entry), or ``None``
+            (targetless transition).
         event (Optional[Union[str, List[str]]]): List of designators of events that trigger this
             transition. Can be either a list of strings, or a space-separated string list of event
             descriptors.
@@ -40,7 +43,7 @@ class Transition:
     def __init__(
         self,
         source: "State",
-        target: "State | None" = None,
+        target: "State | List[State] | None" = None,
         event=None,
         internal=False,
         initial=False,
@@ -52,18 +55,26 @@ def __init__(
         after=None,
     ):
         self.source = source
-        self.target = target
+        if isinstance(target, list):
+            self._targets: "List[State]" = target
+        elif target is not None:
+            self._targets = [target]
+        else:
+            self._targets = []
         self.internal = internal
         self.initial = initial
-        self.is_self = target is source
+        first_target = self._targets[0] if self._targets else None
+        self.is_self = first_target is source
         """Is the target state the same as the source state?"""
 
-        if internal and not (self.is_self or (target and target.is_descendant(source))):
+        if internal and not (
+            self.is_self or (first_target and first_target.is_descendant(source))
+        ):
             raise InvalidDefinition(
                 _(
                     "Not a valid internal transition from source {source!r}, "
                     "target {target!r} should be self or a descendant."
-                ).format(source=source, target=target)
+                ).format(source=source, target=first_target)
             )
 
         if initial and any([cond, unless, event]):
@@ -87,6 +98,23 @@ def __init__(
             .add(unless, priority=CallbackPriority.INLINE, expected_value=False)
         )
 
+    @property
+    def target(self) -> "State | None":
+        """Primary target state (first target for multi-target transitions)."""
+        return self._targets[0] if self._targets else None
+
+    @target.setter
+    def target(self, value: "State | None"):
+        if value is None:
+            self._targets = []
+        else:
+            self._targets = [value]
+
+    @property
+    def targets(self) -> "List[State]":
+        """All target states. For single-target transitions, returns a one-element list."""
+        return self._targets
+
     def __repr__(self):
         return (
             f"{type(self).__name__}({self.source.name!r}, {self.target and self.target.name!r}, "
@@ -147,7 +175,7 @@ def add_event(self, value):
 
     def _copy_with_args(self, **kwargs):
         source = kwargs.pop("source", self.source)
-        target = kwargs.pop("target", self.target)
+        target = kwargs.pop("target", list(self._targets) if self._targets else None)
         event = kwargs.pop("event", self.event)
         internal = kwargs.pop("internal", self.internal)
         new_transition = Transition(