Skip to content

Commit

Permalink
docs: clarify usage of version files
Browse files Browse the repository at this point in the history
I found the current discussion around version files somewhat
confusing.

When you're reading the usage guide, the second point is telling you
to make a version file; strongly implying you should.  But in reality,
you most likely do not need to bother with keeping a specific version
file.  Explain more clearly about the implications of this.

Under this is a section on using `python -m setuptools_scm --help`
which seems like an orphan from the "as a cli" section; move it down
there.

The runtime section starts by telling you what is strongly discouraged
without explaination why.  Make it clearer by giving the first example
as the most supported thing, which is using standard importlib; then
briefly discuss the version file from above, explaining what's in it
for a standard Python template, then the strongly discouraged direct
import method.

In the config doc, update to discuss `importlib` for consistency.

Correct some capitalization and other minor formatting bits while
we're here.
  • Loading branch information
ianw committed Aug 23, 2024
1 parent 6eb52e6 commit 4b29ab9
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 43 deletions.
2 changes: 1 addition & 1 deletion docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
`version_file: Path | PathLike[str] | None = None`
: A path to a file that gets replaced with a file containing the current
version. It is ideal for creating a ``_version.py`` file within the
package, typically used to avoid using `pkg_resources.get_distribution`
package, typically used to avoid using `importlib.metadata`
(which adds some overhead).

!!! warning ""
Expand Down
6 changes: 3 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ or [configuring Git archive][git-archive-docs].

[git-archive-docs]: usage.md#builtin-mechanisms-for-obtaining-version-numbers

## basic usage
## Basic usage

### with setuptools
### With setuptools

Note: `setuptools_scm>=8` intentionally doesn't depend on setuptools to ease non-setuptools usage.
Please ensure a recent version of setuptools (>=64) is installed.
Expand All @@ -37,7 +37,7 @@ dynamic = ["version"]
```


### with hatch
### With hatch

[Hatch-vcs](https://github.com/ofek/hatch-vcs) integrates with setuptools_scm
but provides its own configuration options,
Expand Down
98 changes: 59 additions & 39 deletions docs/usage.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Usage

## at build time
## At build time

The preferred way to configure `setuptools_scm` is to author
settings in the `tool.setuptools_scm` section of `pyproject.toml`.
Expand All @@ -25,7 +25,9 @@ that support PEP 518 ([pip](https://pypi.org/project/pip) and
[pep517](https://pypi.org/project/pep517/)).
Tools that still invoke `setup.py` must ensure build requirements are installed

### version files
### Version files

Version files can be created with the ``version_file`` directive.

```toml title="pyproject.toml"
...
Expand All @@ -34,15 +36,13 @@ version_file = "pkg/_version.py"
```
Where ``pkg`` is the name of your package.

Unless the small overhead of introspecting the version at runtime via
`importlib.metadata` is a concern or you need a version file in an
alternative format such as plain-text (see ``version_file_template``)
you most likely do _not_ need to write a separate version file; see
the runtime discussion below for more details.

```commandline
$ python -m setuptools_scm
# To explore other options, try:
$ python -m setuptools_scm --help
```

## as cli tool
## As cli tool

If you need to confirm which version string is being generated
or debug the configuration, you can install
Expand All @@ -65,46 +65,32 @@ $ python -m setuptools_scm ls # output trimmed for brevity
...
```

!!! note "committed files only"
!!! note "Committed files only"

currently only committed files are listed, this might change in the future

!!! warning "sdists/archives don't provide file lists"

currently there is no builtin mechanism
to safely transfer the file lists to sdists or obtaining them from archives
coordination for setuptools and hatch is ongoing
Currently there is no builtin mechanism
to safely transfer the file lists to sdists or obtaining them from archives.
Coordination for setuptools and hatch is ongoing.

## at runtime (strongly discouraged)

the most simple **looking** way to use `setuptools_scm` at runtime is:

```python
from setuptools_scm import get_version
version = get_version()
```
To explore other options, try


In order to use `setuptools_scm` from code that is one directory deeper
than the project's root, you can use:

```python
from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)
```commandline
$ python -m setuptools_scm --help
```

## At runtime

## Python package metadata


### Python Metadata


### version at runtime

If you have opted not to hardcode the version number inside the package,
you can retrieve it at runtime from [PEP-0566](https://www.python.org/dev/peps/pep-0566/) metadata using
The standard method to retrieve the version number at runtime is via
[PEP-0566](https://www.python.org/dev/peps/pep-0566/) metadata using
``importlib.metadata`` from the standard library (added in Python 3.8)
or the [`importlib_metadata`](https://pypi.org/project/importlib-metadata/) backport:
or the
[`importlib_metadata`](https://pypi.org/project/importlib-metadata/)
backport for earlier versions:

```python title="package_name/__init__.py"
from importlib.metadata import version, PackageNotFoundError
Expand All @@ -116,6 +102,40 @@ except PackageNotFoundError:
pass
```

### Via your version file

If you have opted to create a Python version file via the standard
template, you can import that file, where you will have a ``version``
string and a ``version_tuple`` tuple with elements corresponding to
the version tags.

```python title="Using package_name/_version.py"
import package_name._version as v

print(v.version)
print(v.version_tuple)
```

### Via setuptools_scm (strongly discouraged)

While the most simple **looking** way to use `setuptools_scm` at
runtime is:

```python
from setuptools_scm import get_version
version = get_version()
```

it is strongly discouraged to call directly into `setuptools_scm` over
the standard Python `importlib.metadata`.

In order to use `setuptools_scm` from code that is one directory deeper
than the project's root, you can use:

```python
from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)
```

### Usage from Sphinx

Expand All @@ -132,7 +152,7 @@ the working directory for good reasons and using the installed metadata
prevents using needless volatile data there.


## with Docker/Podman
### With Docker/Podman


In some situations, Docker may not copy the `.git` into the container when
Expand Down

0 comments on commit 4b29ab9

Please sign in to comment.