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

docx/document.py

@@ -0,0 +1,275 @@
+# pyright: reportImportCycles=false
+# pyright: reportPrivateUsage=false
+
+"""|Document| and closely related objects."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Iterator, List, Sequence
+
+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, Inches, Length
+from docx.text.run import Run
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.comments import Comment, Comments
+    from docx.oxml.document import CT_Body, CT_Document
+    from docx.parts.document import DocumentPart
+    from docx.settings import Settings
+    from docx.styles.style import ParagraphStyle, _TableStyle
+    from docx.table import Table
+    from docx.text.paragraph import Paragraph
+    from docx.theme import ThemeFonts
+
+
+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_comment(
+        self,
+        runs: Run | Sequence[Run],
+        text: str | None = "",
+        author: str = "",
+        initials: str | None = "",
+    ) -> Comment:
+        """Add a comment to the document, anchored to the specified runs.
+
+        `runs` can be a single `Run` object or a non-empty sequence of `Run` objects. Only the
+        first and last run of a sequence are used, it's just more convenient to pass a whole
+        sequence when that's what you have handy, like `paragraph.runs` for example. When `runs`
+        contains a single `Run` object, that run serves as both the first and last run.
+
+        A comment can be anchored only on an even run boundary, meaning the text the comment
+        "references" must be a non-zero integer number of consecutive runs. The runs need not be
+        _contiguous_ per se, like the first can be in one paragraph and the last in the next
+        paragraph, but all runs between the first and the last will be included in the reference.
+
+        The comment reference range is delimited by placing a `w:commentRangeStart` element before
+        the first run and a `w:commentRangeEnd` element after the last run. This is why only the
+        first and last run are required and why a single run can serve as both first and last.
+        Word works out which text to highlight in the UI based on these range markers.
+
+        `text` allows the contents of a simple comment to be provided in the call, providing for
+        the common case where a comment is a single phrase or sentence without special formatting
+        such as bold or italics. More complex comments can be added using the returned `Comment`
+        object in much the same way as a `Document` or (table) `Cell` object, using methods like
+        `.add_paragraph()`, .add_run()`, etc.
+
+        The `author` and `initials` parameters allow that metadata to be set for the comment.
+        `author` is a required attribute on a comment and is the empty string by default.
+        `initials` is optional on a comment and may be omitted by passing |None|, but Word adds an
+        `initials` attribute by default and we follow that convention by using the empty string
+        when no `initials` argument is provided.
+        """
+        # -- normalize `runs` to a sequence of runs --
+        runs = [runs] if isinstance(runs, Run) else runs
+        first_run = runs[0]
+        last_run = runs[-1]
+
+        # -- Note that comments can only appear in the document part --
+        comment = self.comments.add_comment(text=text, author=author, initials=initials)
+
+        # -- let the first run orchestrate placement of the comment range start and end --
+        first_run.mark_comment_range(last_run, comment.comment_id)
+
+        return comment
+
+    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
+
+    @property
+    def comments(self) -> Comments:
+        """A |Comments| object providing access to comments added to the document."""
+        return self._part.comments
+
+    @property
+    def core_properties(self):
+        """A |CoreProperties| object providing Dublin Core properties of document."""
+        return self._part.core_properties
+
+    @property
+    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()
+
+    @property
+    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
+
+    @property
+    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)
+
+    @property
+    def sections(self) -> Sections:
+        """|Sections| object providing access to each section in this document."""
+        return Sections(self._element, self._part)
+
+    @property
+    def settings(self) -> Settings:
+        """A |Settings| object providing access to the document-level settings."""
+        return self._part.settings
+
+    @property
+    def styles(self):
+        """A |Styles| object providing access to the styles in this document."""
+        return self._part.styles
+
+    @property
+    def theme_fonts(self) -> ThemeFonts:
+        """The document's |ThemeFonts| scheme.
+
+        Creates a default theme if the document has none. Raises |ValueError| if
+        an existing theme is malformed or lacks a complete font scheme.
+        """
+        return self._part.theme_fonts
+
+    @property
+    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
+
+    @property
+    def _block_width(self) -> Length:
+        """A |Length| object specifying the space between margins in last section."""
+        section = self.sections[-1]
+        page_width = section.page_width or Inches(8.5)
+        left_margin = section.left_margin or Inches(1)
+        right_margin = section.right_margin or Inches(1)
+        return Emu(page_width - left_margin - right_margin)
+
+    @property
+    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) -> _Body:
+        """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

docx/drawing/__init__.py

@@ -0,0 +1,59 @@
+"""DrawingML-related objects are in this subpackage."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx.oxml.drawing import CT_Drawing
+from docx.shared import Parented
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.image.image import Image
+
+
+class Drawing(Parented):
+    """Container for a DrawingML object."""
+
+    def __init__(self, drawing: CT_Drawing, parent: t.ProvidesStoryPart):
+        super().__init__(parent)
+        self._parent = parent
+        self._drawing = self._element = drawing
+
+    @property
+    def has_picture(self) -> bool:
+        """True when `drawing` contains an embedded picture.
+
+        A drawing can contain a picture, but it can also contain a chart, SmartArt, or a
+        drawing canvas. Methods related to a picture, like `.image`, will raise when the drawing
+        does not contain a picture. Use this value to determine whether image methods will succeed.
+
+        This value is `False` when a linked picture is present. This should be relatively rare and
+        the image would only be retrievable from the filesystem.
+
+        Note this does not distinguish between inline and floating images. The presence of either
+        one will cause this value to be `True`.
+        """
+        xpath_expr = (
+            # -- an inline picture --
+            "./wp:inline/a:graphic/a:graphicData/pic:pic"
+            # -- a floating picture --
+            " | ./wp:anchor/a:graphic/a:graphicData/pic:pic"
+        )
+        # -- xpath() will return a list, empty if there are no matches --
+        return bool(self._drawing.xpath(xpath_expr))
+
+    @property
+    def image(self) -> Image:
+        """An `Image` proxy object for the image in this (picture) drawing.
+
+        Raises `ValueError` when this drawing does contains something other than a picture. Use
+        `.has_picture` to qualify drawing objects before using this property.
+        """
+        picture_rIds = self._drawing.xpath(".//pic:blipFill/a:blip/@r:embed")
+        if not picture_rIds:
+            raise ValueError("drawing does not contain a picture")
+        rId = picture_rIds[0]
+        doc_part = self.part
+        image_part = doc_part.related_parts[rId]
+        return image_part.image

docx/enum/base.py

@@ -0,0 +1,150 @@
+"""Base classes and other objects used by enumerations."""
+
+from __future__ import annotations
+
+import enum
+import textwrap
+from typing import TYPE_CHECKING, Any, Dict, Type, TypeVar
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+_T = TypeVar("_T", bound="BaseXmlEnum")
+
+
+class BaseEnum(int, enum.Enum):
+    """Base class for Enums that do not map XML attr values.
+
+    The enum's value will be an integer, corresponding to the integer assigned the
+    corresponding member in the MS API enum of the same name.
+    """
+
+    def __new__(cls, ms_api_value: int, docstr: str):
+        self = int.__new__(cls, ms_api_value)
+        self._value_ = ms_api_value
+        self.__doc__ = docstr.strip()
+        return self
+
+    def __str__(self):
+        """The symbolic name and string value of this member, e.g. 'MIDDLE (3)'."""
+        return f"{self.name} ({self.value})"
+
+
+class BaseXmlEnum(int, enum.Enum):
+    """Base class for Enums that also map XML attr values.
+
+    The enum's value will be an integer, corresponding to the integer assigned the
+    corresponding member in the MS API enum of the same name.
+    """
+
+    xml_value: str | None
+
+    def __new__(cls, ms_api_value: int, xml_value: str | None, docstr: str):
+        self = int.__new__(cls, ms_api_value)
+        self._value_ = ms_api_value
+        self.xml_value = xml_value
+        self.__doc__ = docstr.strip()
+        return self
+
+    def __str__(self):
+        """The symbolic name and string value of this member, e.g. 'MIDDLE (3)'."""
+        return f"{self.name} ({self.value})"
+
+    @classmethod
+    def from_xml(cls, xml_value: str | None) -> Self:
+        """Enumeration member corresponding to XML attribute value `xml_value`.
+
+        Example::
+
+            >>> WD_PARAGRAPH_ALIGNMENT.from_xml("center")
+            WD_PARAGRAPH_ALIGNMENT.CENTER
+
+        """
+        member = next((member for member in cls if member.xml_value == xml_value), None)
+        if member is None:
+            raise ValueError(f"{cls.__name__} has no XML mapping for '{xml_value}'")
+        return member
+
+    @classmethod
+    def to_xml(cls: Type[_T], value: int | _T | None) -> str | None:
+        """XML value of this enum member, generally an XML attribute value."""
+        # -- presence of multi-arg `__new__()` method fools type-checker, but getting a
+        # -- member by its value using EnumCls(val) works as usual.
+        member = cls(value)
+        xml_value = member.xml_value
+        if not xml_value:
+            raise ValueError(f"{cls.__name__}.{member.name} has no XML representation")
+        return xml_value
+
+
+class DocsPageFormatter:
+    """Generate an .rst doc page for an enumeration.
+
+    Formats a RestructuredText documention page (string) for the enumeration class parts
+    passed to the constructor. An immutable one-shot service object.
+    """
+
+    def __init__(self, clsname: str, clsdict: Dict[str, Any]):
+        self._clsname = clsname
+        self._clsdict = clsdict
+
+    @property
+    def page_str(self):
+        """The RestructuredText documentation page for the enumeration.
+
+        This is the only API member for the class.
+        """
+        tmpl = ".. _%s:\n\n%s\n\n%s\n\n----\n\n%s"
+        components = (
+            self._ms_name,
+            self._page_title,
+            self._intro_text,
+            self._member_defs,
+        )
+        return tmpl % components
+
+    @property
+    def _intro_text(self):
+        """Docstring of the enumeration, formatted for documentation page."""
+        try:
+            cls_docstring = self._clsdict["__doc__"]
+        except KeyError:
+            cls_docstring = ""
+
+        if cls_docstring is None:
+            return ""
+
+        return textwrap.dedent(cls_docstring).strip()
+
+    def _member_def(self, member: BaseEnum | BaseXmlEnum):
+        """Return an individual member definition formatted as an RST glossary entry,
+        wrapped to fit within 78 columns."""
+        assert member.__doc__ is not None
+        member_docstring = textwrap.dedent(member.__doc__).strip()
+        member_docstring = textwrap.fill(
+            member_docstring,
+            width=78,
+            initial_indent=" " * 4,
+            subsequent_indent=" " * 4,
+        )
+        return "%s\n%s\n" % (member.name, member_docstring)
+
+    @property
+    def _member_defs(self):
+        """A single string containing the aggregated member definitions section of the
+        documentation page."""
+        members = self._clsdict["__members__"]
+        member_defs = [self._member_def(member) for member in members if member.name is not None]
+        return "\n".join(member_defs)
+
+    @property
+    def _ms_name(self):
+        """The Microsoft API name for this enumeration."""
+        return self._clsdict["__ms_name__"]
+
+    @property
+    def _page_title(self):
+        """The title for the documentation page, formatted as code (surrounded in
+        double-backtics) and underlined with '=' characters."""
+        title_underscore = "=" * (len(self._clsname) + 4)
+        return "``%s``\n%s" % (self._clsname, title_underscore)

docx/enum/dml.py

@@ -0,0 +1,103 @@
+"""Enumerations used by DrawingML objects."""
+
+from .base import BaseEnum, BaseXmlEnum
+
+
+class MSO_COLOR_TYPE(BaseEnum):
+    """Specifies the color specification scheme.
+
+    Example::
+
+        from docx.enum.dml import MSO_COLOR_TYPE
+
+        assert font.color.type == MSO_COLOR_TYPE.SCHEME
+
+    MS API name: `MsoColorType`
+
+    http://msdn.microsoft.com/en-us/library/office/ff864912(v=office.15).aspx
+    """
+
+    RGB = (1, "Color is specified by an |RGBColor| value.")
+    """Color is specified by an |RGBColor| value."""
+
+    THEME = (2, "Color is one of the preset theme colors.")
+    """Color is one of the preset theme colors."""
+
+    AUTO = (101, "Color is determined automatically by the application.")
+    """Color is determined automatically by the application."""
+
+
+class MSO_THEME_COLOR_INDEX(BaseXmlEnum):
+    """Indicates the Office theme color, one of those shown in the color gallery on the
+    formatting ribbon.
+
+    Alias: ``MSO_THEME_COLOR``
+
+    Example::
+
+        from docx.enum.dml import MSO_THEME_COLOR
+
+        font.color.theme_color = MSO_THEME_COLOR.ACCENT_1
+
+    MS API name: `MsoThemeColorIndex`
+
+    http://msdn.microsoft.com/en-us/library/office/ff860782(v=office.15).aspx
+    """
+
+    NOT_THEME_COLOR = (0, "UNMAPPED", "Indicates the color is not a theme color.")
+    """Indicates the color is not a theme color."""
+
+    ACCENT_1 = (5, "accent1", "Specifies the Accent 1 theme color.")
+    """Specifies the Accent 1 theme color."""
+
+    ACCENT_2 = (6, "accent2", "Specifies the Accent 2 theme color.")
+    """Specifies the Accent 2 theme color."""
+
+    ACCENT_3 = (7, "accent3", "Specifies the Accent 3 theme color.")
+    """Specifies the Accent 3 theme color."""
+
+    ACCENT_4 = (8, "accent4", "Specifies the Accent 4 theme color.")
+    """Specifies the Accent 4 theme color."""
+
+    ACCENT_5 = (9, "accent5", "Specifies the Accent 5 theme color.")
+    """Specifies the Accent 5 theme color."""
+
+    ACCENT_6 = (10, "accent6", "Specifies the Accent 6 theme color.")
+    """Specifies the Accent 6 theme color."""
+
+    BACKGROUND_1 = (14, "background1", "Specifies the Background 1 theme color.")
+    """Specifies the Background 1 theme color."""
+
+    BACKGROUND_2 = (16, "background2", "Specifies the Background 2 theme color.")
+    """Specifies the Background 2 theme color."""
+
+    DARK_1 = (1, "dark1", "Specifies the Dark 1 theme color.")
+    """Specifies the Dark 1 theme color."""
+
+    DARK_2 = (3, "dark2", "Specifies the Dark 2 theme color.")
+    """Specifies the Dark 2 theme color."""
+
+    FOLLOWED_HYPERLINK = (
+        12,
+        "followedHyperlink",
+        "Specifies the theme color for a clicked hyperlink.",
+    )
+    """Specifies the theme color for a clicked hyperlink."""
+
+    HYPERLINK = (11, "hyperlink", "Specifies the theme color for a hyperlink.")
+    """Specifies the theme color for a hyperlink."""
+
+    LIGHT_1 = (2, "light1", "Specifies the Light 1 theme color.")
+    """Specifies the Light 1 theme color."""
+
+    LIGHT_2 = (4, "light2", "Specifies the Light 2 theme color.")
+    """Specifies the Light 2 theme color."""
+
+    TEXT_1 = (13, "text1", "Specifies the Text 1 theme color.")
+    """Specifies the Text 1 theme color."""
+
+    TEXT_2 = (15, "text2", "Specifies the Text 2 theme color.")
+    """Specifies the Text 2 theme color."""
+
+
+MSO_THEME_COLOR = MSO_THEME_COLOR_INDEX

docx/enum/section.py

@@ -0,0 +1,86 @@
+"""Enumerations related to the main document in WordprocessingML files."""
+
+from .base import BaseXmlEnum
+
+
+class WD_HEADER_FOOTER_INDEX(BaseXmlEnum):
+    """Alias: **WD_HEADER_FOOTER**
+
+    Specifies one of the three possible header/footer definitions for a section.
+
+    For internal use only; not part of the python-docx API.
+
+    MS API name: `WdHeaderFooterIndex`
+    URL: https://docs.microsoft.com/en-us/office/vba/api/word.wdheaderfooterindex
+    """
+
+    PRIMARY = (1, "default", "Header for odd pages or all if no even header.")
+    """Header for odd pages or all if no even header."""
+
+    FIRST_PAGE = (2, "first", "Header for first page of section.")
+    """Header for first page of section."""
+
+    EVEN_PAGE = (3, "even", "Header for even pages of recto/verso section.")
+    """Header for even pages of recto/verso section."""
+
+
+WD_HEADER_FOOTER = WD_HEADER_FOOTER_INDEX
+
+
+class WD_ORIENTATION(BaseXmlEnum):
+    """Alias: **WD_ORIENT**
+
+    Specifies the page layout orientation.
+
+    Example::
+
+        from docx.enum.section import WD_ORIENT
+
+        section = document.sections[-1] section.orientation = WD_ORIENT.LANDSCAPE
+
+    MS API name: `WdOrientation`
+    MS API URL: http://msdn.microsoft.com/en-us/library/office/ff837902.aspx
+    """
+
+    PORTRAIT = (0, "portrait", "Portrait orientation.")
+    """Portrait orientation."""
+
+    LANDSCAPE = (1, "landscape", "Landscape orientation.")
+    """Landscape orientation."""
+
+
+WD_ORIENT = WD_ORIENTATION
+
+
+class WD_SECTION_START(BaseXmlEnum):
+    """Alias: **WD_SECTION**
+
+    Specifies the start type of a section break.
+
+    Example::
+
+        from docx.enum.section import WD_SECTION
+
+        section = document.sections[0] section.start_type = WD_SECTION.NEW_PAGE
+
+    MS API name: `WdSectionStart`
+    MS API URL: http://msdn.microsoft.com/en-us/library/office/ff840975.aspx
+    """
+
+    CONTINUOUS = (0, "continuous", "Continuous section break.")
+    """Continuous section break."""
+
+    NEW_COLUMN = (1, "nextColumn", "New column section break.")
+    """New column section break."""
+
+    NEW_PAGE = (2, "nextPage", "New page section break.")
+    """New page section break."""
+
+    EVEN_PAGE = (3, "evenPage", "Even pages section break.")
+    """Even pages section break."""
+
+    ODD_PAGE = (4, "oddPage", "Section begins on next odd page.")
+    """Section begins on next odd page."""
+
+
+WD_SECTION = WD_SECTION_START