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

docx/enum/text.py

@@ -0,0 +1,367 @@
+"""Enumerations related to text in WordprocessingML files."""
+
+from __future__ import annotations
+
+import enum
+
+from docx.enum.base import BaseXmlEnum
+
+
+class WD_PARAGRAPH_ALIGNMENT(BaseXmlEnum):
+    """Alias: **WD_ALIGN_PARAGRAPH**
+
+    Specifies paragraph justification type.
+
+    Example::
+
+        from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+        paragraph = document.add_paragraph()
+        paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    """
+
+    LEFT = (0, "left", "Left-aligned")
+    """Left-aligned"""
+
+    CENTER = (1, "center", "Center-aligned.")
+    """Center-aligned."""
+
+    RIGHT = (2, "right", "Right-aligned.")
+    """Right-aligned."""
+
+    JUSTIFY = (3, "both", "Fully justified.")
+    """Fully justified."""
+
+    DISTRIBUTE = (
+        4,
+        "distribute",
+        "Paragraph characters are distributed to fill entire width of paragraph.",
+    )
+    """Paragraph characters are distributed to fill entire width of paragraph."""
+
+    JUSTIFY_MED = (
+        5,
+        "mediumKashida",
+        "Justified with a medium character compression ratio.",
+    )
+    """Justified with a medium character compression ratio."""
+
+    JUSTIFY_HI = (
+        7,
+        "highKashida",
+        "Justified with a high character compression ratio.",
+    )
+    """Justified with a high character compression ratio."""
+
+    JUSTIFY_LOW = (8, "lowKashida", "Justified with a low character compression ratio.")
+    """Justified with a low character compression ratio."""
+
+    THAI_JUSTIFY = (
+        9,
+        "thaiDistribute",
+        "Justified according to Thai formatting layout.",
+    )
+    """Justified according to Thai formatting layout."""
+
+
+WD_ALIGN_PARAGRAPH = WD_PARAGRAPH_ALIGNMENT
+
+
+class WD_BREAK_TYPE(enum.Enum):
+    """Corresponds to WdBreakType enumeration.
+
+    http://msdn.microsoft.com/en-us/library/office/ff195905.aspx.
+    """
+
+    COLUMN = 8
+    LINE = 6
+    LINE_CLEAR_LEFT = 9
+    LINE_CLEAR_RIGHT = 10
+    LINE_CLEAR_ALL = 11  # -- added for consistency, not in MS version --
+    PAGE = 7
+    SECTION_CONTINUOUS = 3
+    SECTION_EVEN_PAGE = 4
+    SECTION_NEXT_PAGE = 2
+    SECTION_ODD_PAGE = 5
+    TEXT_WRAPPING = 11
+
+
+WD_BREAK = WD_BREAK_TYPE
+
+
+class WD_COLOR_INDEX(BaseXmlEnum):
+    """Specifies a standard preset color to apply.
+
+    Used for font highlighting and perhaps other applications.
+
+    * MS API name: `WdColorIndex`
+    * URL: https://msdn.microsoft.com/EN-US/library/office/ff195343.aspx
+    """
+
+    INHERITED = (-1, None, "Color is inherited from the style hierarchy.")
+    """Color is inherited from the style hierarchy."""
+
+    AUTO = (0, "default", "Automatic color. Default; usually black.")
+    """Automatic color. Default; usually black."""
+
+    BLACK = (1, "black", "Black color.")
+    """Black color."""
+
+    BLUE = (2, "blue", "Blue color")
+    """Blue color"""
+
+    BRIGHT_GREEN = (4, "green", "Bright green color.")
+    """Bright green color."""
+
+    DARK_BLUE = (9, "darkBlue", "Dark blue color.")
+    """Dark blue color."""
+
+    DARK_RED = (13, "darkRed", "Dark red color.")
+    """Dark red color."""
+
+    DARK_YELLOW = (14, "darkYellow", "Dark yellow color.")
+    """Dark yellow color."""
+
+    GRAY_25 = (16, "lightGray", "25% shade of gray color.")
+    """25% shade of gray color."""
+
+    GRAY_50 = (15, "darkGray", "50% shade of gray color.")
+    """50% shade of gray color."""
+
+    GREEN = (11, "darkGreen", "Green color.")
+    """Green color."""
+
+    PINK = (5, "magenta", "Pink color.")
+    """Pink color."""
+
+    RED = (6, "red", "Red color.")
+    """Red color."""
+
+    TEAL = (10, "darkCyan", "Teal color.")
+    """Teal color."""
+
+    TURQUOISE = (3, "cyan", "Turquoise color.")
+    """Turquoise color."""
+
+    VIOLET = (12, "darkMagenta", "Violet color.")
+    """Violet color."""
+
+    WHITE = (8, "white", "White color.")
+    """White color."""
+
+    YELLOW = (7, "yellow", "Yellow color.")
+    """Yellow color."""
+
+
+WD_COLOR = WD_COLOR_INDEX
+
+
+class WD_LINE_SPACING(BaseXmlEnum):
+    """Specifies a line spacing format to be applied to a paragraph.
+
+    Example::
+
+        from docx.enum.text import WD_LINE_SPACING
+
+        paragraph = document.add_paragraph()
+        paragraph.line_spacing_rule = WD_LINE_SPACING.EXACTLY
+
+
+    MS API name: `WdLineSpacing`
+
+    URL: http://msdn.microsoft.com/en-us/library/office/ff844910.aspx
+    """
+
+    SINGLE = (0, "UNMAPPED", "Single spaced (default).")
+    """Single spaced (default)."""
+
+    ONE_POINT_FIVE = (1, "UNMAPPED", "Space-and-a-half line spacing.")
+    """Space-and-a-half line spacing."""
+
+    DOUBLE = (2, "UNMAPPED", "Double spaced.")
+    """Double spaced."""
+
+    AT_LEAST = (
+        3,
+        "atLeast",
+        "Minimum line spacing is specified amount. Amount is specified separately.",
+    )
+    """Minimum line spacing is specified amount. Amount is specified separately."""
+
+    EXACTLY = (
+        4,
+        "exact",
+        "Line spacing is exactly specified amount. Amount is specified separately.",
+    )
+    """Line spacing is exactly specified amount. Amount is specified separately."""
+
+    MULTIPLE = (
+        5,
+        "auto",
+        "Line spacing is specified as multiple of line heights. Changing font size"
+        " will change line spacing proportionately.",
+    )
+    """Line spacing is specified as multiple of line heights. Changing font size will
+       change the line spacing proportionately."""
+
+
+class WD_TAB_ALIGNMENT(BaseXmlEnum):
+    """Specifies the tab stop alignment to apply.
+
+    MS API name: `WdTabAlignment`
+
+    URL: https://msdn.microsoft.com/EN-US/library/office/ff195609.aspx
+    """
+
+    LEFT = (0, "left", "Left-aligned.")
+    """Left-aligned."""
+
+    CENTER = (1, "center", "Center-aligned.")
+    """Center-aligned."""
+
+    RIGHT = (2, "right", "Right-aligned.")
+    """Right-aligned."""
+
+    DECIMAL = (3, "decimal", "Decimal-aligned.")
+    """Decimal-aligned."""
+
+    BAR = (4, "bar", "Bar-aligned.")
+    """Bar-aligned."""
+
+    LIST = (6, "list", "List-aligned. (deprecated)")
+    """List-aligned. (deprecated)"""
+
+    CLEAR = (101, "clear", "Clear an inherited tab stop.")
+    """Clear an inherited tab stop."""
+
+    END = (102, "end", "Right-aligned.  (deprecated)")
+    """Right-aligned.  (deprecated)"""
+
+    NUM = (103, "num", "Left-aligned.  (deprecated)")
+    """Left-aligned.  (deprecated)"""
+
+    START = (104, "start", "Left-aligned.  (deprecated)")
+    """Left-aligned.  (deprecated)"""
+
+
+class WD_TAB_LEADER(BaseXmlEnum):
+    """Specifies the character to use as the leader with formatted tabs.
+
+    MS API name: `WdTabLeader`
+
+    URL: https://msdn.microsoft.com/en-us/library/office/ff845050.aspx
+    """
+
+    SPACES = (0, "none", "Spaces. Default.")
+    """Spaces. Default."""
+
+    DOTS = (1, "dot", "Dots.")
+    """Dots."""
+
+    DASHES = (2, "hyphen", "Dashes.")
+    """Dashes."""
+
+    LINES = (3, "underscore", "Double lines.")
+    """Double lines."""
+
+    HEAVY = (4, "heavy", "A heavy line.")
+    """A heavy line."""
+
+    MIDDLE_DOT = (5, "middleDot", "A vertically-centered dot.")
+    """A vertically-centered dot."""
+
+
+class WD_UNDERLINE(BaseXmlEnum):
+    """Specifies the style of underline applied to a run of characters.
+
+    MS API name: `WdUnderline`
+
+    URL: http://msdn.microsoft.com/en-us/library/office/ff822388.aspx
+    """
+
+    INHERITED = (-1, None, "Inherit underline setting from containing paragraph.")
+    """Inherit underline setting from containing paragraph."""
+
+    NONE = (
+        0,
+        "none",
+        "No underline.\n\nThis setting overrides any inherited underline value, so can"
+        " be used to remove underline from a run that inherits underlining from its"
+        " containing paragraph. Note this is not the same as assigning |None| to"
+        " Run.underline. |None| is a valid assignment value, but causes the run to"
+        " inherit its underline value. Assigning `WD_UNDERLINE.NONE` causes"
+        " underlining to be unconditionally turned off.",
+    )
+    """No underline.
+
+    This setting overrides any inherited underline value, so can be used to remove
+    underline from a run that inherits underlining from its containing paragraph. Note
+    this is not the same as assigning |None| to Run.underline. |None| is a valid
+    assignment value, but causes the run to inherit its underline value. Assigning
+    ``WD_UNDERLINE.NONE`` causes underlining to be unconditionally turned off.
+    """
+
+    SINGLE = (
+        1,
+        "single",
+        "A single line.\n\nNote that this setting is write-only in the sense that"
+        " |True| (rather than `WD_UNDERLINE.SINGLE`) is returned for a run having"
+        " this setting.",
+    )
+    """A single line.
+
+    Note that this setting is write-only in the sense that |True|
+    (rather than ``WD_UNDERLINE.SINGLE``) is returned for a run having this setting.
+    """
+
+    WORDS = (2, "words", "Underline individual words only.")
+    """Underline individual words only."""
+
+    DOUBLE = (3, "double", "A double line.")
+    """A double line."""
+
+    DOTTED = (4, "dotted", "Dots.")
+    """Dots."""
+
+    THICK = (6, "thick", "A single thick line.")
+    """A single thick line."""
+
+    DASH = (7, "dash", "Dashes.")
+    """Dashes."""
+
+    DOT_DASH = (9, "dotDash", "Alternating dots and dashes.")
+    """Alternating dots and dashes."""
+
+    DOT_DOT_DASH = (10, "dotDotDash", "An alternating dot-dot-dash pattern.")
+    """An alternating dot-dot-dash pattern."""
+
+    WAVY = (11, "wave", "A single wavy line.")
+    """A single wavy line."""
+
+    DOTTED_HEAVY = (20, "dottedHeavy", "Heavy dots.")
+    """Heavy dots."""
+
+    DASH_HEAVY = (23, "dashedHeavy", "Heavy dashes.")
+    """Heavy dashes."""
+
+    DOT_DASH_HEAVY = (25, "dashDotHeavy", "Alternating heavy dots and heavy dashes.")
+    """Alternating heavy dots and heavy dashes."""
+
+    DOT_DOT_DASH_HEAVY = (
+        26,
+        "dashDotDotHeavy",
+        "An alternating heavy dot-dot-dash pattern.",
+    )
+    """An alternating heavy dot-dot-dash pattern."""
+
+    WAVY_HEAVY = (27, "wavyHeavy", "A heavy wavy line.")
+    """A heavy wavy line."""
+
+    DASH_LONG = (39, "dashLong", "Long dashes.")
+    """Long dashes."""
+
+    WAVY_DOUBLE = (43, "wavyDouble", "A double wavy line.")
+    """A double wavy line."""
+
+    DASH_LONG_HEAVY = (55, "dashLongHeavy", "Long heavy dashes.")
+    """Long heavy dashes."""

