Switch to None or Exception for page_number / get_page_number / get_destination_page_number

[MartinThoma]

Explanation

If a page is not attached to a document, it does not have a page number. So we cannot return a "normal" number.
At the moment, we return -1.

However, callers (users of the library) might not be careful with error handling.

For this reason I suggest to change the behavior to either return None or raise an Exception. I'm not sure what is better.

Pro returning None:

• It makes intuitive sense what it means
• It is part of the type annotation and mypy will complain about it if you don't handle that
• Callers just need to check for None and don't need to catch an exception - which I personally prefer.

[pubpub-zz]

@MartinThoma
How long do you intend to let this thread open?

[MartinThoma]

Good question. I think I want to tackle this with the pypdf==4.0.0 release (if we do it at all), but not earlier. So it will stay open for quite a while.

I want to have that release in early January 2024.

What is your opinion on the topic @pubpub-zz ?

[pubpub-zz]

-1 is not an issue for me : it is consistent with functions like "find_in".find("to_be_found") in any case we need to add a test is None or <0 as 0 is a valid result.
in any case an exception is not a good option

[pubpub-zz]

PS: what about converting this thread to a dicussion/question