Option to let version_file take precedence

[tomas16]

Context: I'd like to define a "release version" in a file, and then use git versioning for commits in between official releases. Our package generates data and for reproducibility we access the full version number at runtime and save it along with the data.

The documentation about version_file says:

Please take into account that version_file is ignored if any tag is present in the current branch.

This creates the following problems:

• Our repo initially only had a main branch, and as it grew we added a develop branch and have a lightweight form of git-flow going on. Since develop branched from the main branch, which already had some version tags, the version_file is ignored for all eternity.
• Even if that weren't the case, if we update the version file on develop and then merge into main, the version file is ignored again. Even though tags are really just for convenience and the ground truth release version is contained in a file, if we forget to add the tag on main, the version reverts to the previous tag.

I looked into using version_callback instead. I tried adding a __release_version__ = "0.1.0" string inside __init__.py and in a separate _version.py file. The respective entries in pyproject.toml I tried are version_callback = "mypackage:__release_version__" and version_callback = "mypackage._version:__release_version__"

However I ran into some issues with this as well:

• I can't get setuptools-git-versioning to actually use this string. I'm getting packaging.version.InvalidVersion: Invalid version: 'mypackage._version.__release_version__' when I either pip install -e . or run python -m setuptools_git_versioning in a terminal. Strangely, when I run that last command in a debugger it spits out the correct version number.
• Even if I can get past this problem, there's another one I don't see a way around. Since I need the full version number, including any "post" and "git" suffixes at runtime, I'm using the importlib method. However, when the package hasn't been installed, I don't ignore the PackageNotFoundError and instead tell users to install the package first. The problem is whenever setuptools-git-versioning would try to import the callback, __init__.py would get imported as well, and we'd get this PackageNotFoundError since we're in the process of installing the package.

Maybe I'm not using this tool right, so I'm open to suggestions.
My request however, would be to add an option to let version_file take precedence over any git tags. That would solve the whole problem.

[dolfinus]

Hi.

Could you please provide your pyproject.toml?

It is possible that these lines are missing in the config:

[build-system]
# __legacy__ is required to have access to package
# during build step
build-backend = "setuptools.build_meta:__legacy__"

[project]
dynamic = ["version"]

[tomas16]

Thanks. It works with the legacy part. I had tried it before but I guess something else must've been messing it up.

However, the key point was that I want the version number to come from a file and not get overridden by whether or not there's a tag in the git history. The idea is that at any given point in the git history, the version number is whatever is in the file, plus the suffix postN.+sha1.dirty.

This is the behavior of the file-based versioning scheme, but I want it to ignore tags.

I've tried an alternative method where I use the callback-based scheme, which ignores tags, but doesn't add the suffix. I was able to solve the importlib related issue by placing the callback in a .py file outside of the package:

.
├── pyproject.toml
└── src
    ├── _version.py
    └── mypackage
        ├── __init__.py
        └── ...

Contents of version.py:

__release_version__ = "0.1.1"

Relevant part of pyproject.toml:

[build-system]
requires = ["setuptools >= 61.0", "setuptools-git-versioning"]
build-backend = "setuptools.build_meta:__legacy__"

[tool.setuptools-git-versioning]
enabled = true
version_callback = "_version:__release_version__"

The problem is now the version number is always "0.1.1", even when I'm 20 commits ahead of when I last updated that version number. Versioning like this can be done without setuptools-git-versioning, like so:

pyproject.toml:

[tool.setuptools.dynamic]
version = {attr = "mypackage.__version__"}

mypackage/__init__.py:

__version__ = "0.1.1"

So this is really a feature request. One of two ways:

• provide an option to let the file-based versioning scheme ignore git tags (I have a slight preference for this approach)
• provide an option to let the callback-based versioning scheme add a suffix to what's returned from the callback

I'd be happy to submit a patch for either approach. But before I put in the effort, I want to make sure you're on board with such a feature.

[tomas16]

I figured out a way to do what I want.... more or less.

pyproject.toml:

[tool.setuptools-git-versioning]
enabled = true
version_file = "VERSION"
count_commits_from_version_file = true
tag_filter = "$^"       # ignore tags

The regular expression in tag_filter matches nothing, so tags are ignored in favor of the version_file.

There's one remaining issue I can live with: this will always use the dev_template or dirty_template. So even when the version number was updated in the last commit, you get something like 0.1.2.post0+git.b0ce782f instead of just 0.1.2.

According to the documentation, this is expected as template is only used if the current commit has been tagged.

So an updated feature request could be: "use template when ccount == 0 and there are no uncommitted or untracked changes."

Finally, the tag_filter trick kind of contradicts the documentation here:

This option is completely ignored if Read some file content as current version schema is used. This is because all tags are set on master / main branch, so commits to other branches like develop are tagless.

I guess it's only implicitly ignored, because the assumption is there are no tags in the first place.

[sztomi]

I ran into this exact problem in a repo that uses tags, but not for versioning. For me, it would be less surprising behavior to use the version_file when it is set in the config, regardless of the existence of tags. Even better, a separate field could explicitly set the desired version scheme instead of the current fallback behavior. Thanks for posting a workaround @tomas16!

[dolfinus]

I honestly don't understand why not just use something like this:
https://github.com/MobileTeleSystems/onetl/blob/aa6f11c51550b3b0316b2875b1db727773f8a169/setup.py#L11

It just reads version from a file, and then adds .dev${BUILD_ID} suffix if necessary. No need to check for latest tag in the branch. No need to calculate count of commits since this tag or since last change of VERSION file. No version collisions if package is built on different branches with exactly the same number of commits.

[sztomi]

@dolfinus I am using a version file, in fact. But (without the workaround above) it is currently ignored if tags exist.

[dolfinus]

Try v2.0.0, it now ignores tags if version_file is used