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

docx/text/run.py

@@ -0,0 +1,257 @@
+"""Run-related proxy objects for python-docx, Run in particular."""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Iterator, cast
+
+from docx.drawing import Drawing
+from docx.enum.style import WD_STYLE_TYPE
+from docx.enum.text import WD_BREAK
+from docx.oxml.drawing import CT_Drawing
+from docx.oxml.text.pagebreak import CT_LastRenderedPageBreak
+from docx.shape import InlineShape
+from docx.shared import StoryChild
+from docx.styles.style import CharacterStyle
+from docx.text.font import Font
+from docx.text.pagebreak import RenderedPageBreak
+
+if TYPE_CHECKING:
+    import docx.types as t
+    from docx.enum.text import WD_UNDERLINE
+    from docx.oxml.text.run import CT_R, CT_Text
+    from docx.shared import Length
+
+
+class Run(StoryChild):
+    """Proxy object wrapping `<w:r>` element.
+
+    Several of the properties on Run take a tri-state value, |True|, |False|, or |None|.
+    |True| and |False| correspond to on and off respectively. |None| indicates the
+    property is not specified directly on the run and its effective value is taken from
+    the style hierarchy.
+    """
+
+    def __init__(self, r: CT_R, parent: t.ProvidesStoryPart):
+        super().__init__(parent)
+        self._r = self._element = self.element = r
+
+    def add_break(self, break_type: WD_BREAK = WD_BREAK.LINE):
+        """Add a break element of `break_type` to this run.
+
+        `break_type` can take the values `WD_BREAK.LINE`, `WD_BREAK.PAGE`, and
+        `WD_BREAK.COLUMN` where `WD_BREAK` is imported from `docx.enum.text`.
+        `break_type` defaults to `WD_BREAK.LINE`.
+        """
+        type_, clear = {
+            WD_BREAK.LINE: (None, None),
+            WD_BREAK.PAGE: ("page", None),
+            WD_BREAK.COLUMN: ("column", None),
+            WD_BREAK.LINE_CLEAR_LEFT: ("textWrapping", "left"),
+            WD_BREAK.LINE_CLEAR_RIGHT: ("textWrapping", "right"),
+            WD_BREAK.LINE_CLEAR_ALL: ("textWrapping", "all"),
+        }[break_type]
+        br = self._r.add_br()
+        if type_ is not None:
+            br.type = type_
+        if clear is not None:
+            br.clear = clear
+
+    def add_picture(
+        self,
+        image_path_or_stream: str | IO[bytes],
+        width: int | Length | None = None,
+        height: int | Length | None = None,
+    ) -> InlineShape:
+        """Return |InlineShape| containing image identified by `image_path_or_stream`.
+
+        The picture is added to the end of this run.
+
+        `image_path_or_stream` can be a path (a string) or a file-like object containing
+        a binary image.
+
+        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.
+        """
+        inline = self.part.new_pic_inline(image_path_or_stream, width, height)
+        self._r.add_drawing(inline)
+        return InlineShape(inline)
+
+    def add_tab(self) -> None:
+        """Add a ``<w:tab/>`` element at the end of the run, which Word interprets as a
+        tab character."""
+        self._r.add_tab()
+
+    def add_text(self, text: str):
+        """Returns a newly appended |_Text| object (corresponding to a new ``<w:t>``
+        child element) to the run, containing `text`.
+
+        Compare with the possibly more friendly approach of assigning text to the
+        :attr:`Run.text` property.
+        """
+        t = self._r.add_t(text)
+        return _Text(t)
+
+    @property
+    def bold(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text of the run to appear in bold face. When |False|,
+        the text unconditionally appears non-bold. When |None| the bold setting for this
+        run is inherited from the style hierarchy.
+        """
+        return self.font.bold
+
+    @bold.setter
+    def bold(self, value: bool | None):
+        self.font.bold = value
+
+    def clear(self):
+        """Return reference to this run after removing all its content.
+
+        All run formatting is preserved.
+        """
+        self._r.clear_content()
+        return self
+
+    @property
+    def contains_page_break(self) -> bool:
+        """`True` when one or more rendered page-breaks occur in this run.
+
+        Note that "hard" page-breaks inserted by the author are not included. A hard
+        page-break gives rise to a rendered page-break in the right position so if those
+        were included that page-break would be "double-counted".
+
+        It would be very rare for multiple rendered page-breaks to occur in a single
+        run, but it is possible.
+        """
+        return bool(self._r.lastRenderedPageBreaks)
+
+    @property
+    def font(self) -> Font:
+        """The |Font| object providing access to the character formatting properties for
+        this run, such as font name and size."""
+        return Font(self._element)
+
+    @property
+    def italic(self) -> bool | None:
+        """Read/write tri-state value.
+
+        When |True|, causes the text of the run to appear in italics. When |False|, the
+        text unconditionally appears non-italic. When |None| the italic setting for this
+        run is inherited from the style hierarchy.
+        """
+        return self.font.italic
+
+    @italic.setter
+    def italic(self, value: bool | None):
+        self.font.italic = value
+
+    def iter_inner_content(self) -> Iterator[str | Drawing | RenderedPageBreak]:
+        """Generate the content-items in this run in the order they appear.
+
+        NOTE: only content-types currently supported by `python-docx` are generated. In
+        this version, that is text and rendered page-breaks. Drawing is included but
+        currently only provides access to its XML element (CT_Drawing) on its
+        `._drawing` attribute. `Drawing` attributes and methods may be expanded in
+        future releases.
+
+        There are a number of element-types that can appear inside a run, but most of
+        those (w:br, w:cr, w:noBreakHyphen, w:t, w:tab) have a clear plain-text
+        equivalent. Any contiguous range of such elements is generated as a single
+        `str`. Rendered page-break and drawing elements are generated individually. Any
+        other elements are ignored.
+        """
+        for item in self._r.inner_content_items:
+            if isinstance(item, str):
+                yield item
+            elif isinstance(item, CT_LastRenderedPageBreak):
+                yield RenderedPageBreak(item, self)
+            elif isinstance(item, CT_Drawing):  # pyright: ignore[reportUnnecessaryIsInstance]
+                yield Drawing(item, self)
+
+    def mark_comment_range(self, last_run: Run, comment_id: int) -> None:
+        """Mark the range of runs from this run to `last_run` (inclusive) as belonging to a comment.
+
+        `comment_id` identfies the comment that references this range.
+        """
+        # -- insert `w:commentRangeStart` with `comment_id` before this (first) run --
+        self._r.insert_comment_range_start_above(comment_id)
+
+        # -- insert `w:commentRangeEnd` and `w:commentReference` run with `comment_id` after
+        # -- `last_run`
+        last_run._r.insert_comment_range_end_and_reference_below(comment_id)
+
+    @property
+    def style(self) -> CharacterStyle:
+        """Read/write.
+
+        A |CharacterStyle| object representing the character style applied to this run.
+        The default character style for the document (often `Default Character Font`) is
+        returned if the run has no directly-applied character style. Setting this
+        property to |None| removes any directly-applied character style.
+        """
+        style_id = self._r.style
+        return cast(CharacterStyle, self.part.get_style(style_id, WD_STYLE_TYPE.CHARACTER))
+
+    @style.setter
+    def style(self, style_or_name: str | CharacterStyle | None):
+        style_id = self.part.get_style_id(style_or_name, WD_STYLE_TYPE.CHARACTER)
+        self._r.style = style_id
+
+    @property
+    def text(self) -> str:
+        """String formed by concatenating the text equivalent of each run.
+
+        Each `<w:t>` element adds the text characters it contains. A `<w:tab/>` element
+        adds a `\\t` character. A `<w:cr/>` or `<w:br>` element each add a `\\n`
+        character. Note that a `<w:br>` element can indicate a page break or column
+        break as well as a line break. Only line-break `<w:br>` elements translate to
+        a `\\n` character. Others are ignored. All other content child elements, such as
+        `<w:drawing>`, are ignored.
+
+        Assigning text to this property has the reverse effect, translating each `\\t`
+        character to a `<w:tab/>` element and each `\\n` or `\\r` character to a
+        `<w:cr/>` element. Any existing run content is replaced. Run formatting is
+        preserved.
+        """
+        return self._r.text
+
+    @text.setter
+    def text(self, text: str):
+        self._r.text = text
+
+    @property
+    def underline(self) -> bool | WD_UNDERLINE | None:
+        """The underline style for this |Run|.
+
+        Value is one of |None|, |True|, |False|, or a member of :ref:`WdUnderline`.
+
+        A value of |None| indicates the run has no directly-applied underline value and
+        so will inherit the underline value of its containing paragraph. Assigning
+        |None| to this property removes any directly-applied underline value.
+
+        A value of |False| indicates a directly-applied setting of no underline,
+        overriding any inherited value.
+
+        A value of |True| indicates single underline.
+
+        The values from :ref:`WdUnderline` are used to specify other outline styles such
+        as double, wavy, and dotted.
+        """
+        return self.font.underline
+
+    @underline.setter
+    def underline(self, value: bool | WD_UNDERLINE | None):
+        self.font.underline = value
+
+
+class _Text:
+    """Proxy object wrapping `<w:t>` element."""
+
+    def __init__(self, t_elm: CT_Text):
+        super(_Text, self).__init__()
+        self._t = t_elm

docx/text/tabstops.py

@@ -0,0 +1,123 @@
+"""Tabstop-related proxy types."""
+
+from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER
+from docx.shared import ElementProxy
+
+
+class TabStops(ElementProxy):
+    """A sequence of |TabStop| objects providing access to the tab stops of a paragraph
+    or paragraph style.
+
+    Supports iteration, indexed access, del, and len(). It is accesed using the
+    :attr:`~.ParagraphFormat.tab_stops` property of ParagraphFormat; it is not intended
+    to be constructed directly.
+    """
+
+    def __init__(self, element):
+        super(TabStops, self).__init__(element, None)
+        self._pPr = element
+
+    def __delitem__(self, idx):
+        """Remove the tab at offset `idx` in this sequence."""
+        tabs = self._pPr.tabs
+        try:
+            tabs.remove(tabs[idx])
+        except (AttributeError, IndexError):
+            raise IndexError("tab index out of range")
+
+        if len(tabs) == 0:
+            self._pPr.remove(tabs)
+
+    def __getitem__(self, idx):
+        """Enables list-style access by index."""
+        tabs = self._pPr.tabs
+        if tabs is None:
+            raise IndexError("TabStops object is empty")
+        tab = tabs.tab_lst[idx]
+        return TabStop(tab)
+
+    def __iter__(self):
+        """Generate a TabStop object for each of the w:tab elements, in XML document
+        order."""
+        tabs = self._pPr.tabs
+        if tabs is not None:
+            for tab in tabs.tab_lst:
+                yield TabStop(tab)
+
+    def __len__(self):
+        tabs = self._pPr.tabs
+        if tabs is None:
+            return 0
+        return len(tabs.tab_lst)
+
+    def add_tab_stop(self, position, alignment=WD_TAB_ALIGNMENT.LEFT, leader=WD_TAB_LEADER.SPACES):
+        """Add a new tab stop at `position`, a |Length| object specifying the location
+        of the tab stop relative to the paragraph edge.
+
+        A negative `position` value is valid and appears in hanging indentation. Tab
+        alignment defaults to left, but may be specified by passing a member of the
+        :ref:`WdTabAlignment` enumeration as `alignment`. An optional leader character
+        can be specified by passing a member of the :ref:`WdTabLeader` enumeration as
+        `leader`.
+        """
+        tabs = self._pPr.get_or_add_tabs()
+        tab = tabs.insert_tab_in_order(position, alignment, leader)
+        return TabStop(tab)
+
+    def clear_all(self):
+        """Remove all custom tab stops."""
+        self._pPr._remove_tabs()
+
+
+class TabStop(ElementProxy):
+    """An individual tab stop applying to a paragraph or style.
+
+    Accessed using list semantics on its containing |TabStops| object.
+    """
+
+    def __init__(self, element):
+        super(TabStop, self).__init__(element, None)
+        self._tab = element
+
+    @property
+    def alignment(self):
+        """A member of :ref:`WdTabAlignment` specifying the alignment setting for this
+        tab stop.
+
+        Read/write.
+        """
+        return self._tab.val
+
+    @alignment.setter
+    def alignment(self, value):
+        self._tab.val = value
+
+    @property
+    def leader(self):
+        """A member of :ref:`WdTabLeader` specifying a repeating character used as a
+        "leader", filling in the space spanned by this tab.
+
+        Assigning |None| produces the same result as assigning `WD_TAB_LEADER.SPACES`.
+        Read/write.
+        """
+        return self._tab.leader
+
+    @leader.setter
+    def leader(self, value):
+        self._tab.leader = value
+
+    @property
+    def position(self):
+        """A |Length| object representing the distance of this tab stop from the inside
+        edge of the paragraph.
+
+        May be positive or negative. Read/write.
+        """
+        return self._tab.pos
+
+    @position.setter
+    def position(self, value):
+        tab = self._tab
+        tabs = tab.getparent()
+        self._tab = tabs.insert_tab_in_order(value, tab.val, tab.leader)
+        tabs.remove(tab)

docx/theme.py

@@ -0,0 +1,67 @@
+"""Document theme font scheme."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docx.oxml.ns import qn
+
+if TYPE_CHECKING:
+    from lxml.etree import _Element  # pyright: ignore[reportPrivateUsage]
+
+
+class ThemeFonts:
+    """The font scheme used by theme references in a document.
+
+    Accessed through :attr:`.Document.theme_fonts`. Changing a typeface does not
+    change styles or runs. Only text already referring to that theme slot follows
+    the change. East Asian, complex-script, and supplemental fonts are preserved.
+    """
+
+    def __init__(self, element: _Element):
+        self._element = element
+        # Validate before any setters can partially update an incomplete scheme.
+        self._latin("major")
+        self._latin("minor")
+
+    @property
+    def name(self) -> str:
+        """Read/write font scheme name shown in the application's theme settings."""
+        return self._element.get("name", "")
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self._element.set("name", value)
+
+    @property
+    def major_latin(self) -> str:
+        """Read/write Latin typeface for the major (heading) theme font."""
+        return self._latin("major").get("typeface", "")
+
+    @major_latin.setter
+    def major_latin(self, value: str) -> None:
+        self._set_latin("major", value)
+
+    @property
+    def minor_latin(self) -> str:
+        """Read/write Latin typeface for the minor (body) theme font."""
+        return self._latin("minor").get("typeface", "")
+
+    @minor_latin.setter
+    def minor_latin(self, value: str) -> None:
+        self._set_latin("minor", value)
+
+    def _latin(self, role: str) -> _Element:
+        latin = self._element.find(f"{qn(f'a:{role}Font')}/{qn('a:latin')}")
+        if latin is None:
+            raise ValueError(f"theme font scheme is missing the {role} Latin font")
+        return latin
+
+    def _set_latin(self, role: str, value: object) -> None:
+        if not isinstance(value, str):
+            raise TypeError("theme typeface must be a string")
+        latin = self._latin(role)
+        latin.set("typeface", value)
+        # These optional metrics describe the previous typeface.
+        for attribute in ("panose", "pitchFamily", "charset"):
+            latin.attrib.pop(attribute, None)

docx/types.py

@@ -0,0 +1,34 @@
+"""Abstract types used by `python-docx`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import Protocol
+
+if TYPE_CHECKING:
+    from docx.opc.part import XmlPart
+    from docx.parts.story import StoryPart
+
+
+class ProvidesStoryPart(Protocol):
+    """An object that provides access to the StoryPart.
+
+    This type is for objects that have a story part like document or header as their
+    root part.
+    """
+
+    @property
+    def part(self) -> StoryPart: ...
+
+
+class ProvidesXmlPart(Protocol):
+    """An object that provides access to its XmlPart.
+
+    This type is for objects that need access to their part but it either isn't a
+    StoryPart or they don't care, possibly because they just need access to the package
+    or related parts.
+    """
+
+    @property
+    def part(self) -> XmlPart: ...

ps_python_docx-1.3.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: ps-python-docx
+Version: 1.3.0
+Summary: A maintained fork of python-docx for reading and authoring Microsoft Word documents.
+Author-email: Steve Canny <stcanny@gmail.com>
+Maintainer: John Paul Ellis
+License: MIT
+Project-URL: Changelog, https://github.com/pseudosavant/python-docx/blob/master/HISTORY.rst
+Project-URL: Documentation, https://python-docx.readthedocs.org/en/latest/
+Project-URL: Homepage, https://github.com/pseudosavant/python-docx
+Project-URL: Repository, https://github.com/pseudosavant/python-docx
+Project-URL: Issues, https://github.com/pseudosavant/python-docx/issues
+Project-URL: Upstream, https://github.com/python-openxml/python-docx
+Keywords: docx,office,openxml,word
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=3.1.0
+Requires-Dist: typing_extensions>=4.9.0
+Dynamic: license-file
+
+# ps-python-docx
+
+*ps-python-docx* is John Paul Ellis's fork of [python-docx](https://github.com/python-openxml/python-docx), a Python library for reading, creating, and updating Microsoft Word 2007+ (.docx) files. It is published independently and is not an official upstream release.
+
+This fork starts from upstream 1.2.0. The packaging setup preserves the upstream API and the `docx` import name. Version 1.3.0 adds public theme font and style inheritance APIs. See the [theme API documentation](docs/api/theme.rst). The original MIT license and upstream attribution are preserved.
+
+## Installation
+
+```
+pip install ps-python-docx
+```
+
+## Example
+
+```python
+>>> from docx import Document
+
+>>> document = Document()
+>>> document.add_paragraph("It was a dark and stormy night.")
+<docx.text.paragraph.Paragraph object at 0x10f19e760>
+>>> document.save("dark-and-stormy.docx")
+
+>>> document = Document("dark-and-stormy.docx")
+>>> document.paragraphs[0].text
+'It was a dark and stormy night.'
+```
+
+Install this distribution in place of `python-docx`. Both provide the `docx` package and should not be installed in the same environment.
+
+More information about the inherited API is available in the [upstream documentation](https://python-docx.readthedocs.org/en/latest/). Report fork-specific issues in [this repository](https://github.com/pseudosavant/python-docx/issues).
+
+## Development and releases
+
+Run the unit and acceptance suites without installing the legacy documentation dependencies:
+
+```text
+uv sync --locked --no-dev --group test
+uv run --locked --no-dev --group test pytest -q
+uv run --locked --no-dev --group test behave --format progress --stop --tags=-wip
+```
+
+See [RELEASING.md](RELEASING.md) for the GitHub-to-PyPI release process.