diff options
Diffstat (limited to '.venv/lib/python3.12/site-packages/docx/text/paragraph.py')
| -rw-r--r-- | .venv/lib/python3.12/site-packages/docx/text/paragraph.py | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/docx/text/paragraph.py b/.venv/lib/python3.12/site-packages/docx/text/paragraph.py new file mode 100644 index 00000000..234ea66c --- /dev/null +++ b/.venv/lib/python3.12/site-packages/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) |