Skip to content

feat(build): pass python-uv build properties to Lambda Builders - #9439

Merged
bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-build-properties
Nov 17, 2026
Merged

bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-build-properties

Conversation

@bnusunny

@bnusunny bnusunny commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Which issue(s) does this change fix?

None. Follow-up to the python-uv build method.

Why is this change necessary?

aws-lambda-builders #966 adds build options to the python_uv workflow: dependency groups, extras, and pruning packages the Lambda runtime already ships (such as boto3). SAM CLI needs a way to pass them from the template.

How does it address the issue?

For a function built with BuildMethod: python-uv, these Metadata.BuildProperties keys are passed to Lambda Builders:

BuildProperty Lambda Builders option Type
UvGroups uv_groups list of strings
UvExtras uv_extras list of strings
UvAllExtras uv_all_extras bool
UvPrune uv_prune list of strings

They are merged with the existing python options (ParentPackageMode). Values are passed through as-is; Lambda Builders checks their types and fails with a clear message.

They work on functions and on layers with BuildMethod: python-uv. If any of these keys is set on a resource that is not built with python-uv (pip, other runtimes, other layers), the build fails and names the resource and keys, instead of ignoring them.

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    CodeUri: src/
    Handler: app.handler
    Runtime: python3.13
  Metadata:
    BuildMethod: python-uv
    BuildProperties:
      UvGroups: [extra]
      UvPrune: [boto3]

sam build --cached already rebuilds when these change, because function metadata is part of the build definition.

