Skip to content

feat(python-uv): add build options (groups, extras, prune) and show uv warnings - #966

Merged
bnusunny merged 1 commit into
aws:developfrom
bnusunny:feat/python-uv-build-options
Nov 16, 2026
Merged

bnusunny merged 1 commit into
aws:developfrom
bnusunny:feat/python-uv-build-options

Conversation

@bnusunny

@bnusunny bnusunny commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Issue #, if available: #839

Description of changes

Adds four build options to the python_uv workflow (groups, extras, all extras, prune), documents which pyproject.toml settings apply, and shows uv warnings in the build log.

The build options are read from the workflow options and passed to uv export. SAM CLI will map them from Metadata.BuildProperties in a follow-up.

Option SAM CLI property Effect on uv export
uv_groups (list of str) UvGroups --group <name> per entry
uv_extras (list of str) UvExtras --extra <name> per entry
uv_all_extras (bool) UvAllExtras --all-extras
uv_prune (list of str) UvPrune --prune <name> per entry: drops the package and any dependency only it needs

With no options set, the export command is unchanged. The project itself is still never exported (--no-emit-project); only its dependencies are installed.

uv_prune is for packages the Lambda runtime already ships, such as boto3: pruning it also drops botocore, s3transfer and jmespath, but keeps urllib3 when requests needs it. The function then runs with the runtime's boto3, whose version AWS picks, not the one in uv.lock.

Bad input fails the build with a clear message (PythonUvBuilder:Validation - ...) instead of being ignored:

  • wrong type, or an unknown uv_* key (catches typos like uv_group)
  • uv_extras together with uv_all_extras
  • any option on a requirements.txt build (they only apply to pyproject.toml / uv.lock projects)
  • a uv_prune name that is not a package in uv.lock (uv export --prune ignores unknown names silently)

uv warnings now show in the build log. Until now the workflow logged uv's output only at debug level, so a normal sam build hid every uv warning. That matters because an unknown key in [tool.uv] or [tool.uv.pip] makes uv ignore every setting in that pyproject.toml, and uv's warning was the only sign. Each warning: block uv prints (with its indented detail lines) is now logged at WARNING level, once per build, even though uv repeats it on lock, export and install. Other uv output stays at debug level, and error handling is unchanged. Example:

WARNING aws_lambda_builders.workflows.python_uv.packager: uv warning: Failed to parse `pyproject.toml` during settings discovery:
  TOML parse error at line 8, column 1
  ...
  unknown field `bogus-key`, expected one of `required-version`, ...

DESIGN.md gets a short "Build options" section and a "Settings from pyproject.toml" section: which [tool.uv], [tool.uv.pip] and UV_* settings reach the build, that the workflow's own flags win, and that only the workspace root's settings count in a uv workspace.

