Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: clarify usage of version files #1069

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify usage of version files #1069

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/config.md
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
Loading