Official Python API for getting KiCad version

[Simon Richter]

Since we don't have a stable Python API for the foreseeable future, it would make sense to have a single stable API entry point to get the KiCad version from Python, so scripts can be adapted to work with multiple different versions.

[Thomas Pointhuber (pointhi)]

I did some initial work to implement such an abstraction layer:

https://github.com/pointhi/kicad-python

[Wayne Stambaugh (stambaughw)]

We should try to make this happen during v6 development. I suspect a lot of folks are going to want input on this.

[Simon Richter (sjr)]

I had hoped to get something like that in 5.1 already — that's why I limited the scope to "get the version information" in order to make this the only API that we need to commit on for now.

[Wayne Stambaugh (stambaughw)]

@Simon, is the function GetBuildVersion() adequate or do you need something different? This is the function used throughout KiCad to fetch the version string.

[Simon Richter (sjr)]

@Wayne, that has all the information, but using that from a script would require parsing the string, which may contain an arbitrary number of dashes in the base tag name and then splits off the number of commits and the git commit ID with more dashes, so I'd think this would be too difficult to use reliably.

The entire point of making this the first official API is that it allows us to say "any version from X onward has this other API", or "we sadly had to rename this API in version Y". The main requirement for the version API is that it will have to remain stable and easy to use in order to be useful.

Maybe the most useful for now would be the nightly commit counter, because that allows simple numerical comparison:

    ver = GetNumericalVersion();

    assert (ver >= 12345), "KiCad version too old"

    Select Case ver
        Case 12345 <= ver < 23456: route_track(...)
        Case 23456 <= ver < 34567: route_trace(...) # API got renamed
    End Select

[Wayne Stambaugh (stambaughw)]

@Simon, I was thinking something cheap and dirty like exposing GetBuildVersion() but your assertion is correct that there may be some issues using the KiCad build string. The issue I see with your solution that git is not always available for builds so using the `git rev-list --count` cannot be ensured. The only way I know is to have a header that we manually update whenever we change any of the exposed pcbnew api but that is probably not going to be any more reliable because it depends on devs remembering to increment the python api counter. I'm open to suggestion on this one.

[Simon Richter (sjr)]

If git is unavailable, the user needs to set a CMake variable, unless they are building from a release tarball. That should work for everyone, the only downside is that it requires that whoever prepares the release to give a default to that variable (as well as adjusting KICAD_VERSION).

[KiCad Janitor (kicad-janitor)]

KiCad bug tracker has moved to Gitlab. This report is now available here: https://gitlab.com/kicad/code/kicad/-/issues/2238