version: fix normalize_version() according to PEP440

[radoering]

Resolves: python-poetry/poetry#5534

• Added tests for changed code.
• Updated documentation for changed code.

normalize_version() seems quite buggy supposing that it should do normalizations according to PEP 440. This PR fixes this method and adds tests derived from PEP 440 examples.

Since I wasn't sure if the to_string(short=False) method has some other usage (seems to be more semver than PEP440), I introduced a new property norm_string.

[abn]

My 2c, I would say we return PEP440 compliant string when short is true rather than introducing another property. I'd like to avoid adding more cognitive load here and standardise one way.

[radoering]

That was my first thought, too. But it seemed a bit confusing later.

It would be a bit weird especially for ReleaseTag because there is a shorten() and an expand() method. At the moment each long name has its short name (rev <-> r, post <-> -). But for PEP440 normalization rev as well as post are normalized to post. So if you call shorten() and expand() on rev you don't get rev back if we make the proposed change. That may be a bit confusing and even increase the cognitive load.

I'm not sure whether the two different variants (short and long) are useful at all. I tend to say that to_string() should always return a normalized version string (no short parameter). If that would be too much a breaking change, I'd say it may be better to introduce norm_string and maybe deprecate to_string().

Further, I'm not happy with short being a bad parameter name for normalized.

[abn]

Very minor comment. Otherwise lgtm.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
1.6% Duplication