python-docx-oss 0.1.0__py3-none-any.whl

docx/image/png.py

@@ -0,0 +1,253 @@
+from .constants import MIME_TYPE, PNG_CHUNK_TYPE
+from .exceptions import InvalidImageStreamError
+from .helpers import BIG_ENDIAN, StreamReader
+from .image import BaseImageHeader
+
+
+class Png(BaseImageHeader):
+    """Image header parser for PNG images."""
+
+    @property
+    def content_type(self):
+        """MIME content type for this image, unconditionally `image/png` for PNG
+        images."""
+        return MIME_TYPE.PNG
+
+    @property
+    def default_ext(self):
+        """Default filename extension, always 'png' for PNG images."""
+        return "png"
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return a |Png| instance having header properties parsed from image in
+        `stream`."""
+        parser = _PngParser.parse(stream)
+
+        px_width = parser.px_width
+        px_height = parser.px_height
+        horz_dpi = parser.horz_dpi
+        vert_dpi = parser.vert_dpi
+
+        return cls(px_width, px_height, horz_dpi, vert_dpi)
+
+
+class _PngParser:
+    """Parses a PNG image stream to extract the image properties found in its chunks."""
+
+    def __init__(self, chunks):
+        super(_PngParser, self).__init__()
+        self._chunks = chunks
+
+    @classmethod
+    def parse(cls, stream):
+        """Return a |_PngParser| instance containing the header properties parsed from
+        the PNG image in `stream`."""
+        chunks = _Chunks.from_stream(stream)
+        return cls(chunks)
+
+    @property
+    def px_width(self):
+        """The number of pixels in each row of the image."""
+        IHDR = self._chunks.IHDR
+        return IHDR.px_width
+
+    @property
+    def px_height(self):
+        """The number of stacked rows of pixels in the image."""
+        IHDR = self._chunks.IHDR
+        return IHDR.px_height
+
+    @property
+    def horz_dpi(self):
+        """Integer dots per inch for the width of this image.
+
+        Defaults to 72 when not present in the file, as is often the case.
+        """
+        pHYs = self._chunks.pHYs
+        if pHYs is None:
+            return 72
+        return self._dpi(pHYs.units_specifier, pHYs.horz_px_per_unit)
+
+    @property
+    def vert_dpi(self):
+        """Integer dots per inch for the height of this image.
+
+        Defaults to 72 when not present in the file, as is often the case.
+        """
+        pHYs = self._chunks.pHYs
+        if pHYs is None:
+            return 72
+        return self._dpi(pHYs.units_specifier, pHYs.vert_px_per_unit)
+
+    @staticmethod
+    def _dpi(units_specifier, px_per_unit):
+        """Return dots per inch value calculated from `units_specifier` and
+        `px_per_unit`."""
+        if units_specifier == 1 and px_per_unit:
+            return int(round(px_per_unit * 0.0254))
+        return 72
+
+
+class _Chunks:
+    """Collection of the chunks parsed from a PNG image stream."""
+
+    def __init__(self, chunk_iterable):
+        super(_Chunks, self).__init__()
+        self._chunks = list(chunk_iterable)
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return a |_Chunks| instance containing the PNG chunks in `stream`."""
+        chunk_parser = _ChunkParser.from_stream(stream)
+        chunks = list(chunk_parser.iter_chunks())
+        return cls(chunks)
+
+    @property
+    def IHDR(self):
+        """IHDR chunk in PNG image."""
+        match = lambda chunk: chunk.type_name == PNG_CHUNK_TYPE.IHDR  # noqa
+        IHDR = self._find_first(match)
+        if IHDR is None:
+            raise InvalidImageStreamError("no IHDR chunk in PNG image")
+        return IHDR
+
+    @property
+    def pHYs(self):
+        """PHYs chunk in PNG image, or |None| if not present."""
+        match = lambda chunk: chunk.type_name == PNG_CHUNK_TYPE.pHYs  # noqa
+        return self._find_first(match)
+
+    def _find_first(self, match):
+        """Return first chunk in stream order returning True for function `match`."""
+        for chunk in self._chunks:
+            if match(chunk):
+                return chunk
+        return None
+
+
+class _ChunkParser:
+    """Extracts chunks from a PNG image stream."""
+
+    def __init__(self, stream_rdr):
+        super(_ChunkParser, self).__init__()
+        self._stream_rdr = stream_rdr
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return a |_ChunkParser| instance that can extract the chunks from the PNG
+        image in `stream`."""
+        stream_rdr = StreamReader(stream, BIG_ENDIAN)
+        return cls(stream_rdr)
+
+    def iter_chunks(self):
+        """Generate a |_Chunk| subclass instance for each chunk in this parser's PNG
+        stream, in the order encountered in the stream."""
+        for chunk_type, offset in self._iter_chunk_offsets():
+            chunk = _ChunkFactory(chunk_type, self._stream_rdr, offset)
+            yield chunk
+
+    def _iter_chunk_offsets(self):
+        """Generate a (chunk_type, chunk_offset) 2-tuple for each of the chunks in the
+        PNG image stream.
+
+        Iteration stops after the IEND chunk is returned.
+        """
+        chunk_offset = 8
+        while True:
+            chunk_data_len = self._stream_rdr.read_long(chunk_offset)
+            chunk_type = self._stream_rdr.read_str(4, chunk_offset, 4)
+            data_offset = chunk_offset + 8
+            yield chunk_type, data_offset
+            if chunk_type == "IEND":
+                break
+            # incr offset for chunk len long, chunk type, chunk data, and CRC
+            chunk_offset += 4 + 4 + chunk_data_len + 4
+
+
+def _ChunkFactory(chunk_type, stream_rdr, offset):
+    """Return a |_Chunk| subclass instance appropriate to `chunk_type` parsed from
+    `stream_rdr` at `offset`."""
+    chunk_cls_map = {
+        PNG_CHUNK_TYPE.IHDR: _IHDRChunk,
+        PNG_CHUNK_TYPE.pHYs: _pHYsChunk,
+    }
+    chunk_cls = chunk_cls_map.get(chunk_type, _Chunk)
+    return chunk_cls.from_offset(chunk_type, stream_rdr, offset)
+
+
+class _Chunk:
+    """Base class for specific chunk types.
+
+    Also serves as the default chunk type.
+    """
+
+    def __init__(self, chunk_type):
+        super(_Chunk, self).__init__()
+        self._chunk_type = chunk_type
+
+    @classmethod
+    def from_offset(cls, chunk_type, stream_rdr, offset):
+        """Return a default _Chunk instance that only knows its chunk type."""
+        return cls(chunk_type)
+
+    @property
+    def type_name(self):
+        """The chunk type name, e.g. 'IHDR', 'pHYs', etc."""
+        return self._chunk_type
+
+
+class _IHDRChunk(_Chunk):
+    """IHDR chunk, contains the image dimensions."""
+
+    def __init__(self, chunk_type, px_width, px_height):
+        super(_IHDRChunk, self).__init__(chunk_type)
+        self._px_width = px_width
+        self._px_height = px_height
+
+    @classmethod
+    def from_offset(cls, chunk_type, stream_rdr, offset):
+        """Return an _IHDRChunk instance containing the image dimensions extracted from
+        the IHDR chunk in `stream` at `offset`."""
+        px_width = stream_rdr.read_long(offset)
+        px_height = stream_rdr.read_long(offset, 4)
+        return cls(chunk_type, px_width, px_height)
+
+    @property
+    def px_width(self):
+        return self._px_width
+
+    @property
+    def px_height(self):
+        return self._px_height
+
+
+class _pHYsChunk(_Chunk):
+    """PYHs chunk, contains the image dpi information."""
+
+    def __init__(self, chunk_type, horz_px_per_unit, vert_px_per_unit, units_specifier):
+        super(_pHYsChunk, self).__init__(chunk_type)
+        self._horz_px_per_unit = horz_px_per_unit
+        self._vert_px_per_unit = vert_px_per_unit
+        self._units_specifier = units_specifier
+
+    @classmethod
+    def from_offset(cls, chunk_type, stream_rdr, offset):
+        """Return a _pHYsChunk instance containing the image resolution extracted from
+        the pHYs chunk in `stream` at `offset`."""
+        horz_px_per_unit = stream_rdr.read_long(offset)
+        vert_px_per_unit = stream_rdr.read_long(offset, 4)
+        units_specifier = stream_rdr.read_byte(offset, 8)
+        return cls(chunk_type, horz_px_per_unit, vert_px_per_unit, units_specifier)
+
+    @property
+    def horz_px_per_unit(self):
+        return self._horz_px_per_unit
+
+    @property
+    def vert_px_per_unit(self):
+        return self._vert_px_per_unit
+
+    @property
+    def units_specifier(self):
+        return self._units_specifier

docx/image/svg.py

@@ -0,0 +1,118 @@
+import re
+import xml.etree.ElementTree as ET
+
+from .constants import MIME_TYPE
+from .image import BaseImageHeader
+
+BASE_PX = 72
+
+
+class Svg(BaseImageHeader):
+    """
+    Image header parser for SVG images.
+    """
+
+    @classmethod
+    def from_stream(cls, stream):
+        """
+        Return |Svg| instance having header properties parsed from SVG image
+        in *stream*.
+        """
+        px_width, px_height = cls._dimensions_from_stream(stream)
+        return cls(px_width, px_height, BASE_PX, BASE_PX)
+
+    @property
+    def content_type(self):
+        """
+        MIME content type for this image, unconditionally `image/svg+xml` for
+        SVG images.
+        """
+        return MIME_TYPE.SVG
+
+    @property
+    def default_ext(self):
+        """
+        Default filename extension, always 'svg' for SVG images.
+        """
+        return "svg"
+
+    @classmethod
+    def _parse_svg_unit_value(cls, value_str: str) -> float:
+        """
+        Parse an SVG length value and return it in points (which are 1/72 of an inch).
+        Handles units like px, pt, cm, mm, in, pc.
+        """
+        if not value_str:
+            return 0.0
+
+        value_str = value_str.strip().lower()
+
+        # Regex to separate the numeric value from the unit, allowing for spaces
+        match = re.match(r"^(-?\d*\.?\d+)\s*([a-z%]*)$", value_str)
+        if not match:
+            # Handle case where there is no unit (treat as px, as per SVG spec)
+            try:
+                return float(value_str)
+            except ValueError:
+                return 0.0
+
+        value, unit = match.groups()
+        numeric_value = float(value)
+
+        # ---conversion factors to points (assuming 72 DPI, where 1pt = 1px)---
+        # This matches the existing behavior of the Svg class.
+        # 1 inch = BASE_PX points
+        # 1 cm = 1/2.54 inch = BASE_PX/2.54 points
+        # 1 mm = 1/25.4 inch = BASE_PX/25.4 points
+        # 1 pc = 12 points
+        # 1 px = 1 point (at BASE_PX DPI)
+
+        if unit in ("pt", "px", ""):
+            return numeric_value
+        elif unit == "in":
+            return numeric_value * float(BASE_PX)
+        elif unit == "pc":
+            return numeric_value * 12.0
+        elif unit == "cm":
+            return numeric_value * float(BASE_PX) / 2.54
+        elif unit == "mm":
+            return numeric_value * float(BASE_PX) / 25.4
+        # ---treat other units as px for now---
+        else:
+            return numeric_value
+
+    @classmethod
+    def _dimensions_from_stream(cls, stream):
+        stream.seek(0)
+        data = stream.read()
+        root = ET.fromstring(data)
+
+        width_str = root.attrib.get("width")
+        height_str = root.attrib.get("height")
+
+        if width_str and height_str:
+            width = round(cls._parse_svg_unit_value(width_str))
+            height = round(cls._parse_svg_unit_value(height_str))
+            return width, height
+
+        if root.attrib.get("viewBox"):
+            return cls._calculate_scaled_dimensions(root.attrib["viewBox"])
+
+        return 0, 0
+
+    @classmethod
+    def _calculate_scaled_dimensions(
+        cls, viewbox: str, base_px: int = BASE_PX
+    ) -> tuple[int, int]:
+        _, _, logical_width, logical_height = map(float, viewbox.split())
+
+        aspect_ratio = logical_width / logical_height
+
+        if aspect_ratio >= 1:
+            final_width = base_px
+            final_height = base_px / aspect_ratio
+        else:
+            final_height = base_px
+            final_width = base_px * aspect_ratio
+
+        return round(final_width), round(final_height)

docx/image/tiff.py

@@ -0,0 +1,289 @@
+from .constants import MIME_TYPE, TIFF_FLD, TIFF_TAG
+from .helpers import BIG_ENDIAN, LITTLE_ENDIAN, StreamReader
+from .image import BaseImageHeader
+
+
+class Tiff(BaseImageHeader):
+    """Image header parser for TIFF images.
+
+    Handles both big and little endian byte ordering.
+    """
+
+    @property
+    def content_type(self):
+        """Return the MIME type of this TIFF image, unconditionally the string
+        ``image/tiff``."""
+        return MIME_TYPE.TIFF
+
+    @property
+    def default_ext(self):
+        """Default filename extension, always 'tiff' for TIFF images."""
+        return "tiff"
+
+    @classmethod
+    def from_stream(cls, stream):
+        """Return a |Tiff| instance containing the properties of the TIFF image in
+        `stream`."""
+        parser = _TiffParser.parse(stream)
+
+        px_width = parser.px_width
+        px_height = parser.px_height
+        horz_dpi = parser.horz_dpi
+        vert_dpi = parser.vert_dpi
+
+        return cls(px_width, px_height, horz_dpi, vert_dpi)
+
+
+class _TiffParser:
+    """Parses a TIFF image stream to extract the image properties found in its main
+    image file directory (IFD)"""
+
+    def __init__(self, ifd_entries):
+        super(_TiffParser, self).__init__()
+        self._ifd_entries = ifd_entries
+
+    @classmethod
+    def parse(cls, stream):
+        """Return an instance of |_TiffParser| containing the properties parsed from the
+        TIFF image in `stream`."""
+        stream_rdr = cls._make_stream_reader(stream)
+        ifd0_offset = stream_rdr.read_long(4)
+        ifd_entries = _IfdEntries.from_stream(stream_rdr, ifd0_offset)
+        return cls(ifd_entries)
+
+    @property
+    def horz_dpi(self):
+        """The horizontal dots per inch value calculated from the XResolution and
+        ResolutionUnit tags of the IFD; defaults to 72 if those tags are not present."""
+        return self._dpi(TIFF_TAG.X_RESOLUTION)
+
+    @property
+    def vert_dpi(self):
+        """The vertical dots per inch value calculated from the XResolution and
+        ResolutionUnit tags of the IFD; defaults to 72 if those tags are not present."""
+        return self._dpi(TIFF_TAG.Y_RESOLUTION)
+
+    @property
+    def px_height(self):
+        """The number of stacked rows of pixels in the image, |None| if the IFD contains
+        no ``ImageLength`` tag, the expected case when the TIFF is embeded in an Exif
+        image."""
+        return self._ifd_entries.get(TIFF_TAG.IMAGE_LENGTH)
+
+    @property
+    def px_width(self):
+        """The number of pixels in each row in the image, |None| if the IFD contains no
+        ``ImageWidth`` tag, the expected case when the TIFF is embeded in an Exif
+        image."""
+        return self._ifd_entries.get(TIFF_TAG.IMAGE_WIDTH)
+
+    @classmethod
+    def _detect_endian(cls, stream):
+        """Return either BIG_ENDIAN or LITTLE_ENDIAN depending on the endian indicator
+        found in the TIFF `stream` header, either 'MM' or 'II'."""
+        stream.seek(0)
+        endian_str = stream.read(2)
+        return BIG_ENDIAN if endian_str == b"MM" else LITTLE_ENDIAN
+
+    def _dpi(self, resolution_tag):
+        """Return the dpi value calculated for `resolution_tag`, which can be either
+        TIFF_TAG.X_RESOLUTION or TIFF_TAG.Y_RESOLUTION.
+
+        The calculation is based on the values of both that tag and the
+        TIFF_TAG.RESOLUTION_UNIT tag in this parser's |_IfdEntries| instance.
+        """
+        ifd_entries = self._ifd_entries
+
+        if resolution_tag not in ifd_entries:
+            return 72
+
+        # resolution unit defaults to inches (2)
+        resolution_unit = ifd_entries.get(TIFF_TAG.RESOLUTION_UNIT, 2)
+
+        if resolution_unit == 1:  # aspect ratio only
+            return 72
+        # resolution_unit == 2 for inches, 3 for centimeters
+        units_per_inch = 1 if resolution_unit == 2 else 2.54
+        dots_per_unit = ifd_entries[resolution_tag]
+        return int(round(dots_per_unit * units_per_inch))
+
+    @classmethod
+    def _make_stream_reader(cls, stream):
+        """Return a |StreamReader| instance with wrapping `stream` and having "endian-
+        ness" determined by the 'MM' or 'II' indicator in the TIFF stream header."""
+        endian = cls._detect_endian(stream)
+        return StreamReader(stream, endian)
+
+
+class _IfdEntries:
+    """Image File Directory for a TIFF image, having mapping (dict) semantics allowing
+    "tag" values to be retrieved by tag code."""
+
+    def __init__(self, entries):
+        super(_IfdEntries, self).__init__()
+        self._entries = entries
+
+    def __contains__(self, key):
+        """Provides ``in`` operator, e.g. ``tag in ifd_entries``"""
+        return self._entries.__contains__(key)
+
+    def __getitem__(self, key):
+        """Provides indexed access, e.g. ``tag_value = ifd_entries[tag_code]``"""
+        return self._entries.__getitem__(key)
+
+    @classmethod
+    def from_stream(cls, stream, offset):
+        """Return a new |_IfdEntries| instance parsed from `stream` starting at
+        `offset`."""
+        ifd_parser = _IfdParser(stream, offset)
+        entries = {e.tag: e.value for e in ifd_parser.iter_entries()}
+        return cls(entries)
+
+    def get(self, tag_code, default=None):
+        """Return value of IFD entry having tag matching `tag_code`, or `default` if no
+        matching tag found."""
+        return self._entries.get(tag_code, default)
+
+
+class _IfdParser:
+    """Service object that knows how to extract directory entries from an Image File
+    Directory (IFD)"""
+
+    def __init__(self, stream_rdr, offset):
+        super(_IfdParser, self).__init__()
+        self._stream_rdr = stream_rdr
+        self._offset = offset
+
+    def iter_entries(self):
+        """Generate an |_IfdEntry| instance corresponding to each entry in the
+        directory."""
+        for idx in range(self._entry_count):
+            dir_entry_offset = self._offset + 2 + (idx * 12)
+            ifd_entry = _IfdEntryFactory(self._stream_rdr, dir_entry_offset)
+            yield ifd_entry
+
+    @property
+    def _entry_count(self):
+        """The count of directory entries, read from the top of the IFD header."""
+        return self._stream_rdr.read_short(self._offset)
+
+
+def _IfdEntryFactory(stream_rdr, offset):
+    """Return an |_IfdEntry| subclass instance containing the value of the directory
+    entry at `offset` in `stream_rdr`."""
+    ifd_entry_classes = {
+        TIFF_FLD.ASCII: _AsciiIfdEntry,
+        TIFF_FLD.SHORT: _ShortIfdEntry,
+        TIFF_FLD.LONG: _LongIfdEntry,
+        TIFF_FLD.RATIONAL: _RationalIfdEntry,
+    }
+    field_type = stream_rdr.read_short(offset, 2)
+    EntryCls = ifd_entry_classes.get(field_type, _IfdEntry)
+    return EntryCls.from_stream(stream_rdr, offset)
+
+
+class _IfdEntry:
+    """Base class for IFD entry classes.
+
+    Subclasses are differentiated by value type, e.g. ASCII, long int, etc.
+    """
+
+    def __init__(self, tag_code, value):
+        super(_IfdEntry, self).__init__()
+        self._tag_code = tag_code
+        self._value = value
+
+    @classmethod
+    def from_stream(cls, stream_rdr, offset):
+        """Return an |_IfdEntry| subclass instance containing the tag and value of the
+        tag parsed from `stream_rdr` at `offset`.
+
+        Note this method is common to all subclasses. Override the ``_parse_value()``
+        method to provide distinctive behavior based on field type.
+        """
+        tag_code = stream_rdr.read_short(offset, 0)
+        value_count = stream_rdr.read_long(offset, 4)
+        value_offset = stream_rdr.read_long(offset, 8)
+        value = cls._parse_value(stream_rdr, offset, value_count, value_offset)
+        return cls(tag_code, value)
+
+    @classmethod
+    def _parse_value(cls, stream_rdr, offset, value_count, value_offset):
+        """Return the value of this field parsed from `stream_rdr` at `offset`.
+
+        Intended to be overridden by subclasses.
+        """
+        return "UNIMPLEMENTED FIELD TYPE"  # pragma: no cover
+
+    @property
+    def tag(self):
+        """Short int code that identifies this IFD entry."""
+        return self._tag_code
+
+    @property
+    def value(self):
+        """Value of this tag, its type being dependent on the tag."""
+        return self._value
+
+
+class _AsciiIfdEntry(_IfdEntry):
+    """IFD entry having the form of a NULL-terminated ASCII string."""
+
+    @classmethod
+    def _parse_value(cls, stream_rdr, offset, value_count, value_offset):
+        """Return the ASCII string parsed from `stream_rdr` at `value_offset`.
+
+        The length of the string, including a terminating '\x00' (NUL) character, is in
+        `value_count`.
+        """
+        return stream_rdr.read_str(value_count - 1, value_offset)
+
+
+class _ShortIfdEntry(_IfdEntry):
+    """IFD entry expressed as a short (2-byte) integer."""
+
+    @classmethod
+    def _parse_value(cls, stream_rdr, offset, value_count, value_offset):
+        """Return the short int value contained in the `value_offset` field of this
+        entry.
+
+        Only supports single values at present.
+        """
+        if value_count == 1:
+            return stream_rdr.read_short(offset, 8)
+        else:  # pragma: no cover
+            return "Multi-value short integer NOT IMPLEMENTED"
+
+
+class _LongIfdEntry(_IfdEntry):
+    """IFD entry expressed as a long (4-byte) integer."""
+
+    @classmethod
+    def _parse_value(cls, stream_rdr, offset, value_count, value_offset):
+        """Return the long int value contained in the `value_offset` field of this
+        entry.
+
+        Only supports single values at present.
+        """
+        if value_count == 1:
+            return stream_rdr.read_long(offset, 8)
+        else:  # pragma: no cover
+            return "Multi-value long integer NOT IMPLEMENTED"
+
+
+class _RationalIfdEntry(_IfdEntry):
+    """IFD entry expressed as a numerator, denominator pair."""
+
+    @classmethod
+    def _parse_value(cls, stream_rdr, offset, value_count, value_offset):
+        """Return the rational (numerator / denominator) value at `value_offset` in
+        `stream_rdr` as a floating-point number.
+
+        Only supports single values at present.
+        """
+        if value_count == 1:
+            numerator = stream_rdr.read_long(value_offset)
+            denominator = stream_rdr.read_long(value_offset, 4)
+            return numerator / denominator
+        else:  # pragma: no cover
+            return "Multi-value Rational NOT IMPLEMENTED"