two version of R2R are hereHEADmaster

1 files changed, 234 insertions, 0 deletions

diff --git a/.venv/lib/python3.12/site-packages/docx/image/image.py b/.venv/lib/python3.12/site-packages/docx/image/image.py
new file mode 100644
index 00000000..0022b5b4
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/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