@adhd/apigen-python-env 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.3 (2026-07-24)
+
+This was a version bump only for apigen-python-env to align it with other projects, there were no code changes.
+
 ## 0.1.2 (2026-07-23)
 
 

package/index.d.ts

@@ -1,2 +1,3 @@
 export { ensurePythonEnv, resolvePythonPkgDir } from './lib/python-env';
 export type { IPythonEnv, IEnsurePythonEnvOptions } from './lib/python-env';
+export { runExtractorEmitJson } from './lib/run-extractor';

package/index.js

@@ -1,8 +1,10 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const T=require("node:fs"),I=require("node:os"),q=require("node:path"),F=require("node:crypto"),h=require("node:child_process");function S(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const r in t)if(r!=="default"){const i=Object.getOwnPropertyDescriptor(t,r);Object.defineProperty(e,r,i.get?i:{enumerable:!0,get:()=>t[r]})}}return e.default=t,Object.freeze(e)}const n=S(T),E=S(I),o=S(q);function k(t){const e=t??__dirname,r=o.resolve(e,"..","..","..","python");if(n.existsSync(o.join(r,"apigen_python")))return r;let i=e;for(let p=0;p<20;p++){const s=o.join(i,"packages","apigen","python");if(n.existsSync(o.join(s,"apigen_python")))return s;const u=o.dirname(i);if(u===i)break;i=u}return r}const N=["python3.13","python3.12","python3.11","python3"],d=[3,11];function M(t){const e=h.spawnSync(t,["-c",'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'],{encoding:"utf8",timeout:15e3});if(e.status!==0||!e.stdout)return;const[r,i]=e.stdout.trim().split(".").map(Number);if(!(!Number.isFinite(r)||!Number.isFinite(i)))return[r,i]}function Y(){for(const t of N){const e=M(t);if(e&&(e[0]>d[0]||e[0]===d[0]&&e[1]>=d[1]))return t}throw new Error(`apigen-python-env: no Python >= ${d.join(".")} found on PATH (tried: ${N.join(", ")}). Install Python ${d.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`)}function G(t){return process.platform==="win32"?o.join(t,"Scripts","python.exe"):o.join(t,"bin","python3")}function B(t){const e=n.readFileSync(o.join(t,"pyproject.toml"));return F.createHash("sha256").update(e).digest("hex")}function $(t){try{const e=JSON.parse(n.readFileSync(t,"utf8"));if(typeof e.pyprojectHash=="string"&&Array.isArray(e.extras))return e}catch{}}function V(t,e,r){const i=Date.now()+e;for(;;)try{n.mkdirSync(t,{recursive:!1});break}catch{if(Date.now()>i){try{n.rmdirSync(t)}catch{}continue}h.spawnSync(process.execPath,["-e","setTimeout(()=>{}, 250)"],{timeout:5e3})}try{return r()}finally{try{n.rmdirSync(t)}catch{}}}function J(t={}){const e=k(),r=process.env.APIGEN_PYTHON;if(r){if(!n.existsSync(r))throw new Error(`apigen-python-env: APIGEN_PYTHON points to a missing file: ${r}`);return{python:r,venvDir:"",pythonPkgDir:e}}const i=[...new Set(t.extras??[])].sort(),p=t.envHome??process.env.APIGEN_PYENV_HOME??o.join(E.homedir(),".adhd","apigen"),s=o.join(p,"pyvenv"),u=o.join(s,".apigen-stamp"),g=B(e),y=G(s),w=()=>{if(!n.existsSync(y))return!1;const c=$(u);return!c||c.pyprojectHash!==g?!1:i.every(f=>c.extras.includes(f))};if(w())return{python:y,venvDir:s,pythonPkgDir:e};n.mkdirSync(p,{recursive:!0});const H=o.join(p,"pyvenv.lock"),D=t.lockTimeoutMs??3e5;return V(H,D,()=>{if(w())return{python:y,venvDir:s,pythonPkgDir:e};const c=$(u),f=[...new Set([...(c==null?void 0:c.extras)??[],...i])].sort();n.rmSync(s,{recursive:!0,force:!0});const j=Y(),v=h.spawnSync(j,["-m","venv",s],{encoding:"utf8",timeout:12e4});if(v.status!==0)throw new Error(`apigen-python-env: "${j} -m venv" failed (exit ${v.status}):
-${v.stderr}`);const P=o.join(e,"build");n.existsSync(P)&&n.rmSync(P,{recursive:!0,force:!0});for(const a of n.readdirSync(e))a.endsWith(".egg-info")&&n.rmSync(o.join(e,a),{recursive:!0,force:!0});const l=n.mkdtempSync(o.join(E.tmpdir(),"apigen-python-wheel-"));try{const a=h.spawnSync(y,["-m","pip","wheel","--no-deps","--wheel-dir",l,e],{encoding:"utf8",timeout:6e5});if(a.status!==0)throw new Error(`apigen-python-env: pip wheel failed (exit ${a.status}):
-${a.stderr}
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const D=require("node:fs"),I=require("node:os"),q=require("node:path"),F=require("node:crypto"),h=require("node:child_process");function P(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const n in t)if(n!=="default"){const o=Object.getOwnPropertyDescriptor(t,n);Object.defineProperty(e,n,o.get?o:{enumerable:!0,get:()=>t[n]})}}return e.default=t,Object.freeze(e)}const r=P(D),b=P(I),i=P(q);function k(t){const e=t??__dirname,n=i.resolve(e,"..","..","..","python");if(r.existsSync(i.join(n,"apigen_python")))return n;let o=e;for(let u=0;u<20;u++){const c=i.join(o,"packages","apigen","python");if(r.existsSync(i.join(c,"apigen_python")))return c;const a=i.dirname(o);if(a===o)break;o=a}return n}const H=["python3.13","python3.12","python3.11","python3"],m=[3,11];function J(t){const e=h.spawnSync(t,["-c",'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'],{encoding:"utf8",timeout:15e3});if(e.status!==0||!e.stdout)return;const[n,o]=e.stdout.trim().split(".").map(Number);if(!(!Number.isFinite(n)||!Number.isFinite(o)))return[n,o]}function M(){for(const t of H){const e=J(t);if(e&&(e[0]>m[0]||e[0]===m[0]&&e[1]>=m[1]))return t}throw new Error(`apigen-python-env: no Python >= ${m.join(".")} found on PATH (tried: ${H.join(", ")}). Install Python ${m.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`)}function Y(t){return process.platform==="win32"?i.join(t,"Scripts","python.exe"):i.join(t,"bin","python3")}function G(t){const e=r.readFileSync(i.join(t,"pyproject.toml"));return F.createHash("sha256").update(e).digest("hex")}function O(t){try{const e=JSON.parse(r.readFileSync(t,"utf8"));if(typeof e.pyprojectHash=="string"&&Array.isArray(e.extras))return e}catch{}}function B(t,e,n){const o=Date.now()+e;for(;;)try{r.mkdirSync(t,{recursive:!1});break}catch{if(Date.now()>o){try{r.rmdirSync(t)}catch{}continue}h.spawnSync(process.execPath,["-e","setTimeout(()=>{}, 250)"],{timeout:5e3})}try{return n()}finally{try{r.rmdirSync(t)}catch{}}}function V(t={}){const e=k(),n=process.env.APIGEN_PYTHON;if(n){if(!r.existsSync(n))throw new Error(`apigen-python-env: APIGEN_PYTHON points to a missing file: ${n}`);return{python:n,venvDir:"",pythonPkgDir:e}}const o=[...new Set(t.extras??[])].sort(),u=t.envHome??process.env.APIGEN_PYENV_HOME??i.join(b.homedir(),".adhd","apigen"),c=i.join(u,"pyvenv"),a=i.join(c,".apigen-stamp"),d=G(e),p=Y(c),l=()=>{if(!r.existsSync(p))return!1;const s=O(a);return!s||s.pyprojectHash!==d?!1:o.every(y=>s.extras.includes(y))};if(l())return{python:p,venvDir:c,pythonPkgDir:e};r.mkdirSync(u,{recursive:!0});const v=i.join(u,"pyvenv.lock"),w=t.lockTimeoutMs??3e5;return B(v,w,()=>{if(l())return{python:p,venvDir:c,pythonPkgDir:e};const s=O(a),y=[...new Set([...(s==null?void 0:s.extras)??[],...o])].sort();r.rmSync(c,{recursive:!0,force:!0});const _=M(),j=h.spawnSync(_,["-m","venv",c],{encoding:"utf8",timeout:12e4});if(j.status!==0)throw new Error(`apigen-python-env: "${_} -m venv" failed (exit ${j.status}):
+${j.stderr}`);const x=i.join(e,"build");r.existsSync(x)&&r.rmSync(x,{recursive:!0,force:!0});for(const f of r.readdirSync(e))f.endsWith(".egg-info")&&r.rmSync(i.join(e,f),{recursive:!0,force:!0});const S=r.mkdtempSync(i.join(b.tmpdir(),"apigen-python-wheel-"));try{const f=h.spawnSync(p,["-m","pip","wheel","--no-deps","--wheel-dir",S,e],{encoding:"utf8",timeout:6e5});if(f.status!==0)throw new Error(`apigen-python-env: pip wheel failed (exit ${f.status}):
+${f.stderr}
 stdout:
-${a.stdout}`);const _=n.readdirSync(l).filter(A=>A.endsWith(".whl"));if(_.length===0)throw new Error("apigen-python-env: pip wheel produced no .whl file");const b=o.join(l,_[0]),x=f.length?`${b}[${f.join(",")}]`:b,m=h.spawnSync(y,["-m","pip","install","--quiet","--disable-pip-version-check",x],{encoding:"utf8",timeout:6e5});if(m.status!==0)throw new Error(`apigen-python-env: pip install "${x}" failed (exit ${m.status}):
-${m.stderr}
+${f.stdout}`);const E=r.readdirSync(S).filter(A=>A.endsWith(".whl"));if(E.length===0)throw new Error("apigen-python-env: pip wheel produced no .whl file");const $=i.join(S,E[0]),N=y.length?`${$}[${y.join(",")}]`:$,g=h.spawnSync(p,["-m","pip","install","--quiet","--disable-pip-version-check",N],{encoding:"utf8",timeout:6e5});if(g.status!==0)throw new Error(`apigen-python-env: pip install "${N}" failed (exit ${g.status}):
+${g.stderr}
 stdout:
-${m.stdout}`)}finally{n.rmSync(l,{recursive:!0,force:!0})}const O={pyprojectHash:g,extras:f};return n.writeFileSync(u,JSON.stringify(O)),{python:y,venvDir:s,pythonPkgDir:e}})}exports.ensurePythonEnv=J;exports.resolvePythonPkgDir=k;
+${g.stdout}`)}finally{r.rmSync(S,{recursive:!0,force:!0})}const T={pyprojectHash:d,extras:y};return r.writeFileSync(a,JSON.stringify(T)),{python:p,venvDir:c,pythonPkgDir:e}})}function W(t,e,n,o,u){return new Promise((c,a)=>{var v,w;const d=h.spawn(t,["-m","apigen_python.extractor",n,"--namespace",o,"--emit-json"],{cwd:e,env:{...process.env,PYTHONPATH:e},stdio:["ignore","pipe","pipe"]});let p="",l="";(v=d.stdout)==null||v.on("data",s=>{p+=s.toString("utf8")}),(w=d.stderr)==null||w.on("data",s=>{l+=s.toString("utf8")}),d.on("error",a),d.on("exit",s=>{if(s!==0){a(new Error(`${u}: extractor --emit-json exited with code ${s}:
+${l}`));return}try{c(JSON.parse(p))}catch(y){a(new Error(`${u}: extractor --emit-json produced invalid JSON (${y.message}):
+${p}`))}})})}exports.ensurePythonEnv=V;exports.resolvePythonPkgDir=k;exports.runExtractorEmitJson=W;

package/index.mjs

@@ -1,27 +1,27 @@
 import * as n from "node:fs";
-import * as E from "node:os";
+import * as H from "node:os";
 import * as r from "node:path";
-import { createHash as D } from "node:crypto";
-import { spawnSync as d } from "node:child_process";
-function I(e) {
+import { createHash as T } from "node:crypto";
+import { spawnSync as l, spawn as I } from "node:child_process";
+function O(e) {
   const t = e ?? __dirname, o = r.resolve(t, "..", "..", "..", "python");
   if (n.existsSync(r.join(o, "apigen_python")))
     return o;
   let i = t;
-  for (let a = 0; a < 20; a++) {
-    const s = r.join(i, "packages", "apigen", "python");
-    if (n.existsSync(r.join(s, "apigen_python")))
-      return s;
-    const u = r.dirname(i);
-    if (u === i)
+  for (let u = 0; u < 20; u++) {
+    const c = r.join(i, "packages", "apigen", "python");
+    if (n.existsSync(r.join(c, "apigen_python")))
+      return c;
+    const a = r.dirname(i);
+    if (a === i)
       break;
-    i = u;
+    i = a;
   }
   return o;
 }
-const N = ["python3.13", "python3.12", "python3.11", "python3"], h = [3, 11];
-function T(e) {
-  const t = d(e, ["-c", 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'], {
+const _ = ["python3.13", "python3.12", "python3.11", "python3"], m = [3, 11];
+function D(e) {
+  const t = l(e, ["-c", 'import sys; print(f"{sys.version_info[0]}.{sys.version_info[1]}")'], {
     encoding: "utf8",
     timeout: 15e3
   });
@@ -32,21 +32,21 @@ function T(e) {
     return [o, i];
 }
 function F() {
-  for (const e of N) {
-    const t = T(e);
-    if (t && (t[0] > h[0] || t[0] === h[0] && t[1] >= h[1]))
+  for (const e of _) {
+    const t = D(e);
+    if (t && (t[0] > m[0] || t[0] === m[0] && t[1] >= m[1]))
       return e;
   }
   throw new Error(
-    `apigen-python-env: no Python >= ${h.join(".")} found on PATH (tried: ${N.join(", ")}). Install Python ${h.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`
+    `apigen-python-env: no Python >= ${m.join(".")} found on PATH (tried: ${_.join(", ")}). Install Python ${m.join(".")}+ or set APIGEN_PYTHON to a provisioned interpreter.`
   );
 }
-function O(e) {
+function Y(e) {
   return process.platform === "win32" ? r.join(e, "Scripts", "python.exe") : r.join(e, "bin", "python3");
 }
-function Y(e) {
+function J(e) {
   const t = n.readFileSync(r.join(e, "pyproject.toml"));
-  return D("sha256").update(t).digest("hex");
+  return T("sha256").update(t).digest("hex");
 }
 function k(e) {
   try {
@@ -70,7 +70,7 @@ function G(e, t, o) {
         }
         continue;
       }
-      d(process.execPath, ["-e", "setTimeout(()=>{}, 250)"], { timeout: 5e3 });
+      l(process.execPath, ["-e", "setTimeout(()=>{}, 250)"], { timeout: 5e3 });
     }
   try {
     return o();
@@ -82,74 +82,111 @@ function G(e, t, o) {
   }
 }
 function V(e = {}) {
-  const t = I(), o = process.env.APIGEN_PYTHON;
+  const t = O(), o = process.env.APIGEN_PYTHON;
   if (o) {
     if (!n.existsSync(o))
       throw new Error(`apigen-python-env: APIGEN_PYTHON points to a missing file: ${o}`);
     return { python: o, venvDir: "", pythonPkgDir: t };
   }
-  const i = [...new Set(e.extras ?? [])].sort(), a = e.envHome ?? process.env.APIGEN_PYENV_HOME ?? r.join(E.homedir(), ".adhd", "apigen"), s = r.join(a, "pyvenv"), u = r.join(s, ".apigen-stamp"), w = Y(t), y = O(s), S = () => {
-    if (!n.existsSync(y))
+  const i = [...new Set(e.extras ?? [])].sort(), u = e.envHome ?? process.env.APIGEN_PYENV_HOME ?? r.join(H.homedir(), ".adhd", "apigen"), c = r.join(u, "pyvenv"), a = r.join(c, ".apigen-stamp"), d = J(t), p = Y(c), h = () => {
+    if (!n.existsSync(p))
       return !1;
-    const c = k(u);
-    return !c || c.pyprojectHash !== w ? !1 : i.every((f) => c.extras.includes(f));
+    const s = k(a);
+    return !s || s.pyprojectHash !== d ? !1 : i.every((f) => s.extras.includes(f));
   };
-  if (S())
-    return { python: y, venvDir: s, pythonPkgDir: t };
-  n.mkdirSync(a, { recursive: !0 });
-  const H = r.join(a, "pyvenv.lock"), _ = e.lockTimeoutMs ?? 3e5;
-  return G(H, _, () => {
-    if (S())
-      return { python: y, venvDir: s, pythonPkgDir: t };
-    const c = k(u), f = [.../* @__PURE__ */ new Set([...(c == null ? void 0 : c.extras) ?? [], ...i])].sort();
-    n.rmSync(s, { recursive: !0, force: !0 });
-    const g = F(), v = d(g, ["-m", "venv", s], { encoding: "utf8", timeout: 12e4 });
-    if (v.status !== 0)
+  if (h())
+    return { python: p, venvDir: c, pythonPkgDir: t };
+  n.mkdirSync(u, { recursive: !0 });
+  const v = r.join(u, "pyvenv.lock"), w = e.lockTimeoutMs ?? 3e5;
+  return G(v, w, () => {
+    if (h())
+      return { python: p, venvDir: c, pythonPkgDir: t };
+    const s = k(a), f = [.../* @__PURE__ */ new Set([...(s == null ? void 0 : s.extras) ?? [], ...i])].sort();
+    n.rmSync(c, { recursive: !0, force: !0 });
+    const x = F(), j = l(x, ["-m", "venv", c], { encoding: "utf8", timeout: 12e4 });
+    if (j.status !== 0)
       throw new Error(
-        `apigen-python-env: "${g} -m venv" failed (exit ${v.status}):
-${v.stderr}`
+        `apigen-python-env: "${x} -m venv" failed (exit ${j.status}):
+${j.stderr}`
       );
-    const j = r.join(t, "build");
-    n.existsSync(j) && n.rmSync(j, { recursive: !0, force: !0 });
-    for (const p of n.readdirSync(t))
-      p.endsWith(".egg-info") && n.rmSync(r.join(t, p), { recursive: !0, force: !0 });
-    const m = n.mkdtempSync(r.join(E.tmpdir(), "apigen-python-wheel-"));
+    const $ = r.join(t, "build");
+    n.existsSync($) && n.rmSync($, { recursive: !0, force: !0 });
+    for (const y of n.readdirSync(t))
+      y.endsWith(".egg-info") && n.rmSync(r.join(t, y), { recursive: !0, force: !0 });
+    const S = n.mkdtempSync(r.join(H.tmpdir(), "apigen-python-wheel-"));
     try {
-      const p = d(
-        y,
-        ["-m", "pip", "wheel", "--no-deps", "--wheel-dir", m, t],
+      const y = l(
+        p,
+        ["-m", "pip", "wheel", "--no-deps", "--wheel-dir", S, t],
         { encoding: "utf8", timeout: 6e5 }
       );
-      if (p.status !== 0)
+      if (y.status !== 0)
         throw new Error(
-          `apigen-python-env: pip wheel failed (exit ${p.status}):
-${p.stderr}
+          `apigen-python-env: pip wheel failed (exit ${y.status}):
+${y.stderr}
 stdout:
-${p.stdout}`
+${y.stdout}`
         );
-      const P = n.readdirSync(m).filter((A) => A.endsWith(".whl"));
+      const P = n.readdirSync(S).filter((b) => b.endsWith(".whl"));
       if (P.length === 0)
         throw new Error("apigen-python-env: pip wheel produced no .whl file");
-      const x = r.join(m, P[0]), $ = f.length ? `${x}[${f.join(",")}]` : x, l = d(
-        y,
-        ["-m", "pip", "install", "--quiet", "--disable-pip-version-check", $],
+      const E = r.join(S, P[0]), N = f.length ? `${E}[${f.join(",")}]` : E, g = l(
+        p,
+        ["-m", "pip", "install", "--quiet", "--disable-pip-version-check", N],
         { encoding: "utf8", timeout: 6e5 }
       );
-      if (l.status !== 0)
+      if (g.status !== 0)
         throw new Error(
-          `apigen-python-env: pip install "${$}" failed (exit ${l.status}):
-${l.stderr}
+          `apigen-python-env: pip install "${N}" failed (exit ${g.status}):
+${g.stderr}
 stdout:
-${l.stdout}`
+${g.stdout}`
         );
     } finally {
-      n.rmSync(m, { recursive: !0, force: !0 });
+      n.rmSync(S, { recursive: !0, force: !0 });
     }
-    const b = { pyprojectHash: w, extras: f };
-    return n.writeFileSync(u, JSON.stringify(b)), { python: y, venvDir: s, pythonPkgDir: t };
+    const A = { pyprojectHash: d, extras: f };
+    return n.writeFileSync(a, JSON.stringify(A)), { python: p, venvDir: c, pythonPkgDir: t };
+  });
+}
+function q(e, t, o, i, u) {
+  return new Promise((c, a) => {
+    var v, w;
+    const d = I(
+      e,
+      ["-m", "apigen_python.extractor", o, "--namespace", i, "--emit-json"],
+      {
+        cwd: t,
+        env: { ...process.env, PYTHONPATH: t },
+        stdio: ["ignore", "pipe", "pipe"]
+      }
+    );
+    let p = "", h = "";
+    (v = d.stdout) == null || v.on("data", (s) => {
+      p += s.toString("utf8");
+    }), (w = d.stderr) == null || w.on("data", (s) => {
+      h += s.toString("utf8");
+    }), d.on("error", a), d.on("exit", (s) => {
+      if (s !== 0) {
+        a(new Error(`${u}: extractor --emit-json exited with code ${s}:
+${h}`));
+        return;
+      }
+      try {
+        c(JSON.parse(p));
+      } catch (f) {
+        a(
+          new Error(
+            `${u}: extractor --emit-json produced invalid JSON (${f.message}):
+${p}`
+          )
+        );
+      }
+    });
   });
 }
 export {
   V as ensurePythonEnv,
-  I as resolvePythonPkgDir
+  O as resolvePythonPkgDir,
+  q as runExtractorEmitJson
 };

package/lib/run-extractor.d.ts

@@ -0,0 +1,20 @@
+import { Operation } from '@adhd/apigen-core-client';
+
+/**
+ * Runs `python -m apigen_python.extractor --emit-json` to completion and
+ * parses its stdout into `Operation[]` — phase 1 of the py-flask / py-grpc
+ * two-phase spawn (extract-only, then `project()`, then serve). This is a
+ * short-lived process: it exits as soon as extraction finishes, well before
+ * the actual server process is spawned.
+ *
+ * @param python      - Absolute path (or bare name, e.g. `'python3'`) of the
+ *                       interpreter to spawn.
+ * @param pythonPkgDir - Absolute path to `packages/apigen/python` (used as
+ *                       both `cwd` and `PYTHONPATH` for the subprocess).
+ * @param modulePath   - Absolute path to the `.py` module to extract from.
+ * @param namespace    - Namespace passed to the extractor's `--namespace` flag.
+ * @param label        - Short caller identifier (e.g. `'py-flask'`, `'py-grpc'`)
+ *                       prefixed onto error messages so failures are traceable
+ *                       to their caller.
+ */
+export declare function runExtractorEmitJson(python: string, pythonPkgDir: string, modulePath: string, namespace: string, label: string): Promise<Operation[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/apigen-python-env",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -11,6 +11,9 @@
     "venv",
     "provisioning"
   ],
+  "dependencies": {
+    "@adhd/apigen-core-client": "^0.1.3"
+  },
   "publishConfig": {
     "access": "public"
   }