Class OptionalAttribute

src/pptx/oxml/xmlchemy.py:177–228

Defines an optional attribute on a custom element class. An optional attribute returns a default value when not present for reading. When assigned |None|, the attribute is removed.

class OptionalAttribute(BaseAttribute):
    """Defines an optional attribute on a custom element class.

    An optional attribute returns a default value when not present for reading. When assigned
    |None|, the attribute is removed.
    """

    def __init__(self, attr_name: str, simple_type: type[AttributeType], default: Any = None):
        super(OptionalAttribute, self).__init__(attr_name, simple_type)
        self._default = default

    @property
    def _docstring(self):
        """
        Return the string to use as the ``__doc__`` attribute of the property
        for this attribute.
        """
        return (
            "%s type-converted value of ``%s`` attribute, or |None| (or spec"
            "ified default value) if not present. Assigning the default valu"
            "e causes the attribute to be removed from the element."
            % (self._simple_type.__name__, self._attr_name)
        )

    @property
    def _getter(self) -> Callable[[BaseOxmlElement], Any]:
        """Callable suitable for the "get" side of the attribute property descriptor."""

        def get_attr_value(obj: BaseOxmlElement) -> Any:
            attr_str_value = obj.get(self._clark_name)
            if attr_str_value is None:
                return self._default
            return self._simple_type.from_xml(attr_str_value)

        get_attr_value.__doc__ = self._docstring
        return get_attr_value

    @property
    def _setter(self) -> Callable[[BaseOxmlElement, Any], None]:
        """Callable suitable for the "set" side of the attribute property descriptor."""

        def set_attr_value(obj: BaseOxmlElement, value: Any) -> None:
            # -- when an XML attribute has a default value, setting it to that default removes the
            # -- attribute from the element (when it is present)
            if value == self._default:
                if self._clark_name in obj.attrib:
                    del obj.attrib[self._clark_name]
                return
            str_value = self._simple_type.to_xml(value)
            obj.set(self._clark_name, str_value)

        return set_attr_value


class RequiredAttribute(BaseAttribute):