modn: modernize tests

- inline single-test fixtures
- remove obsolete pre-cxml XML builders

Author: scanny

src/docx/dml/color.py

@@ -1,83 +1,95 @@
 """DrawingML objects related to color, ColorFormat being the most prominent."""
 
-from ..enum.dml import MSO_COLOR_TYPE
-from ..oxml.simpletypes import ST_HexColorAuto
-from ..shared import ElementProxy
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from typing_extensions import TypeAlias
+
+from docx.enum.dml import MSO_COLOR_TYPE
+from docx.oxml.simpletypes import ST_HexColorAuto
+from docx.shared import ElementProxy, RGBColor
+
+if TYPE_CHECKING:
+    from docx.enum.dml import MSO_THEME_COLOR
+    from docx.oxml.text.font import CT_Color
+    from docx.oxml.text.run import CT_R
+
+# -- other element types can be a parent of an `w:rPr` element, but for now only `w:r` is --
+RPrParent: TypeAlias = "CT_R"
 
 
 class ColorFormat(ElementProxy):
-    """Provides access to color settings such as RGB color, theme color, and luminance
-    adjustments."""
+    """Provides access to color settings like RGB color, theme color, and luminance adjustments."""
 
-    def __init__(self, rPr_parent):
+    def __init__(self, rPr_parent: RPrParent):
         super(ColorFormat, self).__init__(rPr_parent)
+        self._element = rPr_parent
 
     @property
-    def rgb(self):
+    def rgb(self) -> RGBColor | None:
         """An |RGBColor| value or |None| if no RGB color is specified.
 
-        When :attr:`type` is `MSO_COLOR_TYPE.RGB`, the value of this property will
-        always be an |RGBColor| value. It may also be an |RGBColor| value if
-        :attr:`type` is `MSO_COLOR_TYPE.THEME`, as Word writes the current value of a
-        theme color when one is assigned. In that case, the RGB value should be
-        interpreted as no more than a good guess however, as the theme color takes
-        precedence at rendering time. Its value is |None| whenever :attr:`type` is
-        either |None| or `MSO_COLOR_TYPE.AUTO`.
-
-        Assigning an |RGBColor| value causes :attr:`type` to become `MSO_COLOR_TYPE.RGB`
-        and any theme color is removed. Assigning |None| causes any color to be removed
-        such that the effective color is inherited from the style hierarchy.
+        When :attr:`type` is `MSO_COLOR_TYPE.RGB`, the value of this property will always be an
+        |RGBColor| value. It may also be an |RGBColor| value if :attr:`type` is
+        `MSO_COLOR_TYPE.THEME`, as Word writes the current value of a theme color when one is
+        assigned. In that case, the RGB value should be interpreted as no more than a good guess
+        however, as the theme color takes precedence at rendering time. Its value is |None|
+        whenever :attr:`type` is either |None| or `MSO_COLOR_TYPE.AUTO`.
+
+        Assigning an |RGBColor| value causes :attr:`type` to become `MSO_COLOR_TYPE.RGB` and any
+        theme color is removed. Assigning |None| causes any color to be removed such that the
+        effective color is inherited from the style hierarchy.
         """
         color = self._color
         if color is None:
             return None
         if color.val == ST_HexColorAuto.AUTO:
             return None
-        return color.val
+        return cast(RGBColor, color.val)
 
     @rgb.setter
-    def rgb(self, value):
+    def rgb(self, value: RGBColor | None):
         if value is None and self._color is None:
             return
         rPr = self._element.get_or_add_rPr()
-        rPr._remove_color()
+        rPr._remove_color()  # pyright: ignore[reportPrivateUsage]
         if value is not None:
             rPr.get_or_add_color().val = value
 
     @property
-    def theme_color(self):
+    def theme_color(self) -> MSO_THEME_COLOR | None:
         """Member of :ref:`MsoThemeColorIndex` or |None| if no theme color is specified.
 
-        When :attr:`type` is `MSO_COLOR_TYPE.THEME`, the value of this property will
-        always be a member of :ref:`MsoThemeColorIndex`. When :attr:`type` has any other
-        value, the value of this property is |None|.
+        When :attr:`type` is `MSO_COLOR_TYPE.THEME`, the value of this property will always be a
+        member of :ref:`MsoThemeColorIndex`. When :attr:`type` has any other value, the value of
+        this property is |None|.
 
         Assigning a member of :ref:`MsoThemeColorIndex` causes :attr:`type` to become
-        `MSO_COLOR_TYPE.THEME`. Any existing RGB value is retained but ignored by Word.
-        Assigning |None| causes any color specification to be removed such that the
-        effective color is inherited from the style hierarchy.
+        `MSO_COLOR_TYPE.THEME`. Any existing RGB value is retained but ignored by Word. Assigning
+        |None| causes any color specification to be removed such that the effective color is
+        inherited from the style hierarchy.
         """
         color = self._color
