ENH: Add Cloning

[pubpub-zz]

The method .clone(pdf_dest,[force_duplicate]) clones the objects and all referenced objects.

If an object is already cloned, the already cloned object is returned (unless force_duplicate is set)
mainly for internal use but can be used on a page
for pageObject/DictionnaryObject/[Encoded/Decoded/Content]Stream an extra parameter ignore_fields list that provide the list of fields that should not be cloned.

When available, the pointer to an object is available in indirect_obj attribute.

New API for add_page/insert_page that :

• returns the cloned page object
• ignore_fields can be provided as a parameter.

Others

• file is closed at the end of PdfWriter.write when a filename is provided
• Breaking Change: add_outline_item now has a parameter before which is not the last parameter

Update

• The public API of PdfMerger has been added to PdfWriter (ready to make PdfMerger an alias of it)
• Process properly Outline merging
• Process properly Named destinated

Deals with #1194, #1322, #471, #1337

[codecov]

Codecov Report

Base: 94.14% // Head: 92.70% // Decreases project coverage by -1.43% ⚠️

Coverage data is based on head (4ccfbff) compared to base (7633477).
Patch coverage: 84.45% of modified lines in pull request are covered.

❗ Current head 4ccfbff differs from pull request most recent head afebcab. Consider uploading reports for the commit afebcab to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1371      +/-   ##
==========================================
- Coverage   94.14%   92.70%   -1.44%     
==========================================
  Files          31       29       -2     
  Lines        5480     5691     +211     
  Branches     1037     1112      +75     
==========================================
+ Hits         5159     5276     +117     
- Misses        193      267      +74     
- Partials      128      148      +20     

Impacted Files	Coverage Δ
PyPDF2/_merger.py	97.60% <ø> (+4.42%)	⬆️
PyPDF2/generic/_data_structures.py	89.75% <79.08%> (-5.57%)	⬇️
PyPDF2/_protocols.py	81.25% <81.25%> (ø)
PyPDF2/_writer.py	86.12% <84.11%> (-3.43%)	⬇️
PyPDF2/generic/_base.py	99.64% <98.36%> (-0.36%)	⬇️
PyPDF2/_page.py	92.23% <100.00%> (+0.28%)	⬆️
PyPDF2/_reader.py	90.33% <100.00%> (+0.04%)	⬆️
PyPDF2/types.py	100.00% <100.00%> (ø)
... and 11 more

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]

mypy didn't complain when I checked. As you asked me to look at mypy, I checked all 'type: ignore' comments. Several were not necessary at all. In some cases mypy needed an assert variable is not None as a hint. And in some cases I could at least narrow the ignore down to be a bit more specific

[MartinThoma]

Finally! I'll have another quick look at the code and then merge today :-)

[MartinThoma]

@pubpub-zz Thank you so much for this moonshot extension 🙏 ❤️

[xilopaint]

@pubpub-zz thanks for all the effort you've put into this PR!