ps-python-docx 1.3.0__py3-none-any.whl

docx/text/font.py

@@ -0,0 +1,472 @@
+"""Font-related proxy objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+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 theme_font(self) -> Literal["major", "minor"] | None:
+        """Latin theme family, either ``"major"`` (heading) or ``"minor"`` (body).
+
+        |None| means no uniform local theme family is set for ASCII and high ANSI.
+        This does not resolve inherited or mixed references. Assigning a family
+        removes conflicting literal Latin names. Assigning |None| removes only
+        those theme references, leaving literal names and other scripts unchanged.
+
+        To use a literal typeface, clear this property before setting ``name``.
+        The existing behavior of ``name`` is unchanged.
+        """
+        rPr = self._element.rPr
+        if rPr is None or rPr.rFonts is None:
+            return None
+        fonts = rPr.rFonts
+        if fonts.asciiTheme in ("majorAscii", "majorHAnsi") and fonts.hAnsiTheme in (
+            "majorAscii",
+            "majorHAnsi",
+        ):
+            return "major"
+        if fonts.asciiTheme in ("minorAscii", "minorHAnsi") and fonts.hAnsiTheme in (
+            "minorAscii",
+            "minorHAnsi",
+        ):
+            return "minor"
+        return None
+
+    @theme_font.setter
+    def theme_font(self, value: Literal["major", "minor"] | None) -> None:
+        if value not in (None, "major", "minor"):
+            raise ValueError("theme_font must be 'major', 'minor', or None")
+        if value is None:
+            rPr = self._element.rPr
+            if rPr is not None and rPr.rFonts is not None:
+                rPr.rFonts.asciiTheme = None
+                rPr.rFonts.hAnsiTheme = None
+            return
+        fonts = self._element.get_or_add_rPr().get_or_add_rFonts()
+        fonts.ascii = None
+        fonts.hAnsi = None
+        fonts.asciiTheme = f"{value}HAnsi"
+        fonts.hAnsiTheme = f"{value}HAnsi"
+
+    @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]

docx/text/hyperlink.py

@@ -0,0 +1,121 @@
+"""Hyperlink-related proxy objects for python-docx, Hyperlink in particular.
+
+A hyperlink occurs in a paragraph, at the same level as a Run, and a hyperlink itself
+contains runs, which is where the visible text of the hyperlink is stored. So it's kind
+of in-between, less than a paragraph and more than a run. So it gets its own module.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx.shared import Parented
+from docx.text.run import Run
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.oxml.text.hyperlink import CT_Hyperlink
+
+
+class Hyperlink(Parented):
+    """Proxy object wrapping a `<w:hyperlink>` element.
+
+    A hyperlink occurs as a child of a paragraph, at the same level as a Run. A
+    hyperlink itself contains runs, which is where the visible text of the hyperlink is
+    stored.
+    """
+
+    def __init__(self, hyperlink: CT_Hyperlink, parent: t.ProvidesStoryPart):
+        super().__init__(parent)
+        self._parent = parent
+        self._hyperlink = self._element = hyperlink
+
+    @property
+    def address(self) -> str:
+        """The "URL" of the hyperlink (but not necessarily a web link).
+
+        While commonly a web link like "https://google.com" the hyperlink address can
+        take a variety of forms including "internal links" to bookmarked locations
+        within the document. When this hyperlink is an internal "jump" to for example a
+        heading from the table-of-contents (TOC), the address is blank. The bookmark
+        reference (like "_Toc147925734") is stored in the `.fragment` property.
+        """
+        rId = self._hyperlink.rId
+        return self._parent.part.rels[rId].target_ref if rId else ""
+
+    @property
+    def contains_page_break(self) -> bool:
+        """True when the text of this hyperlink is broken across page boundaries.
+
+        This is not uncommon and can happen for example when the hyperlink text is
+        multiple words and occurs in the last line of a page. Theoretically, a hyperlink
+        can contain more than one page break but that would be extremely uncommon in
+        practice. Still, this value should be understood to mean that "one-or-more"
+        rendered page breaks are present.
+        """
+        return bool(self._hyperlink.lastRenderedPageBreaks)
+
+    @property
+    def fragment(self) -> str:
+        """Reference like `#glossary` at end of URL that refers to a sub-resource.
+
+        Note that this value does not include the fragment-separator character ("#").
+
+        This value is known as a "named anchor" in an HTML context and "anchor" in the
+        MS API, but an "anchor" element (`<a>`) represents a full hyperlink in HTML so
+        we avoid confusion by using the more precise RFC 3986 naming "URI fragment".
+
+        These are also used to refer to bookmarks within the same document, in which
+        case the `.address` value with be blank ("") and this property will hold a
+        value like "_Toc147925734".
+
+        To reliably get an entire web URL you will need to concatenate this with the
+        `.address` value, separated by "#" when both are present. Consider using the
+        `.url` property for that purpose.
+
+        Word sometimes stores a fragment in this property (an XML attribute) and
+        sometimes with the address, depending on how the URL is inserted, so don't
+        depend on this field being empty to indicate no fragment is present.
+        """
+        return self._hyperlink.anchor or ""
+
+    @property
+    def runs(self) -> list[Run]:
+        """List of |Run| instances in this hyperlink.
+
+        Together these define the visible text of the hyperlink. The text of a hyperlink
+        is typically contained in a single run will be broken into multiple runs if for
+        example part of the hyperlink is bold or the text was changed after the document
+        was saved.
+        """
+        return [Run(r, self._parent) for r in self._hyperlink.r_lst]
+
+    @property
+    def text(self) -> str:
+        """String formed by concatenating the text of each run in the hyperlink.
+
+        Tabs and line breaks in the XML are mapped to ``\\t`` and ``\\n`` characters
+        respectively. Note that rendered page-breaks can occur within a hyperlink but
+        they are not reflected in this text.
+        """
+        return self._hyperlink.text
+
+    @property
+    def url(self) -> str:
+        """Convenience property to get web URLs from hyperlinks that contain them.
+
+        This value is the empty string ("") when there is no address portion, so its
+        boolean value can also be used to distinguish external URIs from internal "jump"
+        hyperlinks like those found in a table-of-contents.
+
+        Note that this value may also be a link to a file, so if you only want web-urls
+        you'll need to check for a protocol prefix like `https://`.
+
+        When both an address and fragment are present, the return value joins the two
+        separated by the fragment-separator hash ("#"). Otherwise this value is the same
+        as that of the `.address` property.
+        """
+        address, fragment = self.address, self.fragment
+        if not address:
+            return ""
+        return f"{address}#{fragment}" if fragment else address