docx/exceptions.py

@@ -0,0 +1,18 @@
+"""Exceptions used with python-docx.
+
+The base exception class is PythonDocxError.
+"""
+
+
+class PythonDocxError(Exception):
+    """Generic error class."""
+
+
+class InvalidSpanError(PythonDocxError):
+    """Raised when an invalid merge region is specified in a request to merge table
+    cells."""
+
+
+class InvalidXmlError(PythonDocxError):
+    """Raised when invalid XML is encountered, such as on attempt to access a missing
+    required child element."""

docx/image/__init__.py

@@ -0,0 +1,23 @@
+"""Provides objects that can characterize image streams.
+
+That characterization is as to content type and size, as a required step in including
+them in a document.
+"""
+
+from docx.image.bmp import Bmp
+from docx.image.gif import Gif
+from docx.image.jpeg import Exif, Jfif
+from docx.image.png import Png
+from docx.image.tiff import Tiff
+
+SIGNATURES = (
+    # class, offset, signature_bytes
+    (Png, 0, b"\x89PNG\x0d\x0a\x1a\x0a"),
+    (Jfif, 6, b"JFIF"),
+    (Exif, 6, b"Exif"),
+    (Gif, 0, b"GIF87a"),
+    (Gif, 0, b"GIF89a"),
+    (Tiff, 0, b"MM\x00*"),  # big-endian (Motorola) TIFF
+    (Tiff, 0, b"II*\x00"),  # little-endian (Intel) TIFF
+    (Bmp, 0, b"BM"),
+)

