pillow 12.3.0: Normalize EXIF orientation with Pillow 12.3.0 without mistaking the in-place API's None return for the transformed image.

# Pillow EXIF transpose contract

`ImageOps.exif_transpose` has two deliberately different ownership modes. The
default call returns a new image, while `in_place=True` mutates the input and
returns `None`. In both modes, a handled EXIF Orientation value is removed so
that downstream software does not rotate the pixels a second time.

This contract builds an RGB image and its EXIF bytes entirely in memory. Using
Orientation 6 makes both the dimension swap and the exact clockwise pixel
mapping observable without filesystem fixtures or lossy JPEG encoding.

{"case":{"believed":"ImageOps.exif_transpose always returns the transformed image and accepts in_place as a positional argument.","caseId":"case:sha256:f1f2db3e57984b0c6f1fbaf071d1e0f3df0f53aec6de21c1c4147004426161eb","contract":["The default ImageOps.exif_transpose call returns a distinct transformed copy, removes EXIF Orientation from the copy, and leaves the source image unchanged.","ImageOps.exif_transpose(..., in_place=True) mutates the source pixels and dimensions, removes EXIF Orientation, and returns None rather than the image.","The in_place parameter is keyword-only; passing it positionally raises TypeError.","EXIF Orientation 6 maps a 3-by-2 image to a 2-by-3 clockwise rotation with deterministic pixel order."],"goal":"Normalize EXIF orientation with Pillow 12.3.0 without mistaking the in-place API's None return for the transformed image.","kind":"HOW","packages":["pkg:pypi/pillow@12.3.0"],"schemaVersion":1,"symbols":["PIL.Image.new","PIL.Image.Exif","PIL.ImageOps.exif_transpose","PIL.ExifTags.Base.Orientation","PIL.Image.Transpose.ROTATE_270"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pillow@12.3.0"],"schemaVersion":1,"symbols":["PIL.Image.new","PIL.Image.Exif","PIL.ImageOps.exif_transpose","PIL.ExifTags.Base.Orientation","PIL.Image.Transpose.ROTATE_270"],"verifierAdapter":"python@1"}

Pillow==12.3.0

Pillow==12.3.0

import unittest

import PIL
from PIL import ExifTags, Image, ImageOps


ORIENTATION = ExifTags.Base.Orientation
SOURCE_PIXELS = [
    (1, 0, 0),
    (2, 0, 0),
    (3, 0, 0),
    (4, 0, 0),
    (5, 0, 0),
    (6, 0, 0),
]
ROTATED_PIXELS = [
    (4, 0, 0),
    (1, 0, 0),
    (5, 0, 0),
    (2, 0, 0),
    (6, 0, 0),
    (3, 0, 0),
]


def oriented_image() -> Image.Image:
    image = Image.new("RGB", (3, 2))
    image.putdata(SOURCE_PIXELS)
    exif = Image.Exif()
    exif[ORIENTATION] = 6
    image.info["exif"] = exif.tobytes()
    return image


class ExifTransposeContract(unittest.TestCase):
    def test_contract_runs_against_exact_pillow_release(self) -> None:
        self.assertEqual(PIL.__version__, "12.3.0")
        self.assertTrue(Image.core.__file__.endswith((".so", ".pyd")))

    def test_default_returns_normalized_copy_and_preserves_source(self) -> None:
        source = oriented_image()

        normalized = ImageOps.exif_transpose(source)

        self.assertIsNot(normalized, source)
        self.assertEqual(normalized.size, (2, 3))
        self.assertEqual(list(normalized.getdata()), ROTATED_PIXELS)
        self.assertNotIn(ORIENTATION, normalized.getexif())
        self.assertEqual(source.size, (3, 2))
        self.assertEqual(list(source.getdata()), SOURCE_PIXELS)
        self.assertEqual(source.getexif()[ORIENTATION], 6)

    def test_in_place_mutates_source_and_returns_none(self) -> None:
        source = oriented_image()

        result = ImageOps.exif_transpose(source, in_place=True)

        self.assertIsNone(result)
        self.assertEqual(source.size, (2, 3))
        self.assertEqual(list(source.getdata()), ROTATED_PIXELS)
        self.assertNotIn(ORIENTATION, source.getexif())

    def test_in_place_is_keyword_only(self) -> None:
        with self.assertRaises(TypeError):
            ImageOps.exif_transpose(oriented_image(), True)  # type: ignore[misc]


if __name__ == "__main__":
    unittest.main()