Confusing entries in PyPI and at official website about psycopg

[pythonaddict]

When you search "psycopg" in PyPI search bar, you see many results. Top 2 results are:

• psycopg 3.1.12 : PostgreSQL database adapter for Python
• psycopg2 2.9.9: Python-PostgreSQL Database Adapter

Both packages are written by same authors.

Even though psycopg 3.1.12 is named "pyscopg" at PyPI, it points to the 3rd version of psycopg. So, "psycopg" represents the 3rd and the newer version. But there is also "psycopg2", it points to the 2nd version.

But when you say "psycopg2", one thinks that it's newer than "psycopg". But actually psycopg is the newer and more improved version of psycopg2.

And when you want to install "psycopg3", you have to type pip install "psycopg[binary]", which is also weird. Why not just type pip install pyscopg or pip install pyscopg3?

Another confusion is at https://www.psycopg.org/. This is official pyscopg website:

On the home page, Latest Articles section, it says:

Psycopg 3.1 released
Posted by Daniele Varrazzo on 2022-08-30

Hello,

After several months of development, we are proud to release Psycopg 3.1!

So, the official website is informing people about the psycopg 3. One thinks psycopg 3 is the latest version that the development team is currently working on. However, at "Install" section at home page menu bar , it says:

Psycopg2 installation
The short version
First install the prerequisites (not needed on Windows, please adapt to your *nix distribution):

sudo apt install python3-dev libpq-dev
Then install the module:

pip install psycopg2

It tells you about the installation of "psycopg2" (the 2nd version of the library". It doesn't mention anything about how to install psycopg 3. So, one thinks that the official website wants you to install psycopg 2, not pyscopg 3!

I hope these confusions are eliminated.

[dvarrazzo]

Both packages are written by same authors.

Hi there 👋

Even though psycopg 3.1.12 is named "pyscopg" at PyPI, it points to the 3rd version of psycopg. So, "psycopg" represents the 3rd and the newer version. But there is also "psycopg2", it points to the 2nd version.

The error was to call the Psycopg 2.0 Python module psycopg2, almost 20 years ago. Back in that time semver didn't exist, pip didn't exist, pypi didn't exist, requirements.txt didn't exist... The rename happened because someone asked in the ML to use psycopg 1 and 2 in the same program, so it seemed a good idea to create two libraries which could be imported side-by-side.

Fast forward several years, this convention is not employed anymore: even when there is a non-backward-compatible change, nowadays package names don't change. I didn't want to create psycopg3 (although that was the original package name of Psycopg 3.0 rewrite, and it's still the name of my development directory...) and then expecting to write a psycopg4 as soon as there is a non-backward-compatible feature (which is what a community used to Semver expects).

There was a conversation about the topic a couple of years ago, when I proposed to use the naked psycopg as package name There wasn't a consensus, many (including Federico, the original author) preferred psycopg3. This message of mine explains the rationale behind the choice to call the package psycopg, to start versioning it from 3.0, and to not expect to change it when there will be non-backwards-compatible versions to 4.0, 5.0, etc.

But when you say "psycopg2", one thinks that it's newer than "psycopg". But actually psycopg is the newer and more improved version of psycopg2.

I know, for a newcomer is confusing, for 3 to 5 seconds, then you move on with your life. The benefit of not having the major number in the package name are more important than the little confusion. A major number in the package name is a convention used by almost no package (I count 4 in the top 100 PyPI packages as of right now).

And when you want to install "psycopg3", you have to type pip install "psycopg[binary]", which is also weird.

The choice of having the binary package as an extra is a decision made after having tested several other options since 2017 and after considering the possibilities offered by Python packages metadata and the problem in which the users of the packages have incurred (see the bug tracker).

Why not just type pip install pyscopg or pip install pyscopg3?

Every complex problem has a simple, and wrong, solution. 😛

However, at "Install" section at home page menu bar [...] It tells you about the installation of "psycopg2"

You are right: we should dare updating that page.

Psycopg2 is still the most used version of the package and several other libraries weren't ready for the interaction with Psycopg 3. But things are changing: Psycopg 3 is now used by several big depending libraries (Django, SQLAlchemy) and is the best choice for newer ones (FastAPI). psycopg2 will still stay around for a long time, for established projects, but, for new projects, it's the right choice.

The project is mature enough that we can stop considering psycopg2 the present and Psycopg 3 the future: it's probably time to consider psycopg2 the past and Psycopg 3 the present, and we should update that page accordingly.

[dvarrazzo]

@pythonaddict thank you again for your feedback regarding the 2 vs. 3 status. The point of view of someone fresh is useful.

I have reorganised a few pages of the website, especially the features, which now offer a 2-to-3 comparison, and the install.

If you have other feedback about what would help a newcomer to find their way, it would be welcome to know.

Cheers!

[pythonaddict]

@dvarrazzo Thanks, I'm glad that I helped.

Another confusion is at PyPI. There are 2 entries at pyPI:

• psycopg 3.1.12 : PostgreSQL database adapter for Python
• psycopg2 2.9.9: Python-PostgreSQL Database Adapter

And at neither of the entries they mention about each other. So, it is confusing too. One may be confused which version to choose. I think at psycopg2's "Project description" page at PyPI, there should be some info at the top about psycopg3, something like this: "There's a better and improved version of psycopg2: psycopg 3. Please visit this link for more information"

And at psycopg3's "Project description" page at PyPI, at the top there should be something like this: "This is the latest version of psycopg. For the legacy version psycopg2, please visit this link."

[dvarrazzo]

Yes, that sounds a good idea, thank you. I will try and mention something in that direction in the readme that is rendered on pypi (but it will have to wait for the next release to be published there unfortunately).