@mgorny@social.treehouse.systems2025-06-29 16:44:37
So #Gentoo #Python eclasses are pretty modern, in the sense that they tend to follow the best practices and standards, and eventually deal with deprecations. Nevertheless, they have a long history and carry quite some historical burden, particularly regarding to naming.
The key point is that the eclasses were conceived as a replacement for the old eclasses: "distutils" and "python". Hence, much like we revision ebuilds, I've named the matching eclasses "distutils-r1" and "python-r1". For consistency, I've also used the "-r1" suffix for the remaining eclasses introduced at the time: "python-any-r1", "python-single-r1" and "python-utils-r1" — even though there were never "r0"s.
It didn't take long to realize my first mistake. I've made the multi-impl eclass effectively the "main" eclass, probably largely inspired by the previous Gentoo recommendations. However, in the end I've found out that for the most use cases (i.e. where "distutils-r1" is not involved), there is no real need for multi-impl, and it makes things much harder. So if I were naming them today, I would have named it "python-multi", to indicate the specific use case — and either avoid designating a default at all, or made "python-single" the default.
What aged even worse is the "distutils-r1" eclass. Admittedly, back when it was conceived, distutils was still largely a thing — and there were people (like me) who avoided unnecessary dependency on setuptools. Of course, nowadays it has been entirely devoured by setuptools, and with #PEP517 even "setuptools" wouldn't be a good name anymore. Nowadays, people are getting confused why they are supposed to use "distutils-r1" for, say, Hatchling.
Admittedly, this is something I could have done differently — PEP517 support was a major migration, and involved an explicit switch. Instead of adding DISTUTILS_USE_PEP517 (what a self-contradictory name) variable, I could have forked the eclass. Why didn't I do that? Because there used to be a lot of code shared between the two paths. Of course, over time they diverged more, and eventually I've dropped the legacy support — but the opportunity to rename was lost.
In fact, as a semi-related fact, I've recognized another design problem with the eclass earlier — I should have gone for two eclasses rather than one: a "python-phase" eclass with generic sub-phase support, and a "distutils" (or later "python-pep517") implementing default sub-phases for the common backends. And again, this is precisely how I could have solved the code reuse problem when I introduced PEP517 support.
But then, I didn't anticipate how the eclasses would end up looking like in the end — and I can't really predict what new challenges the Python ecosystem is going to bring us. And I think it's too late to rename or split stuff — too much busywork on everyone.
