ENH: Add page_number property

[pubpub-zz]

add a new property to ease access to page number on all objects

is used in further fix

[codecov]

Codecov Report

Patch coverage: 100.00% and project coverage change: +0.02 🎉

Comparison is base (54e027a) 93.53% compared to head (33668cf) 93.56%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1856      +/-   ##
==========================================
+ Coverage   93.53%   93.56%   +0.02%     
==========================================
  Files          34       34              
  Lines        6625     6634       +9     
  Branches     1296     1297       +1     
==========================================
+ Hits         6197     6207      +10     
  Misses        281      281              
+ Partials      147      146       -1     

Impacted Files	Coverage Δ
pypdf/_page.py	92.04% <100.00%> (+0.10%)	⬆️

... and 1 file with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[MartinThoma]

Only the "not attached" case is something I would like to do different. The rest looks good :-)

[pubpub-zz]

Only the "not attached" case is something I would like to do different. The rest looks good :-)

_get_page_number_by_indirect returns -1 if the page is not found(includes not attached). we will have to change it also?

[MartinThoma]

_get_page_number_by_indirect returns -1 if the page is not found(includes not attached). we will have to change it also?

Oh, interesting. So we have that behavior for a long time in the code base.

I don't care too much about the internal/private functions.
However, get_page_number and get_destination_page_number already have this behavior.

I'm torn now: One the one hand, I think "-1" might cause issues that "None" or an exception would not cause.
On the other hand, inconsistencies are confusing and also lead to issues. And I want to avoid breaking changes.

Let me think about it until Sunday 🤔

[MartinThoma]

(I tend to say "leave things as you already did" though - if we have want to change that, we can do it in one go for the whole codebase)

[mara004]

I'd encourage you to switch from -1 to None for the "no page number available" case, as reverse indexing accidents are just too likely. In my experience, many callers aren't careful about correct error handling, and None is safer in any case.

[MartinThoma]

I've opened #1914 so that I don't forget about it. I want to keep pypdf stable for this year, but we had already a couple of breaking changes. I will collect them and do them all in one go.