docx/image/bmp.py

@@ -0,0 +1,43 @@
+from .constants import MIME_TYPE
+from .helpers import LITTLE_ENDIAN, StreamReader
+from .image import BaseImageHeader
+
+
+class Bmp(BaseImageHeader):
+    """Image header parser for BMP images."""
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return |Bmp| instance having header properties parsed from the BMP image in
+        `stream`."""
+        stream_rdr = StreamReader(stream, LITTLE_ENDIAN)
+
+        px_width = stream_rdr.read_long(0x12)
+        px_height = stream_rdr.read_long(0x16)
+
+        horz_px_per_meter = stream_rdr.read_long(0x26)
+        vert_px_per_meter = stream_rdr.read_long(0x2A)
+
+        horz_dpi = cls._dpi(horz_px_per_meter)
+        vert_dpi = cls._dpi(vert_px_per_meter)
+
+        return cls(px_width, px_height, horz_dpi, vert_dpi)
+
+    @property
+    def content_type(self):
+        """MIME content type for this image, unconditionally `image/bmp` for BMP
+        images."""
+        return MIME_TYPE.BMP
+
+    @property
+    def default_ext(self):
+        """Default filename extension, always 'bmp' for BMP images."""
+        return "bmp"
+
+    @staticmethod
+    def _dpi(px_per_meter):
+        """Return the integer pixels per inch from `px_per_meter`, defaulting to 96 if
+        `px_per_meter` is zero."""
+        if px_per_meter == 0:
+            return 96
+        return int(round(px_per_meter * 0.0254))

docx/image/constants.py

@@ -0,0 +1,172 @@
+"""Constants specific the the image sub-package."""
+
+
+class JPEG_MARKER_CODE:
+    """JPEG marker codes."""
+
+    TEM = b"\x01"
+    DHT = b"\xc4"
+    DAC = b"\xcc"
+    JPG = b"\xc8"
+
+    SOF0 = b"\xc0"
+    SOF1 = b"\xc1"
+    SOF2 = b"\xc2"
+    SOF3 = b"\xc3"
+    SOF5 = b"\xc5"
+    SOF6 = b"\xc6"
+    SOF7 = b"\xc7"
+    SOF9 = b"\xc9"
+    SOFA = b"\xca"
+    SOFB = b"\xcb"
+    SOFD = b"\xcd"
+    SOFE = b"\xce"
+    SOFF = b"\xcf"
+
+    RST0 = b"\xd0"
+    RST1 = b"\xd1"
+    RST2 = b"\xd2"
+    RST3 = b"\xd3"
+    RST4 = b"\xd4"
+    RST5 = b"\xd5"
+    RST6 = b"\xd6"
+    RST7 = b"\xd7"
+
+    SOI = b"\xd8"
+    EOI = b"\xd9"
+    SOS = b"\xda"
+    DQT = b"\xdb"  # Define Quantization Table(s)
+    DNL = b"\xdc"
+    DRI = b"\xdd"
+    DHP = b"\xde"
+    EXP = b"\xdf"
+
+    APP0 = b"\xe0"
+    APP1 = b"\xe1"
+    APP2 = b"\xe2"
+    APP3 = b"\xe3"
+    APP4 = b"\xe4"
+    APP5 = b"\xe5"
+    APP6 = b"\xe6"
+    APP7 = b"\xe7"
+    APP8 = b"\xe8"
+    APP9 = b"\xe9"
+    APPA = b"\xea"
+    APPB = b"\xeb"
+    APPC = b"\xec"
+    APPD = b"\xed"
+    APPE = b"\xee"
+    APPF = b"\xef"
+
+    STANDALONE_MARKERS = (TEM, SOI, EOI, RST0, RST1, RST2, RST3, RST4, RST5, RST6, RST7)
+
+    SOF_MARKER_CODES = (
+        SOF0,
+        SOF1,
+        SOF2,
+        SOF3,
+        SOF5,
+        SOF6,
+        SOF7,
+        SOF9,
+        SOFA,
+        SOFB,
+        SOFD,
+        SOFE,
+        SOFF,
+    )
+
+    marker_names = {
+        b"\x00": "UNKNOWN",
+        b"\xc0": "SOF0",
+        b"\xc2": "SOF2",
+        b"\xc4": "DHT",
+        b"\xda": "SOS",  # start of scan
+        b"\xd8": "SOI",  # start of image
+        b"\xd9": "EOI",  # end of image
+        b"\xdb": "DQT",
+        b"\xe0": "APP0",
+        b"\xe1": "APP1",
+        b"\xe2": "APP2",
+        b"\xed": "APP13",
+        b"\xee": "APP14",
+    }
+
+    @classmethod
+    def is_standalone(cls, marker_code):
+        return marker_code in cls.STANDALONE_MARKERS
+
+
+class MIME_TYPE:
+    """Image content types."""
+
+    BMP = "image/bmp"
+    GIF = "image/gif"
+    JPEG = "image/jpeg"
+    PNG = "image/png"
+    TIFF = "image/tiff"
+
+
+class PNG_CHUNK_TYPE:
+    """PNG chunk type names."""
+
+    IHDR = "IHDR"
+    pHYs = "pHYs"
+    IEND = "IEND"
+
+
+class TIFF_FLD_TYPE:
+    """Tag codes for TIFF Image File Directory (IFD) entries."""
+
+    BYTE = 1
+    ASCII = 2
+    SHORT = 3
+    LONG = 4
+    RATIONAL = 5
+
+    field_type_names = {
+        1: "BYTE",
+        2: "ASCII char",
+        3: "SHORT",
+        4: "LONG",
+        5: "RATIONAL",
+    }
+
+
+TIFF_FLD = TIFF_FLD_TYPE
+
+
+class TIFF_TAG:
+    """Tag codes for TIFF Image File Directory (IFD) entries."""
+
+    IMAGE_WIDTH = 0x0100
+    IMAGE_LENGTH = 0x0101
+    X_RESOLUTION = 0x011A
+    Y_RESOLUTION = 0x011B
+    RESOLUTION_UNIT = 0x0128
+
+    tag_names = {
+        0x00FE: "NewSubfileType",
+        0x0100: "ImageWidth",
+        0x0101: "ImageLength",
+        0x0102: "BitsPerSample",
+        0x0103: "Compression",
+        0x0106: "PhotometricInterpretation",
+        0x010E: "ImageDescription",
+        0x010F: "Make",
+        0x0110: "Model",
+        0x0111: "StripOffsets",
+        0x0112: "Orientation",
+        0x0115: "SamplesPerPixel",
+        0x0117: "StripByteCounts",
+        0x011A: "XResolution",
+        0x011B: "YResolution",
+        0x011C: "PlanarConfiguration",
+        0x0128: "ResolutionUnit",
+        0x0131: "Software",
+        0x0132: "DateTime",
+        0x0213: "YCbCrPositioning",
+        0x8769: "ExifTag",
+        0x8825: "GPS IFD",
+        0xC4A5: "PrintImageMatching",
+    }

docx/image/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions specific the the image sub-package."""
+
+
+class InvalidImageStreamError(Exception):
+    """The recognized image stream appears to be corrupted."""
+
+
+class UnexpectedEndOfFileError(Exception):
+    """EOF was unexpectedly encountered while reading an image stream."""
+
+
+class UnrecognizedImageError(Exception):
+    """The provided image stream could not be recognized."""

docx/image/gif.py

@@ -0,0 +1,38 @@
+from struct import Struct
+
+from .constants import MIME_TYPE
+from .image import BaseImageHeader
+
+
+class Gif(BaseImageHeader):
+    """Image header parser for GIF images.
+
+    Note that the GIF format does not support resolution (DPI) information. Both
+    horizontal and vertical DPI default to 72.
+    """
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return |Gif| instance having header properties parsed from GIF image in
+        `stream`."""
+        px_width, px_height = cls._dimensions_from_stream(stream)
+        return cls(px_width, px_height, 72, 72)
+
+    @property
+    def content_type(self):
+        """MIME content type for this image, unconditionally `image/gif` for GIF
+        images."""
+        return MIME_TYPE.GIF
+
+    @property
+    def default_ext(self):
+        """Default filename extension, always 'gif' for GIF images."""
+        return "gif"
+
+    @classmethod
+    def _dimensions_from_stream(cls, stream):
+        stream.seek(6)
+        bytes_ = stream.read(4)
+        struct = Struct("<HH")
+        px_width, px_height = struct.unpack(bytes_)
+        return px_width, px_height