Allow cross-platform consistency in local file paths for `pylock.toml` exports

[ncoghlan]

Summary

When exporting to pylock.toml, uv currently emits absolute file URLs on all platforms. The "URLs" emitted on windows dump in the raw Windows path, including the use of backslash separators instead of forward slash ones.

This is inconvenient when the local files should be located relative to the lock file (e.g. when they're stored in Git LFS).

Proposed changes:

• always use POSIX path separators in pylock.toml, even on Windows
• emit relative path entries rather than absolute url entries where possible
• emit absolute path entries on Windows if the files referenced are on a different drive from the lock file export location

There could potentially be a config flag to force the use of absolute paths (that may still be useful for some use cases where the files are in known locations on target systems of interest, but the location of the lock file itself at installation time isn't the same as it's location when being exported)

Example

No response

[charliermarsh]

I think those changes generally match how we treat paths in uv.lock (normalize to forward slashes, relativize if possible, fallback to absolute). I can't remember if relative paths are "allowed" under the pylock.toml spec.

[konstin]

They are, I asked for that to be part of the spec to mirror the uv.lock capability https://packaging.python.org/en/latest/specifications/pylock-toml/#packages-directory-path

[charliermarsh]

Do you mind providing an example? I think we already do this in some cases so want to understand when we're getting it wrong.

[ncoghlan]

Adding debug logging to the venvstacks test_local_wheels test case to dump the contents of pyproject.toml, uv.lock, and pylock.toml gives the following for one of the layers that includes two wheels located via --find-links.

As Charlie expected, uv.lock has a relative POSIX-style path in its registry data, so its specifically uv export that is generating the absolute Windows-style paths.

pyproject.toml:

[project]
name = "framework-both-wheels"
version = "0"
dependencies = ["venvstacks-testing-dynlib-consumer", "venvstacks-testing-dynlib-publisher"]
requires-python = "==3.11.*"

[tool.uv]
no-index = true
no-build = true
find-links = ["C:\\Users\\Alyssa\\AppData\\Local\\Temp\\tmpo1yqij0_\\wheels"]
constraint-dependencies = []

uv.lock:

version = 1
revision = 3
requires-python = "==3.11.*"

[[package]]
name = "framework-both-wheels"
version = "0"
source = { virtual = "." }
dependencies = [
    { name = "venvstacks-testing-dynlib-consumer" },
    { name = "venvstacks-testing-dynlib-publisher" },
]

[package.metadata]
requires-dist = [
    { name = "venvstacks-testing-dynlib-consumer" },
    { name = "venvstacks-testing-dynlib-publisher" },
]

[[package]]
name = "venvstacks-testing-dynlib-consumer"
version = "1.0.0"
source = { registry = "../../../tmpo1yqij0_/wheels" }
wheels = [
    { path = "venvstacks_testing_dynlib_consumer-1.0.0-cp311-abi3-win_amd64.whl" },
]

[[package]]
name = "venvstacks-testing-dynlib-publisher"
version = "1.0.0"
source = { registry = "../../../tmpo1yqij0_/wheels" }
wheels = [
    { path = "venvstacks_testing_dynlib_publisher-1.0.0-cp311-abi3-win_amd64.whl" },
]

pylock.toml:

lock-version = "1.0"
created-by = "uv"
requires-python = "==3.11.*"

[[packages]]
name = "venvstacks-testing-dynlib-consumer"
version = "1.0.0"
index = "file:///C:/Users/Alyssa/AppData/Local/Temp/tmpu8r76ysx/wheels"
wheels = [{ url = "file:///C:/Users/Alyssa/AppData/Local/Temp/tmpu8r76ysx/wheels/venvstacks_testing_dynlib_consumer-1.0.0-cp311-abi3-win_amd64.whl", hashes = {} }]

[[packages]]
name = "venvstacks-testing-dynlib-publisher"
version = "1.0.0"
index = "file:///C:/Users/Alyssa/AppData/Local/Temp/tmpu8r76ysx/wheels"
wheels = [{ url = "file:///C:/Users/Alyssa/AppData/Local/Temp/tmpu8r76ysx/wheels/venvstacks_testing_dynlib_publisher-1.0.0-cp311-abi3-win_amd64.whl", hashes = {} }]

[konstin]

For the find links entry, why are you using an absolute path, and what would you expect uv.lock to cover?

find-links = ["C:\Users\Alyssa\AppData\Local\Temp\tmpo1yqij0_\wheels"]

I don't think we can handle absolute paths in input files properly in lockfile, neither choice seems portable, and e.g. relative paths in the lockfile invalidate it when the project moves relative to the absolute directory.

[ncoghlan]

I expect paths relative to the lock file (as uv.lock already includes). It does tightly couple the lock file to the local wheels it is consuming, but that's fine for the two cases that I think are reasonable to support:

• no portability (locking and installation happen on the same system, nothing moves between the two steps)
• lock file + local wheels are transported together (e.g. via an archive or a version control system)

For the first case, it doesn't matter whether the paths are relative or absolute, but for the second the paths need to be relative

The case that absolute paths support but relative paths don't is one where the local wheels are stored in a shared cache that's in a fixed location on every potential installation target, but there are better ways of handling that (starting with relying on uv's own cache, and including alternatives like running a local devpi instance so the cached wheel access is via a localhost URL instead of a filesystem path)