DOC: migration guide is out of date, README pointer is confusing

[dkg]

In README.md, it says:

NOTE: pypdf>=3.1.0 improved a lot compared to pyPdf<2.0.0 and compared to PyPDF2 < 2.0.0. Please read the migration guide.

This is confusing in a couple ways:

• i think the PyPDF < 2.0.0 is supposed to be PyPDF2 < 3.0.0
• the link points to a migration from v1 to v2, but the text implies that this is about the migration from v2 to v3

I'm trying to encourage other packages in debian to migrate from PyPDF2 to pypdf, and i'd like to point maintainers of those packages to a clean migration guide. Does something like that exist?

Without a clear upstream migration guide, i'm inclined to suggest something like "install the last version of PyPDF2 (2.12.1), run your full test suite, and note and resolve any PendingDeprecationWarning that you see."

If you have a better suggestion, i'd be happy to point them to it.

[MartinThoma]

There are three groups that need to do migrations:

• pyPdf users
• PyPDF2 < 2.0.0 users
• PyPDF2 >= 2.0.0 users

In chronological order, without skipping anything, the switches would be:

• Upgrade from pyPdf to PyPDF2 < 2.0.0: Almost no work. Just replace pyPdf by PyPDF2
• Upgrade from PyPDF2<2.0.0 to PyPDF2>=2.0.0: A lot of renamings; see the migration guide
• Upgrade from PyPDF2>=2.0.0 to PyPDF2>=3.0.0: No work, if you did the migration before (it just actually removed stuff)
• Upgrade from PyPDF2>=3.0.0 to pypdf>=3.1.0: Just replace PyPDF2 by pypdf.

So there really only is one "big" migration. As mostly names changed, I think all of those migrations are pretty trivial.

[MartinThoma]

I'm trying to encourage other packages in Debian to migrate from PyPDF2 to pypdf

Thank you 🙏

Do you have a list of those?

[dkg]

This is the primary bug report: https://bugs.debian.org/1029732

There are 10 downstream bugs open, and i've just supplied a patch which should fix two of them in diffoscope.

you should be able to see a summary of them on the src:pypdf page of the debian BTS

[dkg]

oh, and i generated the list of reverse dependencies in debian with apt rdepends python3-pypdf2 from a debian testing/unstable system, in case that's what you're asking.

[MartinThoma]

i generated the list of reverse dependencies in debian with apt rdepends python3-pypdf2 from a debian testing/unstable system, in case that's what you're asking

Yes!

Finished ✔️

• python3-xhtml2pdf (>= 1.26): https://github.com/xhtml2pdf/xhtml2pdf - seems like debian wasn't updated for a while. I've upgraded from PyPDF3 to pypdf in Replace PyPDF3 by pypdf xhtml2pdf/xhtml2pdf#656
• xml2rfc done with chore(deps): Move from PyPDF2 to pypdf>=3.2.1 ietf-tools/xml2rfc#953
• diffoscope: https://salsa.debian.org/reproducible-builds/diffoscope/-/commit/6aed2e5320b5d412f0f81a36dd493ae4bd7c3ff4

In progress ⏳

• oca-core - still https://github.com/OCA/OCB/blob/16.0/setup.py#L47 - that seems to be Odoo; see Incompatibility with latest version of PyPDF2 odoo/odoo#92595
• bookletimposer - still https://github.com/con-f-use/bookletimposer/blob/master/setup.py#L115 (see Migrate from pyPdf / PyPDF2 to pypdf con-f-use/bookletimposer#3 ); I've also written a mail to the author of https://git.codecoop.org/kjo/bookletimposer/-/blob/master/setup.py
• kraft: Migrate from PyPDF2 to pypdf dragotin/kraft#199

Dead projects 💀

• krop - still https://github.com/arminstraub/krop/blob/master/krop/pdfcropper.py#L23, but it seems dead PyPDF2 usage: New syntax / deprecations and the dependency arminstraub/krop#35
• pdfposter - project is dead; the last thing they did was upgrade to PyPDF2
• tryton-modules-stock-package-shipping-dpd - still https://github.com/tryton/stock_package_shipping_dpd/blob/develop/setup.py#L61 - archived project

[dkg]

* Depends: kraft - I don't find any pypdf dependency

It's in tools/erml2pdf.py and tools/watermarkpdf.py, i think.

[MartinThoma]

I was looking at https://github.com/unikraft/kraft/tree/staging/kraft, but that was the wrong one.
I've opened an issue there: dragotin/kraft#199

[MartinThoma]

I don't think there is anything we can do about this topic anymore. If anybody has concrete suggestions, please raise them.

For the moment, I will close this issue.