@vercel/python-analysis 0.8.1 → 0.8.2

package/dist/index.cjs

@@ -74,6 +74,7 @@ __export(src_exports, {
   parseUvLock: () => parseUvLock,
   scanDistributions: () => scanDistributions,
   selectPython: () => selectPython,
+  selectPythonVersion: () => selectPythonVersion,
   stringifyManifest: () => stringifyManifest
 });
 module.exports = __toCommonJS(src_exports);
@@ -739,17 +740,24 @@ function convertPipfileToPyprojectToml(pipfile) {
 function convertPipfileLockToPyprojectToml(pipfileLock) {
   const sources = {};
   const pyproject = {};
+  const pythonVersion = pipfileLock._meta?.requires?.python_version;
   const deps = [];
   for (const dep of pipfileLockDepsToRequirements(pipfileLock.default || {})) {
     deps.push(formatPep508(dep));
     addDepSource(sources, dep);
   }
-  if (deps.length > 0) {
-    pyproject.project = {
+  if (deps.length > 0 || pythonVersion) {
+    const project = {
       name: "app",
-      version: "0.1.0",
-      dependencies: deps
+      version: "0.1.0"
     };
+    if (pythonVersion) {
+      project["requires-python"] = `==${pythonVersion}.*`;
+    }
+    if (deps.length > 0) {
+      project.dependencies = deps;
+    }
+    pyproject.project = project;
   }
   const devDeps = [];
   for (const dep of pipfileLockDepsToRequirements(pipfileLock.develop || {})) {
@@ -1930,8 +1938,10 @@ async function discoverPythonPackage({
   let workspaceManifest;
   let workspaceLockFile;
   if (manifests.length === 0) {
+    const requiresPython2 = computeRequiresPython(void 0, void 0, configs);
     return {
-      configs
+      configs,
+      requiresPython: requiresPython2
     };
   } else {
     entrypointManifest = manifests[0];
@@ -1965,37 +1975,44 @@ async function discoverPythonPackage({
 }
 function computeRequiresPython(manifest, workspaceManifest, configs) {
   const constraints = [];
+  let hasPythonVersionFile = false;
   for (const configSet of configs) {
     const pythonVersionConfig = configSet[".python-version" /* PythonVersion */];
     if (pythonVersionConfig !== void 0) {
       constraints.push({
         request: pythonVersionConfig.data,
-        source: `${pythonVersionConfig.path}`
+        source: pythonVersionConfig.path,
+        prettySource: pythonVersionConfig.path
       });
+      hasPythonVersionFile = true;
       break;
     }
   }
-  const manifestRequiresPython = manifest?.data.project?.["requires-python"];
-  if (manifestRequiresPython) {
-    const parsed = (0, import_specifier.parse)(manifestRequiresPython);
-    if (parsed?.length) {
-      const request = pythonRequestFromConstraint(parsed);
-      constraints.push({
-        request: [request],
-        source: `"requires-python" key in ${manifest.path}`
-      });
-    }
-  } else {
-    const workspaceRequiresPython = workspaceManifest?.data.project?.["requires-python"];
-    if (workspaceRequiresPython) {
-      const parsed = (0, import_specifier.parse)(workspaceRequiresPython);
+  if (!hasPythonVersionFile) {
+    const manifestRequiresPython = manifest?.data.project?.["requires-python"];
+    if (manifestRequiresPython) {
+      const parsed = (0, import_specifier.parse)(manifestRequiresPython);
       if (parsed?.length) {
         const request = pythonRequestFromConstraint(parsed);
         constraints.push({
           request: [request],
-          source: `"requires-python" key in ${workspaceManifest.path}`
+          source: manifest.path,
+          prettySource: `"requires-python" key in ${manifest.path}`
         });
       }
+    } else {
+      const workspaceRequiresPython = workspaceManifest?.data.project?.["requires-python"];
+      if (workspaceRequiresPython) {
+        const parsed = (0, import_specifier.parse)(workspaceRequiresPython);
+        if (parsed?.length) {
+          const request = pythonRequestFromConstraint(parsed);
+          constraints.push({
+            request: [request],
+            source: workspaceManifest.path,
+            prettySource: `"requires-python" key in ${workspaceManifest.path}`
+          });
+        }
+      }
     }
   }
   return constraints;
@@ -2407,13 +2424,15 @@ function selectPython(constraints, available) {
       }
     }
     if (constraintsWithMatches.length > 1) {
-      const sources = constraintsWithMatches.map((i) => constraints[i].source);
+      const sources = constraintsWithMatches.map(
+        (i) => constraints[i].prettySource
+      );
       warnings.push(
         `Python version constraints may not overlap: ${sources.join(", ")}`
       );
     }
   }
-  const constraintDescriptions = constraints.map((c) => c.source).join(", ");
+  const constraintDescriptions = constraints.map((c) => c.prettySource).join(", ");
   errors.push(
     `No Python build satisfies all constraints: ${constraintDescriptions}`
   );
@@ -2423,6 +2442,126 @@ function selectPython(constraints, available) {
     warnings: warnings.length > 0 ? warnings : void 0
   };
 }
+function selectPythonVersion({
+  constraints,
+  availableBuilds,
+  allBuilds,
+  defaultBuild,
+  majorMinorOnly,
+  legacyTildeEquals
+}) {
+  const source = constraints?.[0]?.source;
+  if (!constraints || constraints.length === 0) {
+    return { build: defaultBuild };
+  }
+  let effectiveConstraints = majorMinorOnly ? constraints.map((c) => ({
+    ...c,
+    request: c.request.map(truncatePatchVersionsInRequest)
+  })) : constraints;
+  if (legacyTildeEquals) {
+    effectiveConstraints = effectiveConstraints.map((c) => ({
+      ...c,
+      request: c.request.map(legacyTildeEqualsTransform)
+    }));
+  }
+  const result = selectPython(effectiveConstraints, availableBuilds);
+  if (result.build) {
+    return { build: result.build, source };
+  }
+  const allResult = selectPython(effectiveConstraints, allBuilds);
+  if (allResult.build) {
+    const version = pythonVersionToString(allResult.build.version);
+    return {
+      build: defaultBuild,
+      source,
+      notAvailable: { build: allResult.build, version }
+    };
+  }
+  const versionString = extractConstraintVersionString(constraints);
+  return {
+    build: defaultBuild,
+    source,
+    invalidConstraint: { versionString }
+  };
+}
+function extractConstraintVersionString(constraints) {
+  for (const c of constraints) {
+    for (const req of c.request) {
+      if (req.version?.constraint && req.version.constraint.length > 0) {
+        const specs = req.version.constraint;
+        if (specs.length === 1 && specs[0].operator === "==" && (!specs[0].prefix || specs[0].prefix === ".*")) {
+          return specs[0].version;
+        }
+        return pep440ConstraintsToString(specs);
+      }
+    }
+  }
+  return "unknown";
+}
+function truncatePatchVersionsInRequest(req) {
+  if (!req.version?.constraint || req.version.constraint.length === 0) {
+    return req;
+  }
+  const newConstraints = [];
+  for (const c of req.version.constraint) {
+    const result = truncatePatchConstraint(c);
+    if (result !== null) {
+      newConstraints.push(result);
+    }
+  }
+  const newVersion = {
+    ...req.version,
+    constraint: newConstraints
+  };
+  return { ...req, version: newVersion };
+}
+function truncatePatchConstraint(c) {
+  if (c.operator === "===") {
+    return c;
+  }
+  const parts = c.version.split(".");
+  if (parts.length < 3) {
+    return c;
+  }
+  const majorMinor = parts.slice(0, 2).join(".");
+  const patch = parseInt(parts[2], 10);
+  switch (c.operator) {
+    case "==":
+      return { operator: "==", version: majorMinor, prefix: ".*" };
+    case "!=":
+      return null;
+    case "~=":
+      return { operator: "==", version: majorMinor, prefix: ".*" };
+    case ">=":
+      return { operator: ">=", version: majorMinor, prefix: "" };
+    case "<=":
+      return { operator: "<=", version: majorMinor, prefix: "" };
+    case ">":
+      return patch === 0 ? { operator: ">", version: majorMinor, prefix: "" } : { operator: ">=", version: majorMinor, prefix: "" };
+    case "<":
+      return patch === 0 ? { operator: "<", version: majorMinor, prefix: "" } : { operator: "<=", version: majorMinor, prefix: "" };
+    default:
+      return c;
+  }
+}
+function legacyTildeEqualsTransform(req) {
+  if (!req.version?.constraint || req.version.constraint.length === 0) {
+    return req;
+  }
+  const newConstraints = req.version.constraint.map((c) => {
+    if (c.operator !== "~=")
+      return c;
+    const parts = c.version.split(".");
+    if (parts.length === 2) {
+      return { operator: "==", version: c.version, prefix: ".*" };
+    }
+    return c;
+  });
+  return {
+    ...req,
+    version: { ...req.version, constraint: newConstraints }
+  };
+}
 function pythonVersionToString(version) {
   let str = `${version.major}.${version.minor}`;
   if (version.patch !== void 0) {
@@ -2434,7 +2573,7 @@ function pythonVersionToString(version) {
   return str;
 }
 function pep440ConstraintsToString(constraints) {
-  return constraints.map((c) => `${c.operator}${c.prefix}${c.version}`).join(",");
+  return constraints.map((c) => `${c.operator}${c.version}${c.prefix ?? ""}`).join(",");
 }
 function implementationsMatch(buildImpl, requestImpl) {
   if (PythonImplementation.isUnknown(buildImpl)) {
@@ -2562,5 +2701,6 @@ var HashDigestSchema = hashDigestSchema;
   parseUvLock,
   scanDistributions,
   selectPython,
+  selectPythonVersion,
   stringifyManifest
 });

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { discoverPythonPackage, PythonConfigKind, PythonLockFileKind, PythonMani
 export { createMinimalManifest, stringifyManifest, type CreateMinimalManifestOptions, } from './manifest/serialize';
 export type { ClassifyPackagesOptions, PackageClassification, UvLockFile, UvLockPackage, UvLockPackageSource, } from './manifest/uv-lock-parser';
 export { classifyPackages, isPrivatePackageSource, normalizePackageName, parseUvLock, } from './manifest/uv-lock-parser';
-export type { PythonSelectionResult } from './manifest/python-selector';
-export { selectPython } from './manifest/python-selector';
+export type { PythonSelectionResult, PythonVersionSelectionResult, } from './manifest/python-selector';
+export { selectPython, selectPythonVersion } from './manifest/python-selector';
 export { PythonAnalysisError } from './util/error';
 export { LicenseObjectSchema, LicenseSchema, PersonSchema, PyProjectBuildSystemSchema, PyProjectDependencyGroupsSchema, PyProjectProjectSchema, PyProjectToolSectionSchema, PyProjectTomlSchema, ReadmeObjectSchema, ReadmeSchema, } from './manifest/pyproject/schema';
 export type { License, LicenseObject, Person, PyProjectBuildSystem, PyProjectDependencyGroups, PyProjectProject, PyProjectToml, PyProjectToolSection, Readme, ReadmeObject, } from './manifest/pyproject/types';

package/dist/index.js

@@ -662,17 +662,24 @@ function convertPipfileToPyprojectToml(pipfile) {
 function convertPipfileLockToPyprojectToml(pipfileLock) {
   const sources = {};
   const pyproject = {};
+  const pythonVersion = pipfileLock._meta?.requires?.python_version;
   const deps = [];
   for (const dep of pipfileLockDepsToRequirements(pipfileLock.default || {})) {
     deps.push(formatPep508(dep));
     addDepSource(sources, dep);
   }
-  if (deps.length > 0) {
-    pyproject.project = {
+  if (deps.length > 0 || pythonVersion) {
+    const project = {
       name: "app",
-      version: "0.1.0",
-      dependencies: deps
+      version: "0.1.0"
     };
+    if (pythonVersion) {
+      project["requires-python"] = `==${pythonVersion}.*`;
+    }
+    if (deps.length > 0) {
+      project.dependencies = deps;
+    }
+    pyproject.project = project;
   }
   const devDeps = [];
   for (const dep of pipfileLockDepsToRequirements(pipfileLock.develop || {})) {
@@ -1853,8 +1860,10 @@ async function discoverPythonPackage({
   let workspaceManifest;
   let workspaceLockFile;
   if (manifests.length === 0) {
+    const requiresPython2 = computeRequiresPython(void 0, void 0, configs);
     return {
-      configs
+      configs,
+      requiresPython: requiresPython2
     };
   } else {
     entrypointManifest = manifests[0];
@@ -1888,37 +1897,44 @@ async function discoverPythonPackage({
 }
 function computeRequiresPython(manifest, workspaceManifest, configs) {
   const constraints = [];
+  let hasPythonVersionFile = false;
   for (const configSet of configs) {
     const pythonVersionConfig = configSet[".python-version" /* PythonVersion */];
     if (pythonVersionConfig !== void 0) {
       constraints.push({
         request: pythonVersionConfig.data,
-        source: `${pythonVersionConfig.path}`
+        source: pythonVersionConfig.path,
+        prettySource: pythonVersionConfig.path
       });
+      hasPythonVersionFile = true;
       break;
     }
   }
-  const manifestRequiresPython = manifest?.data.project?.["requires-python"];
-  if (manifestRequiresPython) {
-    const parsed = parse2(manifestRequiresPython);
-    if (parsed?.length) {
-      const request = pythonRequestFromConstraint(parsed);
-      constraints.push({
-        request: [request],
-        source: `"requires-python" key in ${manifest.path}`
-      });
-    }
-  } else {
-    const workspaceRequiresPython = workspaceManifest?.data.project?.["requires-python"];
-    if (workspaceRequiresPython) {
-      const parsed = parse2(workspaceRequiresPython);
+  if (!hasPythonVersionFile) {
+    const manifestRequiresPython = manifest?.data.project?.["requires-python"];
+    if (manifestRequiresPython) {
+      const parsed = parse2(manifestRequiresPython);
       if (parsed?.length) {
         const request = pythonRequestFromConstraint(parsed);
         constraints.push({
           request: [request],
-          source: `"requires-python" key in ${workspaceManifest.path}`
+          source: manifest.path,
+          prettySource: `"requires-python" key in ${manifest.path}`
         });
       }
+    } else {
+      const workspaceRequiresPython = workspaceManifest?.data.project?.["requires-python"];
+      if (workspaceRequiresPython) {
+        const parsed = parse2(workspaceRequiresPython);
+        if (parsed?.length) {
+          const request = pythonRequestFromConstraint(parsed);
+          constraints.push({
+            request: [request],
+            source: workspaceManifest.path,
+            prettySource: `"requires-python" key in ${workspaceManifest.path}`
+          });
+        }
+      }
     }
   }
   return constraints;
@@ -2330,13 +2346,15 @@ function selectPython(constraints, available) {
       }
     }
     if (constraintsWithMatches.length > 1) {
-      const sources = constraintsWithMatches.map((i) => constraints[i].source);
+      const sources = constraintsWithMatches.map(
+        (i) => constraints[i].prettySource
+      );
       warnings.push(
         `Python version constraints may not overlap: ${sources.join(", ")}`
       );
     }
   }
-  const constraintDescriptions = constraints.map((c) => c.source).join(", ");
+  const constraintDescriptions = constraints.map((c) => c.prettySource).join(", ");
   errors.push(
     `No Python build satisfies all constraints: ${constraintDescriptions}`
   );
@@ -2346,6 +2364,126 @@ function selectPython(constraints, available) {
     warnings: warnings.length > 0 ? warnings : void 0
   };
 }
+function selectPythonVersion({
+  constraints,
+  availableBuilds,
+  allBuilds,
+  defaultBuild,
+  majorMinorOnly,
+  legacyTildeEquals
+}) {
+  const source = constraints?.[0]?.source;
+  if (!constraints || constraints.length === 0) {
+    return { build: defaultBuild };
+  }
+  let effectiveConstraints = majorMinorOnly ? constraints.map((c) => ({
+    ...c,
+    request: c.request.map(truncatePatchVersionsInRequest)
+  })) : constraints;
+  if (legacyTildeEquals) {
+    effectiveConstraints = effectiveConstraints.map((c) => ({
+      ...c,
+      request: c.request.map(legacyTildeEqualsTransform)
+    }));
+  }
+  const result = selectPython(effectiveConstraints, availableBuilds);
+  if (result.build) {
+    return { build: result.build, source };
+  }
+  const allResult = selectPython(effectiveConstraints, allBuilds);
+  if (allResult.build) {
+    const version = pythonVersionToString(allResult.build.version);
+    return {
+      build: defaultBuild,
+      source,
+      notAvailable: { build: allResult.build, version }
+    };
+  }
+  const versionString = extractConstraintVersionString(constraints);
+  return {
+    build: defaultBuild,
+    source,
+    invalidConstraint: { versionString }
+  };
+}
+function extractConstraintVersionString(constraints) {
+  for (const c of constraints) {
+    for (const req of c.request) {
+      if (req.version?.constraint && req.version.constraint.length > 0) {
+        const specs = req.version.constraint;
+        if (specs.length === 1 && specs[0].operator === "==" && (!specs[0].prefix || specs[0].prefix === ".*")) {
+          return specs[0].version;
+        }
+        return pep440ConstraintsToString(specs);
+      }
+    }
+  }
+  return "unknown";
+}
+function truncatePatchVersionsInRequest(req) {
+  if (!req.version?.constraint || req.version.constraint.length === 0) {
+    return req;
+  }
+  const newConstraints = [];
+  for (const c of req.version.constraint) {
+    const result = truncatePatchConstraint(c);
+    if (result !== null) {
+      newConstraints.push(result);
+    }
+  }
+  const newVersion = {
+    ...req.version,
+    constraint: newConstraints
+  };
+  return { ...req, version: newVersion };
+}
+function truncatePatchConstraint(c) {
+  if (c.operator === "===") {
+    return c;
+  }
+  const parts = c.version.split(".");
+  if (parts.length < 3) {
+    return c;
+  }
+  const majorMinor = parts.slice(0, 2).join(".");
+  const patch = parseInt(parts[2], 10);
+  switch (c.operator) {
+    case "==":
+      return { operator: "==", version: majorMinor, prefix: ".*" };
+    case "!=":
+      return null;
+    case "~=":
+      return { operator: "==", version: majorMinor, prefix: ".*" };
+    case ">=":
+      return { operator: ">=", version: majorMinor, prefix: "" };
+    case "<=":
+      return { operator: "<=", version: majorMinor, prefix: "" };
+    case ">":
+      return patch === 0 ? { operator: ">", version: majorMinor, prefix: "" } : { operator: ">=", version: majorMinor, prefix: "" };
+    case "<":
+      return patch === 0 ? { operator: "<", version: majorMinor, prefix: "" } : { operator: "<=", version: majorMinor, prefix: "" };
+    default:
+      return c;
+  }
+}
+function legacyTildeEqualsTransform(req) {
+  if (!req.version?.constraint || req.version.constraint.length === 0) {
+    return req;
+  }
+  const newConstraints = req.version.constraint.map((c) => {
+    if (c.operator !== "~=")
+      return c;
+    const parts = c.version.split(".");
+    if (parts.length === 2) {
+      return { operator: "==", version: c.version, prefix: ".*" };
+    }
+    return c;
+  });
+  return {
+    ...req,
+    version: { ...req.version, constraint: newConstraints }
+  };
+}
 function pythonVersionToString(version) {
   let str = `${version.major}.${version.minor}`;
   if (version.patch !== void 0) {
@@ -2357,7 +2495,7 @@ function pythonVersionToString(version) {
   return str;
 }
 function pep440ConstraintsToString(constraints) {
-  return constraints.map((c) => `${c.operator}${c.prefix}${c.version}`).join(",");
+  return constraints.map((c) => `${c.operator}${c.version}${c.prefix ?? ""}`).join(",");
 }
 function implementationsMatch(buildImpl, requestImpl) {
   if (PythonImplementation.isUnknown(buildImpl)) {
@@ -2484,5 +2622,6 @@ export {
   parseUvLock,
   scanDistributions,
   selectPython,
+  selectPythonVersion,
   stringifyManifest
 };

package/dist/manifest/python-selector.d.ts

@@ -20,6 +20,47 @@ export interface PythonSelectionResult {
  * @returns The first matching build, or null with errors/warnings if none match
  */
 export declare function selectPython(constraints: PythonConstraint[], available: PythonBuild[]): PythonSelectionResult;
+/**
+ * Result of the higher-level selectPythonVersion function.
+ */
+export interface PythonVersionSelectionResult {
+    /** The selected build. Falls back to defaultBuild if no constraints match. */
+    build: PythonBuild;
+    /** Source file where the constraint originated (e.g. "pyproject.toml"). */
+    source?: string;
+    /** Diagnostic indicating the constraint was found but the build isn't in availableBuilds. */
+    notAvailable?: {
+        build: PythonBuild;
+        /** The version string of the unavailable build. */
+        version: string;
+    };
+    /** Diagnostic indicating no build matches the constraint at all. */
+    invalidConstraint?: {
+        /** Human-readable version string from the constraint. */
+        versionString: string;
+    };
+}
+/**
+ * Higher-level Python version selection with two-pass matching and diagnostics.
+ *
+ * First tries to match constraints against availableBuilds. If no match,
+ * tries against allBuilds to produce diagnostic information. Falls back
+ * to defaultBuild if no constraints are provided or no match is found.
+ */
+export declare function selectPythonVersion({ constraints, availableBuilds, allBuilds, defaultBuild, majorMinorOnly, legacyTildeEquals, }: {
+    constraints?: PythonConstraint[];
+    availableBuilds: PythonBuild[];
+    allBuilds: PythonBuild[];
+    defaultBuild: PythonBuild;
+    majorMinorOnly?: boolean;
+    /**
+     * When true, treat 2-part compatible-release specifiers (`~=X.Y`) as
+     * pinning to exactly that minor version (`==X.Y.*`) rather than the
+     * PEP 440 correct `>=X.Y, <(X+1).0`.  This preserves the historical
+     * behaviour of the Python builder prior to the python-analysis migration.
+     */
+    legacyTildeEquals?: boolean;
+}): PythonVersionSelectionResult;
 /**
  * Convert a PythonVersion to a string suitable for PEP 440 comparison.
  *

package/dist/manifest/python-specifiers.d.ts

@@ -51,8 +51,10 @@ export interface PythonVersionRequest {
 export interface PythonConstraint {
     /** The Python version request(s) that define this constraint. */
     request: PythonRequest[];
-    /** Human-readable description of where this constraint came from. */
+    /** Config file name where this constraint originated (e.g. "pyproject.toml", ".python-version"). */
     source: string;
+    /** Human-readable description of where this constraint came from. */
+    prettySource: string;
 }
 export type PythonVersion = {
     major: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/python-analysis",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",