Skip to content

Summarize package changes in uv sync json format output#16981

Merged
EliteTK merged 9 commits intomainfrom
tk/sync-summary
Dec 18, 2025
Merged

Summarize package changes in uv sync json format output#16981
EliteTK merged 9 commits intomainfrom
tk/sync-summary

Conversation

@EliteTK
Copy link
Contributor

@EliteTK EliteTK commented Dec 4, 2025

Summary

Implement #16653 by making uv sync --output-format=json output information about package changes.

Test Plan

Additional tests to test the cases where there is no known package version may be beneficial but as the information used is the same as the information used by the dry run logging now, I don't think that's strictly necessary as those cases are tested.

@EliteTK EliteTK added the preview Experimental behavior label Dec 4, 2025
@EliteTK EliteTK marked this pull request as draft December 4, 2025 15:39
@EliteTK EliteTK temporarily deployed to uv-test-registries December 4, 2025 15:42 — with GitHub Actions Inactive
@EliteTK
Copy link
Contributor Author

EliteTK commented Dec 4, 2025

So, to summarise a discussion from Discord, a suggestion was made to pull out the planning step from pip::operations::install into a separate plan function. Or, alternatively, just return the plan from install.

The goal being that a PackageChangeReport::from_plan can be added and used in the dry-run case, avoiding going through Changelog entirely, saving a bunch of code.

I've started to explore the idea of pulling out plan, but I don't think it's worth it. It adds a lot of boilerplate. I'll submit it as a separate PR and then I'll consider the alternative. Then whatever the result of that, this PR can be rebased on top and simplified.

@EliteTK
Copy link
Contributor Author

EliteTK commented Dec 5, 2025

So, the idea behind --dry-run is to produce output which is similar to what is produced without it, but without actually performing any actions. So, for example, the outputs below are almost identical:

$ uv sync
Resolved 6 packages in 2ms
Uninstalled 4 packages in 5ms
Installed 3 packages in 8ms
 - anyio==4.12.0
 + charset-normalizer==3.4.4
 - h11==0.16.0
 - httpcore==1.0.9
 - httpx==0.28.1
 + requests==2.32.5
 + urllib3==2.5.0
$ magically_revert_state # Trade secret
$ uv sync --dry-run
Would use project environment at: .venv
Resolved 6 packages in 1ms
Found up-to-date lockfile at: uv.lock
Would uninstall 4 packages
Would install 3 packages
 - anyio==4.12.0
 + charset-normalizer==3.4.4
 - h11==0.16.0
 - httpcore==1.0.9
 - httpx==0.28.1
 + requests==2.32.5
 + urllib3==2.5.0

And the goal of the json output is to present this information in JSON.

In the output above, the normal path uses InstallLogger::on_complete, but report_dry_run re-implements the code from DefaultInstallLogger::on_complete and kind of effectively produces the same information which would have been in Changelog. This1 Changelog is only ever used to implement InstallLogger::on_complete logging, I think it actually would make sense for Changelog be the type which uniformly stores the information (regardless of whether it was from an install, or a dry-run install).

I think the only real changes which would be required is to: Expand the kinds of dists that Changelog can contain, so it can contain remote dists, and then adjust the respective ChangeEvent type (which similarly is only used within on_complete) to be able to deal with things without versions (possibly just fall back to a URL like the current report_dry_run code does). This would have the knock-on effect of allowing report_dry_run to just use the on_complete logger, cutting it down further.

Finally, report_dry_run can just return this Changelog type.

I believe this can all be done while keeping things pretty clean. Definitely no ZERO_VERSION hack ;).

Let me know what you think.

Footnotes

  1. There are two Changelog types and two ChangeEvent types because of the slightly different requirements of where they are used. Both the logging functionality and the different changelogs could be unified, I think. But I don't think that it would necessarily benefit from being done now. I can kind of see it though, would be good to investigate one day, as there are two places where the DefaultInstallLogger::on_complete functionality is re-implemented verbatim. In fact, the changes suggested here would probably make such a change easier to implement.

@zanieb
Copy link
Member

zanieb commented Dec 5, 2025

Sounds fine to me!

@EliteTK EliteTK temporarily deployed to uv-test-registries December 8, 2025 22:53 — with GitHub Actions Inactive
EliteTK added a commit that referenced this pull request Dec 12, 2025
## Summary

Remove duplication in `report_dry_run` by making `Changelog` support
both local and remote dists. This is in support of #16653 and will form
a new basis for #16981.

This also involved refactoring `InstallLogger` and its implementations
to support dry run logging.

Additionally includes some minor refactoring in `SummaryInstallLogger`
and a fix to `InstalledVersion`.

See https://github.com/astral-sh/uv/compare/tk/dry-run-refactor for an
alternative approach (although obviously comes with some caveats).

## Test Plan

There are already quite a few tests which cover the output and they
pass. Manual testing was used to ensure styling stayed consistent.
@EliteTK
Copy link
Contributor Author

EliteTK commented Dec 12, 2025

Okay, rebased on top of the new changelog stuff, fixed the package naming and attaching the wrong lifetime to a reference in VersionOrUrlRef. This is ready I think?

@EliteTK EliteTK marked this pull request as ready for review December 12, 2025 12:18
@EliteTK EliteTK temporarily deployed to uv-test-registries December 12, 2025 12:36 — with GitHub Actions Inactive
@EliteTK EliteTK temporarily deployed to uv-test-registries December 18, 2025 13:58 — with GitHub Actions Inactive
@EliteTK EliteTK merged commit c2e1983 into main Dec 18, 2025
189 of 192 checks passed
@EliteTK EliteTK deleted the tk/sync-summary branch December 18, 2025 19:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

preview Experimental behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants