1 files changed, 432 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/docx/text/font.py b/.venv/lib/python3.12/site-packages/docx/text/font.py
new file mode 100644
index 00000000..acd60795
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/docx/text/font.py
@@ -0,0 +1,432 @@
+"""Font-related proxy objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from docx.dml.color import ColorFormat
+from docx.enum.text import WD_UNDERLINE
+from docx.shared import ElementProxy, Emu
+
+if TYPE_CHECKING:
+    from docx.enum.text import WD_COLOR_INDEX
+    from docx.oxml.text.run import CT_R
+    from docx.shared import Length
+
+
+class Font(ElementProxy):
+    """Proxy object for parent of a `<w:rPr>` element and providing access to
+    character properties such as font name, font size, bold, and subscript."""
+
+    def __init__(self, r: CT_R, parent: Any | None = None):
+        super().__init__(r, parent)
+        self._element = r
+        self._r = r
+
+    @property
+    def all_caps(self) -> bool | None:
+        """Read/write.
+
+        Causes text in this font to appear in capital letters.
+        """
+        return self._get_bool_prop("caps")
+
+    @all_caps.setter
+    def all_caps(self, value: bool | None) -> None:
+        self._set_bool_prop("caps", value)
+
+    @property
+    def bold(self) -> bool | None:
+        """Read/write.
+
+        Causes text in this font to appear in bold.
+        """
+        return self._get_bool_prop("b")
+
+    @bold.setter
+    def bold(self, value: bool | None) -> None:
+        self._set_bool_prop("b", value)
+
+    @property
+    def color(self):
+        """A |ColorFormat| object providing a way to get and set the text color for this
+        font."""
+        return ColorFormat(self._element)
+
+    @property
+    def complex_script(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the characters in the run to be treated as complex script
+        regardless of their Unicode values.
+        """
+        return self._get_bool_prop("cs")
+
+    @complex_script.setter
+    def complex_script(self, value: bool | None) -> None:
+        self._set_bool_prop("cs", value)
+
+    @property
+    def cs_bold(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the complex script characters in the run to be displayed in
+        bold typeface.
+        """
+        return self._get_bool_prop("bCs")
+
+    @cs_bold.setter
+    def cs_bold(self, value: bool | None) -> None:
+        self._set_bool_prop("bCs", value)
+
+    @property
+    def cs_italic(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the complex script characters in the run to be displayed in
+        italic typeface.
+        """
+        return self._get_bool_prop("iCs")
+
+    @cs_italic.setter
+    def cs_italic(self, value: bool | None) -> None:
+        self._set_bool_prop("iCs", value)
+
+    @property
+    def double_strike(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text in the run to appear with double strikethrough.
+        """
+        return self._get_bool_prop("dstrike")
+
+    @double_strike.setter
+    def double_strike(self, value: bool | None) -> None:
+        self._set_bool_prop("dstrike", value)
+
+    @property
+    def emboss(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text in the run to appear as if raised off the page in
+        relief.
+        """
+        return self._get_bool_prop("emboss")
+
+    @emboss.setter
+    def emboss(self, value: bool | None) -> None:
+        self._set_bool_prop("emboss", value)
+
+    @property
+    def hidden(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text in the run to be hidden from display, unless
+        applications settings force hidden text to be shown.
+        """
+        return self._get_bool_prop("vanish")
+
+    @hidden.setter
+    def hidden(self, value: bool | None) -> None:
+        self._set_bool_prop("vanish", value)
+
+    @property
+    def highlight_color(self) -> WD_COLOR_INDEX | None:
+        """Color of highlighing applied or |None| if not highlighted."""
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.highlight_val
+
+    @highlight_color.setter
+    def highlight_color(self, value: WD_COLOR_INDEX | None):
+        rPr = self._element.get_or_add_rPr()
+        rPr.highlight_val = value
+
+    @property
+    def italic(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text of the run to appear in italics. |None| indicates
+        the effective value is inherited from the style hierarchy.
+        """
+        return self._get_bool_prop("i")
+
+    @italic.setter
+    def italic(self, value: bool | None) -> None:
+        self._set_bool_prop("i", value)
+
+    @property
+    def imprint(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text in the run to appear as if pressed into the page.
+        """
+        return self._get_bool_prop("imprint")
+
+    @imprint.setter
+    def imprint(self, value: bool | None) -> None:
+        self._set_bool_prop("imprint", value)
+
+    @property
+    def math(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, specifies this run contains WML that should be handled as though it
+        was Office Open XML Math.
+        """
+        return self._get_bool_prop("oMath")
+
+    @math.setter
+    def math(self, value: bool | None) -> None:
+        self._set_bool_prop("oMath", value)
+
+    @property
+    def name(self) -> str | None:
+        """The typeface name for this |Font|.
+
+        Causes the text it controls to appear in the named font, if a matching font is
+        found. |None| indicates the typeface is inherited from the style hierarchy.
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.rFonts_ascii
+
+    @name.setter
+    def name(self, value: str | None) -> None:
+        rPr = self._element.get_or_add_rPr()
+        rPr.rFonts_ascii = value
+        rPr.rFonts_hAnsi = value
+
+    @property
+    def no_proof(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, specifies that the contents of this run should not report any
+        errors when the document is scanned for spelling and grammar.
+        """
+        return self._get_bool_prop("noProof")
+
+    @no_proof.setter
+    def no_proof(self, value: bool | None) -> None:
+        self._set_bool_prop("noProof", value)
+
+    @property
+    def outline(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the characters in the run to appear as if they have an
+        outline, by drawing a one pixel wide border around the inside and outside
+        borders of each character glyph.
+        """
+        return self._get_bool_prop("outline")
+
+    @outline.setter
+    def outline(self, value: bool | None) -> None:
+        self._set_bool_prop("outline", value)
+
+    @property
+    def rtl(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the text in the run to have right-to-left characteristics.
+        """
+        return self._get_bool_prop("rtl")
+
+    @rtl.setter
+    def rtl(self, value: bool | None) -> None:
+        self._set_bool_prop("rtl", value)
+
+    @property
+    def shadow(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the text in the run to appear as if each character has a
+        shadow.
+        """
+        return self._get_bool_prop("shadow")
+
+    @shadow.setter
+    def shadow(self, value: bool | None) -> None:
+        self._set_bool_prop("shadow", value)
+
+    @property
+    def size(self) -> Length | None:
+        """Font height in English Metric Units (EMU).
+
+        |None| indicates the font size should be inherited from the style hierarchy.
+        |Length| is a subclass of |int| having properties for convenient conversion into
+        points or other length units. The :class:`docx.shared.Pt` class allows
+        convenient specification of point values::
+
+            >>> font.size = Pt(24)
+            >>> font.size
+            304800
+            >>> font.size.pt
+            24.0
+
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.sz_val
+
+    @size.setter
+    def size(self, emu: int | Length | None) -> None:
+        rPr = self._element.get_or_add_rPr()
+        rPr.sz_val = None if emu is None else Emu(emu)
+
+    @property
+    def small_caps(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the lowercase characters in the run to appear as capital
+        letters two points smaller than the font size specified for the run.
+        """
+        return self._get_bool_prop("smallCaps")
+
+    @small_caps.setter
+    def small_caps(self, value: bool | None) -> None:
+        self._set_bool_prop("smallCaps", value)
+
+    @property
+    def snap_to_grid(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the run to use the document grid characters per line settings
+        defined in the docGrid element when laying out the characters in this run.
+        """
+        return self._get_bool_prop("snapToGrid")
+
+    @snap_to_grid.setter
+    def snap_to_grid(self, value: bool | None) -> None:
+        self._set_bool_prop("snapToGrid", value)
+
+    @property
+    def spec_vanish(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, specifies that the given run shall always behave as if it is
+        hidden, even when hidden text is being displayed in the current document. The
+        property has a very narrow, specialized use related to the table of contents.
+        Consult the spec (§17.3.2.36) for more details.
+        """
+        return self._get_bool_prop("specVanish")
+
+    @spec_vanish.setter
+    def spec_vanish(self, value: bool | None) -> None:
+        self._set_bool_prop("specVanish", value)
+
+    @property
+    def strike(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True| causes the text in the run to appear with a single horizontal line
+        through the center of the line.
+        """
+        return self._get_bool_prop("strike")
+
+    @strike.setter
+    def strike(self, value: bool | None) -> None:
+        self._set_bool_prop("strike", value)
+
+    @property
+    def subscript(self) -> bool | None:
+        """Boolean indicating whether the characters in this |Font| appear as subscript.
+
+        |None| indicates the subscript/subscript value is inherited from the style
+        hierarchy.
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.subscript
+
+    @subscript.setter
+    def subscript(self, value: bool | None) -> None:
+        rPr = self._element.get_or_add_rPr()
+        rPr.subscript = value
+
+    @property
+    def superscript(self) -> bool | None:
+        """Boolean indicating whether the characters in this |Font| appear as
+        superscript.
+
+        |None| indicates the subscript/superscript value is inherited from the style
+        hierarchy.
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.superscript
+
+    @superscript.setter
+    def superscript(self, value: bool | None) -> None:
+        rPr = self._element.get_or_add_rPr()
+        rPr.superscript = value
+
+    @property
+    def underline(self) -> bool | WD_UNDERLINE | None:
+        """The underline style for this |Font|.
+
+        The value is one of |None|, |True|, |False|, or a member of :ref:`WdUnderline`.
+
+        |None| indicates the font inherits its underline value from the style hierarchy.
+        |False| indicates no underline. |True| indicates single underline. The values
+        from :ref:`WdUnderline` are used to specify other outline styles such as double,
+        wavy, and dotted.
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        val = rPr.u_val
+        return (
+            None
+            if val == WD_UNDERLINE.INHERITED
+            else True
+            if val == WD_UNDERLINE.SINGLE
+            else False
+            if val == WD_UNDERLINE.NONE
+            else val
+        )
+
+    @underline.setter
+    def underline(self, value: bool | WD_UNDERLINE | None) -> None:
+        rPr = self._element.get_or_add_rPr()
+        # -- works fine without these two mappings, but only because True == 1 and
+        # -- False == 0, which happen to match the mapping for WD_UNDERLINE.SINGLE
+        # -- and .NONE respectively.
+        val = (
+            WD_UNDERLINE.SINGLE
+            if value is True
+            else WD_UNDERLINE.NONE
+            if value is False
+            else value
+        )
+        rPr.u_val = val
+
+    @property
+    def web_hidden(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, specifies that the contents of this run shall be hidden when the
+        document is displayed in web page view.
+        """
+        return self._get_bool_prop("webHidden")
+
+    @web_hidden.setter
+    def web_hidden(self, value: bool | None) -> None:
+        self._set_bool_prop("webHidden", value)
+
+    def _get_bool_prop(self, name: str) -> bool | None:
+        """Return the value of boolean child of `w:rPr` having `name`."""
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr._get_bool_val(name)  # pyright: ignore[reportPrivateUsage]
+
+    def _set_bool_prop(self, name: str, value: bool | None):
+        """Assign `value` to the boolean child `name` of `w:rPr`."""
+        rPr = self._element.get_or_add_rPr()
+        rPr._set_bool_val(name, value)  # pyright: ignore[reportPrivateUsage]