suggestion(semver): Parse python versions

[justinmchase]

Python versions don't actually conform to semantic versioning and if you have a need to parse them then using this library can be difficult.

I wrote a little helper which could theoretically be integrated into this library if you wanted to be flexible with the parsing. I will put it here just in case.

function parse(versionString: string) {
  // Python version documentation:
  // https://peps.python.org/pep-0440/#public-version-identifiers
  //
  // supports converting _most_ python versions into common semver
  // [N!]N(.N)*[{a|b|rc}N][.postN][.devN]
  //
  // | example      | result        |
  // | ------------ | ------------- |
  // | 0.13.1a0     | 0.13.1-a.0    |
  // | 0.13.1b0     | 0.13.1-b.0    |
  // | 0.13.1rc0    | 0.13.1-rc.0   |
  // | 0.13.1.dev0  | 0.13.1-dev.0  |
  // | 0.13.1.post0 | 0.13.1-post.0 |
  //
  const py = versionString.match(
    /^(\d+)[.](\d+)[.](\d+)[.]?(a|b|rc|dev|post)(\d+)$/,
  );
  if (py) {
    const [, major, minor, patch, pre, dev] = py;
    versionString = `${major}.${minor}.${patch}-${pre}.${dev}`;
  }

  // supports converting partial versions such as 1, 1.0 into valid semantic versions.
  if (versionString.match(/^\d+$/)) {
    versionString = `${versionString}.0.0`;
  } else if (versionString.match(/^\d+[.]\d+$/)) {
    versionString = `${versionString}.0`;
  }
  
  return semver.parse(versionString);
}

[lionel-rowe]

The PEP gives the full regex for parsing parts from a version identifier. That can handle some pretty gnarly identifiers that I don't think can be losslessly converted to/from semver:

const re = new RegExp(String.raw`
    v?
    (?:
        (?:(?P<epoch>[0-9]+)!)?                           # epoch
        (?P<release>[0-9]+(?:\.[0-9]+)*)                  # release segment
        (?P<pre>                                          # pre-release
            [-_\.]?
            (?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)
            [-_\.]?
            (?P<pre_n>[0-9]+)?
        )?
        (?P<post>                                         # post release
            (?:-(?P<post_n1>[0-9]+))
            |
            (?:
                [-_\.]?
                (?P<post_l>post|rev|r)
                [-_\.]?
                (?P<post_n2>[0-9]+)?
            )
        )?
        (?P<dev>                                          # dev release
            [-_\.]?
            (?P<dev_l>dev)
            [-_\.]?
            (?P<dev_n>[0-9]+)?
        )?
    )
    (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
`.replaceAll('?P<', '?<').replaceAll(/#.+|\s+/gm, ''), 'i')

const version = '2!0.2.3.5.3alpha99-post.3.DEV12+9a-9b-9c'
version.match(re).groups
// {
//     dev: ".DEV12",
//     dev_l: "DEV",
//     dev_n: "12",
//     epoch: "2",
//     local: "9a-9b-9c",
//     post: "-post.3",
//     post_l: "post",
//     post_n2: "3",
//     pre: "alpha99",
//     pre_l: "alpha",
//     pre_n: "99",
//     release: "0.2.3.5.3",
// }

E.g. there's no concept of "epoch" in semver, nor any way of representing a version increment smaller than "patch".

[justinmchase]

I don't think can be losslessly converted to/from semver...

Very nice, I don't think its fully lossless but the build metadata is pretty flexible so maybe the extra components could be added there in a consistent way?

function py2semver(opts: PyVersion) {
  const { dev, dev_l, dev_n, epoch, local, post, post_l, post_n2, pre, pre_l, pre_n, release } = opts;
  const [major, minor, patch,...smaller] = release.split('.');
  return {
    major,
    minor,
    patch,
    prerelease: pre ? [pre_l, pre_n ?? 0] : [],
    metadata: [smaller?.join('.'), post_l, post_n2, dev_l, dev_n, local?.replace('-', '.'), epoch].filter(m => m) 
  };
}
const versionString = '2!0.2.3.5.3alpha99-post.3.DEV12+9a-9b-9c'
semver.format(py2semver(versionString.match(re).groups));

// 0.2.3-alpha.99+5.3.post.3.DEV.12.9a.9b.9c.2

If it was really important for it to be lossless you'd probably need some kind of syntax to indicate which part was which.