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

docx/image/helpers.py

@@ -0,0 +1,86 @@
+from struct import Struct
+
+from .exceptions import UnexpectedEndOfFileError
+
+BIG_ENDIAN = ">"
+LITTLE_ENDIAN = "<"
+
+
+class StreamReader:
+    """Wraps a file-like object to provide access to structured data from a binary file.
+
+    Byte-order is configurable. `base_offset` is added to any base value provided to
+    calculate actual location for reads.
+    """
+
+    def __init__(self, stream, byte_order, base_offset=0):
+        super(StreamReader, self).__init__()
+        self._stream = stream
+        self._byte_order = LITTLE_ENDIAN if byte_order == LITTLE_ENDIAN else BIG_ENDIAN
+        self._base_offset = base_offset
+
+    def read(self, count):
+        """Allow pass-through read() call."""
+        return self._stream.read(count)
+
+    def read_byte(self, base, offset=0):
+        """Return the int value of the byte at the file position defined by
+        self._base_offset + `base` + `offset`.
+
+        If `base` is None, the byte is read from the current position in the stream.
+        """
+        fmt = "B"
+        return self._read_int(fmt, base, offset)
+
+    def read_long(self, base, offset=0):
+        """Return the int value of the four bytes at the file position defined by
+        self._base_offset + `base` + `offset`.
+
+        If `base` is None, the long is read from the current position in the stream. The
+        endian setting of this instance is used to interpret the byte layout of the
+        long.
+        """
+        fmt = "<L" if self._byte_order is LITTLE_ENDIAN else ">L"
+        return self._read_int(fmt, base, offset)
+
+    def read_short(self, base, offset=0):
+        """Return the int value of the two bytes at the file position determined by
+        `base` and `offset`, similarly to ``read_long()`` above."""
+        fmt = b"<H" if self._byte_order is LITTLE_ENDIAN else b">H"
+        return self._read_int(fmt, base, offset)
+
+    def read_str(self, char_count, base, offset=0):
+        """Return a string containing the `char_count` bytes at the file position
+        determined by self._base_offset + `base` + `offset`."""
+
+        def str_struct(char_count):
+            format_ = "%ds" % char_count
+            return Struct(format_)
+
+        struct = str_struct(char_count)
+        chars = self._unpack_item(struct, base, offset)
+        unicode_str = chars.decode("UTF-8")
+        return unicode_str
+
+    def seek(self, base, offset=0):
+        location = self._base_offset + base + offset
+        self._stream.seek(location)
+
+    def tell(self):
+        """Allow pass-through tell() call."""
+        return self._stream.tell()
+
+    def _read_bytes(self, byte_count, base, offset):
+        self.seek(base, offset)
+        bytes_ = self._stream.read(byte_count)
+        if len(bytes_) < byte_count:
+            raise UnexpectedEndOfFileError
+        return bytes_
+
+    def _read_int(self, fmt, base, offset):
+        struct = Struct(fmt)
+        return self._unpack_item(struct, base, offset)
+
+    def _unpack_item(self, struct, base, offset):
+        bytes_ = self._read_bytes(struct.size, base, offset)
+        return struct.unpack(bytes_)[0]

docx/image/image.py

