Class ZeroOrOneChoice

src/pptx/oxml/xmlchemy.py:600–660

An `EG_*` element group where at most one of its members may appear as a child.

class ZeroOrOneChoice(_BaseChildElement):
    """An `EG_*` element group where at most one of its members may appear as a child."""

    def __init__(self, choices: Iterable[Choice], successors: Iterable[str] = ()):
        self._choices = tuple(choices)
        self._successors = tuple(successors)

    def populate_class_members(self, element_cls: Type[BaseOxmlElement], prop_name: str):
        """Add the appropriate methods to `element_cls`."""
        super(ZeroOrOneChoice, self).populate_class_members(element_cls, prop_name)
        self._add_choice_getter()
        for choice in self._choices:
            choice.populate_class_members(element_cls, self._prop_name, self._successors)
        self._add_group_remover()

    def _add_choice_getter(self):
        """Add a read-only `.{prop_name}` property to the element class.

        The property returns the present member of this group, or |None| if none are present.
        """
        property_ = property(self._choice_getter, None, None)
        # assign unconditionally to overwrite element name definition
        setattr(self._element_cls, self._prop_name, property_)

    def _add_group_remover(self):
        """Add a `._remove_eg_x()` method to the element class for this choice group."""

        def _remove_choice_group(obj: BaseOxmlElement) -> None:
            for tagname in self._member_nsptagnames:
                obj.remove_all(tagname)

        _remove_choice_group.__doc__ = "Remove the current choice group child element if present."
        self._add_to_class(self._remove_choice_group_method_name, _remove_choice_group)

    @property
    def _choice_getter(self):
        """
        Return a function object suitable for the "get" side of the property
        descriptor.
        """

        def get_group_member_element(obj: BaseOxmlElement) -> BaseOxmlElement | None:
            return cast(
                "BaseOxmlElement | None", obj.first_child_found_in(*self._member_nsptagnames)
            )

        get_group_member_element.__doc__ = (
            "Return the child element belonging to this element group, or "
            "|None| if no member child is present."
        )
        return get_group_member_element

    @lazyproperty
    def _member_nsptagnames(self) -> list[str]:
        """Sequence of namespace-prefixed tagnames, one for each member element of choice group."""
        return [choice.nsptagname for choice in self._choices]

    @lazyproperty