docx/text/pagebreak.py

@@ -0,0 +1,104 @@
+"""Proxy objects related to rendered page-breaks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+from docx.shared import Parented
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.text.paragraph import Paragraph
+
+
+class RenderedPageBreak(Parented):
+    """A page-break inserted by Word during page-layout for print or display purposes.
+
+    This usually does not correspond to a "hard" page-break inserted by the document
+    author, rather just that Word ran out of room on one page and needed to start
+    another. The position of these can change depending on the printer and page-size, as
+    well as margins, etc. They also will change in response to edits, but not until Word
+    loads and saves the document.
+
+    Note these are never inserted by `python-docx` because it has no rendering function.
+    These are generally only useful for text-extraction of existing documents when
+    `python-docx` is being used solely as a document "reader".
+
+    NOTE: a rendered page-break can occur within a hyperlink; consider a multi-word
+    hyperlink like "excellent Wikipedia article on LLMs" that happens to fall close to
+    the end of the last line on a page such that the page breaks between "Wikipedia" and
+    "article". In such a "page-breaks-in-hyperlink" case, THESE METHODS WILL "MOVE" THE
+    PAGE-BREAK to occur after the hyperlink, such that the entire hyperlink appears in
+    the paragraph returned by `.preceding_paragraph_fragment`. While this places the
+    "tail" text of the hyperlink on the "wrong" page, it avoids having two hyperlinks
+    each with a fragment of the actual text and pointing to the same address.
+    """
+
+    def __init__(
+        self,
+        lastRenderedPageBreak: CT_LastRenderedPageBreak,
+        parent: t.ProvidesStoryPart,
+    ):
+        super().__init__(parent)
+        self._element = lastRenderedPageBreak
+        self._lastRenderedPageBreak = lastRenderedPageBreak
+
+    @property
+    def preceding_paragraph_fragment(self) -> Paragraph | None:
+        """A "loose" paragraph containing the content preceding this page-break.
+
+        Compare `.following_paragraph_fragment` as these two are intended to be used
+        together.
+
+        This value is `None` when no content precedes this page-break. This case is
+        common and occurs whenever a page breaks on an even paragraph boundary.
+        Returning `None` for this case avoids "inserting" a non-existent paragraph into
+        the content stream. Note that content can include DrawingML items like images or
+        charts.
+
+        Note the returned paragraph *is divorced from the document body*. Any changes
+        made to it will not be reflected in the document. It is intended to provide a
+        familiar container (`Paragraph`) to interrogate for the content preceding this
+        page-break in the paragraph in which it occured.
+
+        Contains the entire hyperlink when this break occurs within a hyperlink.
+        """
+        if self._lastRenderedPageBreak.precedes_all_content:
+            return None
+
+        from docx.text.paragraph import Paragraph
+
+        return Paragraph(self._lastRenderedPageBreak.preceding_fragment_p, self._parent)
+
+    @property
+    def following_paragraph_fragment(self) -> Paragraph | None:
+        """A "loose" paragraph containing the content following this page-break.
+
+        HAS POTENTIALLY SURPRISING BEHAVIORS so read carefully to be sure this is what
+        you want. This is primarily targeted toward text-extraction use-cases for which
+        precisely associating text with the page it occurs on is important.
+
+        Compare `.preceding_paragraph_fragment` as these two are intended to be used
+        together.
+
+        This value is `None` when no content follows this page-break. This case is
+        unlikely to occur in practice because Word places even-paragraph-boundary
+        page-breaks on the paragraph *following* the page-break. Still, it is possible
+        and must be checked for. Returning `None` for this case avoids "inserting" an
+        extra, non-existent paragraph into the content stream. Note that content can
+        include DrawingML items like images or charts, not just text.
+
+        The returned paragraph *is divorced from the document body*. Any changes made to
+        it will not be reflected in the document. It is intended to provide a container
+        (`Paragraph`) with familiar properties and methods that can be used to
+        characterize the paragraph content following a mid-paragraph page-break.
+
+        Contains no portion of the hyperlink when this break occurs within a hyperlink.
+        """
+        if self._lastRenderedPageBreak.follows_all_content:
+            return None
+
+        from docx.text.paragraph import Paragraph
+
+        return Paragraph(self._lastRenderedPageBreak.following_fragment_p, self._parent)