Class RequiredAttribute

src/docx/oxml/xmlchemy.py:217–261

Defines a required attribute on a custom element class. A required attribute is assumed to be present for reading, so does not have a default value; its actual value is always used. If missing on read, an |InvalidXmlError| is raised. It also does not remove the attribute if |None| is

class RequiredAttribute(BaseAttribute):
    """Defines a required attribute on a custom element class.

    A required attribute is assumed to be present for reading, so does not have a
    default value; its actual value is always used. If missing on read, an
    |InvalidXmlError| is raised. It also does not remove the attribute if |None| is
    assigned. Assigning |None| raises |TypeError| or |ValueError|, depending on the
    simple type of the attribute.
    """

    @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." % (
            self._simple_type.__name__,
            self._attr_name,
        )

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

        def get_attr_value(obj: BaseOxmlElement) -> Any | None:
            attr_str_value = obj.get(self._clark_name)
            if attr_str_value is None:
                raise InvalidXmlError(
                    "required '%s' attribute not present on element %s" % (self._attr_name, obj.tag)
                )
            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]:
        """function object suitable for "set" side of attribute property descriptor."""

        def set_attr_value(obj: BaseOxmlElement, value: Any):
            str_value = self._simple_type.to_xml(value)
            if str_value is None:
                raise ValueError(f"cannot assign {value} to this required attribute")
            obj.set(self._clark_name, str_value)

        return set_attr_value


class _BaseChildElement: