Class Union

traitlets/traitlets.py:2402–2483

A trait type representing a Union type.

class Union(TraitType[t.Any, t.Any]):
    """A trait type representing a Union type."""

    def __init__(self, trait_types: t.Any, **kwargs: t.Any) -> None:
        """Construct a Union  trait.

        This trait allows values that are allowed by at least one of the
        specified trait types. A Union traitlet cannot have metadata on
        its own, besides the metadata of the listed types.

        Parameters
        ----------
        trait_types : sequence
            The list of trait types of length at least 1.
        **kwargs
            Extra kwargs passed to `TraitType`

        Notes
        -----
        Union([Float(), Bool(), Int()]) attempts to validate the provided values
        with the validation function of Float, then Bool, and finally Int.

        Parsing from string is ambiguous for container types which accept other
        collection-like literals (e.g. List accepting both `[]` and `()`
        precludes Union from ever parsing ``Union([List(), Tuple()])`` as a tuple;
        you can modify behaviour of too permissive container traits by overriding
        ``_literal_from_string_pairs`` in subclasses.
        Similarly, parsing unions of numeric types is only unambiguous if
        types are provided in order of increasing permissiveness, e.g.
        ``Union([Int(), Float()])`` (since floats accept integer-looking values).
        """
        self.trait_types = list(trait_types)
        self.info_text = " or ".join([tt.info() for tt in self.trait_types])
        super().__init__(**kwargs)

    def default(self, obj: t.Any = None) -> t.Any:
        default = super().default(obj)
        for trait in self.trait_types:
            if default is Undefined:
                default = trait.default(obj)
            else:
                break
        return default

    def class_init(self, cls: type[HasTraits], name: str | None) -> None:
        for trait_type in reversed(self.trait_types):
            trait_type.class_init(cls, None)
        super().class_init(cls, name)

    def subclass_init(self, cls: type[t.Any]) -> None:
        for trait_type in reversed(self.trait_types):
            trait_type.subclass_init(cls)
        # explicitly not calling super().subclass_init(cls)
        # to opt out of instance_init

    def validate(self, obj: t.Any, value: t.Any) -> t.Any:
        with obj.cross_validation_lock:
            for trait_type in self.trait_types: