PyPDF2 Version 3.0.0

[MartinThoma]

@pubpub-zz @MasterOdin (Also others, of course ❤️ ) I'm currently preparing the 3.0.0 release of PyPDF2. The idea is that this would be the last PyPDF2 release. After that, only patch-releases would happen.

The next big thing would then be pypdf==4.0.0 which would only contain deprecations / the package name change.

Is there anything you would like to get into PyPDF2==3.0.0?

The migration plan

1. Release PyPDF2==3.0.0. Here we can make the last breaking changes.
2. Release pypdf==3.0.0 (edited: I originally wanted to bump directly to pypdf==4.0.0, but I think the community needs a transition phase). Compared to PyPDF2==3.0.0, only the package name changed from PyPDF2 to pypdf (and several project URLs, see Move to pypdf #1488 )

Moving to pypdf==4.0.0 has two advantages:

• We can clean up the code a lot - I'm uncertain though if that actually is a good idea as it removes hints for users how to migrate.
• People might connect pypdf==4.0.0 with PyPDF4. Meaning that people might have an easier time to see that pypdf is the latest one that everybody should use (and let PyPDF2/PyPDF3/PyPDF4 die)... however, that would rather be an argument to jump to pypdf==5.0.0 directly.

How users move

It's a bit of a taste-question, but I'd recommend the following:

• Big-bang for small usage of PyPDF2: Going directly from PyPDF2==2.X to pypdf==4.0.0. Those users can likely just look at every call they make to PyPDF2.
• Incremental move for complex usage of PyPDF2: I'm not sure if it makes sense for anybody to move (1) first to PyPDF2==3.0.0 and then (2) to pypdf==4.0.0. Typically, (2) should just be a regex. I guess once PyPDF2==3.0.0 is out we will get several issues opened with people needing support.
• StackOverflow (pypdf and PyPDF2): This will be interesting and take quite a while. I will update the tag descriptions, but this will be painful
• Realpython and other tutorials: I've already pinged them multiple times. I guess we need the users to complain that their stuff doesn't work anymore 😢 Same goes for other online tutorials / lectures. I was reminding people to use PdfReader instead of PdfFileReader all the time, but people ignored it.

[MartinThoma]

I see a consistency issue around destinations:

• named_dests should be named_destinations
• get_named_dest_root should be get_named_destination_root
• clone(... pdf_dest ...) should be clone( ... destination ...)
• dest_array should be destination_array

[xilopaint]

• however, that would rather be an argument to jump to pypdf==5.0.0 directly.

Please, don't do this.

[MartinThoma]

Why not?

[xilopaint]

I think at this point PyPDF2 is widely recognized as the real PyPDF successor. I don't think skipping a v4 release and breaking the string just to avoid a confusion with PyPDF4 is a good idea. People won't get confused at all because PyPDF4 is clearly abandoned while this project is active with a lot of stars.

[MartinThoma]

What do you mean with "breaking the string"?

The idea is to go back to pypdf. Then the question is with which version of pypdf we continue. It should be higher than the current one of PyPDF2 (so at least 3.0.0), but the question is which one.

I see people being uncertain about the capitalization of PyPDF2 all the time. Aparently a lot of beginners make their first steps into Python with PyPDF2. Additionally to the uncertainty about capitalization, people sometimes ask questions about "pypdf" thinking about "PyPDF2". They are not 100% aware that those are two different projects.

The move from PyPDF2 to pypdf would not break anything in projects that are setup well (version pinning).
PyPDF2 would keep being on PyPI. It would just not get any updates (+ a big warning text that the community moved to pypdf).

For people still using pypdf who have not version-pinned their code, things would break. But the solution is pretty clear: Use version pinning. It would also break early and obviously.

[xilopaint]

Now I'm not sure if I understood you before. As I understand it you proposed to not making a v4 release in order to avoid confusion with PyPDF4 and jump directly to a v5 release. If I got it right I think this is not necessary and we should make a v4 release normally. There's also a PyPDF3 project and you are about to make a v3 release anyway. There's no way to avoid some people getting confused, especially beginners, because there's a lot of attempts to carry on the legacy of PyPDF and most of them have failed.

The idea is to go back to pypdf

I see no problem with adopting this name. Actually I think it's cleaner and the best choice.

[MartinThoma]

Sorry, it's hard to talk about this clearly 🙈

There are several types of "entities":

• Package names: That is what is on PyPI. I have control over https://pypi.org/project/pyPdf/ and https://pypi.org/project/PyPDF2/ . Although it's capitalized, the capitalization is irrelevant. I can change that to all lowercase for pypdf and leave PyPDF2 as it is. I will not introduce any new package.
• import names: Typically the same as the package name, but some packages choose to differ. For example the package "pillow" has the import name "PIL" or the package "pymupdf" has the package name "fitz". Here capitalization matters. I will make pypdf all lowercase and keep PyPDF2 as it is.
• package version: I was talking about this. It has to look like semantic versioning (numbers and dots between them), but we can skip versions. There is no harm in skipping a version. That is what I was talking about. Sometimes packages go from a semantic versioning scheme to a year-based versioning scheme. Then they might jump from 1.42.123 to 2022.12.123

[xilopaint]

1. Release PyPDF2==3.0.0. Here we can make the last breaking changes.
2. Release pypdf==4.0.0. Compared to PyPDF2==3.0.0, only the package name changed from PyPDF2 to pypdf (and several project URLs, see Move to pypdf #1488 )

Will the two releases happen on the same day?

[xilopaint]

I'm waiting for the next release containing the cloning feature to make a release of my project. If v4 comes together with v3 I'll adapt my project to v4.

[MasterOdin]

Once v4 is released, will a deprecation warning be added to __init__.py for v3 to point people towards using pypdf in the future, in case they're using something like automatic dependabot merges and might miss the changelog entry that mentions this.

[xilopaint]

Can we expect v3 for this year? If not, I'll do a new release today on my project, as the cloning feature has already been merged.

[MartinThoma]

Can we expect v3 for this year?

Yes. I cannot say when exactly, but the year only has 19 days left anyway 😄

[MartinThoma]

PyPDF2==3.0.0 was just released :-)

[MasterOdin]

We can clean up the code a lot - I'm uncertain though if that actually is a good idea as it removes hints for users how to migrate.

There should already be a good amount of clean-up going into the 3.0 release as the various camelCase properties / functions and such are all removed. For 4.0.0, it'd then be into removing the deprecated arguments, but what else?

[MartinThoma]

There is actually nothing removed (although we could probably remove the body of the deprecated functions): #1489

The main point is that people are now forced to use the new syntax (e.g. PdfReader instead of PdfFileReader). However, PdfFileReader is still there - it just gives a DeprecationError (exception) when you try to use it. Similar for almost all of the rest.

My comment (the one you quoted) was related to that. With 4.0.0, we would completely remove the deprecated stuff. Meaning the users would just get "unexpected keyword argument" and ImportError. Without any hint on how the new stuff is called.

[MartinThoma]

It's starting: #1488 :-)