Skip to content

feat(build): pass UvCompileBytecode to Lambda Builders - #9449

Merged
bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-compile-bytecode
Nov 19, 2026
Merged

bnusunny merged 2 commits into
aws:developfrom
bnusunny:feat/python-uv-compile-bytecode

Conversation

@bnusunny

@bnusunny bnusunny commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Which issue(s) does this change fix?

Related: aws/aws-lambda-builders#924

Why is this change necessary?

SAM zips use fixed timestamps. A .pyc file that is checked by timestamp never matches its source in the zip, so Python recompiles it on every cold start. A .pyc built with unchecked hashes is used as-is. Lambda Builders is adding a uv_compile_bytecode option to the python-uv workflow for this (aws/aws-lambda-builders#924), and SAM CLI needs a way to set it.

How does it address the issue?

It adds UvCompileBytecode to UV_BUILD_PROPERTIES, so Metadata.BuildProperties.UvCompileBytecode is passed to Lambda Builders as uv_compile_bytecode. It works for functions and python-uv layers, like the other Uv* properties. The value is passed through as-is; Lambda Builders checks the type.

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    CodeUri: src/
    Handler: app.handler
    Runtime: python3.13
  Metadata:
    BuildMethod: python-uv
    BuildProperties:
      UvCompileBytecode: true

Setting it on a resource not built with python-uv fails with InvalidBuildProperties, as the other Uv* properties do.

Needs aws-lambda-builders 1.71.0, which adds the uv_compile_bytecode option (aws/aws-lambda-builders#973); the pin was bumped in #9453. Checked end to end with 1.71.0: a sam build with UvCompileBytecode: true outputs six.cpython-312.pyc with PEP 552 flags 1 (unchecked hash).

What side effects does this change have?

None for templates that do not set UvCompileBytecode.

Tests:

  • New unit tests: a function maps the property, a python-uv layer maps it, and a non-uv function with it fails with InvalidBuildProperties.
  • pytest tests/unit/lib/build_module tests/unit/commands/buildcmd: 576 passed, 1 skipped.
  • black --check, ruff check samcli and mypy samcli/lib/build/app_builder.py are clean.

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 18, 2026 •

Copy link
Copy Markdown

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

Commit 23526f3 · build LambdaToolingHandsOn-NoDocker:42c6d55e-96ab-4d2b-a355-2e29b8ad7229. 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 Run the PR's unit tests for build option mapping and the existing build module/command tests ✅ pass Head, Python 3.11.18, aws_lambda_builders 1.71.0. pytest test_app_builder.py -k uv: 22 passed, including test_python_uv_build_property_mapped_4_UvCompileBytecode and test_uv_compile_bytecode_reject…
S2 New error path: a pip-built Python function that sets UvCompileBytecode must fail with InvalidBuildProperties; on the m… ✅ pass Pip-built python3.11 function with UvCompileBytecode: true. Head: build_exit=1, no traceback, 'Error: MyFunction sets UvCompileBytecode in Metadata.BuildProperties, but these only apply when it is bu…
S3 Main path: a python-uv function with UvCompileBytecode: true. Records what the pinned Lambda Builders does with uv_comp… ✅ pass Outcome (b). Without --beta-features, python-uv stops at a beta-feature confirmation prompt and aborts on both trees (logs 08/09), so the reruns added --beta-features. Head: exit 0, 'Build Succeeded'…
S4 A python-uv layer with UvCompileBytecode: true passes the option the same way as a function does ✅ pass python-uv layer with UvCompileBytecode: true, built with --beta-features. Head: exit 0, no InvalidBuildProperties. .aws-sam/build/MyLayer/python contains six.py and __pycache__/six.cpython-311.pyc wi…
S5 Regression: an existing python-uv function without UvCompileBytecode still builds and is not affected by the new key ✅ pass python-uv function without UvCompileBytecode, built with --beta-features. Head and base both: exit 0, 'Build Succeeded', MyFunction contains app.py and six.py, pyc_count=0, and 0 debug-log lines ment…
S6 Edge case: a pip-built function setting UvCompileBytecode together with UvGroups gets one error that lists both keys ✅ pass Pip-built function with UvGroups and UvCompileBytecode. Head: exit 1, no traceback, 'Error: MyFunction sets UvGroups, UvCompileBytecode in Metadata.BuildProperties, but these only apply when it is bu…
Runner's notes in full
  • S1: Head, Python 3.11.18, aws_lambda_builders 1.71.0. pytest test_app_builder.py -k uv: 22 passed, including test_python_uv_build_property_mapped_4_UvCompileBytecode and test_uv_compile_bytecode_rejected_without_python_uv. test_python_uv_layer_passes_uv_build_properties is collected in that file. pytest tests/unit/lib/build_module tests/unit/commands/buildcmd: 576 passed, 1 skipped, exit 0, which matches the PR's claim. Setup note: with SAM_CLI_DEV=1 the console script is samdev, not sam, so the plan's sam --version step exited 127. All CLI scenarios used samdev instead.
  • S2: Pip-built python3.11 function with UvCompileBytecode: true. Head: build_exit=1, no traceback, 'Error: MyFunction sets UvCompileBytecode in Metadata.BuildProperties, but these only apply when it is built with BuildMethod: python-uv'. Base: build_exit=0, 'Build Succeeded', and the key is silently ignored. Builds ran through scratch script mk.sh with samdev build --debug.
  • S3: Outcome (b). Without --beta-features, python-uv stops at a beta-feature confirmation prompt and aborts on both trees (logs 08/09), so the reruns added --beta-features. Head: exit 0, 'Build Succeeded'. MyFunction contains app.py and six.py. The log shows 'Compiling unchecked-hash bytecode: python3 -m compileall -f -q --invalidation-mode unchecked-hash .../MyFunction'. pyc_count=1 (__pycache__/six.cpython-311.pyc, flags=1). app.py has no .pyc because Lambda Builders compiles before CopySource; that is Lambda Builders behavior. Base: exit 0, six installed, pyc_count=0, no compileall step.
  • S4: python-uv layer with UvCompileBytecode: true, built with --beta-features. Head: exit 0, no InvalidBuildProperties. .aws-sam/build/MyLayer/python contains six.py and __pycache__/six.cpython-311.pyc with flags=1. The log shows compileall --invalidation-mode unchecked-hash on MyLayer/python. Base: exit 0, six installed, pyc_count=0, no compileall step.
  • S5: python-uv function without UvCompileBytecode, built with --beta-features. Head and base both: exit 0, 'Build Succeeded', MyFunction contains app.py and six.py, pyc_count=0, and 0 debug-log lines mention compileall or uv_compile_bytecode. No regression.
  • S6: Pip-built function with UvGroups and UvCompileBytecode. Head: exit 1, no traceback, 'Error: MyFunction sets UvGroups, UvCompileBytecode in Metadata.BuildProperties, but these only apply when it is built with BuildMethod: python-uv'. Base: exit 1, and the message names only UvGroups.

🤖 Automated hands-on test — not a review approval · model claude-opus-5.5 · Kiro kiro-cli 2.33.1 · build LambdaToolingHandsOn-NoDocker:42c6d55e-96ab-4d2b-a355-2e29b8ad7229 · commit 23526f3

History (2)
Commit Result When (UTC) Build
23526f3 No problems observed 2026-11-19 19:37 LambdaToolingHandsOn-NoDocker:42c6d55e-96ab-4d2b-a355-2e29b8ad7229
5b312f1 Problems reproduced: UvCompileBytecode on python-uv functions/layers now fails sam build: pinned aws… 2026-11-18 17:30 LambdaToolingHandsOn-NoDocker:a9504d92-dd0e-4275-aa51-331e734ba373

@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 5b312f1. Commands and evidence are in the hands-on comment.

  1. [COMPATIBILITY] UvCompileBytecode on python-uv functions/layers now fails sam build: pinned aws_lambda_builders 1.70.0 (and develop) rejects uv_compile_bytecode · medium · samcli/lib/build/app_builder.py:115

🤖 Automated hands-on test — not a review approval

"UvExtras": "uv_extras",
"UvAllExtras": "uv_all_extras",
"UvPrune": "uv_prune",
"UvCompileBytecode": "uv_compile_bytecode",

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: [COMPATIBILITY] UvCompileBytecode on python-uv functions/layers now fails sam build: pinned aws_lambda_builders 1.70.0 (and develop) rejects uv_compile_bytecode (reproduced 2 times in S1). Commands and evidence: hands-on comment.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed by #9453, which bumps the aws_lambda_builders pin to 1.71.0 (adds uv_compile_bytecode). This branch now includes it, and the hands-on rerun on 23526f3 passes all 6 scenarios.

@bnusunny
bnusunny marked this pull request as ready for review November 19, 2026 19:30
@bnusunny
bnusunny requested a review from a team as a code owner November 19, 2026 19:30
@bnusunny
bnusunny added this pull request to the merge queue Nov 19, 2026
Merged via the queue into aws:develop with commit d084bb0 Nov 19, 2026
53 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/build sam build command pr/internal

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants