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

docx/__init__.py

@@ -0,0 +1,68 @@
+"""Initialize `docx` package.
+
+Export the `Document` constructor function and establish the mapping of part-type to
+the part-classe that implements that type.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Type
+
+from docx.api import Document
+
+if TYPE_CHECKING:
+    from docx.opc.part import Part
+
+__version__ = "1.3.0"
+
+
+__all__ = ["Document"]
+
+
+# -- register custom Part classes with opc package reader --
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.part import PartFactory
+from docx.opc.parts.coreprops import CorePropertiesPart
+from docx.parts.comments import CommentsPart
+from docx.parts.document import DocumentPart
+from docx.parts.hdrftr import FooterPart, HeaderPart
+from docx.parts.image import ImagePart
+from docx.parts.numbering import NumberingPart
+from docx.parts.settings import SettingsPart
+from docx.parts.styles import StylesPart
+from docx.parts.theme import ThemePart
+
+
+def part_class_selector(content_type: str, reltype: str) -> Type[Part] | None:
+    if reltype == RT.IMAGE:
+        return ImagePart
+    return None
+
+
+PartFactory.part_class_selector = part_class_selector
+PartFactory.part_type_for[CT.OPC_CORE_PROPERTIES] = CorePropertiesPart
+PartFactory.part_type_for[CT.WML_COMMENTS] = CommentsPart
+PartFactory.part_type_for[CT.WML_DOCUMENT_MAIN] = DocumentPart
+PartFactory.part_type_for[CT.WML_FOOTER] = FooterPart
+PartFactory.part_type_for[CT.WML_HEADER] = HeaderPart
+PartFactory.part_type_for[CT.WML_NUMBERING] = NumberingPart
+PartFactory.part_type_for[CT.WML_SETTINGS] = SettingsPart
+PartFactory.part_type_for[CT.WML_STYLES] = StylesPart
+PartFactory.part_type_for[CT.OFC_THEME] = ThemePart
+
+del (
+    CT,
+    CorePropertiesPart,
+    CommentsPart,
+    DocumentPart,
+    FooterPart,
+    HeaderPart,
+    NumberingPart,
+    PartFactory,
+    SettingsPart,
+    StylesPart,
+    ThemePart,
+    part_class_selector,
+)

docx/api.py

@@ -0,0 +1,37 @@
+"""Directly exposed API functions and classes, :func:`Document` for now.
+
+Provides a syntactically more convenient API for interacting with the OpcPackage graph.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import IO, TYPE_CHECKING, cast
+
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.package import Package
+
+if TYPE_CHECKING:
+    from docx.document import Document as DocumentObject
+    from docx.parts.document import DocumentPart
+
+
+def Document(docx: str | IO[bytes] | None = None) -> DocumentObject:
+    """Return a |Document| object loaded from `docx`, where `docx` can be either a path
+    to a ``.docx`` file (a string) or a file-like object.
+
+    If `docx` is missing or ``None``, the built-in default document "template" is
+    loaded.
+    """
+    docx = _default_docx_path() if docx is None else docx
+    document_part = cast("DocumentPart", Package.open(docx).main_document_part)
+    if document_part.content_type != CT.WML_DOCUMENT_MAIN:
+        tmpl = "file '%s' is not a Word file, content type is '%s'"
+        raise ValueError(tmpl % (docx, document_part.content_type))
+    return document_part.document
+
+
+def _default_docx_path():
+    """Return the path to the built-in default .docx package."""
+    _thisdir = os.path.split(__file__)[0]
+    return os.path.join(_thisdir, "templates", "default.docx")

docx/blkcntnr.py

@@ -0,0 +1,101 @@
+# pyright: reportImportCycles=false
+
+"""Block item container, used by body, cell, header, etc.
+
+Block level items are things like paragraph and table, although there are a few other
+specialized ones like structured document tags.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from typing_extensions import TypeAlias
+
+from docx.oxml.table import CT_Tbl
+from docx.oxml.text.paragraph import CT_P
+from docx.shared import StoryChild
+from docx.text.paragraph import Paragraph
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.oxml.comments import CT_Comment
+    from docx.oxml.document import CT_Body
+    from docx.oxml.section import CT_HdrFtr
+    from docx.oxml.table import CT_Tc
+    from docx.shared import Length
+    from docx.styles.style import ParagraphStyle
+    from docx.table import Table
+
+BlockItemElement: TypeAlias = "CT_Body | CT_Comment | CT_HdrFtr | CT_Tc"
+
+
+class BlockItemContainer(StoryChild):
+    """Base class for proxy objects that can contain block items.
+
+    These containers include _Body, _Cell, header, footer, footnote, endnote, comment,
+    and text box objects. Provides the shared functionality to add a block item like a
+    paragraph or table.
+    """
+
+    def __init__(self, element: BlockItemElement, parent: t.ProvidesStoryPart):
+        super(BlockItemContainer, self).__init__(parent)
+        self._element = element
+
+    def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = None) -> Paragraph:
+        """Return paragraph newly added to the end of the content in this container.
+
+        The paragraph has `text` in a single run if present, and is given paragraph
+        style `style`.
+
+        If `style` is |None|, no paragraph style is applied, which has the same effect
+        as applying the 'Normal' style.
+        """
+        paragraph = self._add_paragraph()
+        if text:
+            paragraph.add_run(text)
+        if style is not None:
+            paragraph.style = style
+        return paragraph
+
+    def add_table(self, rows: int, cols: int, width: Length) -> Table:
+        """Return table of `width` having `rows` rows and `cols` columns.
+
+        The table is appended appended at the end of the content in this container.
+
+        `width` is evenly distributed between the table columns.
+        """
+        from docx.table import Table
+
+        tbl = CT_Tbl.new_tbl(rows, cols, width)
+        self._element._insert_tbl(tbl)  # pyright: ignore[reportPrivateUsage]
+        return Table(tbl, self)
+
+    def iter_inner_content(self) -> Iterator[Paragraph | Table]:
+        """Generate each `Paragraph` or `Table` in this container in document order."""
+        from docx.table import Table
+
+        for element in self._element.inner_content_elements:
+            yield (Paragraph(element, self) if isinstance(element, CT_P) else Table(element, self))
+
+    @property
+    def paragraphs(self):
+        """A list containing the paragraphs in this container, in document order.
+
+        Read-only.
+        """
+        return [Paragraph(p, self) for p in self._element.p_lst]
+
+    @property
+    def tables(self):
+        """A list containing the tables in this container, in document order.
+
+        Read-only.
+        """
+        from docx.table import Table
+
+        return [Table(tbl, self) for tbl in self._element.tbl_lst]
+
+    def _add_paragraph(self):
+        """Return paragraph newly added to the end of the content in this container."""
+        return Paragraph(self._element.add_p(), self)

docx/comments.py

@@ -0,0 +1,163 @@
+"""Collection providing access to comments added to this document."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING, Iterator
+
+from docx.blkcntnr import BlockItemContainer
+
+if TYPE_CHECKING:
+    from docx.oxml.comments import CT_Comment, CT_Comments
+    from docx.parts.comments import CommentsPart
+    from docx.styles.style import ParagraphStyle
+    from docx.text.paragraph import Paragraph
+
+
+class Comments:
+    """Collection containing the comments added to this document."""
+
+    def __init__(self, comments_elm: CT_Comments, comments_part: CommentsPart):
+        self._comments_elm = comments_elm
+        self._comments_part = comments_part
+
+    def __iter__(self) -> Iterator[Comment]:
+        """Iterator over the comments in this collection."""
+        return (
+            Comment(comment_elm, self._comments_part)
+            for comment_elm in self._comments_elm.comment_lst
+        )
+
+    def __len__(self) -> int:
+        """The number of comments in this collection."""
+        return len(self._comments_elm.comment_lst)
+
+    def add_comment(self, text: str = "", author: str = "", initials: str | None = "") -> Comment:
+        """Add a new comment to the document and return it.
+
+        The comment is added to the end of the comments collection and is assigned a unique
+        comment-id.
+
+        If `text` is provided, it is added to the comment. This option provides for the common
+        case where a comment contains a modest passage of plain text. Multiple paragraphs can be
+        added using the `text` argument by separating their text with newlines (`"\\\\n"`).
+        Between newlines, text is interpreted as it is in `Document.add_paragraph(text=...)`.
+
+        The default is to place a single empty paragraph in the comment, which is the same
+        behavior as the Word UI when you add a comment. New runs can be added to the first
+        paragraph in the empty comment with `comments.paragraphs[0].add_run()` to adding more
+        complex text with emphasis or images. Additional paragraphs can be added using
+        `.add_paragraph()`.
+
+        `author` is a required attribute, set to the empty string by default.
+
+        `initials` is an optional attribute, set to the empty string by default. Passing |None|
+        for the `initials` parameter causes that attribute to be omitted from the XML.
+        """
+        comment_elm = self._comments_elm.add_comment()
+        comment_elm.author = author
+        comment_elm.initials = initials
+        comment_elm.date = dt.datetime.now(dt.timezone.utc)
+        comment = Comment(comment_elm, self._comments_part)
+
+        if text == "":
+            return comment
+
+        para_text_iter = iter(text.split("\n"))
+
+        first_para_text = next(para_text_iter)
+        first_para = comment.paragraphs[0]
+        first_para.add_run(first_para_text)
+
+        for s in para_text_iter:
+            comment.add_paragraph(text=s)
+
+        return comment
+
+    def get(self, comment_id: int) -> Comment | None:
+        """Return the comment identified by `comment_id`, or |None| if not found."""
+        comment_elm = self._comments_elm.get_comment_by_id(comment_id)
+        return Comment(comment_elm, self._comments_part) if comment_elm is not None else None
+
+
+class Comment(BlockItemContainer):
+    """Proxy for a single comment in the document.
+
+    Provides methods to access comment metadata such as author, initials, and date.
+
+    A comment is also a block-item container, similar to a table cell, so it can contain both
+    paragraphs and tables and its paragraphs can contain rich text, hyperlinks and images,
+    although the common case is that a comment contains a single paragraph of plain text like a
+    sentence or phrase.
+
+    Note that certain content like tables may not be displayed in the Word comment sidebar due to
+    space limitations. Such "over-sized" content can still be viewed in the review pane.
+    """
+
+    def __init__(self, comment_elm: CT_Comment, comments_part: CommentsPart):
+        super().__init__(comment_elm, comments_part)
+        self._comment_elm = comment_elm
+
+    def add_paragraph(self, text: str = "", style: str | ParagraphStyle | None = None) -> Paragraph:
+        """Return paragraph newly added to the end of the content in this container.
+
+        The paragraph has `text` in a single run if present, and is given paragraph style `style`.
+        When `style` is |None| or ommitted, the "CommentText" paragraph style is applied, which is
+        the default style for comments.
+        """
+        paragraph = super().add_paragraph(text, style)
+
+        # -- have to assign style directly to element because `paragraph.style` raises when
+        # -- a style is not present in the styles part
+        if style is None:
+            paragraph._p.style = "CommentText"  # pyright: ignore[reportPrivateUsage]
+
+        return paragraph
+
+    @property
+    def author(self) -> str:
+        """Read/write. The recorded author of this comment.
+
+        This field is required but can be set to the empty string.
+        """
+        return self._comment_elm.author
+
+    @author.setter
+    def author(self, value: str):
+        self._comment_elm.author = value
+
+    @property
+    def comment_id(self) -> int:
+        """The unique identifier of this comment."""
+        return self._comment_elm.id
+
+    @property
+    def initials(self) -> str | None:
+        """Read/write. The recorded initials of the comment author.
+
+        This attribute is optional in the XML, returns |None| if not set. Assigning |None| removes
+        any existing initials from the XML.
+        """
+        return self._comment_elm.initials
+
+    @initials.setter
+    def initials(self, value: str | None):
+        self._comment_elm.initials = value
+
+    @property
+    def text(self) -> str:
+        """The text content of this comment as a string.
+
+        Only content in paragraphs is included and of course all emphasis and styling is stripped.
+
+        Paragraph boundaries are indicated with a newline (`"\\\\n"`)
+        """
+        return "\n".join(p.text for p in self.paragraphs)
+
+    @property
+    def timestamp(self) -> dt.datetime | None:
+        """The date and time this comment was authored.
+
+        This attribute is optional in the XML, returns |None| if not set.
+        """
+        return self._comment_elm.date

docx/dml/color.py

@@ -0,0 +1,112 @@
+"""DrawingML objects related to color, ColorFormat being the most prominent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from typing_extensions import TypeAlias
+
+from docx.enum.dml import MSO_COLOR_TYPE
+from docx.oxml.simpletypes import ST_HexColorAuto
+from docx.shared import ElementProxy, RGBColor
+
+if TYPE_CHECKING:
+    from docx.enum.dml import MSO_THEME_COLOR
+    from docx.oxml.text.font import CT_Color
+    from docx.oxml.text.run import CT_R
+
+# -- other element types can be a parent of an `w:rPr` element, but for now only `w:r` is --
+RPrParent: TypeAlias = "CT_R"
+
+
+class ColorFormat(ElementProxy):
+    """Provides access to color settings like RGB color, theme color, and luminance adjustments."""
+
+    def __init__(self, rPr_parent: RPrParent):
+        super(ColorFormat, self).__init__(rPr_parent)
+        self._element = rPr_parent
+
+    @property
+    def rgb(self) -> RGBColor | None:
+        """An |RGBColor| value or |None| if no RGB color is specified.
+
+        When :attr:`type` is `MSO_COLOR_TYPE.RGB`, the value of this property will always be an
+        |RGBColor| value. It may also be an |RGBColor| value if :attr:`type` is
+        `MSO_COLOR_TYPE.THEME`, as Word writes the current value of a theme color when one is
+        assigned. In that case, the RGB value should be interpreted as no more than a good guess
+        however, as the theme color takes precedence at rendering time. Its value is |None|
+        whenever :attr:`type` is either |None| or `MSO_COLOR_TYPE.AUTO`.
+
+        Assigning an |RGBColor| value causes :attr:`type` to become `MSO_COLOR_TYPE.RGB` and any
+        theme color is removed. Assigning |None| causes any color to be removed such that the
+        effective color is inherited from the style hierarchy.
+        """
+        color = self._color
+        if color is None:
+            return None
+        if color.val == ST_HexColorAuto.AUTO:
+            return None
+        return cast(RGBColor, color.val)
+
+    @rgb.setter
+    def rgb(self, value: RGBColor | None):
+        if value is None and self._color is None:
+            return
+        rPr = self._element.get_or_add_rPr()
+        rPr._remove_color()  # pyright: ignore[reportPrivateUsage]
+        if value is not None:
+            rPr.get_or_add_color().val = value
+
+    @property
+    def theme_color(self) -> MSO_THEME_COLOR | None:
+        """Member of :ref:`MsoThemeColorIndex` or |None| if no theme color is specified.
+
+        When :attr:`type` is `MSO_COLOR_TYPE.THEME`, the value of this property will always be a
+        member of :ref:`MsoThemeColorIndex`. When :attr:`type` has any other value, the value of
+        this property is |None|.
+
+        Assigning a member of :ref:`MsoThemeColorIndex` causes :attr:`type` to become
+        `MSO_COLOR_TYPE.THEME`. Any existing RGB value is retained but ignored by Word. Assigning
+        |None| causes any color specification to be removed such that the effective color is
+        inherited from the style hierarchy.
+        """
+        color = self._color
+        if color is None:
+            return None
+        return color.themeColor
+
+    @theme_color.setter
+    def theme_color(self, value: MSO_THEME_COLOR | None):
+        if value is None:
+            if self._color is not None and self._element.rPr is not None:
+                self._element.rPr._remove_color()  # pyright: ignore[reportPrivateUsage]
+            return
+        self._element.get_or_add_rPr().get_or_add_color().themeColor = value
+
+    @property
+    def type(self) -> MSO_COLOR_TYPE | None:
+        """Read-only.
+
+        A member of :ref:`MsoColorType`, one of RGB, THEME, or AUTO, corresponding to the way this
+        color is defined. Its value is |None| if no color is applied at this level, which causes
+        the effective color to be inherited from the style hierarchy.
+        """
+        color = self._color
+        if color is None:
+            return None
+        if color.themeColor is not None:
+            return MSO_COLOR_TYPE.THEME
+        if color.val == ST_HexColorAuto.AUTO:
+            return MSO_COLOR_TYPE.AUTO
+        return MSO_COLOR_TYPE.RGB
+
+    @property
+    def _color(self) -> CT_Color | None:
+        """Return `w:rPr/w:color` or |None| if not present.
+
+        Helper to factor out repetitive element access.
+        """
+        rPr = self._element.rPr
+        if rPr is None:
+            return None
+        return rPr.color