Setuptools: New API in version 39?

[micahculpepper]

First of all, let me apologize if this was already explained somewhere else. My google-fu has failed me. If anyone can point me in the right direction, I'd appreciate it.

Today, I use pkg_resources.parse_version() to check if a package version number conforms to standards. Before v39, this returned a pkg_resources.SetuptoolsVersion object if the version number was fine, or a pkg_resources.SetuptoolsLegacyVersion if it was not fine.

In the version 39 release that just came out, it looks like pkg_resources.SetuptoolsLegacyVersion has moved to pkg_resources._vendor.packaging.version.LegacyVersion. The fact that it's now in _vendor makes me think that it's an internal namespace that I shouldn't be relying on.

Is there a recommended way for me to use setuptools to determine if a version number is valid? Setuptools is already doing that work, so I'd like to take advantage of the existing library, but it seems like now it's not intended for general use?

[jaraco]

Great question. And good instincts. The good news is you can still rely on Version and LegacyVersion from the packaging.version packages, and the fact that the class is coming from the _vendor package is just an artifact of how Setuptools gets packaging. It can't depend on packaging and thus has to vendor it (due to #581).

So the best recommendation, if you wish to determine if a version number is valid, is to use the packaging. But you're also welcome to use the result from pkg_resources.parse_version.

If you wish for packaging.version to be the same class as the one returned by pkg_resources.parse_version, that's a little more difficult, but you _can_ delete the packages in pkg_resources._vendor and pkg_resources will use packaging as installed. I wouldn't recommend that except in specialized cases where you know what you're doing.

Does that help?

[jaraco]

Re-reading your question and thinking about it some more, here's what I recommend.

The most direct and best way to determine if a version number is valid is to simply parse it with packaging.version.Version, which will raise an exception if it's invalid.

But if you're currently relying on the interfaces supplied by setuptools/pkg_resources, the best way to determine if a version is valid may be something like this:

ver = pkg_resources.parse_version(input)
is_legacy = 'Legacy' in ver.__class__.__name__

That approach will work for old and future versions of pkg_resources for as long as I can foresee.