Make the relationship to pyPdf clear

[MartinThoma]

PyPDF2 is on a good path: We got a lot of PRs merged in April/May and we modernized the interface a lot. A big thank you to everybody 🙏 🎉 🤗

The origin of PyPDF2 is pyPdf, written by Mathieu Fenniak. PyPDF2 has been the recommened fork for many years now, but I still see people just mentioning pyPdf (and probably meaning PyPDF2). And there is still PyPDF3 and PyPDF4 around, which makes it even more confusing for beginners.

I though it might be nice to make the relationship between pyPdf and PyPDF2 clear on the PyPI page of pyPdf. I see two options:

(a) change the README so that it points directly to PyPDF2 + mark pyPdf as "Development Status :: 7 - Inactive"

(b) move PyPDF2 to pyPdf (similar as sklearn / scikit-learn point to the same project) - in that case I would switch the name to completely lowercase pypdf as people get that wrong all the time.

I would always keep the old versions of both (pyPdf and PyPDF2). So people can always just pin the version and use what they currently use.

I've contacted Mathieu and he seems to be open to transfer the PyPI listing of pyPdf to me. So we can actually do those things.

I want to know your opinion : What do you think would be the best use of the pyPdf listing on PyPI for the current and future community?

[pubpub-zz]

I think that PyPDF2 "branch" was selected and it is a good choice : it is in the "middle" between pypdf/PyPDF3/ PyPDF4 and would ease others to "merge" in.
definitively updating status and adding a pointer on pypi should be done
if the only issue is to the install folder that does not respect the standards and should be pypdf, I do not see any reason to not change its name keeping the same project ( this could be the object of a major change)

[MasterOdin]

I would be in favor of taking over the pyPDF package (renamed to pypdf as that follows python suggested practices) and just publishing under that going forward. PyPDF2 was a fork of pyPDF and the fork is now getting upstreamed, the hopeful destiny of any fork. I would also greatly advocate against doing what scikit-learn did with their aliases, and just kill the name you don't use (publish a version that issues a warning on installation that the package is deprecated, use X instead, and put in README on pypi). Whenever I come across a package I don't know, I go to its pypi page, and having any sort of alias business just feels hostile to the new users to the package. From my experience with npm and composer, users seem to handle package deprecations and suggestions to use a different one just fine.

For making things less confusing with regards to forks and stuff, I would include a brief history blurb in the README that touches upon the different forks and stuff, why they existed, etc. That shouldn't be that confusing in the long run.

[MartinThoma]

taking over the pyPDF package (renamed to pypdf as that follows python suggested practices) and just publishing under that going forward

I think I like that idea best as well. The details are not clear to me though

If I got you right, this is what you're proposing:

1. Make a major new release that continues with the current PyPDF2 history. For example, if PyPDF2 currently is at 2.7.8 I would make a new pypdf==3.0.0 release. In that release, the package name would be changed consistently everywhere to pypdf (all lowercase)
2. Make a last PyPDF2==2.7.9 release which just updates the README that the project is now continued under pypdf. Still with working code, but maybe a deprecation warning on module level.

I would like that approach :-)

I would include a brief history blurb in the README

Sounds good in all cases :-) I've also added History of PyPDF2 which I want to extend.

[MartinThoma]

@pubpub-zz What do you think about it? If I got you right, you prefer staying with PyPDF2? Do you have strong feelings about it?

[MartinThoma]

I think I decided on this. I want to go with your approach. In this order:

1. Finish consistency changes
2. Rename the git repository to "pypdf" + update all links. Check if we can get it on read the docs.
3. Create a pypdf2 branch to archive the old state
4. Update the main branch to pypdf everywhere + release pypdf==3.0.0 (or maybe 5.0.0 so that people know it's more modern than PyPDF4?) on pypi. This uses all-lowercase pypdf everywhere
5. Release a last PyPDF2 version (2.x.x). This adds a deprecation message + a big notice in the readme
6. Follow-up releases will only be in pypdf

So it would be consistent, all lowercase, without a number, everywhere.

[pubpub-zz]

I would not have change PyPDF2 project name , i.e. keep doing install through pip install PyPDF2 but change folder name so that we will do import pypdf with a warning to do so in within the pip install. also would not change the github repository name (not an expert and therefore worried repo changed name impact).
If you look at the statistics (https://pypistats.org/packages/pypdf2) I do not think disturbing them too much will be an advantage
completely agree about major number change

however all those are personal point of view 🙊

[MasterOdin]

keep doing install through pip install PyPDF2 but change folder name so that we will do import pypdf

I am very much against having a dependency be installed with one name and used with a different one. It's confusing to end users, and you're still introducing a breaking change. Either make the full breaking change to also change the install package name, or don't make any breaking change, don't go halfway.

also would not change the github repository name (not an expert and therefore worried repo changed name impact).

So long as you don't create a new repository at the location of an old one, then the redirect will exist in forever, even across repository transfers. An example is that https://github.com/asciidoc/asciidoc3 and https://github.com/asciidoc/asciidoc both redirect to https://github.com/asciidoc-py/asciidoc-py, where I had started with the first, renamed to the second, then did a repository transfer to the third.