Typing broken because of `*_forward_decl`

[jc-louis]

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

[julian-smith-artifex-com]

Thanks for this. I have a fix in my tree - use from __future__ import annotations instead of the temporary string values.

[We'll keep this issue open until we've made a release with the fix.]