Warn about potentially incompatible project name canonicalisations #560

PeterJCLaw · 2023-03-05T14:09:04Z

The handling of package names within the Python packaging ecosystem is unfortunately not in a great state at the moment. There exist a large number of packages which contain characters which (some of) the specs indicate are invalid, yet there is not a clear migration path nor destination at the moment.

Poetry's approach is to normalise project names towards their "canonical" form, meaning that existing projects on PyPI which use the more relaxed name forms will be silently renamed if they move to (recent versions of) Poetry. As well as changing the name of these packages (which maintainers are unlikely to expect nor desire) this unfortunately ends up breaking introspection via importlib.metadata in Python 3.8 and 3.9 which are not aware of the canonicalisation rules which Poetry is using.

Adding this warning informs maintainers so that they can decide how (and if) they want this name canonicalisation to happen.

Added tests for changed code.
Not sure this is worthwhile here?
~~Updated documentation for changed code.~~
Not planning to do this given the self-documenting nature of this.

Open to suggestions on better wording. Other details which might be worth including are:

the nature of the breakage on older Python
clarifying that it's downsteam user code which is broken (not the package being built) in those cases
maayybe hints on how to fix that (but that feels too detailed for the warning message)
link to PyPI does not accept wheel file name with . replaced with _ pypi/warehouse#10030, in particular the summary at PyPI does not accept wheel file name with . replaced with _ pypi/warehouse#10030 (comment)

Related to python-poetry/poetry#6198

The handling of package names within the Python packaging ecosystem is unfortunately not in a great state at the moment. There exist a large number of packages which contain characters which (some of) the specs indicate are invalid, yet there is not a clear migration path nor destination at the moment. Poetry's approach is to normalise project names towards their "canonical" form, meaning that existing projects on PyPI which use the more relaxed name forms will be silently renamed if they move to (recent versions of) Poetry. As well as changing the name of these packages (which maintainers are unlikely to expect nor desire) this unfortunately ends up breaking introspection via `importlib.metadata` in Python 3.8 and 3.9 which are not aware of the canonicalisation rules which Poetry is using. Adding this warning informs maintainers so that they can decide how (and if) they want this name canonicalisation to happen.