Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions aws_lambda_builders/workflows/python_uv/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,22 +239,40 @@ SAM CLI maps them from `Metadata.BuildProperties`.
| `uv_extras` | `UvExtras` | list of str | `--extra <name>` per entry |
| `uv_all_extras` | `UvAllExtras` | bool | `--all-extras` |
| `uv_prune` | `UvPrune` | list of str | `--prune <name>` 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
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 <version>`) 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
Expand Down
33 changes: 31 additions & 2 deletions aws_lambda_builders/workflows/python_uv/workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
"""
Expand Down Expand Up @@ -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"):
Comment on lines +174 to +175

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

[BUG] Bytecode enabled with no manifest crashes the build with a TypeError
Before this change, any truthy uv_* option on a build with no manifest stopped at self._fail(...). Now that check runs only when export_options is non-empty. If uv_compile_bytecode is the only truthy value, the code goes on to the unchanged project_name = self._project_name(manifest_path).

That value can also come from a truthy UV_COMPILE_BYTECODE in the environment. When detect_uv_manifest finds nothing, __init__ sets manifest_path = None. _project_name(None) then calls open(None, "rb"), which raises TypeError. _project_name only catches OSError and ValueError, so the error is not handled.

The result: a user with UV_COMPILE_BYTECODE=1 set globally who builds a function with no pyproject.toml or requirements.txt gets an unhandled exception while the workflow is being built. Before this change, the build continued without dependencies. No build action uses the config when there is no manifest.

Fix: only call _project_name when it's needed (if values.get("uv_prune")). Alternatively, return UvConfig(compile_bytecode=...) before the project-name check when manifest_path is None and export_options is empty.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Reproduced by a hands-on run 🧪

Commit 02ea32f · build LambdaToolingHandsOn-NoDocker:ed9079ab-7324-4df2-8610-14f93149e8d1 · scenario S4 · reproduced 2 times · exit codes 2, 2, 0

Commands:

. /work/scratch/venv-head/bin/activate; UV_COMPILE_BYTECODE=1 python /work/scratch/ho/build.py /work/scratch/ho/s4-head requirements.txt '{}'
. /work/scratch/venv-head/bin/activate; env -u UV_COMPILE_BYTECODE python /work/scratch/ho/build.py /work/scratch/ho/s4-head requirements.txt '{"uv_compile_bytecode": true}'
. /work/scratch/venv-base/bin/activate; UV_COMPILE_BYTECODE=1 python /work/scratch/ho/build.py /work/scratch/ho/s4-base requirements.txt '{}'

Evidence:

head, == env=1
WARNING aws_lambda_builders.workflows.python_uv.workflow: No UV-compatible manifest file found (pyproject.toml, requirements.txt). Continuing the build without dependencies.
INFO aws_lambda_builders.workflows.python_uv.workflow: UV_COMPILE_BYTECODE=1 is set, compiling unchecked-hash bytecode for dependencies
BUILD_ERROR TypeError expected str, bytes or os.PathLike object, not NoneType
EXIT=2

head traceback:
  File "/work/head/aws_lambda_builders/workflows/python_uv/workflow.py", line 181, in _uv_config_from_options
    project_name = self._project_name(manifest_path)
  File "/work/head/aws_lambda_builders/workflows/python_uv/workflow.py", line 204, in _project_name
    with open(pyproject_path, "rb") as pyproject_file:
TypeError: expected str, bytes or os.PathLike object, not NoneType

base, == env=1
WARNING ... No UV-compatible manifest file found ...
ARTIFACTS ['app.py']
PYC_COUNT 0
EXIT=0

🤖 Automated hands-on test — not a review approval

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.

Confirmed and reproduced on develop: with no manifest, _project_name(None) raised TypeError. Fixed in #976, which reads the project name only when uv_prune is set. With no manifest the build continues without dependencies, as before this PR.

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'}"
)

Expand All @@ -161,6 +189,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),
)

@staticmethod
Expand Down
75 changes: 75 additions & 0 deletions tests/integration/workflows/python_uv/test_python_uv.py
Original file line number Diff line number Diff line change
Expand Up @@ -687,6 +687,81 @@ def test_workflow_prunes_runtime_provided_packages(self):
)
self.assertIn("uv_prune cannot name the project being built (pruneapp)", 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:
Expand Down
61 changes: 61 additions & 0 deletions tests/unit/workflows/python_uv/test_workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -240,6 +245,59 @@ def test_options_are_passed_to_the_build_action(self, _, extras_options, extras,
self.assertEqual(config.extras, extras)
self.assertEqual(config.all_extras, 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))

@parameterized.expand(
[("app", "app"), ("app", "App"), ("my-app", "my_app"), ("My_App", "my.app"), ("my-app", "My--App")]
Expand Down Expand Up @@ -272,6 +330,7 @@ def test_prune_without_a_project_name_is_left_to_uv(self, content):
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(
[
Expand All @@ -281,6 +340,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"),
]
Expand Down
Loading