Generates a version string from VCS state.
Uses a constrained but useful subset of the full functionality of setuptools_scm (https://github.com/pypa/setuptools_scm). These constraints avoid pitfalls in the interaction of setuptools_scm with Pants's hermetic environments.
In particular, we ignore any existing setuptools_scm config. Instead you must provide a subset of that config in this target's fields.
If you need functionality that is not currently exposed here, please reach out to us at [Getting help](🔗).
Backend: <span style="color: purple"><code>pants.backend.experimental.python</code></span>
## <code>generate_to</code>
<span style="color: purple">type: <code>str</code></span> <span style="color: green">required</span>
Generate the version data to this relative path, using the template field.
Note that the generated output will not be written to disk in the source tree, but will be available as a generated dependency to code that depends on this target.
## <code>template</code>
<span style="color: purple">type: <code>str</code></span> <span style="color: green">required</span>
Generate the version data using this format string, which takes a version format kwarg.
E.g., 'version = "{version}"'
## <code>description</code>
<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>None</code></span>
A human-readable description of the target.
Use `./pants list --documented ::` to see all targets with descriptions.
## <code>python_resolve</code>
<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>None</code></span> backend: <span style="color: green"><code>pants.backend.experimental.python</code></span>
The resolve from `[python].resolves` to use.
If not defined, will default to `[python].default_resolve`.
All dependencies must share the same value for their `resolve` field.
## <code>tag_regex</code>
<span style="color: purple">type: <code>str | None</code></span> <span style="color: green">default: <code>'^(?:[\\w-]+-)?(?P<version>[vV]?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$'</code></span>
A Python regex string to extract the version string from a VCS tag.
The regex needs to contain either a single match group, or a group named version, that captures the actual version information.
Note that this is unrelated to the tags field and Pants's own tags concept.
See https://github.com/pypa/setuptools_scm for implementation details.
## <code>tags</code>
<span style="color: purple">type: <code>Iterable[str] | None</code></span> <span style="color: green">default: <code>None</code></span>
Arbitrary strings to describe a target.
For example, you may tag some test targets with 'integration_test' so that you could run `./pants --tag='integration_test' test ::` to only run on targets with that tag.