page property of Destination is mistyped

[gleachkr]

I think this one is pretty simple. The page property of a destination is current documented (and type-annotated) as returning an Optional[int]:

pypdf/pypdf/generic/_data_structures.py

Line 1714 in 2363750

def page(self) -> Optional[int]:

But in fact, what it returns is generally an IndirectObject, presumably because of how /Page is initialized here:

pypdf/pypdf/generic/_data_structures.py

Line 1634 in 2363750

self[NameObject("/Page")] = page

.

[stefan6419846]

Thanks for the report. Unfortunately, I have some doubts that this is simple to fix.

Looking at

pypdf/pypdf/generic/_data_structures.py

Line 1624 in 2363750

page: Union[NumberObject, IndirectObject, NullObject, DictionaryObject],

indicates that we have quite some options for values here.

pypdf/pypdf/generic/_data_structures.py

Line 1609 in 2363750

be an instance of :class:`IndirectObject<pypdf.generic.IndirectObject>`.

states that it should only hold an IndirectObject, while

pypdf/pypdf/generic/_data_structures.py

Lines 1713 to 1716 in 2363750

	@property
	def page(self) -> Optional[int]:
	"""Read-only property accessing the destination page number."""
	return self.get("/Page")

refers to a page number we most likely never have.

You are of course invited to analyze this in detail and report here and open a corresponding PR if you have found a proper solution, but for now I honestly have some doubts that we can expect to have a consistent value here given the wide range of input data.

[gleachkr]

That's too bad - I'm sorry, I don't really have a proposal for how to fix this properly.

I think it would make sense to change the type hint and docstring to be consistent with Line 1624. The actual behavior of the page is to at least sometimes return an IndirectObject, so that should somehow be indicated in the documentation of the page property.