-        if color is None or color.themeColor is None:
+        if color is None:
             return None
         return color.themeColor
 
     @theme_color.setter
-    def theme_color(self, value):
+    def theme_color(self, value: MSO_THEME_COLOR | None):
         if value is None:
-            if self._color is not None:
-                self._element.rPr._remove_color()
+            if self._color is not None and self._element.rPr is not None:
+                self._element.rPr._remove_color()  # pyright: ignore[reportPrivateUsage]
             return
         self._element.get_or_add_rPr().get_or_add_color().themeColor = value
 
     @property
-    def type(self) -> MSO_COLOR_TYPE:
+    def type(self) -> MSO_COLOR_TYPE | None:
         """Read-only.
 
-        A member of :ref:`MsoColorType`, one of RGB, THEME, or AUTO, corresponding to
-        the way this color is defined. Its value is |None| if no color is applied at
-        this level, which causes the effective color to be inherited from the style
-        hierarchy.
+        A member of :ref:`MsoColorType`, one of RGB, THEME, or AUTO, corresponding to the way this
+        color is defined. Its value is |None| if no color is applied at this level, which causes
+        the effective color to be inherited from the style hierarchy.
         """
         color = self._color
         if color is None:
@@ -89,7 +101,7 @@ def type(self) -> MSO_COLOR_TYPE:
         return MSO_COLOR_TYPE.RGB
 
     @property
-    def _color(self):
+    def _color(self) -> CT_Color | None:
         """Return `w:rPr/w:color` or |None| if not present.
 
         Helper to factor out repetitive element access.

src/docx/document.py

@@ -11,14 +11,13 @@
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
 from docx.section import Section, Sections
-from docx.shared import ElementProxy, Emu
+from docx.shared import ElementProxy, Emu, Inches, Length
 
 if TYPE_CHECKING:
     import docx.types as t
     from docx.oxml.document import CT_Body, CT_Document
     from docx.parts.document import DocumentPart
     from docx.settings import Settings
-    from docx.shared import Length
     from docx.styles.style import ParagraphStyle, _TableStyle
     from docx.table import Table
     from docx.text.paragraph import Paragraph
@@ -178,7 +177,10 @@ def tables(self) -> List[Table]:
     def _block_width(self) -> Length:
         """A |Length| object specifying the space between margins in last section."""
         section = self.sections[-1]
-        return Emu(section.page_width - section.left_margin - section.right_margin)
+        page_width = section.page_width or Inches(8.5)
+        left_margin = section.left_margin or Inches(1)
+        right_margin = section.right_margin or Inches(1)
+        return Emu(page_width - left_margin - right_margin)
 
     @property
     def _body(self) -> _Body:
@@ -198,7 +200,7 @@ def __init__(self, body_elm: CT_Body, parent: t.ProvidesStoryPart):
         super(_Body, self).__init__(body_elm, parent)
         self._body = body_elm
 
-    def clear_content(self):
+    def clear_content(self) -> _Body:
         """Return this |_Body| instance after clearing it of all content.
 
         Section properties for the main document story, if present, are preserved.

src/docx/enum/base.py

@@ -37,9 +37,9 @@ class BaseXmlEnum(int, enum.Enum):
     corresponding member in the MS API enum of the same name.
     """
 
-    xml_value: str
+    xml_value: str | None
 
-    def __new__(cls, ms_api_value: int, xml_value: str, docstr: str):
+    def __new__(cls, ms_api_value: int, xml_value: str | None, docstr: str):
         self = int.__new__(cls, ms_api_value)
         self._value_ = ms_api_value
         self.xml_value = xml_value
@@ -70,7 +70,11 @@ def to_xml(cls: Type[_T], value: int | _T | None) -> str | None:
         """XML value of this enum member, generally an XML attribute value."""
         # -- presence of multi-arg `__new__()` method fools type-checker, but getting a
         # -- member by its value using EnumCls(val) works as usual.
-        return cls(value).xml_value
+        member = cls(value)
+        xml_value = member.xml_value
+        if not xml_value:
+            raise ValueError(f"{cls.__name__}.{member.name} has no XML representation")
+        return xml_value
 
 
 class DocsPageFormatter:

src/docx/opc/package.py

@@ -14,6 +14,8 @@
 from docx.shared import lazyproperty
 
 if TYPE_CHECKING:
+    from typing_extensions import Self
+
     from docx.opc.coreprops import CoreProperties
     from docx.opc.part import Part
     from docx.opc.rel import _Relationship  # pyright: ignore[reportPrivateUsage]
@@ -26,9 +28,6 @@ class OpcPackage:
     to a package file or file-like object containing one.
     """
 
