Use case: Introduce VersionInfo.coerce

Situation

Currently, if you parse a version string into a valid semver version, the version string has to consist of at least the major, minor, and patch parts.

However, in some use cases some parts could be missing, for example the patch part.

Proposed Solution

I propose a classmethod VersionInfo.coerce with the following signature:

@classmethod
def coerce(cls, version):
    """
    Convert an incomplete version string into a semver-compatible VersionInfo
    object

    * Tries to detect a "basic" version string (``major.minor.patch``).
    * If not enough components can be found, missing components are
      set to zero to obtain a valid semver version.

    :param str version: the version string to convert
    :return: a tuple with a :class:`VersionInfo` instance (or ``None``
        if it's not a version) and the rest of the string which doesn't
        belong to a basic version.
    :rtype: tuple(:class:`VersionInfo` | None, str)
    """

I’ve chosen coerce as it is a common function name in other semver implementations, for example, node-semver.

An example session:

>>> import semver
>>> semver.VersionInfo.coerce("v1.2")
(VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '')
>>> semver.VersionInfo.coerce("3.5rc1")
(VersionInfo(major=3, minor=5, patch=0, prerelease=None, build=None), 'rc1')

Questions:

• Do you you think such a function could be useful?
• Should the coerce function accept an integer value (=major)? So coerce(2) would be the same as coerce("2") which would return VersionInfo(major=2, minor=0, patch=0, prerelease=None, build=None).
• Anything else you miss, would change, …?

See also

This issue is related to #137

[scls19fr]

I think that’s enough for now. Thanks @tomschr for your contribution.

[tomschr]

@scls19fr Ok, let’s document this. 👍

I’ve opened PR #215 and introduced a new section “Dealing with Invalid Versions”. There I’ve used a modified coerce() function as an example.

It’s a start, I’m not sure if this is enough. What do you think?