From d556e82b8b9cdaec977768c7f49d4ebc8a9f4c8d Mon Sep 17 00:00:00 2001 From: Harold Sun Date: Wed, 18 Nov 2026 19:05:50 +0000 Subject: [PATCH] feat(python-uv): add uv_compile_bytecode build option Adds a uv_compile_bytecode (bool) build option that turns on the unchecked-hash bytecode compilation from #926. It also works for requirements.txt builds. UV_COMPILE_BYTECODE is honored when the option is not given; an explicit false wins. Fixes #925 --- .../workflows/python_uv/DESIGN.md | 22 +++++- .../workflows/python_uv/workflow.py | 33 +++++++- .../workflows/python_uv/test_python_uv.py | 75 +++++++++++++++++++ .../unit/workflows/python_uv/test_workflow.py | 61 +++++++++++++++ 4 files changed, 187 insertions(+), 4 deletions(-) diff --git a/aws_lambda_builders/workflows/python_uv/DESIGN.md b/aws_lambda_builders/workflows/python_uv/DESIGN.md index 3ef5a60d6..802e72670 100644 --- a/aws_lambda_builders/workflows/python_uv/DESIGN.md +++ b/aws_lambda_builders/workflows/python_uv/DESIGN.md @@ -231,6 +231,7 @@ SAM CLI maps them from `Metadata.BuildProperties`. | `uv_extras` | `UvExtras` | list of str | `--extra ` per entry | | `uv_all_extras` | `UvAllExtras` | bool | `--all-extras` | | `uv_prune` | `UvPrune` | list of str | `--prune ` per entry: drops the package and any dependency only it needs | +| `uv_compile_bytecode` | `UvCompileBytecode` | bool | none; after install, runs `compileall --invalidation-mode unchecked-hash` with the target Python (also for `requirements.txt` builds) | Default groups stay excluded (`--no-default-groups`); `uv_groups` adds groups on top of that. `uv_prune` is meant for packages the Lambda runtime already ships, such as `boto3`. The function then @@ -238,15 +239,32 @@ uses the runtime's version, which AWS picks, not the version in `uv.lock`. The build fails with a clear message, instead of ignoring the option, when: - a value has the wrong type, or an unknown `uv_*` key is given; - `uv_extras` and `uv_all_extras` are combined; -- an option is set on a `requirements.txt` build (they apply only to pyproject.toml / uv.lock projects); +- an option other than `uv_compile_bytecode` is set on a `requirements.txt` build (they apply only to + pyproject.toml / uv.lock projects); - a `uv_prune` name is not a package in `uv.lock`, which `uv export --prune` would otherwise ignore. +### Bytecode + +uv writes timestamp-based `.pyc` files, which the Lambda runtime rejects once SAM normalizes file +timestamps in the deployment package. So the workflow always passes `--no-compile-bytecode` to +`uv pip install`, removes `UV_COMPILE_BYTECODE` from that command's environment (uv refuses the flag and +the variable together), and, when bytecode is enabled, runs the target Python +(`uv python find --no-project --no-python-downloads `) as +`python -m compileall -f -q --invalidation-mode unchecked-hash` over the install directory. + +Bytecode is enabled by `uv_compile_bytecode: true`. When that option isn't given, a truthy +`UV_COMPILE_BYTECODE` in the build environment enables it too, and the build logs that at INFO. Values are +read the way uv reads them, case-insensitively: `1`, `true`, `t`, `yes`, `y`, `on` enable it; `0`, `false`, +`f`, `no`, `n`, `off` leave it off; any other value logs a warning and leaves it off. An explicit +`uv_compile_bytecode: false` always wins over the variable. If the target Python isn't installed, or the +runtime gives no version, the build logs a warning and ships no bytecode instead of failing. + ### Settings from pyproject.toml The workflow runs `uv export` and `uv pip install` from the project, so uv reads its own settings there. Build-control settings in `[tool.uv]` (`no-build`, `no-build-package`, `no-binary`, `no-binary-package`) apply to both steps; `[tool.uv.pip]` settings (`no-build`, `no-binary`, `only-binary`) apply to the install. `UV_*` -environment variables apply to every uv call. The workflow's own flags always win: the target platform and +environment variables apply to every uv call, except `UV_COMPILE_BYTECODE` (see Bytecode). The workflow's own flags always win: the target platform and Python version come from the function's architecture and runtime, default groups are excluded, and nothing is installed editable. In a uv workspace only the workspace root's `pyproject.toml` settings are used; a member's `[tool.uv]` and `[tool.uv.pip]` tables are ignored. An unknown key in either table makes uv ignore diff --git a/aws_lambda_builders/workflows/python_uv/workflow.py b/aws_lambda_builders/workflows/python_uv/workflow.py index 7f95ff515..ffb43d4cc 100644 --- a/aws_lambda_builders/workflows/python_uv/workflow.py +++ b/aws_lambda_builders/workflows/python_uv/workflow.py @@ -20,8 +20,29 @@ "uv_extras": list, "uv_all_extras": bool, "uv_prune": list, + "uv_compile_bytecode": bool, } +# Values uv accepts for UV_COMPILE_BYTECODE (clap's boolish parser, case-insensitive) +UV_ENV_TRUE = ("1", "true", "t", "yes", "y", "on") +UV_ENV_FALSE = ("0", "false", "f", "no", "n", "off") + + +def _compile_bytecode_from_env(): + """Honor UV_COMPILE_BYTECODE when the uv_compile_bytecode build option isn't given. + + The builder drops the variable from `uv pip install` (it conflicts with --no-compile-bytecode), + so read the user's intent here and compile unchecked-hash bytecode instead. + """ + value = os.environ.get("UV_COMPILE_BYTECODE") + if value is None or value.lower() in UV_ENV_FALSE: + return False + if value.lower() in UV_ENV_TRUE: + LOG.info("UV_COMPILE_BYTECODE=%s is set, compiling unchecked-hash bytecode for dependencies", value) + return True + LOG.warning("Ignoring UV_COMPILE_BYTECODE=%r: expected one of %s", value, ", ".join(UV_ENV_TRUE + UV_ENV_FALSE)) + return False + class PythonUvWorkflow(BaseWorkflow): """ @@ -141,12 +162,19 @@ def _uv_config_from_options(self, manifest_path): if values.get("uv_all_extras") and values.get("uv_extras"): self._fail("Build options uv_extras and uv_all_extras cannot be used together") + # An explicit uv_compile_bytecode (true or false) wins over the environment + if "uv_compile_bytecode" not in values: + values["uv_compile_bytecode"] = _compile_bytecode_from_env() + if not any(values.values()): return UvConfig() - if not manifest_path or os.path.basename(manifest_path) != "pyproject.toml": + # Bytecode is compiled after install, so it works for every manifest type; + # the other options shape `uv export` and need a pyproject.toml project. + export_options = {key: value for key, value in values.items() if key != "uv_compile_bytecode" and value} + if export_options and (not manifest_path or os.path.basename(manifest_path) != "pyproject.toml"): self._fail( - f"Build options {', '.join(sorted(values))} need a pyproject.toml project, " + f"Build options {', '.join(sorted(export_options))} need a pyproject.toml project, " f"but this build uses {os.path.basename(manifest_path) if manifest_path else 'no manifest'}" ) @@ -155,6 +183,7 @@ def _uv_config_from_options(self, manifest_path): extras=values.get("uv_extras"), all_extras=values.get("uv_all_extras", False), prune=values.get("uv_prune"), + compile_bytecode=values.get("uv_compile_bytecode", False), ) def _setup_build_actions(self, source_dir, artifacts_dir, scratch_dir, manifest_path, runtime, config=None): diff --git a/tests/integration/workflows/python_uv/test_python_uv.py b/tests/integration/workflows/python_uv/test_python_uv.py index 899233e71..7522175ca 100644 --- a/tests/integration/workflows/python_uv/test_python_uv.py +++ b/tests/integration/workflows/python_uv/test_python_uv.py @@ -677,6 +677,81 @@ def test_workflow_prunes_runtime_provided_packages(self): ) self.assertIn("uv_prune names packages not in", str(ctx.exception)) + @skipIf(which("uv") is None, "uv not available") + @patch.dict(os.environ, {"UV_COMPILE_BYTECODE": "1"}) + def test_workflow_honors_uv_compile_bytecode_env_without_option(self): + with tempfile.TemporaryDirectory() as source_dir, tempfile.TemporaryDirectory() as disabled_dir: + requirements = os.path.join(source_dir, "requirements.txt") + pathlib.Path(requirements).write_text("six==1.16.0\n") + builder = LambdaBuilder(language="python", dependency_manager="uv", application_framework=None) + runtime = f"python{sys.version_info.major}.{sys.version_info.minor}" + + builder.build( + source_dir, + self.artifacts_dir, + self.scratch_dir, + requirements, + runtime=runtime, + experimental_flags=self.experimental_flags, + ) + # Named for the target interpreter, e.g. six.cpython-312.pyc + tag = f"cpython-{sys.version_info.major}{sys.version_info.minor}" + pyc_files = list(pathlib.Path(self.artifacts_dir, "__pycache__").glob("six.*.pyc")) + self.assertEqual([pyc.name for pyc in pyc_files], [f"six.{tag}.pyc"]) + # PEP 552 flags word: 1 = hash-based, unchecked + self.assertEqual(int.from_bytes(pyc_files[0].read_bytes()[4:8], "little"), 1) + + # An explicit uv_compile_bytecode: false wins over the environment + builder.build( + source_dir, + disabled_dir, + self.scratch_dir, + requirements, + runtime=runtime, + experimental_flags=self.experimental_flags, + options={"uv_compile_bytecode": False}, + ) + self.assertTrue(pathlib.Path(disabled_dir, "six.py").is_file()) + self.assertEqual(list(pathlib.Path(disabled_dir).rglob("__pycache__")), []) + + @skipIf(which("uv") is None, "uv not available") + def test_workflow_compiles_unchecked_hash_bytecode_when_enabled(self): + with ( + patch.dict(os.environ), + tempfile.TemporaryDirectory() as source_dir, + tempfile.TemporaryDirectory() as compiled_dir, + ): + os.environ.pop("UV_COMPILE_BYTECODE", None) + requirements = os.path.join(source_dir, "requirements.txt") + pathlib.Path(requirements).write_text("six==1.16.0\n") + builder = LambdaBuilder(language="python", dependency_manager="uv", application_framework=None) + runtime = f"python{sys.version_info.major}.{sys.version_info.minor}" + + builder.build( + source_dir, + self.artifacts_dir, + self.scratch_dir, + requirements, + runtime=runtime, + experimental_flags=self.experimental_flags, + ) + self.assertTrue(pathlib.Path(self.artifacts_dir, "six.py").is_file()) + self.assertEqual(list(pathlib.Path(self.artifacts_dir).rglob("__pycache__")), []) + + builder.build( + source_dir, + compiled_dir, + self.scratch_dir, + requirements, + runtime=runtime, + experimental_flags=self.experimental_flags, + options={"uv_compile_bytecode": True}, + ) + pyc_files = list(pathlib.Path(compiled_dir, "__pycache__").glob("six.*.pyc")) + self.assertEqual(len(pyc_files), 1) + # PEP 552 flags word: 1 = hash-based, unchecked + self.assertEqual(int.from_bytes(pyc_files[0].read_bytes()[4:8], "little"), 1) + @skipIf(which("uv") is None, "uv not available") def test_workflow_shows_uv_warnings(self): with tempfile.TemporaryDirectory() as source_dir: diff --git a/tests/unit/workflows/python_uv/test_workflow.py b/tests/unit/workflows/python_uv/test_workflow.py index fe3437c9b..5207111e9 100644 --- a/tests/unit/workflows/python_uv/test_workflow.py +++ b/tests/unit/workflows/python_uv/test_workflow.py @@ -200,6 +200,11 @@ def setUp(self): self.source_dir = tempfile.mkdtemp() self.pyproject = os.path.join(self.source_dir, "pyproject.toml") self._write_pyproject('[build-system]\nrequires = ["uv_build"]\nbuild-backend = "uv_build"\n') + # Keep a developer's own UV_COMPILE_BYTECODE out of these tests + env = patch.dict(os.environ) + env.start() + self.addCleanup(env.stop) + os.environ.pop("UV_COMPILE_BYTECODE", None) def tearDown(self): shutil.rmtree(self.source_dir) @@ -233,10 +238,64 @@ def test_options_are_passed_to_the_build_action(self): self.assertEqual(config.extras, ["fast"]) self.assertFalse(config.all_extras) self.assertEqual(config.prune, ["boto3"]) + self.assertFalse(config.compile_bytecode) + + def test_compile_bytecode_option_is_passed_to_the_build_action(self): + config = self._workflow({"uv_compile_bytecode": True}).actions[0].config + self.assertTrue(config.compile_bytecode) + + def test_compile_bytecode_on_requirements_build_is_allowed(self): + requirements = os.path.join(self.source_dir, "requirements.txt") + open(requirements, "w").close() + config = self._workflow({"uv_compile_bytecode": True}, manifest=requirements).actions[0].config + self.assertTrue(config.compile_bytecode) + + def test_export_option_with_compile_bytecode_on_requirements_build_fails(self): + requirements = os.path.join(self.source_dir, "requirements.txt") + open(requirements, "w").close() + with self.assertRaises(WorkflowFailedError) as ctx: + self._workflow({"uv_groups": ["lambda"], "uv_compile_bytecode": True}, manifest=requirements) + self.assertIn("Build options uv_groups need a pyproject.toml project", str(ctx.exception)) + + @parameterized.expand([("1",), ("true",), ("YES",), ("On",), ("y",), ("t",)]) + def test_truthy_env_enables_compile_bytecode_without_option(self, value): + os.environ["UV_COMPILE_BYTECODE"] = value + with self.assertLogs("aws_lambda_builders.workflows.python_uv.workflow", "INFO") as logs: + config = self._workflow(None).actions[0].config + self.assertTrue(config.compile_bytecode) + self.assertIn(f"UV_COMPILE_BYTECODE={value} is set", "\n".join(logs.output)) + + def test_truthy_env_enables_compile_bytecode_on_requirements_build(self): + os.environ["UV_COMPILE_BYTECODE"] = "1" + requirements = os.path.join(self.source_dir, "requirements.txt") + open(requirements, "w").close() + config = self._workflow({"build_logical_id": "Fn"}, manifest=requirements).actions[0].config + self.assertTrue(config.compile_bytecode) + + def test_explicit_false_option_wins_over_truthy_env(self): + os.environ["UV_COMPILE_BYTECODE"] = "1" + config = self._workflow({"uv_compile_bytecode": False}).actions[0].config + self.assertFalse(config.compile_bytecode) + + @parameterized.expand([("0",), ("false",), ("OFF",), ("no",), ("n",), ("f",)]) + def test_falsy_env_keeps_compile_bytecode_off(self, value): + os.environ["UV_COMPILE_BYTECODE"] = value + with self.assertNoLogs("aws_lambda_builders.workflows.python_uv.workflow", "INFO"): + config = self._workflow(None).actions[0].config + self.assertFalse(config.compile_bytecode) + + @parameterized.expand([("2",), ("maybe",), ("",)]) + def test_unknown_env_value_warns_and_keeps_compile_bytecode_off(self, value): + os.environ["UV_COMPILE_BYTECODE"] = value + with self.assertLogs("aws_lambda_builders.workflows.python_uv.workflow", "WARNING") as logs: + config = self._workflow(None).actions[0].config + self.assertFalse(config.compile_bytecode) + self.assertIn(f"Ignoring UV_COMPILE_BYTECODE={value!r}", "\n".join(logs.output)) def test_no_options_keep_defaults(self): config = self._workflow(None).actions[0].config self.assertEqual(config.to_export_args(), []) + self.assertFalse(config.compile_bytecode) @parameterized.expand( [ @@ -246,6 +305,8 @@ def test_no_options_keep_defaults(self): ({"uv_all_extras": "true"}, "uv_all_extras must be true or false"), ({"uv_prune": "boto3"}, "uv_prune must be a list of non-empty strings"), ({"uv_prune": [""]}, "uv_prune must be a list of non-empty strings"), + ({"uv_compile_bytecode": "true"}, "uv_compile_bytecode must be true or false"), + ({"uv_compile_bytecode": 1}, "uv_compile_bytecode must be true or false"), ({"uv_group": ["lambda"]}, "Unknown uv build option(s): uv_group"), ({"uv_extras": ["x"], "uv_all_extras": True}, "uv_extras and uv_all_extras cannot be used together"), ]