-    def __init__(self):
-        super(OpcPackage, self).__init__()
-
     def after_unmarshal(self):
         """Entry point for any post-unmarshaling processing.
 
@@ -122,7 +121,7 @@ def next_partname(self, template: str) -> PackURI:
                 return PackURI(candidate_partname)
 
     @classmethod
-    def open(cls, pkg_file: str | IO[bytes]) -> OpcPackage:
+    def open(cls, pkg_file: str | IO[bytes]) -> Self:
         """Return an |OpcPackage| instance loaded with the contents of `pkg_file`."""
         pkg_reader = PackageReader.from_file(pkg_file)
         package = cls()

src/docx/oxml/text/font.py

@@ -1,3 +1,5 @@
+# pyright: reportAssignmentType=false
+
 """Custom element classes related to run properties (font)."""
 
 from __future__ import annotations
@@ -20,6 +22,7 @@
     RequiredAttribute,
     ZeroOrOne,
 )
+from docx.shared import RGBColor
 
 if TYPE_CHECKING:
     from docx.oxml.shared import CT_OnOff, CT_String
@@ -29,8 +32,8 @@
 class CT_Color(BaseOxmlElement):
     """`w:color` element, specifying the color of a font and perhaps other objects."""
 
-    val = RequiredAttribute("w:val", ST_HexColor)
-    themeColor = OptionalAttribute("w:themeColor", MSO_THEME_COLOR)
+    val: RGBColor | str = RequiredAttribute("w:val", ST_HexColor)
+    themeColor: MSO_THEME_COLOR | None = OptionalAttribute("w:themeColor", MSO_THEME_COLOR)
 
 
 class CT_Fonts(BaseOxmlElement):
@@ -39,39 +42,33 @@ class CT_Fonts(BaseOxmlElement):
     Specifies typeface name for the various language types.
     """
 
-    ascii: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
-        "w:ascii", ST_String
-    )
-    hAnsi: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
-        "w:hAnsi", ST_String
-    )
+    ascii: str | None = OptionalAttribute("w:ascii", ST_String)
+    hAnsi: str | None = OptionalAttribute("w:hAnsi", ST_String)
 
 
 class CT_Highlight(BaseOxmlElement):
     """`w:highlight` element, specifying font highlighting/background color."""
 
-    val: WD_COLOR_INDEX = RequiredAttribute(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:val", WD_COLOR_INDEX
-    )
+    val: WD_COLOR_INDEX = RequiredAttribute("w:val", WD_COLOR_INDEX)
 
 
 class CT_HpsMeasure(BaseOxmlElement):
     """Used for `<w:sz>` element and others, specifying font size in half-points."""
 
-    val: Length = RequiredAttribute(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:val", ST_HpsMeasure
-    )
+    val: Length = RequiredAttribute("w:val", ST_HpsMeasure)
 
 
 class CT_RPr(BaseOxmlElement):
     """`<w:rPr>` element, containing the properties for a run."""
 
+    get_or_add_color: Callable[[], CT_Color]
     get_or_add_highlight: Callable[[], CT_Highlight]
     get_or_add_rFonts: Callable[[], CT_Fonts]
     get_or_add_sz: Callable[[], CT_HpsMeasure]
     get_or_add_vertAlign: Callable[[], CT_VerticalAlignRun]
     _add_rStyle: Callable[..., CT_String]
     _add_u: Callable[[], CT_Underline]
+    _remove_color: Callable[[], None]
     _remove_highlight: Callable[[], None]
     _remove_rFonts: Callable[[], None]
     _remove_rStyle: Callable[[], None]
@@ -120,15 +117,9 @@ class CT_RPr(BaseOxmlElement):
         "w:specVanish",
         "w:oMath",
     )