@@ -0,0 +1,234 @@
+"""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 __future__ import annotations
+
+import hashlib
+import io
+import os
+from typing import IO, Tuple
+
+from docx.image.exceptions import UnrecognizedImageError
+from docx.shared import Emu, Inches, Length, lazyproperty
+
+
+class Image:
+    """Graphical image stream such as JPEG, PNG, or GIF with properties and methods
+    required by ImagePart."""
+
+    def __init__(self, blob: bytes, filename: str, image_header: BaseImageHeader):
+        super(Image, self).__init__()
+        self._blob = blob
+        self._filename = filename
+        self._image_header = image_header
+
+    @classmethod
+    def from_blob(cls, blob: bytes) -> Image:
+        """Return a new |Image| subclass instance parsed from the image binary contained
+        in `blob`."""
+        stream = io.BytesIO(blob)
+        return cls._from_stream(stream, blob)
+
+    @classmethod
+    def from_file(cls, image_descriptor: str | IO[bytes]):
+        """Return a new |Image| subclass instance loaded from the image file identified
+        by `image_descriptor`, a path or file-like object."""
+        if isinstance(image_descriptor, str):
+            path = image_descriptor
+            with open(path, "rb") as f:
+                blob = f.read()
+                stream = io.BytesIO(blob)
+            filename = os.path.basename(path)
+        else:
+            stream = image_descriptor
+            stream.seek(0)
+            blob = stream.read()
+            filename = None
+        return cls._from_stream(stream, blob, filename)
+
+    @property
+    def blob(self):
+        """The bytes of the image 'file'."""
+        return self._blob
+
+    @property
+    def content_type(self) -> str:
+        """MIME content type for this image, e.g. ``'image/jpeg'`` for a JPEG image."""
+        return self._image_header.content_type
+
+    @lazyproperty
+    def ext(self):
+        """The file extension for the image.
+
+        If an actual one is available from a load filename it is used. Otherwise a
+        canonical extension is assigned based on the content type. Does not contain the
+        leading period, e.g. 'jpg', not '.jpg'.
+        """
+        return os.path.splitext(self._filename)[1][1:]
+
+    @property
+    def filename(self):
+        """Original image file name, if loaded from disk, or a generic filename if
+        loaded from an anonymous stream."""
+        return self._filename
+
+    @property
+    def px_width(self) -> int:
+        """The horizontal pixel dimension of the image."""
+        return self._image_header.px_width
+
+    @property
+    def px_height(self) -> int:
+        """The vertical pixel dimension of the image."""
+        return self._image_header.px_height
+
+    @property
+    def horz_dpi(self) -> int:
+        """Integer dots per inch for the width of this image.
+
+        Defaults to 72 when not present in the file, as is often the case.
+        """
+        return self._image_header.horz_dpi
+
+    @property
+    def vert_dpi(self) -> int:
+        """Integer dots per inch for the height of this image.
+
+        Defaults to 72 when not present in the file, as is often the case.
+        """
+        return self._image_header.vert_dpi
+
+    @property
+    def width(self) -> Inches:
+        """A |Length| value representing the native width of the image, calculated from
+        the values of `px_width` and `horz_dpi`."""
+        return Inches(self.px_width / self.horz_dpi)
+
+    @property
+    def height(self) -> Inches:
+        """A |Length| value representing the native height of the image, calculated from
+        the values of `px_height` and `vert_dpi`."""
+        return Inches(self.px_height / self.vert_dpi)
+
+    def scaled_dimensions(
+        self, width: int | Length | None = None, height: int | Length | None = None
+    ) -> Tuple[Length, Length]:
+        """(cx, cy) pair representing scaled dimensions of this image.
+
+        The native dimensions of the image are scaled by applying the following rules to
+        the `width` and `height` arguments.
+
+        * If both `width` and `height` are specified, the return value is (`width`,
+        `height`); no scaling is performed.
+        * 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.
+        * If both `width` and `height` are |None|, the native dimensions are returned.
+
+        The native dimensions are calculated using the dots-per-inch (dpi) value
+        embedded in the image, defaulting to 72 dpi if no value is specified, as is
+        often the case. The returned values are both |Length| objects.
+        """
+        if width is None and height is None:
+            return self.width, self.height
+
+        if width is None:
+            assert height is not None
+            scaling_factor = float(height) / float(self.height)
+            width = round(self.width * scaling_factor)
+
+        if height is None:
+            scaling_factor = float(width) / float(self.width)
+            height = round(self.height * scaling_factor)
+
+        return Emu(width), Emu(height)
+
+    @lazyproperty
+    def sha1(self):
+        """SHA1 hash digest of the image blob."""
+        return hashlib.sha1(self._blob).hexdigest()
+
+    @classmethod
+    def _from_stream(
+        cls,
+        stream: IO[bytes],
+        blob: bytes,
+        filename: str | None = None,
+    ) -> Image:
+        """Return an instance of the |Image| subclass corresponding to the format of the
+        image in `stream`."""
+        image_header = _ImageHeaderFactory(stream)
+        if filename is None:
+            filename = "image.%s" % image_header.default_ext
+        return cls(blob, filename, image_header)
+
+
+def _ImageHeaderFactory(stream: IO[bytes]):
+    """A |BaseImageHeader| subclass instance that can parse headers of image in `stream`."""
+    from docx.image import SIGNATURES
+
+    def read_32(stream: IO[bytes]):
+        stream.seek(0)
+        return stream.read(32)
+
+    header = read_32(stream)
+    for cls, offset, signature_bytes in SIGNATURES:
+        end = offset + len(signature_bytes)
+        found_bytes = header[offset:end]
+        if found_bytes == signature_bytes:
+            return cls.from_stream(stream)
+    raise UnrecognizedImageError
+
+
+class BaseImageHeader:
+    """Base class for image header subclasses like |Jpeg| and |Tiff|."""
+
+    def __init__(self, px_width: int, px_height: int, horz_dpi: int, vert_dpi: int):
+        self._px_width = px_width
+        self._px_height = px_height
+        self._horz_dpi = horz_dpi
+        self._vert_dpi = vert_dpi
+
+    @property
+    def content_type(self) -> str:
+        """Abstract property definition, must be implemented by all subclasses."""
+        msg = "content_type property must be implemented by all subclasses of BaseImageHeader"
+        raise NotImplementedError(msg)
+
+    @property
+    def default_ext(self) -> str:
+        """Default filename extension for images of this type.
+
+        An abstract property definition, must be implemented by all subclasses.
+        """
+        raise NotImplementedError(
+            "default_ext property must be implemented by all subclasses of BaseImageHeader"
+        )
+
+    @property
+    def px_width(self):
+        """The horizontal pixel dimension of the image."""
+        return self._px_width
+
+    @property
+    def px_height(self):
+        """The vertical pixel dimension of the image."""
+        return self._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.
+        """
+        return self._horz_dpi
+
+    @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.
+        """
+        return self._vert_dpi