Deprecate LegacyVersion/LegacySpecifier

[di]

There's too much confusion about how the LegacyVersion and LegacySpecifier interact with their non-legacy counterparts when mixed. (See #74, #112, #275, #307, #320, and probably more)

In #12 @dstufft said :

I don't think it's something that we're going to be able to realistically deprecate anytime soon.

But that was six years ago. I think the community has been publishing/using non-legacy versions for long enough that we can remove the need for this library to support it.

I propose a deprecation period, where creating a LegacyVersion/LegacySpecifier produces a deprecation warning, followed by a removal, where this would raise an InvalidVersion/InvalidSpecifier exception instead (possibly with some additional details about them being legacy).

[dstufft]

We should probably figure out how many projects this would make uninstallable on PyPI before we decide to do this.

[xavfernandez]

Without necessarily deciding on a deprecation period, simply poping up a Warning when LegacyVersion / LegacySpecifier are used as fallback in packaging.version.parse & SpecifierSet.__init__ would be a less impactful first step.

[brettcannon]

I agree with @dstufft that a quick analysis of the latest releases of projects to see which ones would get excluded would be good. But I will also say that the consistent confusion about LegacyVersion suggests we should deprecate it regardless of the analysis outcome and that the analysis informs more how quickly we can drop it rather than whether we should.

[pradyunsg]

Q: Who's doing the analysis tho?

[di]

I did the analysis (scripts and data are here).

Out of nearly 2M releases on PyPI, less than 0.2% releases have a LegacyVersion (5172 total)

The last release to publish with a LegacyVersion was published on 2015-09-10.

[pradyunsg]

Thanks @di!

I say we can deprecate now (say, in a release this month?) and drop support in early 2021.

[dstufft]

Do you happen to have the spare cycles to do the same thing with specifiers @di? Just using the info that's in the eDB should be good enough.

The concern is that it doesn't surprise me that versions are a minor %, given PyPI has actively rejected non PEP 440 versions for awhile, so anything that has been released recently is incapable of not being a valid PEP 440 version. However, I don't think we do the same validation on dependency specifiers, which means people could be publishing invalid specifiers still to this day.

[di]

@xavfernandez @pradyunsg Regarding a deprecation warning, I'm thinking that we might want to handle this differently when deprecating in this library vs. deprecating in pip.

Here, I'd expect any time a LegacyVersion is initialized to emit a warning, but I think that has the potential to produce a lot of warnings when pip does it's usual things. I think instead in pip we'd want to just emit a warning whenever a user has explicitly constructed a LegacyVersion via a specifier, etc.

But I'm not super familiar w/ pip's internals, so maybe that isn't necessary?

[pradyunsg]

deprecating in this library vs. deprecating in pip

FWIW, I realized after reading your comment that we'd probably want to expose this warning in some form to end users of pip. I was thinking purely in terms of deprecating in this library. :)

But I'm not super familiar w/ pip's internals, so maybe that isn't necessary?

I think we'd be putting this through the warnings module here and, IIUC, you would only see 1 warning get printed regardless of how many class calls (thanks autocorrect) are made unless the warning module's default configuration is changed. And pip doesn't do that, so it'll be fine?

---

don't think we do the same validation on dependency specifiers

Huh. TIL.

I'd argue: if warehouse isn't performing validation on specifiers, maybe we should treat these as two separate deprecations? :)

[di]

I parsed all the specifiers as well (scripts are here, GitHub couldn't handle the CSV file)

Of the nearly 5M requirement strings, only 5719 parsed as including a LegacySpecifier.

In addition, a lot of these look like typos, e.g. plone.app.form>=1.1.8plone.app.vocabularies

[dstufft]

Cool, that strongly suggests that deprecating and ultimately removing these things is not going to cause any major problems.

The only other comment I have is it might make sense to keep the classes around, but simply stop the fallback to the Legacy classes when parsing. That would mean that by default we would fail on legacy versions and specifiers, but if someone is using the API directly, and they have a reason to, they can still interact with legacy versions/specifiers. I don't believe either of these modules really requires much in the way of maintenance, so I don't think it would be a large maintenance burden or anything.

The main reason I could see not to do that, is specifically for the specifier code, is that there are some minor simplifications that could be made to the logic if we completely drop the legacy forms.

[brettcannon]

I say drop the old versions and if people really need them they can either copy the code or rely on an old version of 'packaging'.