Skip to content

document fallback root in config/api #1178

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

Merged
merged 1 commit into from
Aug 4, 2025
Merged

document fallback root in config/api #1178

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
10 changes: 10 additions & 0 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,16 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
unset (the default), `setuptools-scm` will error if it fails to detect the
version.

`fallback_root: Path | PathLike[str] = "."`
: The directory to use when SCM metadata is not available (e.g., in extracted
archives like PyPI tarballs). This is particularly useful for legacy
configurations that need to work both in development (with SCM metadata)
and from archives (without SCM metadata). Defaults to the current directory.

When SCM metadata is present, the `root` parameter is used; when it's not
available, `fallback_root` is used instead. This allows the same configuration
to work in both scenarios without modification.

`parse: Callable[[Path, Config], ScmVersion] | None = None`
: A function that will be used instead of the discovered SCM
for parsing the version. Use with caution,
Expand Down
31 changes: 31 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,8 +178,24 @@ from setuptools_scm import get_version
version = get_version(root='..', relative_to=__file__)
```

For legacy configurations or when working with extracted archives (like PyPI tarballs),
you may need to specify a `fallback_root` parameter. This is particularly useful
for legacy Sphinx configurations that use `get_version()` instead of getting the
version from the installed package:

```python
from setuptools_scm import get_version
# For legacy Sphinx conf.py that needs to work both in development and from archives
version = get_version(root='..', fallback_root='..', relative_to=__file__)
```

The `fallback_root` parameter specifies the directory to use when the SCM metadata
is not available (e.g., in extracted tarballs), while `root` is used when SCM
metadata is present.

### Usage from Sphinx

The recommended approach for Sphinx configurations is to use the installed package metadata:

``` {.python file=docs/.entangled/sphinx_conf.py}
from importlib.metadata import version as get_version
Expand All @@ -192,6 +208,21 @@ The underlying reason is that services like *Read the Docs* sometimes change
the working directory for good reasons and using the installed metadata
prevents using needless volatile data there.

!!! note "Legacy Sphinx configurations"

If you have a legacy Sphinx configuration that still uses `setuptools_scm.get_version()`
directly (instead of `importlib.metadata`), you may need to use the `fallback_root`
parameter to ensure it works both in development and when building from archives:

```python
from setuptools_scm import get_version
# Legacy approach - use fallback_root for archive compatibility
release = get_version(root='..', fallback_root='..', relative_to=__file__)
version = ".".join(release.split('.')[:2])
```

However, it's strongly recommended to migrate to the `importlib.metadata` approach above.


### With Docker/Podman

Expand Down
Loading