Should the effect version stamping achieves be preserved?

[EliahKagan]

Much of the dynamic logic in setup.py serves the purpose of stamping the package version into __version__, which starts out as "git". When, or before, the project definition is made declarative, as discussed in comments in #1716, the version stamping logic needs to be removed.

From the discussion there, it seems a goal is to have pyproject.toml become the single source of the version, and to use importlib.metadata to retrieve it when accessed as git.__version__ (with the importlib_metadata backport used on 3.7).

Changes in #1886 have the additional effect of making it so this can be done at any time, since there is already a mechanism in place, and in use for some other attributes, to provide dynamically computed attributes of the top-level git module, and already tests to verify that other attribute access there, and the robustness of static type checking, are not broken by it.

The question is what the logic should actually be. A common and straightforward approach is to simply use importlib.metadata.version on the known package name to always return the version from when the package was installed (whether that was from a local directory, editably or not, or from an sdist or wheel, obtained automatically from PyPI or otherwise). For example, the jsonschema library contains this code:

def __getattr__(name):
    if name == "__version__":
        warnings.warn(
            "Accessing jsonschema.__version__ is deprecated and will be "
            "removed in a future release. Use importlib.metadata directly "
            "to query for jsonschema's version.",
            DeprecationWarning,
            stacklevel=2,
        )

        from importlib import metadata
        return metadata.version("jsonschema")
    elif ...

This can of course be done without deprecating __version__ by simply omitting the warning.

However, it may not always work quite how one wants. For example, if one makes an editable install, and then pulls changes that increase the version number, the old version number that was installed with will still be used. This could be confusing, and this sort of thing may have been part of why the complex version stamping logic in setup.py was introduced, or perhaps more likely, of why it has been kept.

I believe, though, that we can achieve something effectively equivalent to that, by using other facilities of importlib.metadata, and other metadata such as the __file__ variable, to check for the same conditions under which the version would have been stamped, return it in those cases, and otherwise return "git" instead, as with version stamping.

That the version "git" is used is itself potentially confusing, since, for example, when installing from a commit, branch, or tag by giving pip a git+https:// URL -- as well as simply doing a non-editable install from a clone and accessing it from a directory other than the root of the repository's working tree -- one already gets the stamped version number originally from VERSION, rather than "git". However, on the whole, it may be that this behavior is desirable and ought to be preserved so long as doing so does not turn out to be excessively complex.

If GitPython is also to deprecate __version__, then of course that should not be done. The simpler approach would certainly be best then, I would say. However, as noted in #1716 (comment), the readme currently says to report git.__version__ when reporting bugs, so if it is to be deprecated then that should be removed or changed to some other recommendation.

What should be done here?

[Byron]

Thanks for bringing this up!

To me it seems going with the simple version and deprecating __version__ at the same time is the way to go as Python seems to move away from the __version__ approach. The current behaviour is probably quite anachronistic, and nothing to hold on to, given its own problems and inconsistencies.

Thanks to your work, in huge parts, I think using deprecations generously leads the way to an eventual version 4.0 with moderately breaking changes, for a GitPython that will feel more modern than ever.