Add type hints support (#355) by JoshCLWren · Pull Request #564 · libvips/pyvips

JoshCLWren · 2025-12-25T19:04:33Z

Closes #355

This PR adds PEP 561 type stubs for pyvips, enabling IDE autocomplete and type checking with mypy.

Changes

Add pyvips/__init__.pyi - Type stubs for all Image operations (300+ methods)
Add pyvips/generate_type_stubs.py - Script to regenerate stubs from libvips introspection
Add tests/test_type_hints.py - Test verifying type stubs work correctly
Update README.rst with type checking section
Add mypy check to CI workflow

Design Decisions

Type stubs are generated rather than handwritten because:

pyvips is a binding around libvips C library, which evolves independently
libvips has 300+ operations with complex signatures
New operations are added to libvips frequently
Generation uses same introspection as existing doc/enum generation
Ensures stubs stay synchronized with available operations

This follows the existing pattern used for:

Enum generation (examples/gen-enums.py)
Documentation generation (pyvips.Operation.generate_sphinx_all())

Features

✅ Complete coverage of Image methods via introspection
✅ No use of Any - specific Union types instead
✅ Supports both string and enum values for enum parameters
✅ Python keyword escaping (e.g., in_ for in parameter)
✅ Proper typing for optional outputs with dictionaries
✅ CI integration to validate stubs
✅ Zero runtime overhead (stubs only used by type checkers)

Usage

Users can now type check pyvips code:

pip install mypy
mypy your_script.py

Regenerate stubs after libvips updates:

python pyvips/generate_type_stubs.py

Testing

All existing tests pass (48 passed, 7 skipped)
New test_type_hints.py added
Mypy validation passes

Adds PEP 561 type stubs for pyvips, enabling IDE autocomplete and type checking with mypy. - Add pyvips/__init__.pyi with type stubs for 300+ Image operations - Add generate_type_stubs.py script using introspection (follows existing enum/doc pattern) - Add test_type_hints.py with mypy validation - Update README with type checking documentation - Add mypy check to CI workflow Type stubs are generated to handle libvips's 300+ operations and frequent updates. Zero runtime overhead, full type coverage.

jcupitt · 2025-12-26T10:20:48Z

This is great @JoshCLWren!

I'm on holiday right now, but I'll read this carefully when I get home again.

jcupitt

Other:

we need a line in the changelog, and please credit yourself for doing this nice work
generate_type_stubs.py needs to be set executable
does the type stub generator need to be in pyvips/? it's something for maintainers, so I'd be inclined to put it in examples/. The doc generator is in pyvips/ because it's used for help() output
perhaps we could run mypy on the demo scripts in examples/ as part of CI? but it'll need eg. a hint for image * [1, 2, 3] first

jcupitt · 2025-12-28T12:00:32Z

pyvips/generate_type_stubs.py

+    stub += """
+
+    # Operator overloads
+    def __add__(self, other: Union[Image, float, int]) -> Image: ...


You can have arrays of float and int too, eg. a + [1, 2, 3] adds 1 to band 0, 2 to band 1, 3 to band 2.

jcupitt · 2025-12-28T12:13:17Z

examples/generate_type_stubs.py

+    def __call__(self, x: int, y: int) -> List[float]: ...
+    def __repr__(self) -> str: ...
+
+


There are a set of hand-written bindings too, perhaps some of them could have type hints?

Easy: image.floor() etc.

Medium: bandjoin, bandsplit, composite etc.

Horrible: ifthenelse.

…erator overloads - Add type hints for ifthenelse, composite, floor, ceil, rint, bandsplit, bandjoin, bandrank, hasalpha, get_page_height - Enhance operator overloads to support List[float] and List[int] operands - Move generate_type_stubs.py from pyvips/ to examples/ for better maintainability - Add CI mypy checks for examples/affine.py and examples/convolve.py - Update documentation references for type stub generation path

jcupitt · 2025-12-28T15:36:16Z

pyvips/__init__.pyi

    @staticmethod
-    def new_from_list(array: List[List[float]], scale: float =1.0, offset: float = 0.0) -> Image: ...
+    def new_from_list(
+        array: List[List[float]], scale: float = 1.0, offset: float = 0.0


I think this can also be List[List[int]]

jcupitt · 2025-12-28T15:43:21Z

examples/generate_type_stubs.py

+    enum_classes = "\n".join([f"class {name}: ..." for name in enum_names])
+
+    stub = f'''"""Type stubs for pyvips.
+


Add:

# flake8: noqa: E501

to stop flake8 moaning about long lines in the generated output.

jcupitt · 2025-12-28T15:44:10Z

examples/generate_type_stubs.py

+"""
+
+import typing
+from typing import Any, Optional, Union


You don't use any of these (I think).

jcupitt · 2025-12-28T15:44:42Z

examples/generate_type_stubs.py

+    type_map,
+    type_from_name,
+    nickname_find,
+    at_least_libvips,


jcupitt · 2025-12-28T15:45:11Z

examples/generate_type_stubs.py

+    nickname_find,
+    at_least_libvips,
+)
+from pyvips import ffi, Error, _to_bytes, _to_string


_to_byes, _to_string unused

jcupitt · 2025-12-28T16:13:45Z

examples/generate_type_stubs.py

+    import os
+
+    # Script is in examples/, need to go up one level to find pyvips/
+    stub_file = os.path.join(os.path.dirname(__file__), "..", "pyvips", "__init__.pyi")


I'm not sure we need this -- just generate __init__.pyi in the current directory and let the user know. Or just print to stdout (the safest).

jcupitt · 2025-12-28T16:18:42Z

examples/generate_type_stubs.py

+    """Generate type signature for an operation method."""
+    intro = Introspect.get(operation_name)
+
+    if (intro.flags & 4) != 0:  # _OPERATION_DEPRECATED


Is this correct? VipsOperationFlags uses 8 for VipsOperationFlags. I think you're removed all uncacheable operations instead.

jcupitt · 2025-12-28T16:22:08Z

examples/generate_type_stubs.py

+
+    # Return type
+    output_types = [
+        gtype_to_python_type(intro.details[name]["type"])


no newline before this

jcupitt · 2025-12-28T16:25:51Z

examples/generate_type_stubs.py

+
+    # Optional output dicts can contain any metadata value type
+    if len(intro.doc_optional_output) > 0:
+        dict_value_type = (


We don't need the brackets

jcupitt · 2025-12-28T16:38:57Z

examples/generate_type_stubs.py

+    return "\n".join([sig for _, sig in all_names])
+
+
+def get_all_enum_names() -> list[str]:


I suppose we should handle flags as well as enums, but perhaps that can wait for another PR.

gen-enums has this code as well, of course, perhaps it should be moved into Introspect

jcupitt · 2025-12-28T16:41:16Z

Sorry, there are a lot of comments. I don't know how much time you have -- we could merge and share the work of fixups in later PRs, if you like.

jcupitt · 2025-12-28T16:46:20Z

Oh, I just saw cdisplayagain, nice!

You have:

The project requires pyvips for fast image processing. Install the libvips library via your package manager:

Another possible solution is:

$ pip install pyvips[binary]

And it should download and use a libvips binary appropriate for your system. It might be a little easier for your users.

JoshCLWren · 2025-12-28T18:26:35Z

Sorry, there are a lot of comments. I don't know how much time you have -- we could merge and share the work of fixups in later PRs, if you like.

No worries! Thanks for the feedback. I'll get on it this afternoon/evening.

JoshCLWren · 2025-12-28T18:27:29Z

Oh, I just saw cdisplayagain, nice!

You have:

The project requires pyvips for fast image processing. Install the libvips library via your package manager:

Another possible solution is:
$ pip install pyvips[binary]
And it should download and use a libvips binary appropriate for your system. It might be a little easier for your users.

Good call, I think that'll help a lot.

…precated operations Changed hardcoded value 4 (NOCACHE) to use _OPERATION_DEPRECATED constant (8). This fixes incorrect filtering that was excluding uncacheable operations instead of deprecated ones.

…, add flake8 noqa

- Add SourceCustom class with on_read() and on_seek() methods - Add Source.new_from_descriptor() and Target.new_to_descriptor() static methods - Add pyvips.call() function for calling libvips operations - Add erode() and dilate() methods to Image class stub - Add explicit enum attributes for Direction and Align (HORIZONTAL, VERTICAL, LOW, CENTRE, HIGH) - Fix try7.py to use .format instead of non-existent .bandfmt attribute - Add type: ignore comments for Union type narrowing issues in 7 example files - All 35 example files now pass mypy type checking - Type stub file passes mypy with 0 errors

- Update version.py to 3.2.0 - Update CHANGELOG.rst with version 3.2.0 entry - Update doc/conf.py to version 3.2.0 - Expand CI mypy checks to include more example scripts

Match operator overload signatures which already support int and List[int] types. Ensures type consistency across the Image API.

- Revert examples/*.py to origin/master (remove type: ignore comments that caused flake8 E501 errors) - Revert doc/conf.py quote-style changes back to single quotes - Keep only version bump (3.1 -> 3.2, 3.1.1 -> 3.2.0) - Fix remaining line-length issues in doc/conf.py

mypy 1.19+ introduced a dependency on the librt module which is not available on PyPy 3.9, causing ModuleNotFoundError during type checking. This pins mypy to version 1.18.x which works across all Python versions in the CI matrix.

jcupitt · 2026-01-20T19:20:17Z

Sorry for the pause. Let's merge!

Thank you again for doing this work, @JoshCLWren.

jcupitt reviewed Dec 28, 2025

View reviewed changes

JoshCLWren added 4 commits December 28, 2025 08:45

Update CHANGELOG credit to JoshCLWren

21a345a

Add type hints for composite and ifthenelse hand-written bindings

7091264

Expand mypy type checking to more example scripts

d823939

JoshCLWren mentioned this pull request Dec 28, 2025

Update test coverage to 96% and fix test suite crash JoshCLWren/cdisplayagain#34

Merged

jcupitt reviewed Dec 28, 2025

View reviewed changes

JoshCLWren added 8 commits December 28, 2025 15:46

Fix operation filtering in type stub generator to correctly filter de…

21a20d6

…precated operations Changed hardcoded value 4 (NOCACHE) to use _OPERATION_DEPRECATED constant (8). This fixes incorrect filtering that was excluding uncacheable operations instead of deprecated ones.

Clean up type stub generator: remove unused imports, extra blank line…

97ebaf5

…, add flake8 noqa

Update version to 3.2.0 and update CI

a665ba4

- Update version.py to 3.2.0 - Update CHANGELOG.rst with version 3.2.0 entry - Update doc/conf.py to version 3.2.0 - Expand CI mypy checks to include more example scripts

Fix new_from_image type annotation to include int and List[int] support

9ee133c

Match operator overload signatures which already support int and List[int] types. Ensures type consistency across the Image API.

Fix doc/conf.py syntax and line-length errors

b3c7b41

pin mypy to <1.19 for PyPy 3.9 compatibility

41902a3

mypy 1.19+ introduced a dependency on the librt module which is not available on PyPy 3.9, causing ModuleNotFoundError during type checking. This pins mypy to version 1.18.x which works across all Python versions in the CI matrix.

jcupitt merged commit e855f6c into libvips:master Jan 20, 2026
6 checks passed

		def __call__(self, x: int, y: int) -> List[float]: ...
		def __repr__(self) -> str: ...

		enum_classes = "\n".join([f"class {name}: ..." for name in enum_names])

		stub = f'''"""Type stubs for pyvips.

		return "\n".join([sig for _, sig in all_names])


		def get_all_enum_names() -> list[str]:

Conversation

JoshCLWren commented Dec 25, 2025

Changes

Design Decisions

Features

Usage

Testing

Uh oh!

jcupitt commented Dec 26, 2025

Uh oh!

jcupitt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jcupitt commented Dec 28, 2025

Uh oh!

jcupitt commented Dec 28, 2025

Uh oh!

JoshCLWren commented Dec 28, 2025

Uh oh!

JoshCLWren commented Dec 28, 2025

Uh oh!

Uh oh!

jcupitt commented Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments