Document how setuptools_scm works

[cdeil]

I've been reading through your docs https://github.com/pypa/setuptools_scm/blob/master/README.rst and I'm having a hard time to figure out how setuptools_scm works.

---

Question 1:

I see an option use_scm_version is passed to setuptools.setup.
Looking at the docs for setuptools https://setuptools.readthedocs.io/en/latest/ I can't find this option!? (might have missed it, unfortunately those docs don't have the normal Sphinx search field!?)
Is this option to setuptools.setup somehow an extension that's provided by the setuptools_scm package itself?

---

Question 2:

Does setuptools_scm ever generate a file with a version number?
The docs mention PKG-INFO under:
https://github.com/pypa/setuptools_scm/blob/master/README.rst#builtin-mechanisms-for-obtaining-version-numbers
Does setuptools_scm compute or directly store a version number in PKG-INFO or some other file?

---

Please consider this issue as a documentation request for people like me, that would like to understand how setuptools and setuptools_scm work and for which of my projects I should consider using setuptools_scm. (I guess all Python / git projects?)

Some extra sentences and links to relevant info (e.g. https://www.python.org/dev/peps/pep-0314/) would help.

Links to a few packages using setuptools_scm as "working examples" that I can look at and play around with before trying to modify my existing packages would also be very useful.

[RonnyPfannschmidt]

@cdeil thanks for bringing those points that need clarification to attention,
i will put a short rundown into this ticket so we can tackle a more detailed explanation for actual sphinx documentation later on

1. setuptools has an extension system to allow python packages to declare new keyword arguments to setup using entrypoints

this is similar to how console_scripts and gui_scripts works

2. PKG-INFO is a file generated by setuptools/distutils using the metadata from from the distribution object that is internal to setuptools/distutils

setuptools_scm has an optional tool that allows to write the version to text/python files using the albeit badly documented write_to argument

by default setuptools_scm does not write to any files, it only sets the version attribute of the distribution object used by setuptools/distutils

im using it with virtually all of my packges, - pytest-xdist, iniconfig, sentaku are just a few examples

[RonnyPfannschmidt]

another user was introduced by borgbackup/borg#161 :)

[WhyNotHugo]

Another point missing clarification is package data files.

It seems that setuptools-scm makes git-tracked file inside python modules get installed (if include_package_data is True), but this isn't clearly documented, and I've recently seen some breakage surrounding this (and I'm not even sure if something broke, or it only worked-by-coincidence before).

[RonnyPfannschmidt]

@hobarrera the surrounding breakage was setuptools ignoring sdist metadata in a major release, there is nothing we can do about that

[WhyNotHugo]

Right, I wasn't complaining about the breakage per se, just pointing out that the entire feature is mostly undocumented on setuptool-scm's side, so I wasn't sure if the previous behaviour was expected, or the current one was (eg: maybe I was just relying on a bug).

While we're on that topic though (slight OT for this thread though): this should be fixed in future by setuptools?

[RonnyPfannschmidt]

@hobarrera the setuptools bug will be fixed by setuptools,

btw, the file finders are mentionend in the readme, its not really comprehensible that way

unfortunately i rarely find the time to work on documentation atm

[maphew]

It took me some experimenting to figure out how to use the keywords instead of the default use_scm_version=True, so here's an example for the docs:

scm_version_options = {
    'write_to' : 'core/version.py'
    }

setup(
    ...
    use_scm_version = scm_version_options,
    setup_requires=['setuptools_scm'],
    ...
    )

[Kentzo]

@RonnyPfannschmidt Would you consider enabling wiki with community access?

[nealmcb]

Another thing I don't understand, along these lines. I'm using setuptools_scm just fine, somehow miraculously, since I never installed it. After searching a bit more, it seems that the setup_requires option does background installations of packages, not via pip, for any invocation of setup.py (even a "setup.py clean" step).
Ouch, as noted at what seems to me the aptly-named issue Avoid using setup_requires parameter in setup.py. #136 in another package.

Surely I'm missing something here. I'm used to installing the software I use to do a build up-front. That allows me to use the build software to find out what would be built, and, in this case, what version would be given to the package that is built. It also allows the from setuptools_scm import get_version command to work.

Can you document how to use setuptools_scm without requiring the use of setup_requires?
Or is it still necessary, even if this package is installed locally?

[RonnyPfannschmidt]

as soon as setuptools_scm is available in the local workingset it will no longer try to install it in .eggs

[RonnyPfannschmidt]

the general goal here is to slowly get people to use PEP-517/518 and let pip sort it out with a ephemeral env

[cdeil]

I tried setuptools_scm again today.

Couldn't figure out how to get a version number into the release sdist.

I have a git tag "v0.1" but apparently it's not found by setup.py. setuptools_scm only seems to work with pip, but to make a release, I need to run python setup.py sdist, no?

Looking through the docs of setuptools_scm I couldn't find this basic info concerning making a release.

😞

$ python setup.py build sdist
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'use_scm_version'
  warnings.warn(msg)
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'setup_requires'
  warnings.warn(msg)
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'install_requires'
  warnings.warn(msg)
running build
running build_py
running sdist
running check
warning: check: missing required meta-data: version

reading manifest template 'MANIFEST.in'
writing manifest file 'MANIFEST'
creating multinorm-0.0.0
making hard links in multinorm-0.0.0...
hard linking LICENSE -> multinorm-0.0.0
hard linking README.rst -> multinorm-0.0.0
hard linking multinorm.py -> multinorm-0.0.0
hard linking setup.py -> multinorm-0.0.0
creating dist
Creating tar archive
removing 'multinorm-0.0.0' (and everything under it)

$ python setup.py egg_info
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'use_scm_version'
  warnings.warn(msg)
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'setup_requires'
  warnings.warn(msg)
/Users/deil/software/anaconda3/envs/multinorm/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'install_requires'
  warnings.warn(msg)
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

error: invalid command 'egg_info'