prebuilt: address PR #92 council review (python_requires note + 4 clarity/robustness)

- python_requires>=3.10 (blocking): add a setup.py comment (both packages) that the
  floor mirrors the internal minimum (<3.10 dropped internally); no 3.10-only
  construct in the code — _parse_build_system_requires has tomllib/tomli/regex.
- Pass B shared overlay: _overlay_install now warns when a build dep is re-staged
  at a DIFFERENT version (surfaces the documented shared-overlay conflict instead
  of a silent miscompilation).
- deferred_sdists: comment that "url" is the guaranteed source (is_downloadable_url
  filter) and "filename" is only a best-effort hint (harmless if None).
- _gather_embedded_wheels Case D/E: comment that p.url is a placeholder
  (is_real_url=False + cached wheel => p.url is never fetched).
- Pass B overlay cleanup: comment that the on-failure rmtree + the finally rmtree
  double-remove is intentional and safe (ignore_errors=True).

No functional change to validated paths (comments + one diagnostic warning).
77 prebuilt unit tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Nissan Pow

metaflow-netflixext/setup.py

@@ -50,6 +50,7 @@
     package_data={
         "metaflow_extensions.netflixext.plugins.conda.resources": ["*.png", "*.svg"]
     },
+    # Mirrors the internal minimum (support for <3.10 was dropped internally).
     python_requires=">=3.10",
     install_requires=["metaflow>=2.16.0"],
     extras_require={

metaflow-prebuilt/metaflow_extensions/prebuilt/plugins/conda/prebuilt_build_install.py

@@ -308,7 +308,9 @@ def _run_deferred_sdist_builds(env_dir, resolved_env):  # type: ignore[no-untype
     build_env["PATH"] = (
         os.path.dirname(python_bin) + os.pathsep + build_env.get("PATH", "")
     )
-    overlay_state = {"dir": None}  # lazily created on first need
+    # dir: overlay path (lazily created); staged: base-name -> the spec last staged,
+    # used to warn when a build dep is re-staged at a different version (below).
+    overlay_state = {"dir": None, "staged": {}}
 
     def _ensure_overlay():
         if overlay_state["dir"] is None:
@@ -321,6 +323,23 @@ def _ensure_overlay():
     def _overlay_install(pkgs, what):
         if not pkgs:
             return
+        # The overlay is SHARED across an image's deferred sdists. If two sdists
+        # declare the same build dep at different versions, the last writer wins —
+        # an earlier sdist may have built against the now-replaced version. We can't
+        # isolate per-sdist (that fights --no-build-isolation), but we surface it
+        # with a warning instead of a silent miscompilation.
+        staged = overlay_state["staged"]
+        for pkg in pkgs:
+            base = re.split(r"[<>=!~ \[;]", pkg.strip(), 1)[0].strip().lower()
+            prev = staged.get(base)
+            if prev is not None and prev != pkg.strip():
+                _echo(
+                    " WARNING: Pass B build dep %r re-staged as %r in the shared "
+                    "overlay (was %r); an earlier sdist may have built against the "
+                    "previous version." % (base, pkg.strip(), prev),
+                    timestamp=False,
+                )
+            staged[base] = pkg.strip()
         overlay = _ensure_overlay()
         _echo(" (staging %s) ..." % what, timestamp=False, nl=False)
         if os.path.isfile(uv_bin):
@@ -349,6 +368,8 @@ def _overlay_install(pkgs, what):
             ] + list(pkgs)
         r = subprocess.run(args, capture_output=True, text=True)
         if r.returncode != 0:
+            # Remove the partial overlay now; the outer finally also rmtrees it
+            # (ignore_errors=True), so this double-remove is intentional and safe.
             shutil.rmtree(overlay, ignore_errors=True)
             raise CondaException(
                 "Pass B: could not stage %s into the build overlay.\nstderr: %s"

metaflow-prebuilt/metaflow_extensions/prebuilt/plugins/conda/prebuilt_conda_environment.py

@@ -504,6 +504,11 @@ def _get_or_build_image(
         # that wheel below, so they must NOT be deferred (the container would
         # otherwise rebuild from source, and only_binary=True would drop the
         # source archive in Pass A). Non-web and conda packages are excluded here.
+        # "url" is the GUARANTEED build source — the is_downloadable_url() filter
+        # below ensures it is a real, fetchable URL. "filename" is only a best-effort
+        # hint: Pass B prefers the hash-verified local artifact matched by filename
+        # and falls back to "url" when there's no match (so a None/empty filename is
+        # harmless). Pass B raises only if BOTH are unusable.
         deferred_sdists: List[Any] = [
             {
                 "name": p.package_name,
@@ -720,6 +725,9 @@ def _gather_embedded_wheels(
                     wheel_fname = wheel_basename[: -len(cache_whl.format)]
                     fetch_spec = PypiPackageSpecification(
                         wheel_fname,
+                        # p.url is the SOURCE url and is only a placeholder: with
+                        # is_real_url=False + add_cached_version(".whl") below,
+                        # lazy_fetch reads the cached wheel and never fetches p.url.
                         p.url,
                         is_real_url=False,  # built wheel: cache-only, never web
                         url_format=".whl",

metaflow-prebuilt/setup.py

@@ -36,6 +36,9 @@
     py_modules=[
         "metaflow_extensions",
     ],
+    # Mirrors the internal minimum (support for <3.10 was dropped internally). The
+    # code has no 3.10-only construct — _parse_build_system_requires uses a
+    # tomllib/tomli/regex fallback chain that works on any version.
     python_requires=">=3.10",
     install_requires=["metaflow>=2.16.0", "metaflow-netflixext>=1.3.12"],
     extras_require={