Needs aws-lambda-builders 1.70.0 (aws-lambda-builders #966), which develop now pins (#9442).

Tested end to end with Lambda Builders installed from the #966 branch: the example above ran uv export ... --group extra --prune boto3, and the artifact had six and idna but no boto3/botocore.

What side effects does this change have?

Templates that already set a Uv* BuildProperty on a non-python-uv resource now fail to build. These keys had no effect before.

Mandatory Checklist

PRs will only be reviewed after checklist is complete

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

@aws-sam-tooling-bot

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

Copy link
Copy Markdown

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

Commit 24446d5 · build LambdaToolingHandsOn-NoDocker:e8ca6e6d-9c89-4a14-8a75-7f0b2a898649. 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: a python-uv function with UvGroups, UvExtras, UvAllExtras and UvPrune builds and SAM passes them to Lambda B… ✅ pass Adapted the plan: python-uv is a beta build method in both trees, so builds need --beta-features (without it sam prompts and aborts, logs 03/04). Installed aws_lambda_builders 1.70.0 does implement u…
S2 New error path: a pip-built function (no BuildMethod) that sets UvGroups and UvPrune fails with a message naming the fu… ✅ pass Head: Build Failed, exit 1, 'Error: PipFunction sets UvGroups, UvPrune in Metadata.BuildProperties, but these only apply when it is built with BuildMethod: python-uv', no traceback. Base: exit 0, Bui…
S3 Layers: a python-uv layer passes Uv* properties through (the new dependency_manager argument in _build_layer), and a pi… ✅ pass Used UvPrune: [idna] for the same reason as S1. The python-uv layer on head exits 0 with options {"uv_groups": ["extra"], "uv_prune": ["idna"]}. Base exits 0 with options null. The pip layer (BuildMe…
S4 Possible regression: the new check runs 'key in build_props' for every resource. With an empty 'BuildProperties:' (YAML… ✅ pass The PR adds no regression. A makefile function with an empty (null) 'BuildProperties:' crashes the same way on head and base: exit 1 with tomlkit ConvertError 'Unable to convert an object of <NoneTyp…
S5 Author's claim: 'sam build --cached' rebuilds a python-uv function when a Uv* build property changes. ✅ pass Used UvPrune [six] then [idna], with --beta-features. All three --cached builds exit 0. After the UvPrune change, Lambda Builders runs again with {"uv_prune": ["idna"]}, as the author claims. The sec…
S6 Run the changed unit test module, including the new parameterized _get_build_options tests and the updated _build_layer… ✅ pass tests/unit/lib/build_module/test_app_builder.py on head: 193 passed, 3 subtests passed, 0 failed.
Runner's notes in full
  • S1: Adapted the plan: python-uv is a beta build method in both trees, so builds need --beta-features (without it sam prompts and aborts, logs 03/04). Installed aws_lambda_builders 1.70.0 does implement uv_prune and rejects names missing from uv.lock, so UvPrune: [boto3] failed in Lambda Builders on head ('uv_prune names packages not in .../uv.lock: boto3', log 05). This error comes from the fixture, not the PR. With UvPrune: [idna], head exits 0 and options.log shows {"uv_groups": ["extra"], "uv_extras": ["fast"], "uv_all_extras": false, "uv_prune": ["idna"]}. Artifacts include app.py and six. Base exits 0 with options null.
  • S2: Head: Build Failed, exit 1, 'Error: PipFunction sets UvGroups, UvPrune in Metadata.BuildProperties, but these only apply when it is built with BuildMethod: python-uv', no traceback. Base: exit 0, Build Succeeded, keys ignored.
  • S3: Used UvPrune: [idna] for the same reason as S1. The python-uv layer on head exits 0 with options {"uv_groups": ["extra"], "uv_prune": ["idna"]}. Base exits 0 with options null. The pip layer (BuildMethod python3.11) with UvGroups fails on head with exit 1 and 'Error: PipLayer sets UvGroups in Metadata.BuildProperties, but these only apply when it is built with BuildMethod: python-uv', no traceback. Base: exit 0.
  • S4: The PR adds no regression. A makefile function with an empty (null) 'BuildProperties:' crashes the same way on head and base: exit 1 with tomlkit ConvertError 'Unable to convert an object of to a TOML item' from build_graph._function_build_definition_to_toml_table, before _get_build_options runs. The plan expected base to exit 0, but it does not. Calling _get_build_options directly with BuildProperties None also fails in both trees: head raises TypeError (the new 'key in build_props'), base raises AttributeError ('NoneType' object has no attribute 'get'). So null BuildProperties was already unsupported. Not reported as a finding.
  • S5: Used UvPrune [six] then [idna], with --beta-features. All three --cached builds exit 0. After the UvPrune change, Lambda Builders runs again with {"uv_prune": ["idna"]}, as the author claims. The second, unchanged build also called Lambda Builders, so options.log has 3 lines, not the 2 the plan expected. Base does the same (3 calls, options null), so --cached never reuses python-uv builds in either tree. This is not caused by the PR.

🤖 Automated hands-on test — not a review approval · model claude-opus-5.5 · Kiro kiro-cli 2.33.1 · build LambdaToolingHandsOn-NoDocker:e8ca6e6d-9c89-4a14-8a75-7f0b2a898649 · commit 24446d5

History (2)
Commit Result When (UTC) Build
24446d5 No problems observed 2026-11-17 20:05 LambdaToolingHandsOn-NoDocker:e8ca6e6d-9c89-4a14-8a75-7f0b2a898649
be4e054 No problems observed 2026-11-16 16:56 LambdaToolingHandsOn-NoDocker:f1142d79-7a0e-46d3-b768-17e64855ab03

@bnusunny
bnusunny marked this pull request as ready for review November 17, 2026 19:28
@bnusunny
bnusunny requested a review from a team as a code owner November 17, 2026 19:28
licjun
licjun previously approved these changes Nov 17, 2026
Map Metadata.BuildProperties UvGroups, UvExtras, UvAllExtras and UvPrune to
the python_uv workflow options uv_groups, uv_extras, uv_all_extras and
uv_prune. Fail the build when these keys are set on a resource that is not
built with BuildMethod: python-uv, instead of ignoring them.
_build_layer called _get_build_options without a dependency manager, so a
BuildMethod: python-uv layer with Uv* BuildProperties hit the
'only apply with python-uv' check. Pass the dependency manager for uv
layers only; other layers keep None so their options are unchanged.
@bnusunny
bnusunny added this pull request to the merge queue Nov 17, 2026
Merged via the queue into aws:develop with commit c917ec2 Nov 17, 2026
54 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants