Skip to content

Keep a FastAPI router's prefix off routers the file didn't make (Python side of #71) - #161

Open
IdirBenSlama wants to merge 1 commit into
haydenschmitty:mainfrom
IdirBenSlama:fix/160-python-unknown-mount-name
Open

IdirBenSlama wants to merge 1 commit into
haydenschmitty:mainfrom
IdirBenSlama:fix/160-python-unknown-mount-name

Conversation

@IdirBenSlama

Copy link
Copy Markdown

What this changes

Fixes #160.

In a Python file, a router included under a name the file neither made nor imported from the project was taken for
a router of that file. Examples are what a factory returned, kept in a variable or called in place
(app.include_router(make_admin_router(), prefix="/admin")), and a router from an installed package. Its prefix
then went on every other router the file included, so the map showed endpoints like
/api/v1/graphql/api/v1/items/list beside the real /api/v1/items/list. A check added where it was included
(dependencies=[Depends(...)]) counted for those routers too, so Health could call an open endpoint protected.

mountTarget's Python fallback now treats a name as the file's own router only in two cases:

  • the file makes it with APIRouter(...), Blueprint(...) or Router(...) (it is in routers);
  • the file declares routes on it. This covers a router made some other way, by a factory or by a subclass of
    APIRouter, whose routes are written in this file.

Any other name returns null, the same as jsMountTarget has done since #71.

Narrowing the fallback means routers has to find every router a file makes, or a router that only holds other
routers (an api_router that includes the rest) would stop handing its prefix on to them. Its pattern in
extract.mjs didn't read a type annotation (api_router: APIRouter = APIRouter(), or a Flask blueprint declared
the same way) or more than one module name (fastapi.routing.APIRouter()). It now reads both, with an annotation of
at most 200 characters, like the JS router pattern. A side effect people will notice: such a router's own prefix,
admin_router: APIRouter = APIRouter(prefix="/admin"), was dropped before and now applies.

What this change doesn't do:

  • It doesn't follow a factory into its file to put the factory's own routes under the prefix, as the Express side
    does. When the scan can see those routes, they keep their own path, which is the same as before this change.
    Following the factory would need the Python extractor to record name = factory() assignments, so I left it out
    to keep this change small.
  • A router made by another class (api = TimedRouter(), a subclass of APIRouter) that declares no routes of its
    own and only holds other routers isn't recognised, so the routers it holds lose its prefix. Before this change it
    was recognised only because every unknown name was. Recording which router each Python mount is registered on
    (the separate problem below) would cover this case too.

Changed files:

  • skills/floorplan/scripts/lib/routes.mjs: the Python fallback in mountTarget.
  • skills/floorplan/scripts/lib/extract.mjs: the Python routers pattern.
  • tests/fastapi-mounts.test.mjs and the sample tests/fixtures/fastapi-mounts/: new.
  • docs/development.md: a row for the new test file.
  • CHANGELOG.md: a line under ## Unreleased.

How I tested it

  • npm test: 494 tests, 493 pass, 0 fail, 1 skipped (the Windows-only test). Run on macOS with Node 24.15.0.
  • claude plugin validate .: passed.
  • The new tests: 4 of the 6 fail on main and all 6 pass with the change.
    • The sample in fixtures/fastapi-mounts comes out as exactly GET /api/v1/status/ping,
      GET /api/v1/items/list and DELETE /api/v1/items/{item_id}. On main, the two items endpoints also appear
      again under /api/v1/graphql.
    • A check on the factory router's include no longer protects items, so Health reports
      DELETE /items/{item_id} as open. This is checked before the endpoint list, so on main the test fails on the
      Health result itself (no open endpoints).
    • A factory called in place and a router from an installed package put no prefix on the other routers.
    • A router made with a type annotation or fastapi.routing.APIRouter(prefix=...) gets its own prefix (on main,
      POST /reset instead of POST /admin/reset).
    • Two tests pass on main too, and guard against the fallback becoming too narrow: routers the file made (plain,
      annotated, or from a factory with routes declared on them) still get the prefix they are included with, and a
      router that only holds other routers (annotated, under fastapi.routing, or an annotated Flask blueprint)
      still hands its prefix on to them.
  • Real project: a large Python FastAPI service, one repo. I scanned it with main and with this branch. On main,
    359 endpoints sat under a factory router's prefix, and 352 of them were missing at their real address. With this
    change, none are under that prefix, all 359 are at their real address, and every other endpoint kept its
    address. One more of the project's own requests is matched to its endpoint (47 before, 48 after).

Checklist

  • No new dependencies
  • Anything the map shows people is in plain language
  • No secret values stored or printed
  • No details of a real private project in code, comments, docs or screenshots
  • npm test passes
  • claude plugin validate . passes
  • CHANGELOG.md updated, if people will notice the change

Created with Claude Opus 5.5 in Claude Code.

🤖 Generated with Claude Code

A Python mount whose name the file neither made nor imported from the
project, such as what a factory returned (graphql_router =
make_graphql_router(), then app.include_router(graphql_router,
prefix="/api/v1/graphql")) or a router from an installed package, was
taken for a router of the mounting file. Its prefix then went on every
other router that file included (/api/v1/graphql/api/v1/items/list
beside /api/v1/items/list), and a check added where it was included
counted for them too, so Health could miss an open endpoint.

This is the Python side of haydenschmitty#71: like jsMountTarget, mountTarget now
returns null for such a name. A router the file makes, or declares
routes on, is still the file's own. So that routers which only hold
other routers keep handing their prefix on, the pattern for a router
the file makes now also reads a type annotation and a longer module
name (api_router: APIRouter = fastapi.routing.APIRouter()). The
prefix a router declared that way is made with, APIRouter(prefix=...),
is no longer dropped either.

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

Fixes haydenschmitty#160.
@IdirBenSlama
IdirBenSlama force-pushed the fix/160-python-unknown-mount-name branch from f15ede5 to 8ab2f32 Compare November 20, 2026 22:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

FastAPI: a router returned by a factory puts its prefix on every other router the file includes

1 participant