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
33 changes: 33 additions & 0 deletions aws_lambda_builders/workflows/python_uv/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,39 @@ config = {
}
```

### Build options

`PythonUvWorkflow` reads these keys from the workflow `options` and passes them to `uv export`.
SAM CLI maps them from `Metadata.BuildProperties`.

| Option | SAM CLI property | Type | `uv export` effect |
|---|---|---|---|
| `uv_groups` | `UvGroups` | list of str | `--group <name>` per entry |
| `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 |

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);
- a `uv_prune` name is not a package in `uv.lock`, which `uv export --prune` would otherwise ignore.

### 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
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
every setting in that file. The build log shows uv's warning about it (the workflow logs every `warning:`
that uv prints, once per build), so check the key names against uv's settings reference.

### Caching

The workflow does not pass `--cache-dir` unless a caller supplies one, so UV uses its own
Expand Down
46 changes: 45 additions & 1 deletion aws_lambda_builders/workflows/python_uv/packager.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
import logging
import os
import re
from typing import Dict, List, Optional
from typing import Dict, List, Optional, Set

from aws_lambda_builders.architecture import ARM64, X86_64

Expand All @@ -24,6 +24,7 @@ def __init__(self, osutils: Optional[OSUtils] = None):
osutils = OSUtils()
self._osutils = osutils
self._uv_executable = self._find_uv_executable()
self._warnings_seen: Set[str] = set()

def _find_uv_executable(self) -> str:
"""Find UV executable in PATH."""
Expand Down Expand Up @@ -76,9 +77,28 @@ def run_uv_command(self, args: List[str], cwd: Optional[str] = None, env: Option
LOG.debug("UV command return code: %d", rc)
LOG.debug("UV stdout: %s", stdout)
LOG.debug("UV stderr: %s", stderr)
self._log_warnings(stderr)

return rc, stdout, stderr

def _log_warnings(self, stderr: Optional[str]) -> None:
"""Log each `warning:` block uv prints, once per build; uv repeats some on every command."""
blocks: List[List[str]] = []
current = None
for line in (stderr or "").splitlines():
if line.startswith("warning:"):
current = [line]
blocks.append(current)
elif current is not None and line[:1] in (" ", "\t"):
current.append(line) # uv indents a warning's continuation lines
else:
current = None
for block in blocks:
message = "\n".join(block)
if message not in self._warnings_seen:
self._warnings_seen.add(message)
LOG.warning("uv %s", message)


class UvRunner:
"""High-level wrapper around UV operations."""
Expand Down Expand Up @@ -458,6 +478,28 @@ def _lock_export_options(lock_path: str) -> List[str]:
args.extend(["--exclude-newer-package", f"{package}={value}"])
return args

@staticmethod
def _check_prune_names(lock_path: str, prune: List[str]) -> None:
"""Fail on prune names missing from the lock; `uv export --prune` ignores them silently."""
if not prune:
return
try:
import tomllib
except ModuleNotFoundError: # Python 3.10
import tomli as tomllib

try:
with open(lock_path, "rb") as lock_file:
packages = tomllib.load(lock_file).get("package", [])
except FileNotFoundError:
# Leave missing-lock diagnostics to UV.
return

locked = {package.get("name") for package in packages if isinstance(package, dict)}
missing = [name for name in prune if re.sub(r"[-_.]+", "-", name).lower() not in locked]
if missing:
raise LockFileError(reason=f"Build option uv_prune names packages not in {lock_path}: {', '.join(missing)}")

def _build_from_lock_file(
self,
lock_path: str,
Expand All @@ -480,6 +522,7 @@ def _build_from_lock_file(
try:
if project_dir is None:
project_dir = os.path.dirname(lock_path)
self._check_prune_names(lock_path, config.prune)

# Export lock file to requirements.txt for platform-specific install
# Export and install may run from different directories in a workspace
Expand All @@ -500,6 +543,7 @@ def _build_from_lock_file(
"--python",
python_version,
]
export_args.extend(config.to_export_args())
Comment thread
bnusunny marked this conversation as resolved.
Resolved
export_args.extend(self._lock_export_options(lock_path))
export_args.extend(config.cache_args())

Expand Down
21 changes: 21 additions & 0 deletions aws_lambda_builders/workflows/python_uv/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,10 @@ def __init__(
compile_bytecode: bool = True,
exclude_newer: Optional[str] = None,
generate_hashes: bool = False,
groups: Optional[List[str]] = None,
extras: Optional[List[str]] = None,
all_extras: bool = False,
prune: Optional[List[str]] = None,
):
self.index_url = index_url
self.extra_index_urls = extra_index_urls or []
Expand All @@ -146,6 +150,23 @@ def __init__(
self.compile_bytecode = compile_bytecode
self.exclude_newer = exclude_newer
self.generate_hashes = generate_hashes
self.groups = groups or []
self.extras = extras or []
self.all_extras = all_extras
self.prune = prune or []

def to_export_args(self) -> List[str]:
"""Convert the dependency selection to `uv export` arguments."""
args = []
for group in self.groups:
args.extend(["--group", group])
for extra in self.extras:
args.extend(["--extra", extra])
if self.all_extras:
args.append("--all-extras")
for package in self.prune:
args.extend(["--prune", package])
return args

def cache_args(self) -> List[str]:
"""Convert the cache options to UV command line arguments."""
Expand Down
58 changes: 55 additions & 3 deletions aws_lambda_builders/workflows/python_uv/workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,25 @@
"""

import logging
import os

from aws_lambda_builders.actions import CleanUpAction, CopyDependenciesAction, CopySourceAction
from aws_lambda_builders.exceptions import WorkflowFailedError
from aws_lambda_builders.workflow import BaseWorkflow, BuildDirectory, BuildInSourceSupport, Capability

from .actions import PythonUvBuildAction
from .utils import OSUtils, detect_uv_manifest
from .utils import OSUtils, UvConfig, detect_uv_manifest

LOG = logging.getLogger(__name__)

# Build options (from sam-cli Metadata.BuildProperties) and their expected types
UV_OPTIONS = {
"uv_groups": list,
"uv_extras": list,
"uv_all_extras": bool,
"uv_prune": list,
}


class PythonUvWorkflow(BaseWorkflow):
"""
Expand Down Expand Up @@ -104,9 +114,50 @@ def __init__(self, source_dir, artifacts_dir, scratch_dir, manifest_path, runtim
)
manifest_path = None

self._setup_build_actions(source_dir, artifacts_dir, scratch_dir, manifest_path, runtime)
config = self._uv_config_from_options(manifest_path)
self._setup_build_actions(source_dir, artifacts_dir, scratch_dir, manifest_path, runtime, config)

def _fail(self, reason):
# Same action name BaseWorkflow uses for runtime validation errors
raise WorkflowFailedError(workflow_name=self.NAME, action_name="Validation", reason=reason)

def _uv_config_from_options(self, manifest_path):
"""Build the UvConfig from the uv_* build options, rejecting anything invalid."""
options = self.options if isinstance(self.options, dict) else {}
unknown = sorted(key for key in options if key.startswith("uv_") and key not in UV_OPTIONS)
if unknown:
self._fail(f"Unknown uv build option(s): {', '.join(unknown)}. Supported: {', '.join(UV_OPTIONS)}")

values = {key: options[key] for key in UV_OPTIONS if options.get(key) is not None}
for key, value in values.items():
if UV_OPTIONS[key] is bool:
valid = isinstance(value, bool)
else:
valid = isinstance(value, list) and all(isinstance(item, str) and item for item in value)
if not valid:
expected = "true or false" if UV_OPTIONS[key] is bool else "a list of non-empty strings"
self._fail(f"Build option {key} must be {expected}, got {value!r}")

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

if not any(values.values()):
return UvConfig()

if 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"but this build uses {os.path.basename(manifest_path) if manifest_path else 'no manifest'}"
)

return UvConfig(
groups=values.get("uv_groups"),
extras=values.get("uv_extras"),
all_extras=values.get("uv_all_extras", False),
prune=values.get("uv_prune"),
)

def _setup_build_actions(self, source_dir, artifacts_dir, scratch_dir, manifest_path, runtime):
def _setup_build_actions(self, source_dir, artifacts_dir, scratch_dir, manifest_path, runtime, config=None):
"""
Set up the build actions based on configuration.

Expand Down Expand Up @@ -136,6 +187,7 @@ def _setup_build_actions(self, source_dir, artifacts_dir, scratch_dir, manifest_
self.dependencies_dir, # Pass for action's internal logic
binaries=self.binaries,
architecture=self.architecture,
config=config,
Comment thread
aws-sam-tooling-bot[bot] marked this conversation as resolved.
Resolved
)
)

Expand Down
28 changes: 28 additions & 0 deletions tests/functional/workflows/python_uv/test_packager.py
Original file line number Diff line number Diff line change
Expand Up @@ -658,3 +658,31 @@ def test_can_build_with_hash_verification(self, tmpdir, uv_runner, osutils):
fake_uv.validate()

assert "certifi" in installed_packages

def test_lock_export_uses_build_options(self, tmpdir, uv_runner, osutils):
"""Build options select groups and extras"""
fake_uv, runner = uv_runner
appdir, builder, manifest_path = self._make_appdir_and_dependency_builder(
["six"], tmpdir, runner, manifest_type="pyproject"
)
with open(os.path.join(appdir, "uv.lock"), "w") as f:
f.write('version = 1\nrequires-python = ">=3.8"\n')
config = UvConfig(groups=["lambda"], extras=["fast", "small"])

with osutils.tempdir() as scratch_dir:
builder.build_dependencies(
artifacts_dir_path=os.path.join(appdir, "site-packages"),
scratch_dir_path=scratch_dir,
manifest_path=manifest_path,
architecture=X86_64,
config=config,
)

export_args = fake_uv._calls["export"][0][0]
assert "--no-emit-project" in export_args
assert "--no-editable" in export_args
assert "--no-default-groups" in export_args
assert export_args[export_args.index("--group") :][:2] == ["--group", "lambda"]
assert [export_args[i + 1] for i, arg in enumerate(export_args) if arg == "--extra"] == ["fast", "small"]
(pip_args,) = (call[0] for call in fake_uv._calls["pip"])
assert "--group" not in pip_args and "--extra" not in pip_args
93 changes: 93 additions & 0 deletions tests/integration/workflows/python_uv/test_python_uv.py
Original file line number Diff line number Diff line change
Expand Up @@ -581,3 +581,96 @@ def test_workflow_reuses_existing_workspace_lock(self):
self.assertTrue(pathlib.Path(self.artifacts_dir, "workspace_lib", "__init__.py").is_file())
self.assertEqual(list(pathlib.Path(self.artifacts_dir).glob("workspace_app-*.dist-info")), [])
self.assertEqual(list(pathlib.Path(self.artifacts_dir).rglob("*.pth")), [])

@skipIf(which("uv") is None, "uv not available")
def test_workflow_applies_build_options(self):
with tempfile.TemporaryDirectory() as source_dir:
pathlib.Path(source_dir, "pyproject.toml").write_text(
'[project]\nname = "optsapp"\nversion = "0.1.0"\nrequires-python = ">=3.9"\n'
'dependencies = ["six==1.16.0"]\n\n'
'[project.optional-dependencies]\ndns = ["idna==3.10"]\n\n'
'[dependency-groups]\nlambda = ["toml==0.10.2"]\nother = ["pyasn1==0.6.1"]\n\n'
'[build-system]\nrequires = ["uv_build>=0.8,<1"]\nbuild-backend = "uv_build"\n'
)
package_dir = pathlib.Path(source_dir, "src", "optsapp")
package_dir.mkdir(parents=True)
package_dir.joinpath("__init__.py").write_text("VALUE = 1\n")

builder = LambdaBuilder(language="python", dependency_manager="uv", application_framework=None)
builder.build(
source_dir,
self.artifacts_dir,
self.scratch_dir,
os.path.join(source_dir, "pyproject.toml"),
runtime=f"python{sys.version_info.major}.{sys.version_info.minor}",
experimental_flags=self.experimental_flags,
options={"uv_groups": ["lambda"], "uv_extras": ["dns"]},
)

artifacts = pathlib.Path(self.artifacts_dir)
self.assertTrue(artifacts.joinpath("six.py").is_file())
self.assertTrue(artifacts.joinpath("toml", "__init__.py").is_file())
self.assertTrue(artifacts.joinpath("idna", "__init__.py").is_file())
self.assertEqual(list(artifacts.glob("pyasn1*")), [])
# Only dependencies are exported; the project itself is not installed
self.assertEqual(list(artifacts.glob("optsapp-*.dist-info")), [])
self.assertEqual(list(artifacts.rglob("*.pth")), [])

@skipIf(which("uv") is None, "uv not available")
def test_workflow_prunes_runtime_provided_packages(self):
with tempfile.TemporaryDirectory() as source_dir:
pathlib.Path(source_dir, "pyproject.toml").write_text(
'[project]\nname = "pruneapp"\nversion = "0.1.0"\nrequires-python = ">=3.9"\n'
'dependencies = ["boto3==1.35.0", "requests==2.32.3"]\n'
)
builder = LambdaBuilder(language="python", dependency_manager="uv", application_framework=None)
build_args = (source_dir, self.artifacts_dir, self.scratch_dir, os.path.join(source_dir, "pyproject.toml"))
runtime = f"python{sys.version_info.major}.{sys.version_info.minor}"

builder.build(
*build_args,
runtime=runtime,
experimental_flags=self.experimental_flags,
options={"uv_prune": ["boto3"]},
)

artifacts = pathlib.Path(self.artifacts_dir)
for pruned in ("boto3", "botocore", "s3transfer", "jmespath"):
self.assertEqual(list(artifacts.glob(f"{pruned}*")), [], pruned)
# urllib3 stays because requests also needs it
self.assertTrue(artifacts.joinpath("requests", "__init__.py").is_file())
self.assertTrue(artifacts.joinpath("urllib3", "__init__.py").is_file())

with self.assertRaises(WorkflowFailedError) as ctx:
builder.build(
*build_args,
runtime=runtime,
experimental_flags=self.experimental_flags,
options={"uv_prune": ["not-a-locked-package"]},
)
self.assertIn("uv_prune names packages not in", str(ctx.exception))

@skipIf(which("uv") is None, "uv not available")
def test_workflow_shows_uv_warnings(self):
with tempfile.TemporaryDirectory() as source_dir:
# An unknown [tool.uv] key makes uv ignore every setting in the file; only a warning says so
pathlib.Path(source_dir, "pyproject.toml").write_text(
'[project]\nname = "warnapp"\nversion = "0.1.0"\nrequires-python = ">=3.9"\n'
'dependencies = ["six==1.16.0"]\n\n[tool.uv]\nbogus-key = true\n'
)
with self.assertLogs("aws_lambda_builders.workflows.python_uv.packager", level="WARNING") as logs:
LambdaBuilder(language="python", dependency_manager="uv", application_framework=None).build(
source_dir,
self.artifacts_dir,
self.scratch_dir,
os.path.join(source_dir, "pyproject.toml"),
runtime=f"python{sys.version_info.major}.{sys.version_info.minor}",
experimental_flags=self.experimental_flags,
)

warnings = [record.getMessage() for record in logs.records if "bogus-key" in record.getMessage()]
# uv repeats it on lock, export and install; the build shows it once
self.assertEqual(len(warnings), 1, warnings)
self.assertTrue(warnings[0].startswith("uv warning: Failed to parse `pyproject.toml`"), warnings[0])
self.assertIn("unknown field `bogus-key`", warnings[0])
self.assertIn("six.py", os.listdir(self.artifacts_dir))
Loading
Loading