Build docs from pylock.toml#149058
Conversation
uv pip compile Doc/requirements.txt \ --exclude-newer P14D \ --no-cache \ --output-file Doc/pylock.toml \ --python-version 3.10 \ --universal
|
On hold pending: pypa/packaging#1178 |
|
It might work if you can afford to remove |
|
Thanks! That's working, we can use this in the short term, as I expect tooling will re-add it when relocking. Trying to install with 3.11 gives this error, which is clear enough: |
|
|
||
| [[packages]] | ||
| name = "python-docs-theme" | ||
| version = "2026.3" |
There was a problem hiding this comment.
Hmm, I'd prefer to keep our bug fixes, can we exclude certain packages (i.e., first party packages) from the 14 day rule?
There was a problem hiding this comment.
Yes we can with something like:
--exclude-newer-package python-docs-theme=PT0S
Are there any others we'd want to exclude? Perhaps linklint?
| wheels = [{ url = "https://files.pythonhosted.org/packages/04/54/6f679c435d28e0a568d8e8a7c0a93a09010818634c3c3907fc98d8983770/roman_numerals-4.1.0-py3-none-any.whl", upload-time = 2025-12-17T18:25:33Z, size = 7676, hashes = { sha256 = "647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7" } }] | ||
|
|
||
| [[packages]] | ||
| name = "roman-numerals-py" |
There was a problem hiding this comment.
I wonder what is pulling this in, it is deprecated in favour of roman-numerals which we already install.
There was a problem hiding this comment.
Sphinx 8.2.3 depends on it:
https://github.com/sphinx-doc/sphinx/blob/v8.2.3/pyproject.toml#L84
And we can't upgrade to Sphinx 9 yet:
There was a problem hiding this comment.
What about make.bat?
And the docs build workflow:
There was a problem hiding this comment.
Is there a way to ensure this is consistent with the `requirements.txt?
There was a problem hiding this comment.
We could run the lock command in CI and fail if the lockfile changes?
Although that will have to wait for a packaging release with pypa/packaging#1178, we need to manually edit the lockfile for now.
Background
As discussed in the last Docs WG meeting, maintaining the docs builds in older branches can be difficult, because of differing dependencies and version support. And especially for the oldest branches, which are rarely updated, and rarely rebuilt, so we don't see failures.
A docs build is essentially an application: we want to install a given set of deps each time. We have some limited pinning in
Doc/requirements.txtandDoc/constraints.txt, but usually just upper or lower bounds, and this doesn't include all transitive dependencies.A lockfile would help towards reproducible builds.
pip and pylock.toml
The newest pip 26.1 (released yesterday) now comes with experimental support for installing from pylock.toml lockfiles 🎉
pip has had experimental support for generating lockfiles for a year, since 25.1, however:
So if I create a lockfile on macOS, you can't use it on Linux because it only lists macOS wheels. So we need another tool, such as uv or pyenv, to create a universal lockfile.
I created it with:
And updated the Makefile to consume the lockfile by default instead of requirements.txt.
Testing: the docs build succesfully on macOS with
make -C Doc clean venv htmllive, using both pip and uv, and also on Read the Docs (Linux/uv) (build, docs).Experimental
The pip team make it clear that their pylock.toml support is experimental, and can be modified/deprecated/removed without notice, but also that they need feedback in order to get this production ready.
I think we are well placed to help try this feature out and give feedback. We might not want to backport this all the way back just yet. We could also/instead use this in our other docs sites, such as the devguide, although we don't have as strong a need for a lockfile there.
📚 Documentation preview 📚: https://cpython-previews--149058.org.readthedocs.build/