Experience & Contributions

The uv.lock file is valid TOML, so Python's tomllib can parse it. The challenge is not the format but the schema — understanding how packages, sources, wheels, and markers are structured inside the file. Here is a simplified snippet of what a uv.lock entry looks like:

The file starts with a header: version = 1, revision = 3, and requires-python. Each [[package]] section has name, version, source, dependencies, and inline sdist and wheels entries — each wheel contains its full PyPI download URL and SHA256 hash. The parser would need to walk through these entries, build a list of what to download, and verify checksums. I also want to follow the patterns of Hermeto's existing parsers (requirements.py for pip, yarn/ backend for yarn.lock).

I plan to start with simple single-package projects and work up to more complex cases during the research phase.

From looking at real uv.lock files, the lockfile already contains full download URLs for each wheel and sdist. This means the backend does not need to query the PyPI simple API at fetch time — it can download directly from the URLs in the lockfile. The pip backend already handles PyPI downloads through http_requests.py — I would reuse that infrastructure rather than writing something from scratch.

The source registry field tells us where the package came from originally, but the actual download URLs are baked into the sdist and wheels entries. This simplifies the fetching logic compared to pip where download URLs need to be resolved separately.

This is a core Hermeto rule. From what I have read, uv does not run setup.py during resolution — it reads metadata statically. That would align with Hermeto's security model. But I have not fully verified this yet and it is one of the first things I need to confirm during the research phase.

This is important enough that I would want to trace through uv's actual source code during the research phase rather than just trusting what the documentation says. The mentors specifically listed “inspecting uv's internals to verify whether there's a potential arbitrary code execution path” as an expectation, so this cannot be hand-waved.

Each fetched package needs to become a CycloneDX component in the SBOM. The pip backend already maps Python packages to pkg:pypi/ PURLs through sbom.py. The uv backend would produce the same PURL entries — the packages come from the same ecosystem (PyPI), just resolved through a different tool.

These follow the same pkg:pypi/ format Hermeto already generates for pip packages (I verified this in the test suite at tests/unit/package_managers/pip/test_main.py). The tricky part is ensuring metadata accuracy for packages with non-PyPI sources — git dependencies and direct URLs need special PURL qualifiers.

Also, since the uv backend would launch as experimental (x-uv), the SBOM needs to include the experimental backend annotations. From the design template, experimental backends mark their components with annotations like hermeto:backend:experimental:x-uv. This needs to be wired up from the start.

After fetching, Hermeto needs to tell uv to use the cached dependencies instead of the network. uv has environment variables for cache directory and offline mode that should work for this. I still need to dig into the exact configuration during the research phase.

The key question is whether uv sync can be pointed entirely at a local cache with no network fallback. If it can, the generate-env step just needs to emit the right env vars. If not, there may be config files that need to be injected. This is one of those things that is easier to figure out by testing locally than by reading docs.

A note on output directory structure: Hermeto's fetch-deps typically downloads wheels and sdists into a flat output directory (e.g. deps/pip/ for pip, deps/npm/ for npm). uv, on the other hand, has a highly specific, complex internal cache structure (UV_CACHE_DIR). A key research deliverable is figuring out how to feed Hermeto's flat downloaded files into uv sync --offline. I will investigate whether to construct a local index (--find-links or a local file URI index) or if uv exposes a way to directly consume flat files without its internal cache layout. This is a friction point the design document will need to solve before any implementation starts.