@vercel/python-analysis 0.8.1 → 0.9.0

package/dist/index.cjs

@@ -64,16 +64,17 @@ __export(src_exports, {
   UvIndexEntrySchema: () => UvIndexEntrySchema,
   classifyPackages: () => classifyPackages,
   containsAppOrHandler: () => containsAppOrHandler,
+  containsTopLevelCallable: () => containsTopLevelCallable,
   createMinimalManifest: () => createMinimalManifest,
   discoverPythonPackage: () => discoverPythonPackage,
   extendDistRecord: () => extendDistRecord,
   getStringConstant: () => getStringConstant,
   isPrivatePackageSource: () => isPrivatePackageSource,
   normalizePackageName: () => normalizePackageName2,
-  parseDjangoSettingsModule: () => parseDjangoSettingsModule,
   parseUvLock: () => parseUvLock,
   scanDistributions: () => scanDistributions,
   selectPython: () => selectPython,
+  selectPythonVersion: () => selectPythonVersion,
   stringifyManifest: () => stringifyManifest
 });
 module.exports = __toCommonJS(src_exports);
@@ -126,17 +127,16 @@ async function containsAppOrHandler(source) {
   const mod = await importWasmModule();
   return mod.containsAppOrHandler(source);
 }
-async function getStringConstant(source, name) {
+async function containsTopLevelCallable(source, name) {
+  if (!source.includes(name)) {
+    return false;
+  }
   const mod = await importWasmModule();
-  return mod.getStringConstant(source, name) ?? null;
+  return mod.containsTopLevelCallable(source, name);
 }
-var DJANGO_SETTINGS_MODULE_PATTERN_RE = /DJANGO_SETTINGS_MODULE/;
-async function parseDjangoSettingsModule(content) {
-  if (!DJANGO_SETTINGS_MODULE_PATTERN_RE.test(content)) {
-    return null;
-  }
+async function getStringConstant(source, name) {
   const mod = await importWasmModule();
-  return mod.parseDjangoSettingsModule(content) ?? null;
+  return mod.getStringConstant(source, name) ?? null;
 }
 
 // src/manifest/dist-metadata.ts
@@ -739,17 +739,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 +1937,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 +1974,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 +2423,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 +2441,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 +2572,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)) {
@@ -2552,15 +2690,16 @@ var HashDigestSchema = hashDigestSchema;
   UvIndexEntrySchema,
   classifyPackages,
   containsAppOrHandler,
+  containsTopLevelCallable,
   createMinimalManifest,
   discoverPythonPackage,
   extendDistRecord,
   getStringConstant,
   isPrivatePackageSource,
   normalizePackageName,
-  parseDjangoSettingsModule,
   parseUvLock,
   scanDistributions,
   selectPython,
+  selectPythonVersion,
   stringifyManifest
 });

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module @vercel/python-analysis
  */
-export { containsAppOrHandler, getStringConstant, parseDjangoSettingsModule, } from './semantic/entrypoints';
+export { containsAppOrHandler, containsTopLevelCallable, getStringConstant, } from './semantic/entrypoints';
 export type { Distribution, DistributionIndex, PackagePath, DirectUrlInfo, } from './manifest/dist-metadata';
 export { extendDistRecord, scanDistributions } from './manifest/dist-metadata';
 export type { PythonConfig, PythonConfigs, PythonLockFile, PythonManifest, PythonManifestOrigin, PythonPackage, PythonVersionConfig, } from './manifest/package';
@@ -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

@@ -46,17 +46,16 @@ async function containsAppOrHandler(source) {
   const mod = await importWasmModule();
   return mod.containsAppOrHandler(source);
 }
-async function getStringConstant(source, name) {
+async function containsTopLevelCallable(source, name) {
+  if (!source.includes(name)) {
+    return false;
+  }
   const mod = await importWasmModule();
-  return mod.getStringConstant(source, name) ?? null;
+  return mod.containsTopLevelCallable(source, name);
 }
-var DJANGO_SETTINGS_MODULE_PATTERN_RE = /DJANGO_SETTINGS_MODULE/;
-async function parseDjangoSettingsModule(content) {
-  if (!DJANGO_SETTINGS_MODULE_PATTERN_RE.test(content)) {
-    return null;
-  }
+async function getStringConstant(source, name) {
   const mod = await importWasmModule();
-  return mod.parseDjangoSettingsModule(content) ?? null;
+  return mod.getStringConstant(source, name) ?? null;
 }
 
 // src/manifest/dist-metadata.ts
@@ -662,17 +661,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 +1859,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 +1896,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 +2345,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 +2363,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 +2494,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)) {
@@ -2474,15 +2611,16 @@ export {
   UvIndexEntrySchema,
   classifyPackages,
   containsAppOrHandler,
+  containsTopLevelCallable,
   createMinimalManifest,
   discoverPythonPackage,
   extendDistRecord,
   getStringConstant,
   isPrivatePackageSource,
   normalizePackageName2 as normalizePackageName,
-  parseDjangoSettingsModule,
   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;