ImageOps.autocontrast typing doesn't permit a tuple value for cutoff, even though docs say it should be allowed

[pa-tna]

What did you do?

from PIL import Image, ImageOps

img: Image.Image = Image.open("in.png")
img = ImageOps.autocontrast(img, (5, 45))
img = img.convert('1', dither=Image.Dither.NONE)
img.save("out.png")

in.png:

What did you expect to happen?

mypy would validate the above code snippet as containing no typing errors—the documentation for ImageOps.autocontrast says that cutoff can be a number or a tuple of length 2.

What actually happened?

error: Argument 2 to "autocontrast" has incompatible type "tuple[int, int]"; expected "int" [arg-type]

What are your OS, Python and Pillow versions?

• OS: Windows 10 version 22H2 (OS Build 19045.3930)
• Python: 3.10.11
• Pillow: 10.2.0

[Yay295]

ImageOps.autocontrast doesn't currently have any typing. It's probably getting it wrong because it has a default value.

Pillow/src/PIL/ImageOps.py

Line 68 in 5bd8fd1

def autocontrast(image, cutoff=0, ignore=None, mask=None, preserve_tone=False):

[hugovk]

Do you have types-Pillow installed?

Typeshed has only int there:

https://github.com/python/typeshed/blob/994d22bfbb542956be24580323d5b4aeef822c77/stubs/Pillow/PIL/ImageOps.pyi#L14-L16

[pa-tna]

Yes, I do have types-Pillow installed. I can see that Typeshed is the appropriate place to resolve this issue.

It looks like cutoff should allow an int, float or tuple[int | float, int | float] value. Does that seem right? If so I can open an issue or PR there instead.

[radarhere]

I've created PR #7786 to add a type hint to cutoff of float | tuple[float, float], as https://peps.python.org/pep-0484/#the-numeric-tower

when an argument is annotated as having type float, an argument of type int is acceptable

However, yes, if you're using types-Pillow, you will need to make a change elsewhere.

[radarhere]

You might also be interested to know that the tuple behaviour was added in Pillow 8.0.0 with #4749

[radarhere]

python/typeshed#11408 has been merged to update types-Pillow.

[radarhere]

python/typeshed#11409 was later merged to change the type hints to allow floats as well.

[radarhere]

You might be interested to know that typeshed's Pillow stubs have been removed, now that Pillow has its own type hints.