Add type hints support (#355) (#564)

* Add type hints support (#355)

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.

* Add comprehensive type hints for hand-written bindings and enhance operator 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

* Update CHANGELOG credit to JoshCLWren

* Add type hints for composite and ifthenelse hand-written bindings

* Expand mypy type checking to more example scripts

* Fix operation filtering in type stub generator to correctly filter deprecated 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, add flake8 noqa

* Complete comprehensive type hints for pyvips

- 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 to 3.2.0 and update CI

- 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

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

* Revert linting changes in examples and doc/conf.py

- 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

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

* pin mypy to <1.19 for PyPy 3.9 compatibility

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.

Author: JoshCLWren

.github/workflows/ci.yml

@@ -32,6 +32,16 @@ jobs:
           pip install flake8
           flake8 .
 
+      - name: Type check with mypy
+        run: |
+          # Pin mypy to <1.19 due to librt dependency in 1.19+
+          # which is not available on PyPy 3.9
+          pip install "mypy<1.19"
+          mypy pyvips/__init__.pyi --no-error-summary
+          mypy examples/affine.py examples/convolve.py examples/try5.py examples/watermark.py \
+                examples/annotate-animation.py examples/join-animation.py examples/progress.py \
+                --no-error-summary
+
       - name: Install tox and any other packages
         run: pip install tox
 

CHANGELOG.rst

@@ -1,3 +1,10 @@
+## Version 3.2.0 (released TBA)
+
+- add comprehensive type hints for all pyvips operations via generated stubs [JoshCLWren]
+- add operator overload type hints with array support (int, float, list[int], list[float]) [JoshCLWren]
+- add hand-written binding type hints for common methods [JoshCLWren]
+- add test coverage for type stubs [JoshCLWren]
+
 ## Version 3.1.1 (released 9 December 2025)
 
 - fix get_gainmap arguments [jcupitt]

README.rst

@@ -228,6 +228,30 @@ Stylecheck:
 
     $ flake8
 
+Stylecheck:
+
+.. code-block:: shell
+
+    $ flake8
+
+Type checking:
+
+pyvips includes type hints via PEP 561 type stub files (``pyvips/__init__.pyi``).
+To enable type checking in your project, install a type checker like mypy:
+
+.. code-block:: shell
+
+    $ pip install mypy pyvips
+
+Then run mypy on your code:
+
+.. code-block:: shell
+
+    $ mypy your_script.py
+
+Note: ``pyvips`` methods accept arbitrary keyword arguments for libvips options,
+which may not be fully covered by type hints.
+
 Generate HTML docs in ``doc/build/html``:
 
 .. code-block:: shell
@@ -246,6 +270,16 @@ then
 
 Then check and move `enums.py` into `pyvips/`.
 
+Regenerate type stubs:
+
+After adding new libvips operations or updating libvips itself, regenerate type stubs:
+
+.. code-block:: shell
+
+    $ python examples/generate_type_stubs.py
+
+This updates ``pyvips/__init__.pyi`` with the latest operations.
+
 Regenerate autodocs:
 
 Make sure you have installed a libvips with all optional packages enabled,

doc/conf.py

@@ -19,6 +19,7 @@
 import os
 import sys
 import sphinx_rtd_theme
+
 sys.path.insert(0, os.path.abspath('..'))
 
 
@@ -55,24 +56,24 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'pyvips'
-copyright = u'2019, John Cupitt'
-author = u'John Cupitt'
+project = 'pyvips'
+copyright = '2019, John Cupitt'
+author = 'John Cupitt'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'3.1'
+version = u'3.2'
 # The full version, including alpha/beta/rc tags.
-release = u'3.1.1'
+release = u'3.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
+# Usually you set 'language' from the command line for these cases.
 language = None
 
 # List of patterns, relative to source directory, that match files and
@@ -103,7 +104,7 @@
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# so a file named 'default.css' will overwrite the builtin 'default.css'.
 html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
@@ -126,7 +127,7 @@
     # each page.
     'github_user': 'libvips',
     'github_repo': 'pyvips',
-    'github_version': 'master/doc/'
+    'github_version': 'master/doc/',
 }
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -141,15 +142,12 @@
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -159,19 +157,15 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'pyvips.tex', u'pyvips Documentation',
-     u'john', 'manual'),
+    (master_doc, 'pyvips.tex', 'pyvips Documentation', 'john', 'manual'),
 ]
 
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pyvips', u'pyvips Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, 'pyvips', 'pyvips Documentation', [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -180,19 +174,26 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pyvips', u'pyvips Documentation',
-     author, 'pyvips', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        'pyvips',
+        'pyvips Documentation',
+        author,
+        'pyvips',
+        'One line description of project.',
+        'Miscellaneous',
+    ),
 ]
 
 
 # see https://stackoverflow.com/questions/20569011
 # adds autoautosummary directive, see vimage.rst
 
+
 # try to exclude deprecated
 def skip_deprecated(app, what, name, obj, skip, options):
     if hasattr(obj, "func_dict") and "__deprecated__" in obj.func_dict:
-        print("skipping " + name)
+        print('skipping ' + name)
         return True
     return skip or False
 
@@ -206,10 +207,9 @@ def setup(app):
         from sphinx.util.inspect import safe_getattr
 
         class AutoAutoSummary(Autosummary):
-
             option_spec = {
                 'methods': directives.unchanged,
-                'attributes': directives.unchanged
+                'attributes': directives.unchanged,
             }
 
             required_arguments = 1
@@ -227,8 +227,10 @@ def get_members(obj, typ, include_public=None):
                         continue
                     if documenter.objtype == typ:
                         items.append(name)
-                public = [x for x in items
-                          if x in include_public or not x.startswith('_')]
+                public = [
+                    x for x in items
+                    if x in include_public or not x.startswith('_')
+                ]
                 return public, items
 
             def run(self):
@@ -242,17 +244,21 @@ def run(self):
                         _, methods = self.get_members(c,
                                                       'method', ['__init__'])
 
-                        self.content = ["~%s.%s" % (clazz, method)
-                                        for method in methods
-                                        if not method.startswith('_')]
+                        self.content = [
+                            '~%s.%s' % (clazz, method)
+                            for method in methods
+                            if not method.startswith('_')
+                        ]
                     if 'attributes' in self.options:
                         _, attribs = self.get_members(c, 'attribute')
-                        self.content = ["~%s.%s" % (clazz, attrib)
-                                        for attrib in attribs
-                                        if not attrib.startswith('_')]
+                        self.content = [
+                            '~%s.%s' % (clazz, attrib)
+                            for attrib in attribs
+                            if not attrib.startswith('_')
+                        ]
                 finally:
                     return super(AutoAutoSummary, self).run()
 
-        app.add_directive('autoautosummary', AutoAutoSummary)
+        app.add_directive("autoautosummary", AutoAutoSummary)
     except BaseException as e:
         raise e