repro-lambda 0.8.2__tar.gz → 0.9.0__tar.gz

repro_lambda-0.9.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.9.0"
+}

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.0](https://github.com/antonbabenko/repro-lambda/compare/v0.8.2...v0.9.0) (2026-10-30)
+
+
+### Features
+
+* compile_bytecode ships checked-hash bytecode in python lambdas ([#22](https://github.com/antonbabenko/repro-lambda/issues/22)) ([47677cf](https://github.com/antonbabenko/repro-lambda/commit/47677cfdafe3832e5d0a570c5ce1fa7b509864c1))
+
 ## [0.8.2](https://github.com/antonbabenko/repro-lambda/compare/v0.8.1...v0.8.2) (2026-09-23)
 
 

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: repro-lambda
-Version: 0.8.2
+Version: 0.9.0
 Summary: Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf.
 Project-URL: Homepage, https://github.com/antonbabenko/repro-lambda
 Project-URL: Repository, https://github.com/antonbabenko/repro-lambda

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/USAGE.md

@@ -63,6 +63,29 @@ Pin the `base_image_python` to a specific digest with `docker pull <image> &&
 docker inspect --format='{{index .RepoDigests 0}}' <image>` - never use a
 floating tag in production.
 
+### Shipping bytecode (`compile_bytecode`)
+
+A Lambda's `/var/task` is read-only, so a package shipped without `.pyc` files is
+recompiled from source by every new Python process that imports it. For a large
+package (or a handler that starts Python subprocesses) that can cost seconds per
+invocation. Set `compile_bytecode = true` on a pip `[[lambda]]` to compile the whole
+package in the builder image (the runtime's own interpreter) and keep the bytecode
+in the zip:
+
+```toml
+[[lambda]]
+logical_name     = "app"
+# ...
+compile_bytecode = true
+```
+
+The zip step removes any bytecode already in the tree, then runs `compileall` with
+`--invalidation-mode checked-hash` (no source mtimes; the interpreter checks each
+`.pyc` against its source hash on import) and `PYTHONHASHSEED=0`, recording file paths
+as `/var/task/...` so the bytes do not depend on the staging directory. The zip stays
+byte-reproducible. The flag is part of the content key (only when set, so lambdas
+without it keep their keys). A file that does not compile ships as source only.
+
 ### Per-lambda builder overrides
 
 `[builder]` sets the defaults for every lambda. Any `[[lambda]]` may override

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repro-lambda"
-version = "0.8.2"
+version = "0.9.0"
 description = "Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf."
 readme = "README.md"
 requires-python = ">=3.11"

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/__init__.py

@@ -1,3 +1,3 @@
 """repro-lambda — reproducible AWS Lambda packaging outside Terraform."""
 
-__version__ = "0.8.2"  # x-release-please-version
+__version__ = "0.9.0"  # x-release-please-version

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/build.py

@@ -167,6 +167,7 @@ def build_one(
                 base_image=builder.base_image_python,
                 arch=spec.arch,
                 python_version=spec.runtime.removeprefix("python"),
+                compile_bytecode=spec.compile_bytecode,
             )
         else:  # npm
             # nodejs22.x -> "22"; nodejs20.x -> "20"

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/cli.py

@@ -381,18 +381,33 @@ _LAMBDA_ZIP_EXCLUDES = [
 ]
 
 
-def _zip_impl(src: Path, out: Path) -> None:
+_BYTECODE_PATTERNS = ("*__pycache__*", "*.pyc")
+
+
+def _zip_impl(src: Path, out: Path, compile_bytecode: bool = False) -> None:
     """Pack a directory into a deterministic zip (used inside container)."""
+    from repro_lambda.zip_packager import compile_bytecode as compile_tree
     from repro_lambda.zip_packager import pack_directory
 
-    pack_directory(src, out, exclude_glob=_LAMBDA_ZIP_EXCLUDES)
+    excludes = _LAMBDA_ZIP_EXCLUDES
+    if compile_bytecode:
+        compile_tree(src)
+        excludes = [p for p in excludes if p not in _BYTECODE_PATTERNS]
+    pack_directory(src, out, exclude_glob=excludes)
 
 
 @app.command(name="zip")
 def zip_(
     src: Annotated[Path, typer.Option("--src", help="Staged package directory.")],
     out: Annotated[Path, typer.Option("--out", help="Output zip path.")],
+    compile_bytecode: Annotated[
+        bool,
+        typer.Option(
+            "--compile-bytecode",
+            help="Compile checked-hash bytecode with this interpreter and keep it in the zip.",
+        ),
+    ] = False,
 ) -> None:
     """Pack a directory into a deterministic zip (used inside container)."""
-    _zip_impl(src, out)
+    _zip_impl(src, out, compile_bytecode)
     raise typer.Exit(0)

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/docker_runner.py

@@ -91,8 +91,11 @@ pip install \
 
 # Byte-output cleanup (caches + non-deterministic dist-info metadata) happens in the
 # Python zip step below, so this script needs no findutils/xargs (both absent from the
-# minimal AWS Lambda base images).
-python3 -m repro_lambda zip --src "$PKG" --out /out/lambda.zip
+# minimal AWS Lambda base images). With COMPILE_BYTECODE=1 the zip step first compiles
+# the tree with this image's interpreter (the Lambda runtime) and keeps the bytecode.
+ZIP_ARGS=""
+if [ "$COMPILE_BYTECODE" = "1" ]; then ZIP_ARGS="--compile-bytecode"; fi
+python3 -m repro_lambda zip --src "$PKG" --out /out/lambda.zip $ZIP_ARGS
 """
 
 _NODEJS_INSTALL_SCRIPT = r"""
@@ -161,6 +164,7 @@ def build_python_lambda(
     base_image: str,
     arch: str,
     python_version: str,
+    compile_bytecode: bool = False,
 ) -> None:
     """v0.1-compatible: install + pack inside the Python container."""
     if arch not in ARCH_TO_PIP_PLATFORMS:
@@ -196,6 +200,8 @@ def build_python_lambda(
         f"PIP_ABI=cp{pyver_compact}",
         "-e",
         f"PIP_PYVER={pyver}",
+        "-e",
+        f"COMPILE_BYTECODE={int(compile_bytecode)}",
         "--entrypoint",
         "bash",
         base_image,

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/hasher.py

@@ -85,6 +85,8 @@ def compute_content_hash(
     h.update(f"package_manager={spec.package_manager}\n".encode())
     h.update(f"lambda_at_edge={int(spec.lambda_at_edge)}\n".encode())
     h.update(f"hash_extra={spec.hash_extra}\n".encode())
+    if spec.compile_bytecode:  # only when set, so specs without it keep their hashes
+        h.update(b"compile_bytecode=1\n")
     h.update(f"base_image={base_image}\n".encode())
     h.update(f"builder_version={builder_version}\n".encode())
 

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/manifest.py

@@ -131,6 +131,9 @@ class LambdaSpec:
     include_patterns: list[str] | None = None
     exclude_patterns: list[str] | None = None
     sources: tuple[Source, ...] = ()
+    # pip only: ship checked-hash bytecode compiled in the builder image, so a read-only
+    # /var/task does not recompile every imported module in every new process.
+    compile_bytecode: bool = False
 
     @property
     def resolved_requirements_lock(self) -> str:
@@ -450,6 +453,16 @@ def load_manifest(path: Path) -> Manifest:
 
         extra_files = _parse_extra_files(path, entry)
         sources = _parse_sources(path, entry)
+        compile_bytecode = entry.get("compile_bytecode", False)
+        if not isinstance(compile_bytecode, bool):
+            raise ValueError(
+                f"{path}: lambda {entry.get('logical_name')!r} compile_bytecode must be a boolean "
+                f"(got {compile_bytecode!r})"
+            )
+        if compile_bytecode and pkg != "pip":
+            raise ValueError(
+                f"{path}: lambda {entry.get('logical_name')!r} compile_bytecode is for pip lambdas"
+            )
 
         override_base_image = entry.get("base_image_python")
         if override_base_image is not None and "@sha256:" not in override_base_image:
@@ -489,6 +502,7 @@ def load_manifest(path: Path) -> Manifest:
                 include_patterns=list(override_include) if override_include is not None else None,
                 exclude_patterns=list(override_exclude) if override_exclude is not None else None,
                 sources=sources,
+                compile_bytecode=compile_bytecode,
             )
         )
 

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/verify.py

@@ -68,6 +68,7 @@ def verify_reproducible(
                     base_image=builder.base_image_python,
                     arch=spec.arch,
                     python_version=spec.runtime.removeprefix("python"),
+                    compile_bytecode=spec.compile_bytecode,
                 )
             else:  # npm
                 node_ver = spec.runtime.removeprefix("nodejs").removesuffix(".x")

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/src/repro_lambda/zip_packager.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import fnmatch
+import os
 import sys
 from pathlib import Path
 from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
@@ -76,3 +77,46 @@ def pack_directory(
             else:
                 data = p.read_bytes()
             zf.writestr(zinfo, data)
+
+
+def compile_bytecode(src: Path, deploy_root: str = "/var/task") -> None:
+    """Replace any bytecode under `src` with checked-hash .pyc built by this interpreter.
+
+    checked-hash bytecode carries no source mtime (the zip resets every mtime) and the
+    interpreter checks it against the source hash on import, so it stays valid in a
+    read-only deploy dir. Recorded file paths are rewritten from `src` to `deploy_root`
+    (tracebacks show the deployed paths, and the bytes do not depend on the staging dir);
+    PYTHONHASHSEED=0 keeps the marshalled output stable. A file that does not compile gets
+    no bytecode and is compiled at import as before; compileall's report is printed.
+    """
+    import shutil
+    import subprocess
+
+    root = src.resolve()
+    for cache in sorted(root.rglob("__pycache__"), reverse=True):
+        if cache.is_dir() and not cache.is_symlink():
+            shutil.rmtree(cache)
+    for stale in root.rglob("*.pyc"):
+        stale.unlink()
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "compileall",
+            "-q",
+            "--invalidation-mode",
+            "checked-hash",
+            "-s",
+            str(root),
+            "-p",
+            deploy_root,
+            str(root),
+        ],
+        env={**os.environ, "PYTHONHASHSEED": "0"},
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(
+            f"warning: some files did not compile:\n{result.stdout}{result.stderr}", file=sys.stderr
+        )

repro_lambda-0.9.0/tests/test_compile_bytecode.py

@@ -0,0 +1,114 @@
+"""compile_bytecode: checked-hash .pyc built in the zip step, keyed into the content hash."""
+
+import dataclasses
+import importlib.util
+import marshal
+from pathlib import Path
+from zipfile import ZipFile
+
+import pytest
+from typer.testing import CliRunner
+
+from repro_lambda.cli import app
+from repro_lambda.hasher import compute_content_hash
+from repro_lambda.manifest import LambdaSpec, load_manifest
+
+runner = CliRunner()
+
+
+def _pkg(root: Path) -> Path:
+    pkg = root / "pkg"
+    (pkg / "mymod" / "__pycache__").mkdir(parents=True)
+    (pkg / "mymod" / "__init__.py").write_text("VALUES = frozenset({'a', 'b', 'c'})\n")
+    (pkg / "mymod" / "__pycache__" / "stale.cpython-313.pyc").write_bytes(b"\x00")
+    (pkg / "mymod" / "orphan.pyc").write_bytes(b"\x00")
+    (pkg / "broken.py").write_text("def broken(:\n")
+    return pkg
+
+
+def _zip(pkg: Path, out: Path, *extra: str) -> list[str]:
+    result = runner.invoke(app, ["zip", "--src", str(pkg), "--out", str(out), *extra])
+    assert result.exit_code == 0, result.output
+    return ZipFile(out).namelist()
+
+
+def test_zip_compiles_checked_hash_bytecode_with_deployed_paths(tmp_path: Path):
+    names = _zip(_pkg(tmp_path), tmp_path / "lambda.zip", "--compile-bytecode")
+    pycs = [n for n in names if n.endswith(".pyc")]
+    assert len(pycs) == 1 and pycs[0].startswith("mymod/__pycache__/__init__.")
+    data = ZipFile(tmp_path / "lambda.zip").read(pycs[0])
+    assert data[:4] == importlib.util.MAGIC_NUMBER
+    assert int.from_bytes(data[4:8], "little") == 0b11  # hash-based, checked
+    assert marshal.loads(data[16:]).co_filename == "/var/task/mymod/__init__.py"
+    assert "mymod/orphan.pyc" not in names  # stale bytecode is replaced, not shipped
+    assert "broken.py" in names  # a file that does not compile ships as source only
+
+
+def test_compiled_zip_is_byte_identical_across_builds(tmp_path: Path):
+    a, b = tmp_path / "a", tmp_path / "b"  # different staging dirs, same tree
+    _zip(_pkg(a), a / "lambda.zip", "--compile-bytecode")
+    _zip(_pkg(b), b / "lambda.zip", "--compile-bytecode")
+    assert (a / "lambda.zip").read_bytes() == (b / "lambda.zip").read_bytes()
+
+
+def test_zip_without_the_flag_still_strips_bytecode(tmp_path: Path):
+    names = _zip(_pkg(tmp_path), tmp_path / "lambda.zip")
+    assert not any(n.endswith(".pyc") or "__pycache__" in n for n in names)
+
+
+def _spec(**kw) -> LambdaSpec:
+    base = LambdaSpec(
+        logical_name="app",
+        source_dir="handler",
+        requirements_lock="handler/requirements.${arch}.lock",
+        runtime="python3.13",
+        arch="arm64",
+        handler="app.lambda_handler",
+    )
+    return dataclasses.replace(base, **kw)
+
+
+def test_flag_changes_the_content_hash_and_default_keeps_it(tmp_path: Path):
+    src = tmp_path / "source"
+    src.mkdir()
+    (src / "app.py").write_text("x = 1\n")
+    lock = tmp_path / "requirements.arm64.lock"
+    lock.write_text("# empty\n")
+    off = compute_content_hash(src, lock, _spec(), "x@sha256:0", "1")
+    on = compute_content_hash(src, lock, _spec(compile_bytecode=True), "x@sha256:0", "1")
+    assert off != on
+    assert off == compute_content_hash(src, lock, _spec(compile_bytecode=False), "x@sha256:0", "1")
+
+
+def _manifest(tmp_path: Path, extra: str, package_manager: str = "pip") -> Path:
+    path = tmp_path / "lambdas.toml"
+    path.write_text(
+        f"""
+[[lambda]]
+logical_name = "app"
+source_dir = "handler"
+requirements_lock = "handler/requirements.${{arch}}.lock"
+runtime = "python3.13"
+arch = "arm64"
+handler = "app.lambda_handler"
+package_manager = "{package_manager}"
+{extra}
+
+[builder]
+base_image_python = "public.ecr.aws/lambda/python:3.13@sha256:abc"
+"""
+    )
+    return path
+
+
+def test_manifest_reads_the_flag(tmp_path: Path):
+    assert (
+        load_manifest(_manifest(tmp_path, "compile_bytecode = true")).lambdas[0].compile_bytecode
+        is True
+    )
+    assert load_manifest(_manifest(tmp_path, "")).lambdas[0].compile_bytecode is False
+
+
+def test_manifest_rejects_a_non_boolean_flag(tmp_path: Path):
+    with pytest.raises(ValueError, match="compile_bytecode must be a boolean"):
+        load_manifest(_manifest(tmp_path, 'compile_bytecode = "yes"'))

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/tests/test_hash_contract.py

@@ -18,10 +18,11 @@ _PKG = Path(repro_lambda.__file__).parent
 # Known gap: npm packaging uses base_image_python, which is not in the key (issue #20).
 PACKAGING_FINGERPRINTS = {
     "0.8.0": {
-        "build.py": "2dc3140e8af9e7e68d70199f85f261db04eef3e847d60ac21c9276133e9ec041",
-        "hasher.py": "c5eb56e00737efdca6c4bb47b694390b3dbd8941569f6c5cb299ba4cd5b18704",
-        "zip_packager.py": "56810a5e337a2fd5f72c269ba81bab06ca2f019e14e0edb728d6c37881d7cf0a",
-        "docker_runner.py": "0092a103b8dd11e6c0a00979e4c38272ccc6d707f2ee74035d8d84e61fed4988",
+        # compile_bytecode: off by default and hashed only when on, so no bump.
+        "build.py": "21b10b59acf04dae78431e1c50ebbb89d300dd5d32bbdd36e0ee9c2cb3673ea9",
+        "hasher.py": "1061efdcb802598001c9638e34222b25b083c6123ff9b59a18dff996a4e0a70f",
+        "zip_packager.py": "40d48633ece8d5d9ffffdb786d7479b8588ec7b1fae99a7db748e3963f9b333a",
+        "docker_runner.py": "e53208a62ee7ee40e33068b6c3ba936c5e7d75037b1502f1af8fed92391f8f52",
         "source_stager.py": "38186277fb94ab6feac8a07cad2ae35f5adfaa52bde3d51ac71daccb003d3c68",
         "sources.py": "10415ccc89b85f521fb64ef199f084f0bea1842032d414cb3d3537334f6caa0b",
     },

{repro_lambda-0.8.2 → repro_lambda-0.9.0}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.11"
 
 [[package]]
@@ -646,7 +646,7 @@ wheels = [
 
 [[package]]
 name = "repro-lambda"
-version = "0.8.2"
+version = "0.9.0"
 source = { editable = "." }
 dependencies = [
     { name = "boto3" },

repro_lambda-0.8.2/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.8.2"
-}