apiforge-analyzer 1.3.7 → 1.3.8

package/README.md

@@ -1,6 +1,6 @@
 # apiforge-analyzer
 
-CLI and library for auto-generating API documentation from live Express, Fastify, NestJS, Next.js, Vite, and React Router apps.
+CLI and library for auto-generating API documentation from live Express, Fastify, NestJS, Next.js, Vite, and React Router apps — and Python FastAPI, Flask, and Django apps.
 
 Routes are extracted at runtime by walking the framework's internal route stack — no static analysis, no decorators, no changes to your production code.
 
@@ -260,6 +260,64 @@ await analyzeReactRouter({
 })
 ```
 
+### Python — FastAPI, Flask, Django / DRF
+
+Run `npx apiforge` from the Python project root (Node ≥ 18 is still needed to run the CLI).
+The project is recognised from `manage.py` or from `fastapi` / `flask` / `django` in
+`requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, or `setup.cfg`.
+
+It works like the Node flow. The CLI:
+
+1. Finds the file to patch: the module that creates the app (`main.py`, the Flask `create_app` module), or
+   Django's `manage.py`.
+2. Checks that the framework is installed. If it isn't, it offers to create `.venv` and `pip install` the
+   project's dependencies from `requirements.txt`, `setup.py`/`pyproject.toml` (`pip install -e .`), or a
+   bare `pyproject.toml` dependency list. This is the `npm install` step, done for you.
+3. Asks which command starts your server, like the npm-script picker:
+   - FastAPI: `fastapi dev`, `fastapi run`, `uvicorn main:app`, `python main.py`
+   - Flask: `flask --app app run`, `python app.py`
+   - Django: `manage.py runserver --noreload`, `manage.py runserver`
+
+   You can also type your own. All of these use the project's venv Python.
+4. Adds a temporary snippet to that file and runs the command. The snippet reads the routes as soon as
+   the app is loaded, before the server binds its port.
+5. If the server crashes with `No module named 'x'`, offers to install the package and retry. Only packages
+   the project declares (including extras such as `[test]`) or well-known import≠pip names (`jose` →
+   `python-jose`) are offered.
+6. Stops the server and uploads the routes. At the end it asks "Remove APIForge code changes?", like the
+   Node flow. Ctrl+C removes the snippet immediately.
+
+The snippet holds no API key and does nothing unless the CLI runs it: it needs an `APIFORGE_INTROSPECT`
+environment variable that only the CLI sets. It writes routes to a temp file outside the project, and the
+CLI uploads them. If you keep the snippet, it does nothing on its own, and the next run replaces it.
+Because your own start command runs, the server needs what it normally needs, such as env vars like a
+database URL. If it fails, the CLI shows the last lines of its output, where Python prints the actual error.
+
+The routes are read from the framework's live route table:
+
+| Framework | Source of truth |
+|---|---|
+| FastAPI | `app.openapi()`, which gives real Pydantic types for params, bodies, and responses. It also picks up dependency names, `HTTPException` codes raised in handlers, and `app.mount()` sub-apps. |
+| Flask | `app.url_map` plus each view's source: `request.args`, `request.get_json()`, `abort()`, decorators. Blueprints and `MethodView` are supported. |
+| Django | The root URLconf resolver, including `path()`/`re_path()`, class-based views, DRF ViewSets/routers, `@api_view`, serializers, and `permission_classes`. Admin and DRF login URLs are skipped. |
+
+The suggested commands use `APIFORGE_PYTHON`, else the active virtualenv, else `.venv/`, `venv/` or `env/`
+in the project, else the system `python`. That interpreter must have the app's dependencies installed.
+
+Programmatic use from Node doesn't inject anything or start a server. It imports the app with that same
+interpreter and reads the route table directly:
+
+```ts
+import { analyze } from 'apiforge-analyzer'
+
+await analyze(null, {
+  projectName: 'My API',
+  framework: 'fastapi',          // or 'flask' / 'django' — auto-detected when omitted
+  pythonApp: 'main:app',         // Flask factory: 'app:create_app' + pythonFactory: true
+  // djangoSettings: 'mysite.settings',  // Django: defaults to the one manage.py sets
+})
+```
+
 ## Options
 
 ```ts
@@ -288,12 +346,18 @@ interface AnalyzerOptions {
   errorCatalogPath?: string
   envelopes?: Record<string, { wrapper: string; dataField: string; excluded?: string[] } | { bare: true }>
   annotationsPath?: string
+
+  // Python only — see "Python" above
+  pythonApp?: string           // app import path, e.g. 'main:app' (auto-detected when omitted)
+  pythonFactory?: boolean      // call pythonApp as a factory (Flask create_app)
+  pythonPath?: string          // interpreter (default: APIFORGE_PYTHON / active venv / project venv)
+  djangoSettings?: string      // e.g. 'mysite.settings' (default: read from manage.py)
 }
 ```
 
 `analyze()` throws instead of resolving to `[]` when the detected or forced framework has no
 analyzer (currently: anything other than `express`, `fastify`, `nestjs`, `nextjs-pages`,
-`nextjs-app`, `vite`, `react-router`). Every other early-exit (no API key, debounced, zero
+`nextjs-app`, `vite`, `react-router`, `fastapi`, `flask`, `django`). Every other early-exit (no API key, debounced, zero
 routes found, `NODE_ENV=production`) still resolves to `[]` — only "this framework cannot be
 analyzed" is a thrown error, so a caller can tell the two apart. `detectFramework()` also
 exposes this directly: `detectFramework(app).supported` is `false` for a framework it can