setup.cfg 元数据中的“version”条目被忽略

Question

I wanted to write a new Python package that I want to make available via PyPI. In the past I always used setup.py . But this time I decided to embrace new best practices of using setup.cfg instead. So I started reading a little bit of the documentation, mainly https://setuptools.pypa.io/en/latest/userguide/declarative_config.html .

I also decided to use pyscaffold for the generation of the files. pyscaffold generated a setup.cfg file for me and I added (just for testing purposes) version = 5.1.1 in under the metadata section, as described in the documentation above.

For convenience I'm using anaconda and created a new empty environment:

$ python --version
Python 3.9.7
$  pip list
...
PyScaffold                    4.1.1
setuptools                    58.4.0
setuptools-scm                6.3.2
wheel                         0.37.0

But when I executed pip install -e . , the version was ignored and pip assigned a different one:

$ pip install -e .
Obtaining file:///tmp/test_package
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Installing collected packages: test-package
  Attempting uninstall: test-package
    Found existing installation: test-package 0.0.post1.dev10+g3ed39c8.d20211106
    Uninstalling test-package-0.0.post1.dev10+g3ed39c8.d20211106:
      Successfully uninstalled test-package-0.0.post1.dev10+g3ed39c8.d20211106
  Running setup.py develop for test-package
Successfully installed test-package-0.0.post1.dev1+g228b46c

https://stackoverflow.com/a/27077610/1480131 mentions that setuptools version 30.3.0 supports putting metadata in setup.cfg , I'm using 58.4.0 , so a much more recent version.

I also tested with different formats like version = file:VERSION.txt but that didn't help either, pip simply ignores the version entry.

What am I missing? What am I doing wrong?

I prepared a small git repo with the files in order to be able to reproduce the error: https://github.com/shaoran/test_package Does anybody get a different result?

Answer 1

That's because pyscaffold generated a project that uses setuptools-scm for version detection. When setuptools-scm is used, the version is not read from version metadata, but parsed from the repository tags. The version 0.0.post1.dev10+g3ed39c8.d20211106 can be read as follows:

• 0.0.post1 - dummy version since you don't have any tags in repo yet;
• dev10 - you have ten commits that are not included in any version tag (basically the amount of commits you made since tagging last);
• g3ed39c8 - the short hash of commit you have installed from is 3ed39c8 (prefix g means it is a Git repo);
• d20211106 - d means you have installed from a dirty state (some files versioned by Git were modified), the rest is just the timestamp.

If you want to use the version metadata from setup.cfg instead, just drop setuptools-scm activation in setup.py :

if __name__ == "__main__":
    try:
        setup()
    except:
        ...

You can then also clean up pyproject.toml , although this isn't required explicitly:

[build-system]
requires = ["setuptools>=46.1.0", "wheel"]
build-backend = "setuptools.build_meta"

If you want to keep using setuptools-scm (which IMO is a great tool to prevent you from accidentally releasing dists with same version, but different contents), then just add a new tag to start versioning from:

$ git tag -a 5.1.1 -m 'start versioning'

If you had a clean repo state (no modified files), pip install -e . will install the version 5.1.1 right away. Otherwise, you will get a 5.1.1 with a suffix.

The neat part of using setuptools-scm is that the version metadata in setup.cfg is ignored, so you don't have to bump it yourself and can safely remove version = 5.1.1 line.