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

docx/text/paragraph.py

@@ -0,0 +1,173 @@
+"""Paragraph-related proxy types."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator, List, cast
+
+from docx.enum.style import WD_STYLE_TYPE
+from docx.oxml.text.run import CT_R
+from docx.shared import StoryChild
+from docx.styles.style import ParagraphStyle
+from docx.text.hyperlink import Hyperlink
+from docx.text.pagebreak import RenderedPageBreak
+from docx.text.parfmt import ParagraphFormat
+from docx.text.run import Run
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
+    from docx.oxml.text.paragraph import CT_P
+    from docx.styles.style import CharacterStyle
+
+
+class Paragraph(StoryChild):
+    """Proxy object wrapping a `<w:p>` element."""
+
+    def __init__(self, p: CT_P, parent: t.ProvidesStoryPart):
+        super(Paragraph, self).__init__(parent)
+        self._p = self._element = p
+
+    def add_run(self, text: str | None = None, style: str | CharacterStyle | None = None) -> Run:
+        """Append run containing `text` and having character-style `style`.
+
+        `text` can contain tab (``\\t``) characters, which are converted to the
+        appropriate XML form for a tab. `text` can also include newline (``\\n``) or
+        carriage return (``\\r``) characters, each of which is converted to a line
+        break. When `text` is `None`, the new run is empty.
+        """
+        r = self._p.add_r()
+        run = Run(r, self)
+        if text:
+            run.text = text
+        if style:
+            run.style = style
+        return run
+
+    @property
+    def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None:
+        """A member of the :ref:`WdParagraphAlignment` enumeration specifying the
+        justification setting for this paragraph.
+
+        A value of |None| indicates the paragraph has no directly-applied alignment
+        value and will inherit its alignment value from its style hierarchy. Assigning
+        |None| to this property removes any directly-applied alignment value.
+        """
+        return self._p.alignment
+
+    @alignment.setter
+    def alignment(self, value: WD_PARAGRAPH_ALIGNMENT):
+        self._p.alignment = value
+
+    def clear(self):
+        """Return this same paragraph after removing all its content.
+
+        Paragraph-level formatting, such as style, is preserved.
+        """
+        self._p.clear_content()
+        return self
+
+    @property
+    def contains_page_break(self) -> bool:
+        """`True` when one or more rendered page-breaks occur in this paragraph."""
+        return bool(self._p.lastRenderedPageBreaks)
+
+    @property
+    def hyperlinks(self) -> List[Hyperlink]:
+        """A |Hyperlink| instance for each hyperlink in this paragraph."""
+        return [Hyperlink(hyperlink, self) for hyperlink in self._p.hyperlink_lst]
+
+    def insert_paragraph_before(
+        self, text: str | None = None, style: str | ParagraphStyle | None = None
+    ) -> Paragraph:
+        """Return a newly created paragraph, inserted directly before this paragraph.
+
+        If `text` is supplied, the new paragraph contains that text in a single run. If
+        `style` is provided, that style is assigned to the new paragraph.
+        """
+        paragraph = self._insert_paragraph_before()
+        if text:
+            paragraph.add_run(text)
+        if style is not None:
+            paragraph.style = style
+        return paragraph
+
+    def iter_inner_content(self) -> Iterator[Run | Hyperlink]:
+        """Generate the runs and hyperlinks in this paragraph, in the order they appear.
+
+        The content in a paragraph consists of both runs and hyperlinks. This method
+        allows accessing each of those separately, in document order, for when the
+        precise position of the hyperlink within the paragraph text is important. Note
+        that a hyperlink itself contains runs.
+        """
+        for r_or_hlink in self._p.inner_content_elements:
+            yield (
+                Run(r_or_hlink, self)
+                if isinstance(r_or_hlink, CT_R)
+                else Hyperlink(r_or_hlink, self)
+            )
+
+    @property
+    def paragraph_format(self):
+        """The |ParagraphFormat| object providing access to the formatting properties
+        for this paragraph, such as line spacing and indentation."""
+        return ParagraphFormat(self._element)
+
+    @property
+    def rendered_page_breaks(self) -> List[RenderedPageBreak]:
+        """All rendered page-breaks in this paragraph.
+
+        Most often an empty list, sometimes contains one page-break, but can contain
+        more than one is rare or contrived cases.
+        """
+        return [RenderedPageBreak(lrpb, self) for lrpb in self._p.lastRenderedPageBreaks]
+
+    @property
+    def runs(self) -> List[Run]:
+        """Sequence of |Run| instances corresponding to the <w:r> elements in this
+        paragraph."""
+        return [Run(r, self) for r in self._p.r_lst]
+
+    @property
+    def style(self) -> ParagraphStyle | None:
+        """Read/Write.
+
+        |_ParagraphStyle| object representing the style assigned to this paragraph. If
+        no explicit style is assigned to this paragraph, its value is the default
+        paragraph style for the document. A paragraph style name can be assigned in lieu
+        of a paragraph style object. Assigning |None| removes any applied style, making
+        its effective value the default paragraph style for the document.
+        """
+        style_id = self._p.style
+        style = self.part.get_style(style_id, WD_STYLE_TYPE.PARAGRAPH)
+        return cast(ParagraphStyle, style)
+
+    @style.setter
+    def style(self, style_or_name: str | ParagraphStyle | None):
+        style_id = self.part.get_style_id(style_or_name, WD_STYLE_TYPE.PARAGRAPH)
+        self._p.style = style_id
+
+    @property
+    def text(self) -> str:
+        """The textual content of this paragraph.
+
+        The text includes the visible-text portion of any hyperlinks in the paragraph.
+        Tabs and line breaks in the XML are mapped to ``\\t`` and ``\\n`` characters
+        respectively.
+
+        Assigning text to this property causes all existing paragraph content to be
+        replaced with a single run containing the assigned text. A ``\\t`` character in
+        the text is mapped to a ``<w:tab/>`` element and each ``\\n`` or ``\\r``
+        character is mapped to a line break. Paragraph-level formatting, such as style,
+        is preserved. All run-level formatting, such as bold or italic, is removed.
+        """
+        return self._p.text
+
+    @text.setter
+    def text(self, text: str | None):
+        self.clear()
+        self.add_run(text)
+
+    def _insert_paragraph_before(self):
+        """Return a newly created paragraph, inserted directly before this paragraph."""
+        p = self._p.add_p_before()
+        return Paragraph(p, self._parent)

docx/text/parfmt.py

@@ -0,0 +1,286 @@
+"""Paragraph-related proxy types."""
+
+from docx.enum.text import WD_LINE_SPACING
+from docx.shared import ElementProxy, Emu, Length, Pt, Twips, lazyproperty
+from docx.text.tabstops import TabStops
+
+
+class ParagraphFormat(ElementProxy):
+    """Provides access to paragraph formatting such as justification, indentation, line
+    spacing, space before and after, and widow/orphan control."""
+
+    @property
+    def alignment(self):
+        """A member of the :ref:`WdParagraphAlignment` enumeration specifying the
+        justification setting for this paragraph.
+
+        A value of |None| indicates paragraph alignment is inherited from the style
+        hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.jc_val
+
+    @alignment.setter
+    def alignment(self, value):
+        pPr = self._element.get_or_add_pPr()
+        pPr.jc_val = value
+
+    @property
+    def first_line_indent(self):
+        """|Length| value specifying the relative difference in indentation for the
+        first line of the paragraph.
+
+        A positive value causes the first line to be indented. A negative value produces
+        a hanging indent. |None| indicates first line indentation is inherited from the
+        style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.first_line_indent
+
+    @first_line_indent.setter
+    def first_line_indent(self, value):
+        pPr = self._element.get_or_add_pPr()
+        pPr.first_line_indent = value
+
+    @property
+    def keep_together(self):
+        """|True| if the paragraph should be kept "in one piece" and not broken across a
+        page boundary when the document is rendered.
+
+        |None| indicates its effective value is inherited from the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.keepLines_val
+
+    @keep_together.setter
+    def keep_together(self, value):
+        self._element.get_or_add_pPr().keepLines_val = value
+
+    @property
+    def keep_with_next(self):
+        """|True| if the paragraph should be kept on the same page as the subsequent
+        paragraph when the document is rendered.
+
+        For example, this property could be used to keep a section heading on the same
+        page as its first paragraph. |None| indicates its effective value is inherited
+        from the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.keepNext_val
+
+    @keep_with_next.setter
+    def keep_with_next(self, value):
+        self._element.get_or_add_pPr().keepNext_val = value
+
+    @property
+    def left_indent(self):
+        """|Length| value specifying the space between the left margin and the left side
+        of the paragraph.
+
+        |None| indicates the left indent value is inherited from the style hierarchy.
+        Use an |Inches| value object as a convenient way to apply indentation in units
+        of inches.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.ind_left
+
+    @left_indent.setter
+    def left_indent(self, value):
+        pPr = self._element.get_or_add_pPr()
+        pPr.ind_left = value
+
+    @property
+    def line_spacing(self):
+        """|float| or |Length| value specifying the space between baselines in
+        successive lines of the paragraph.
+
+        A value of |None| indicates line spacing is inherited from the style hierarchy.
+        A float value, e.g. ``2.0`` or ``1.75``, indicates spacing is applied in
+        multiples of line heights. A |Length| value such as ``Pt(12)`` indicates spacing
+        is a fixed height. The |Pt| value class is a convenient way to apply line
+        spacing in units of points. Assigning |None| resets line spacing to inherit from
+        the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return self._line_spacing(pPr.spacing_line, pPr.spacing_lineRule)
+
+    @line_spacing.setter
+    def line_spacing(self, value):
+        pPr = self._element.get_or_add_pPr()
+        if value is None:
+            pPr.spacing_line = None
+            pPr.spacing_lineRule = None
+        elif isinstance(value, Length):
+            pPr.spacing_line = value
+            if pPr.spacing_lineRule != WD_LINE_SPACING.AT_LEAST:
+                pPr.spacing_lineRule = WD_LINE_SPACING.EXACTLY
+        else:
+            pPr.spacing_line = Emu(value * Twips(240))
+            pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
+
+    @property
+    def line_spacing_rule(self):
+        """A member of the :ref:`WdLineSpacing` enumeration indicating how the value of
+        :attr:`line_spacing` should be interpreted.
+
+        Assigning any of the :ref:`WdLineSpacing` members :attr:`SINGLE`,
+        :attr:`DOUBLE`, or :attr:`ONE_POINT_FIVE` will cause the value of
+        :attr:`line_spacing` to be updated to produce the corresponding line spacing.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return self._line_spacing_rule(pPr.spacing_line, pPr.spacing_lineRule)
+
+    @line_spacing_rule.setter
+    def line_spacing_rule(self, value):
+        pPr = self._element.get_or_add_pPr()
+        if value == WD_LINE_SPACING.SINGLE:
+            pPr.spacing_line = Twips(240)
+            pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
+        elif value == WD_LINE_SPACING.ONE_POINT_FIVE:
+            pPr.spacing_line = Twips(360)
+            pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
+        elif value == WD_LINE_SPACING.DOUBLE:
+            pPr.spacing_line = Twips(480)
+            pPr.spacing_lineRule = WD_LINE_SPACING.MULTIPLE
+        else:
+            pPr.spacing_lineRule = value
+
+    @property
+    def page_break_before(self):
+        """|True| if the paragraph should appear at the top of the page following the
+        prior paragraph.
+
+        |None| indicates its effective value is inherited from the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.pageBreakBefore_val
+
+    @page_break_before.setter
+    def page_break_before(self, value):
+        self._element.get_or_add_pPr().pageBreakBefore_val = value
+
+    @property
+    def right_indent(self):
+        """|Length| value specifying the space between the right margin and the right
+        side of the paragraph.
+
+        |None| indicates the right indent value is inherited from the style hierarchy.
+        Use a |Cm| value object as a convenient way to apply indentation in units of
+        centimeters.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.ind_right
+
+    @right_indent.setter
+    def right_indent(self, value):
+        pPr = self._element.get_or_add_pPr()
+        pPr.ind_right = value
+
+    @property
+    def space_after(self):
+        """|Length| value specifying the spacing to appear between this paragraph and
+        the subsequent paragraph.
+
+        |None| indicates this value is inherited from the style hierarchy. |Length|
+        objects provide convenience properties, such as :attr:`~.Length.pt` and
+        :attr:`~.Length.inches`, that allow easy conversion to various length units.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.spacing_after
+
+    @space_after.setter
+    def space_after(self, value):
+        self._element.get_or_add_pPr().spacing_after = value
+
+    @property
+    def space_before(self):
+        """|Length| value specifying the spacing to appear between this paragraph and
+        the prior paragraph.
+
+        |None| indicates this value is inherited from the style hierarchy. |Length|
+        objects provide convenience properties, such as :attr:`~.Length.pt` and
+        :attr:`~.Length.cm`, that allow easy conversion to various length units.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.spacing_before
+
+    @space_before.setter
+    def space_before(self, value):
+        self._element.get_or_add_pPr().spacing_before = value
+
+    @lazyproperty
+    def tab_stops(self):
+        """|TabStops| object providing access to the tab stops defined for this
+        paragraph format."""
+        pPr = self._element.get_or_add_pPr()
+        return TabStops(pPr)
+
+    @property
+    def widow_control(self):
+        """|True| if the first and last lines in the paragraph remain on the same page
+        as the rest of the paragraph when Word repaginates the document.
+
+        |None| indicates its effective value is inherited from the style hierarchy.
+        """
+        pPr = self._element.pPr
+        if pPr is None:
+            return None
+        return pPr.widowControl_val
+
+    @widow_control.setter
+    def widow_control(self, value):
+        self._element.get_or_add_pPr().widowControl_val = value
+
+    @staticmethod
+    def _line_spacing(spacing_line, spacing_lineRule):
+        """Return the line spacing value calculated from the combination of
+        `spacing_line` and `spacing_lineRule`.
+
+        Returns a |float| number of lines when `spacing_lineRule` is
+        ``WD_LINE_SPACING.MULTIPLE``, otherwise a |Length| object of absolute line
+        height is returned. Returns |None| when `spacing_line` is |None|.
+        """
+        if spacing_line is None:
+            return None
+        if spacing_lineRule == WD_LINE_SPACING.MULTIPLE:
+            return spacing_line / Pt(12)
+        return spacing_line
+
+    @staticmethod
+    def _line_spacing_rule(line, lineRule):
+        """Return the line spacing rule value calculated from the combination of `line`
+        and `lineRule`.
+
+        Returns special members of the :ref:`WdLineSpacing` enumeration when line
+        spacing is single, double, or 1.5 lines.
+        """
+        if lineRule == WD_LINE_SPACING.MULTIPLE:
+            if line == Twips(240):
+                return WD_LINE_SPACING.SINGLE
+            if line == Twips(360):
+                return WD_LINE_SPACING.ONE_POINT_FIVE
+            if line == Twips(480):
+                return WD_LINE_SPACING.DOUBLE
+        return lineRule