MAINT: indirect_ref/ido ➔ indirect_reference, dest➔ page_destination

[kygoben]

From issue #1187 used the descriptions from @mtd91429 to make a few modifications to PdfWriter and PdfReader

• indirect_ref ➔ indirect_reference and ido ➔ indirect_reference in PdfReader._get_object_from_stream and PdfWriter.get_object
• dest➔ page_destination and dest_ref ➔ page_destination_ref in PdfWriter.add_outline_item_destination and PdfWriter.add_named_destination_object

[codecov]

Codecov Report

Base: 93.85% // Head: 93.76% // Decreases project coverage by -0.08% ⚠️

Coverage data is based on head (ea4a29d) compared to base (e356a39).
Patch coverage: 74.07% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1467      +/-   ##
==========================================
- Coverage   93.85%   93.76%   -0.09%     
==========================================
  Files          30       30              
  Lines        5464     5470       +6     
  Branches     1046     1048       +2     
==========================================
+ Hits         5128     5129       +1     
- Misses        202      206       +4     
- Partials      134      135       +1     

Impacted Files	Coverage Δ
PyPDF2/_writer.py	87.42% <65.00%> (-0.65%)	⬇️
PyPDF2/_reader.py	90.30% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

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

[MartinThoma]

@kygoben Thank you for approaching this!

When we make those changes, we want to make them first in a non-breaking way. That means people who use the method with keyword parameters should receive a warning (but not an exception) that their usage is deprecated.

We also need to add this to the migration guide: https://pypdf2.readthedocs.io/en/latest/user/migration-1-to-2.html

Finally, we should typically use the long form. That means:

• Instead of indirect_ref I would like to have indirect_reference
• pagedest should rather be page_destination

See #1365 for a similar PR

[kygoben]

Hi @MartinThoma, I am a bit unsure how to completely approach your comments. For instance, you said that the migration guide would need to be updated. Where can I find this, and how should this be updated? And the second one is to give people a warning when using the keywords. Thank you for your help :)

[kygoben]

Not sure what I did incorrectly in these last modifications. Could someone give me some pointers to fix the test outcomes?
Thanks,
Kyle

[MartinThoma]

I'll have a look at the weekend. I was at a company event this week and moving/getting married last week :-)

[MartinThoma]

If you look into _page.py you can see in the __init__ method some indirect_ref that need to be changed to indirect_reference

[MartinThoma]

It would also be good to add a property indirect_ref that gives a deprecation warning + returns the indirect_reference. Just in case people use it in their code.

[MartinThoma]

I'll add this either before the PyPDF2==3.0.0 release or earlier.

[MartinThoma]

Rename Page.indirect_reference temporarily back to Page.indirect_ref to fix the PR