Fix #3515 by preserving images quality by default

Author: Lucas-C

Makefile

@@ -26,4 +26,4 @@ mypy:
 	mypy pypdf --ignore-missing-imports --check-untyped --strict
 
 ruff:
-	ruff check pypdf tests make_release.py
+	ruff check --fix pypdf tests make_release.py

pypdf/_page.py

@@ -387,6 +387,8 @@ def replace(self, new_image: Image, **kwargs: Any) -> None:
         if not isinstance(new_image, Image):
             raise TypeError("new_image shall be a PIL Image")
         b = BytesIO()
+        if "quality" not in kwargs:
+            kwargs["quality"] = "keep"
         new_image.save(b, "PDF", **kwargs)
         reader = PdfReader(b)
         assert reader.pages[0].images[0].indirect_reference is not None
@@ -398,7 +400,8 @@ def replace(self, new_image: Image, **kwargs: Any) -> None:
         ).indirect_reference = self.indirect_reference
         # change the object attributes
         extension, byte_stream, img = _xobj_to_image(
-            cast(DictionaryObject, self.indirect_reference.get_object())
+            cast(DictionaryObject, self.indirect_reference.get_object()),
+            pil_params=kwargs,
         )
         assert extension is not None
         self.name = self.name[: self.name.rfind(".")] + extension

pypdf/filters.py

@@ -791,15 +791,20 @@ def decode_stream_data(stream: Any) -> bytes:
     return data
 
 
-def _xobj_to_image(x_object: dict[str, Any]) -> tuple[Optional[str], bytes, Any]:
+def _xobj_to_image(
+        x_object: dict[str, Any],
+        pil_params: Union[dict[str, Any], None] = None
+    ) -> tuple[Optional[str], bytes, Any]:
     """
     Users need to have the pillow package installed.
 
     It's unclear if pypdf will keep this function here, hence it's private.
     It might get removed at any point.
 
     Args:
-      x_object:
+        x_object:
+        pil_params: parameters provided to Pillow Image.save() method,
+            cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
 
     Returns:
         Tuple[file extension, bytes, PIL.Image.Image]
@@ -846,6 +851,9 @@ def _apply_alpha(
                 extension = ".png"
         return img, extension, image_format
 
+    if pil_params is None:
+        pil_params = {}
+
     # For error reporting
     obj_as_text = (
         x_object.indirect_reference.__repr__()
@@ -905,6 +913,8 @@ def _apply_alpha(
         except UnidentifiedImageError:
             img = _extended_image_frombytes(mode, size, data)
     elif lfilters == FT.DCT_DECODE:
+        if "quality" not in pil_params:
+            pil_params["quality"] = "keep"
         img, image_format, extension = Image.open(BytesIO(data)), "JPEG", ".jpg"
         # invert_color kept unchanged
     elif lfilters == FT.JPX_DECODE:
@@ -950,7 +960,7 @@ def _apply_alpha(
     # Save image to bytes
     img_byte_arr = BytesIO()
     try:
-        img.save(img_byte_arr, format=image_format)
+        img.save(img_byte_arr, format=image_format, **pil_params)
     except OSError:  # pragma: no cover  # covered with pillow 10.3
         # in case of we convert to RGBA and then to PNG
         img1 = img.convert("RGBA")

pypdf/generic/_data_structures.py

@@ -1046,10 +1046,14 @@ def flate_encode(self, level: int = -1) -> "EncodedStreamObject":
         retval._data = FlateDecode.encode(self._data, level)
         return retval
 
-    def decode_as_image(self) -> Any:
+    def decode_as_image(self, pil_params: Union[dict[str, Any], None] = None) -> Any:
         """
         Try to decode the stream object as an image
 
+        Args:
+            pil_params: parameters provided to Pillow Image.save() method,
+                cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
+
         Returns:
             a PIL image if proper decoding has been found
         Raises:
@@ -1066,7 +1070,7 @@ def decode_as_image(self) -> Any:
             except AttributeError:
                 msg = f"{self.__repr__()} object does not seem to be an Image"  # pragma: no cover
             logger_warning(msg, __name__)
-        extension, _, img = _xobj_to_image(self)
+        extension, _, img = _xobj_to_image(self, pil_params)
         if extension is None:
             return None  # pragma: no cover
         return img