Spaces:
Paused
Paused
| # pyright: reportImportCycles=false | |
| # pyright: reportPrivateUsage=false | |
| """|Document| and closely related objects.""" | |
| from __future__ import annotations | |
| from typing import IO, TYPE_CHECKING, Iterator, List | |
| from docx.blkcntnr import BlockItemContainer | |
| 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 | |
| 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 | |
| class Document(ElementProxy): | |
| """WordprocessingML (WML) document. | |
| Not intended to be constructed directly. Use :func:`docx.Document` to open or create | |
| a document. | |
| """ | |
| def __init__(self, element: CT_Document, part: DocumentPart): | |
| super(Document, self).__init__(element) | |
| self._element = element | |
| self._part = part | |
| self.__body = None | |
| def add_heading(self, text: str = "", level: int = 1): | |
| """Return a heading paragraph newly added to the end of the document. | |
| The heading paragraph will contain `text` and have its paragraph style | |
| determined by `level`. If `level` is 0, the style is set to `Title`. If `level` | |
| is 1 (or omitted), `Heading 1` is used. Otherwise the style is set to `Heading | |
| {level}`. Raises |ValueError| if `level` is outside the range 0-9. | |
| """ | |
| if not 0 <= level <= 9: | |
| raise ValueError("level must be in range 0-9, got %d" % level) | |
| style = "Title" if level == 0 else "Heading %d" % level | |
| return self.add_paragraph(text, style) | |
| def add_page_break(self): | |
| """Return newly |Paragraph| object containing only a page break.""" | |
| paragraph = self.add_paragraph() | |
| paragraph.add_run().add_break(WD_BREAK.PAGE) | |
| return paragraph | |
| def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = None) -> Paragraph: | |
| """Return paragraph newly added to the end of the document. | |
| The paragraph is populated with `text` and having paragraph 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. | |
| """ | |
| return self._body.add_paragraph(text, style) | |
| def add_picture( | |
| self, | |
| image_path_or_stream: str | IO[bytes], | |
| width: int | Length | None = None, | |
| height: int | Length | None = None, | |
| ): | |
| """Return new picture shape added in its own paragraph at end of the document. | |
| The picture contains the image at `image_path_or_stream`, scaled based on | |
| `width` and `height`. If neither width nor height is specified, the picture | |
| appears at its native size. If only one is specified, it is used to compute a | |
| scaling factor that is then applied to the unspecified dimension, preserving the | |
| aspect ratio of the image. The native size of the picture is calculated using | |
| the dots-per-inch (dpi) value specified in the image file, defaulting to 72 dpi | |
| if no value is specified, as is often the case. | |
| """ | |
| run = self.add_paragraph().add_run() | |
| return run.add_picture(image_path_or_stream, width, height) | |
| def add_section(self, start_type: WD_SECTION = WD_SECTION.NEW_PAGE): | |
| """Return a |Section| object newly added at the end of the document. | |
| The optional `start_type` argument must be a member of the :ref:`WdSectionStart` | |
| enumeration, and defaults to ``WD_SECTION.NEW_PAGE`` if not provided. | |
| """ | |
| new_sectPr = self._element.body.add_section_break() | |
| new_sectPr.start_type = start_type | |
| return Section(new_sectPr, self._part) | |
| def add_table(self, rows: int, cols: int, style: str | _TableStyle | None = None): | |
| """Add a table having row and column counts of `rows` and `cols` respectively. | |
| `style` may be a table style object or a table style name. If `style` is |None|, | |
| the table inherits the default table style of the document. | |
| """ | |
| table = self._body.add_table(rows, cols, self._block_width) | |
| table.style = style | |
| return table | |
| def core_properties(self): | |
| """A |CoreProperties| object providing Dublin Core properties of document.""" | |
| return self._part.core_properties | |
| def inline_shapes(self): | |
| """The |InlineShapes| collection for this document. | |
| An inline shape is a graphical object, such as a picture, contained in a run of | |
| text and behaving like a character glyph, being flowed like other text in a | |
| paragraph. | |
| """ | |
| return self._part.inline_shapes | |
| def iter_inner_content(self) -> Iterator[Paragraph | Table]: | |
| """Generate each `Paragraph` or `Table` in this document in document order.""" | |
| return self._body.iter_inner_content() | |
| def paragraphs(self) -> List[Paragraph]: | |
| """The |Paragraph| instances in the document, in document order. | |
| Note that paragraphs within revision marks such as ``<w:ins>`` or ``<w:del>`` do | |
| not appear in this list. | |
| """ | |
| return self._body.paragraphs | |
| def part(self) -> DocumentPart: | |
| """The |DocumentPart| object of this document.""" | |
| return self._part | |
| def save(self, path_or_stream: str | IO[bytes]): | |
| """Save this document to `path_or_stream`. | |
| `path_or_stream` can be either a path to a filesystem location (a string) or a | |
| file-like object. | |
| """ | |
| self._part.save(path_or_stream) | |
| def sections(self) -> Sections: | |
| """|Sections| object providing access to each section in this document.""" | |
| return Sections(self._element, self._part) | |
| def settings(self) -> Settings: | |
| """A |Settings| object providing access to the document-level settings.""" | |
| return self._part.settings | |
| def styles(self): | |
| """A |Styles| object providing access to the styles in this document.""" | |
| return self._part.styles | |
| def tables(self) -> List[Table]: | |
| """All |Table| instances in the document, in document order. | |
| Note that only tables appearing at the top level of the document appear in this | |
| list; a table nested inside a table cell does not appear. A table within | |
| revision marks such as ``<w:ins>`` or ``<w:del>`` will also not appear in the | |
| list. | |
| """ | |
| return self._body.tables | |
| 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) | |
| def _body(self) -> _Body: | |
| """The |_Body| instance containing the content for this document.""" | |
| if self.__body is None: | |
| self.__body = _Body(self._element.body, self) | |
| return self.__body | |
| class _Body(BlockItemContainer): | |
| """Proxy for `<w:body>` element in this document. | |
| It's primary role is a container for document content. | |
| """ | |
| 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): | |
| """Return this |_Body| instance after clearing it of all content. | |
| Section properties for the main document story, if present, are preserved. | |
| """ | |
| self._body.clear_content() | |
| return self | |