-    rStyle: CT_String | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:rStyle", successors=_tag_seq[1:]
-    )
-    rFonts: CT_Fonts | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:rFonts", successors=_tag_seq[2:]
-    )
-    b: CT_OnOff | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:b", successors=_tag_seq[3:]
-    )
+    rStyle: CT_String | None = ZeroOrOne("w:rStyle", successors=_tag_seq[1:])
+    rFonts: CT_Fonts | None = ZeroOrOne("w:rFonts", successors=_tag_seq[2:])
+    b: CT_OnOff | None = ZeroOrOne("w:b", successors=_tag_seq[3:])
     bCs = ZeroOrOne("w:bCs", successors=_tag_seq[4:])
     i = ZeroOrOne("w:i", successors=_tag_seq[5:])
     iCs = ZeroOrOne("w:iCs", successors=_tag_seq[6:])
@@ -144,19 +135,11 @@ class CT_RPr(BaseOxmlElement):
     snapToGrid = ZeroOrOne("w:snapToGrid", successors=_tag_seq[16:])
     vanish = ZeroOrOne("w:vanish", successors=_tag_seq[17:])
     webHidden = ZeroOrOne("w:webHidden", successors=_tag_seq[18:])
-    color = ZeroOrOne("w:color", successors=_tag_seq[19:])
-    sz: CT_HpsMeasure | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:sz", successors=_tag_seq[24:]
-    )
-    highlight: CT_Highlight | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:highlight", successors=_tag_seq[26:]
-    )
-    u: CT_Underline | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:u", successors=_tag_seq[27:]
-    )
-    vertAlign: CT_VerticalAlignRun | None = ZeroOrOne(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:vertAlign", successors=_tag_seq[32:]
-    )
+    color: CT_Color | None = ZeroOrOne("w:color", successors=_tag_seq[19:])
+    sz: CT_HpsMeasure | None = ZeroOrOne("w:sz", successors=_tag_seq[24:])
+    highlight: CT_Highlight | None = ZeroOrOne("w:highlight", successors=_tag_seq[26:])
+    u: CT_Underline | None = ZeroOrOne("w:u", successors=_tag_seq[27:])
+    vertAlign: CT_VerticalAlignRun | None = ZeroOrOne("w:vertAlign", successors=_tag_seq[32:])
     rtl = ZeroOrOne("w:rtl", successors=_tag_seq[33:])
     cs = ZeroOrOne("w:cs", successors=_tag_seq[34:])
     specVanish = ZeroOrOne("w:specVanish", successors=_tag_seq[38:])
@@ -343,14 +326,10 @@ def _set_bool_val(self, name: str, value: bool | None):
 class CT_Underline(BaseOxmlElement):
     """`<w:u>` element, specifying the underlining style for a run."""
 
-    val: WD_UNDERLINE | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
-        "w:val", WD_UNDERLINE
-    )
+    val: WD_UNDERLINE | None = OptionalAttribute("w:val", WD_UNDERLINE)
 
 
 class CT_VerticalAlignRun(BaseOxmlElement):
     """`<w:vertAlign>` element, specifying subscript or superscript."""
 
-    val: str = RequiredAttribute(  # pyright: ignore[reportGeneralTypeIssues]
-        "w:val", ST_VerticalAlignRun
-    )
+    val: str = RequiredAttribute("w:val", ST_VerticalAlignRun)

src/docx/parts/document.py

@@ -89,14 +89,13 @@ def inline_shapes(self):
         return InlineShapes(self._element.body, self)
 
     @lazyproperty
-    def numbering_part(self):
-        """A |NumberingPart| object providing access to the numbering definitions for
-        this document.
+    def numbering_part(self) -> NumberingPart:
+        """A |NumberingPart| object providing access to the numbering definitions for this document.
 
         Creates an empty numbering part if one is not present.
         """
         try:
-            return self.part_related_by(RT.NUMBERING)
+            return cast(NumberingPart, self.part_related_by(RT.NUMBERING))
         except KeyError:
             numbering_part = NumberingPart.new()
             self.relate_to(numbering_part, RT.NUMBERING)

src/docx/parts/numbering.py

@@ -9,9 +9,8 @@ class NumberingPart(XmlPart):
     or glossary."""
 
     @classmethod
-    def new(cls):
-        """Return newly created empty numbering part, containing only the root
-        ``<w:numbering>`` element."""
+    def new(cls) -> "NumberingPart":
+        """Newly created numbering part, containing only the root ``<w:numbering>`` element."""
         raise NotImplementedError
 
     @lazyproperty