Repository navigation
Typing broken because of *_forward_decl #4903
Description
Description of the bug
Since #4857, running mypy on code that uses pymupdf.Page as a type annotation or iterates over a Document produces errors, even though the code works perfectly at runtime.
pymupdf/init.py assigns Page as a string on line 478 before the actual class definition on line 9516:
mypy uses the first assignment's type, so it treats Page as a str variable rather than a class. This makes pymupdf.Page unusable in type annotations.
How to reproduce the bug
import pymupdf
def get_page_width(page: pymupdf.Page) -> float: # error: Variable "pymupdf.Page" is not valid as a type
return page.rect.width # error: pymupdf.Page? has no attribute "rect"$ mypy repro.py
error: Variable "pymupdf.Page" is not valid as a type [valid-type]
error: pymupdf.Page? has no attribute "rect" [attr-defined]
PyMuPDF version
1.27.1
Reacted by James Braza
Activity
julian-smith-artifex-com commentedon Feb 16, 2026
Thanks for this. I have a fix in my tree - use
from __future__ import annotationsinstead of the temporary string values.[We'll keep this issue open until we've made a release with the fix.]
tests/test_typing.py: add test for forward declarations of pymudf.Page.
src/__init__.py: improve forwards-declaration typing of Page and Point.
tests/test_typing.py: add test for forward declarations of pymudf.Page.
src/__init__.py: improve forwards-declaration typing of Page and Point.
julian-smith-artifex-com commentedon Mar 10, 2026
Fixed in PyMuPDF-1.27.2.