Not in this PR: bytecode compilation (#926); and an index option. uv pip install already reads non-explicit [[tool.uv.index]] and index-url from the project's pyproject.toml, because it runs from the project directory. Explicit indexes pinned through [tool.uv.sources] are not honored on this path yet; that needs a separate change.

Description of how you validated changes

  • Unit tests: export argument building, option validation, and options reaching the build action.
  • Functional test (fake uv): the options reach uv export and do not leak into uv pip install.
  • Integration tests (real uv 0.13.8): one dependency group and one extra. It checks that the selected group and extra are installed, an unselected group is not, the project itself is not installed, and there is no .pth. A second test prunes boto3 from a project that also depends on requests: boto3, botocore, s3transfer and jmespath are gone, requests and urllib3 stay, and an unknown prune name fails the build.
  • uv warnings: unit tests for the parsing (multi-line warning kept whole, non-warning and error: lines not promoted, repeats logged once, also on a failed command). An integration test builds a project with an unknown [tool.uv] key through LambdaBuilder with real uv 0.13.8 and checks the warning is logged exactly once at WARNING level.
  • make lint, make black-check and make test pass (1135 passed, 95.30% coverage). All 62 python_uv integration tests pass.

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@bnusunny
bnusunny requested a review from a team as a code owner November 14, 2026 19:38
@aws-sam-tooling-bot

aws-sam-tooling-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

🧪 Hands-on test: No problems observed in 6 scenarios

Commit 7e73f78 · build LambdaToolingHandsOn-NoDocker:67d58040-2197-4168-b681-122d21223619. The plan's scenarios ran on an isolated build host; a problem is reported only if it reproduced at least twice. Passing scenarios show only that these checks behaved as expected, not that the change is correct.

Scenarios

Scenario Planned check Result Runner's note
S1 Main path: uv_groups and uv_extras select one dependency group and one extra; the unselected group, the project itself … ✅ pass Head: uv_groups=[lambda], uv_extras=[dns] builds with rc=0; six.py, toml/ and idna/ present; no pyasn1*, no optsapp-*.dist-info, 0 .pth files. Base: rc=0 but toml/ and idna/ missing (options ignored)…
S2 uv_prune drops boto3 and the dependencies only it needs (botocore, s3transfer, jmespath) and keeps urllib3, which reque… ✅ pass Head: uv_prune=[Boto3] on a project at 'prune app ü' builds rc=0; boto3, botocore, s3transfer, jmespath (and the botocore-only python-dateutil/six) are absent; requests/ and urllib3/ present. Base: r…
S3 Each new validation path fails the build with a clear message instead of silently ignoring the input: an unknown prune … ✅ pass Head: (a) unknown prune name fails rc=2 with 'Build option uv_prune names packages not in .../uv.lock: not-a-locked-package' (reported under PythonUvBuilder:ResolveDependencies, not Validation); (b) …
S4 uv warnings now appear at WARNING level. An unknown [tool.uv] key makes uv print a warning on lock, export and install,… ✅ pass Head: rc=0, BUILD OK, six.py built. Log has one 'WARNING aws_lambda_builders.workflows.python_uv.packager: uv warning: Failed to parse pyproject.toml' block with indented detail naming bogus-key; w…
S5 Edge cases the PR doesn't validate itself: uv_all_extras alone, a group name not in [dependency-groups], and an extra n… ✅ pass (a) uv_all_extras alone: rc=0, idna/ present, toml/ absent. (b) uv_groups=[nope]: rc=2, uv error 'Group nope is not defined in the project's dependency-groups table'. (c) uv_extras=[nope]: rc=2, …
S6 Run the repository's python_uv unit and functional tests, plus the PR's new integration tests against real uv. This als… ✅ pass Unit + functional python_uv tests: 149 passed, 53 subtests passed. New integration tests (-k build_options/prunes_runtime/shows_uv_warnings): 6 passed, none skipped. Full python_uv integration suite:…
Runner's notes in full
  • S1: Head: uv_groups=[lambda], uv_extras=[dns] builds with rc=0; six.py, toml/ and idna/ present; no pyasn1*, no optsapp-*.dist-info, 0 .pth files. Base: rc=0 but toml/ and idna/ missing (options ignored), as expected. Paths adapted to /work/scratch/ht with separate per-tree project copies and venvs.
  • S2: Head: uv_prune=[Boto3] on a project at 'prune app ü' builds rc=0; boto3, botocore, s3transfer, jmespath (and the botocore-only python-dateutil/six) are absent; requests/ and urllib3/ present. Base: rc=0 with boto3, botocore, s3transfer, jmespath all present.
  • S3: Head: (a) unknown prune name fails rc=2 with 'Build option uv_prune names packages not in .../uv.lock: not-a-locked-package' (reported under PythonUvBuilder:ResolveDependencies, not Validation); (b) 'PythonUvBuilder:Validation - Unknown uv build option(s): uv_group'; (c) 'uv_groups must be a list of non-empty strings'; (d) 'uv_extras and uv_all_extras cannot be used together'; (e) 'uv_groups need a pyproject.toml project, but this build uses requirements.txt'; all rc=2, no traceback. (f) default-valued options on requirements.txt: rc=0, six.py built. Base: all six builds rc=0 BUILD OK (options ignored).
  • S4: Head: rc=0, BUILD OK, six.py built. Log has one 'WARNING aws_lambda_builders.workflows.python_uv.packager: uv warning: Failed to parse pyproject.toml' block with indented detail naming bogus-key; warning_blocks=1, unknown_field_lines=1. Base: rc=0, warning_blocks=0 (warning hidden).
  • S5: (a) uv_all_extras alone: rc=0, idna/ present, toml/ absent. (b) uv_groups=[nope]: rc=2, uv error 'Group nope is not defined in the project's dependency-groups table'. (c) uv_extras=[nope]: rc=2, 'Extra nope is not defined in the optional-dependencies table for optsapp'. No tracebacks. Extra check: a fresh project with no uv.lock and uv_prune=[botoo3] also fails rc=2 ('uv_prune names packages not in .../uv.lock: botoo3'), so the prune check is not skipped when the lock is generated during the build.
  • S6: Unit + functional python_uv tests: 149 passed, 53 subtests passed. New integration tests (-k build_options/prunes_runtime/shows_uv_warnings): 6 passed, none skipped. Full python_uv integration suite: 62 passed, exit 0.

🤖 Automated hands-on test — not a review approval · model claude-opus-5.5 · Kiro kiro-cli 2.33.1 · build LambdaToolingHandsOn-NoDocker:67d58040-2197-4168-b681-122d21223619 · commit 7e73f78

History (6)
Commit Result When (UTC) Build
7e73f78 No problems observed 2026-11-16 21:06 LambdaToolingHandsOn-NoDocker:67d58040-2197-4168-b681-122d21223619
640f2b7 No problems observed 2026-11-14 21:25 LambdaToolingHandsOn-NoDocker:ebdc5bd7-b6f1-4f16-b6de-73d96bc994d7
94f821b No problems observed 2026-11-14 21:13 LambdaToolingHandsOn-NoDocker:c8d5be01-e739-442b-b287-4aa2643efee3
eba8b15 Superseded 2026-11-14 21:05 LambdaToolingHandsOn-NoDocker:50b6110f-028a-4e7f-a878-15e173724a58
cdfac24 Problems reproduced: uv_install_project (setuptools) fails with configparser InterpolationSyntaxErro…; uv_install_project with dependencies_dir and download_dependencies=False ships … 2026-11-14 20:19 LambdaToolingHandsOn-NoDocker:d29d5d52-3731-49ee-9746-57955538791f
67405ec Problems reproduced: uv_install_project on a tool.uv.package=true project without [build-system] lea…; New build-option validation errors read 'PythonUvBuilder:None - ...' because _f… 2026-11-14 19:50 LambdaToolingHandsOn-NoDocker:a0eb6d42-b9f8-46f8-b566-ed81efc96c48

@aws-sam-tooling-bot aws-sam-tooling-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧪 Hands-on test reproduced 2 new problems on commit 67405ec. Commands and evidence are in the hands-on comment.

  1. [BUG] uv_install_project on a tool.uv.package=true project without [build-system] leaves build/ and *.egg-info in the source dir, and build/ is copied into the Lambda artifacts · medium · aws_lambda_builders/workflows/python_uv/packager.py:517
  2. [UX] New build-option validation errors read 'PythonUvBuilder:None - ...' because _fail passes action_name=None · low · aws_lambda_builders/workflows/python_uv/workflow.py:146

🤖 Automated hands-on test — not a review approval

@aws-sam-tooling-bot aws-sam-tooling-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review Results

Reviewed: 3a508d9..cdfac24
Files: 9
Comments: 2

@aws-sam-tooling-bot aws-sam-tooling-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧪 Hands-on test reproduced 1 new problem on commit cdfac24. Commands and evidence are in the hands-on comment.

  1. [BUG] uv_install_project (setuptools) fails with configparser InterpolationSyntaxError when the scratch path contains '%' · low · aws_lambda_builders/workflows/python_uv/packager.py:176

🤖 Automated hands-on test — not a review approval

@bnusunny bnusunny changed the title feat(python-uv): add build options and show uv warnings feat(python-uv): add build options (groups, extras, prune) and show uv warnings Nov 14, 2026
@bnusunny
bnusunny force-pushed the feat/python-uv-build-options branch from 94f821b to 640f2b7 Compare November 14, 2026 21:13
…v warnings

Add uv_groups, uv_extras, uv_all_extras and uv_prune build options to the
python_uv workflow. They are passed to uv export; bad values, unknown uv_*
keys, combining uv_extras with uv_all_extras, options on a requirements.txt
build, and uv_prune names missing from uv.lock fail the build with a clear
PythonUvBuilder:Validation error.

Log uv warning blocks at WARNING level, once per build, so problems such as
an unknown [tool.uv] key are visible in a normal sam build.

Document which pyproject.toml and UV_* settings reach the build.
@bnusunny
bnusunny force-pushed the feat/python-uv-build-options branch from 640f2b7 to 7e73f78 Compare November 16, 2026 20:57

@vicheey vicheey left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, the validation and the prune pre-check read well.

  1. Could you add uv_all_extras: True to the workflow test that checks options reach the config (test_options_are_passed_to_the_build_action)? Today the value is only asserted as False, so a change that stops forwarding it would not fail any test.
  2. uv warnings now print at WARNING for every build, including ones with no options set. For example, uv's "Failed to hardlink files; falling back to full copy" notice will now show on builds where the cache and target are on different filesystems. Could you mention that in the PR description and DESIGN.md, or limit the promoted warnings to the settings-related ones?

Optional: uv_prune with the project's own name passes the lock check and produces an empty dependency set. Rejecting it, or failing on an empty export, would make that mistake visible.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants