Importing the FastAPI adapter without its extra says 'No module named starlette' instead of naming the extra

[AlexeyShalaev]

Measured on 0.10.0 in a fresh venv with uv pip install servicewright and nothing else, importing each adapter subpackage:

servicewright.adapters.fastapi  -> ModuleNotFoundError: No module named 'starlette'
servicewright.adapters.litestar -> ImportError: Litestar support requires servicewright[litestar]; install it.
servicewright.adapters.grpc     -> ImportError: gRPC support requires servicewright[grpc]; install it.
servicewright.adapters.dishka   -> ImportError: Dishka support requires servicewright[dishka]; install it.

Three of the four say what to install. The FastAPI one says starlette, which is a package the user never asked for, never named in the extras table, and cannot obviously map back to servicewright[fastapi] — especially for someone who has installed FastAPI in some other environment and is now looking at a dependency they have never heard of.

docs/agents.md states the contract in the adapters section: "Each subpackage needs its extra; importing one without it raises ImportError naming what to install", and the errors table repeats it: "an adapter, sink or settings model imported without its extra — the message names the extra". ModuleNotFoundError is an ImportError subclass, so the type is right and the message is not.

The cause is import order: something in the FastAPI adapter's module graph imports starlette (directly or through a submodule) before the guarded fastapi import that produces the friendly message. Whichever import runs first is the one the user sees.

What I think it needs: the guard has to cover every third-party import the subpackage's __init__ can reach, not just the headline one — so either the guarded import moves ahead of everything else in adapters/fastapi/__init__.py, or the guard checks starlette too and names the same extra. Then a test per adapter that imports it in an environment without the extra and asserts the message names the extra; without one, this drifts back the next time an import moves. The other three adapters presumably pass such a test today, which is exactly why the FastAPI one is worth catching.

While you are there: servicewright.settings (the [settings] extra) raises ModuleNotFoundError: No module named 'servicewright.settings' in a bare install rather than an ImportError naming the extra. That reads as "this library has no settings module" rather than "install the extra", and the errors table promises the second. If the module genuinely is not shipped without the extra, the docs should say so; if it is, it needs the same guard.

[AlexeyShalaev]

Reproduced on 0.10.0 in a fresh venv with uv pip install servicewright and nothing else — same four lines, plus the settings module for completeness:

servicewright.adapters.fastapi  -> ModuleNotFoundError: No module named 'starlette'
servicewright.adapters.litestar -> ImportError: Litestar support requires servicewright[litestar]; install it.
servicewright.adapters.grpc     -> ImportError: gRPC support requires servicewright[grpc]; install it.
servicewright.adapters.dishka   -> ImportError: Dishka support requires servicewright[dishka]; install it.
servicewright.adapters.settings -> ImportError: Settings models require servicewright[settings]; install it.

The traceback names the exact door:

adapters/fastapi/__init__.py:15   from .context import (...)
adapters/fastapi/context.py:23    from .middlewares.protocols import ContextSetter
adapters/fastapi/middlewares/__init__.py:12  from .context import (...)
adapters/fastapi/middlewares/context.py:9    from starlette.datastructures import Headers

Your diagnosis is right, and it is broader than one line. adapters/fastapi/_imports.py says in its own docstring that "every HTTP submodule imports its third-party symbols from here", but eight module-level imports in the subpackage never got the memo:

Module	Import
middlewares/context.py:9	from starlette.datastructures import Headers
middlewares/logging.py:15	from starlette.datastructures import Headers
middlewares/processing_time.py:8	from starlette.datastructures import MutableHeaders
schemas.py:7	from pydantic import BaseModel, ConfigDict, Field
headers.py:12	from fastapi import Header
unit_scope.py:23	from fastapi import Depends, Request
exceptions.py:21	from deadline_budget import DeadlineExceededError
exceptions.py:22	from fastapi.exceptions import RequestValidationError

Whichever runs first wins, and today that is starlette. I parsed every extra-gated adapter the same way: litestar, grpc, dishka, settings, apscheduler3 and apscheduler4 have no runtime third-party import outside their guard, which is exactly why the other three messages are correct.

What I am going to do. Route all eight through _imports.py, so the guard becomes the single door the docstring already claims it is. Every module in the subpackage then reaches it first, whether you import the package or a submodule directly.

What I rejected:

• Add starlette to the guard's try: block. That is the symptom: pydantic and deadline_budget are unguarded too, and the next import that drifts out re-opens the same hole.
• Import ._imports first in adapters/fastapi/__init__.py. Fixes the package import only. import servicewright.adapters.fastapi.schemas still says "No module named 'pydantic'", and one reordered import in __init__ puts it back.
• A shared require_extra(...) helper across all adapters. A new concept for everyone to learn, to replace a per-adapter _imports.py pattern that already works in six of seven adapters. The one that drifted needs discipline, not a framework.

And a test, so it does not drift back. One parametrized case per extra-gated subpackage (fastapi, litestar, grpc, dishka, settings, apscheduler3, apscheduler4): a subprocess with a sys.meta_path finder that blocks everything the extra installs, then imports the subpackage and asserts the exception is an ImportError — not a bare ModuleNotFoundError — whose message names servicewright[<extra>]. Honest in a dev environment where every extra is installed, and it fails today for fastapi alone.

On servicewright.settings: that module has never existed — the models live at servicewright.adapters.settings, which is what docs/agents.md, the settings guide and the API reference all point at, and it already raises ImportError: Settings models require servicewright[settings]; install it. (last line of the run above). So the ModuleNotFoundError: No module named 'servicewright.settings' you saw is Python correctly reporting a module that is not part of the library, not a missing guard. It will be covered by the same test under its real name. If you hit that path from something I wrote, point me at it and I will fix the page.

[AlexeyShalaev]

Shipped in #54 (CI green), which closes this on merge.

Your branch, installed with no extras into the same venv that produced the report:

servicewright.adapters.fastapi  -> ImportError: FastAPI support requires servicewright[fastapi]; install it.
servicewright.adapters.litestar -> ImportError: Litestar support requires servicewright[litestar]; install it.
servicewright.adapters.grpc     -> ImportError: gRPC support requires servicewright[grpc]; install it.
servicewright.adapters.dishka   -> ImportError: Dishka support requires servicewright[dishka]; install it.

All eight drifted imports go back through adapters/fastapi/_imports.py, so the guard is the single door structurally rather than by import order. TYPE_CHECKING-only imports keep naming starlette directly — they never run.

Two corrections to what I wrote in the plan.

First: I claimed importing servicewright.adapters.fastapi.schemas directly would bypass a guard that only sits at the top of __init__.py. That is wrong — Python runs the package __init__ before any submodule, so the one-line version would have fixed the reported symptom too. I still went with routing every import through the guard, because the one-liner is a fix that lives in the order of an import block: one reordering and it is silently gone, with the _imports.py docstring's claim still false. But the reason is durability, not correctness, and the plan overstated it.

Second: servicewright.settings is not a missing guard. That module has never existed — the models are at servicewright.adapters.settings, which is what docs/agents.md, the settings guide and the API reference all point at, and which already raised the right message before this change:

servicewright.adapters.settings -> ImportError: Settings models require servicewright[settings]; install it.

So No module named 'servicewright.settings' is Python correctly reporting a module that is not part of the library. Nothing to change in the code or the docs — but if you got that path from something I wrote rather than from muscle memory, tell me where and I will fix the page.

Nothing to change on your side. The drift guard you asked for is tests/unit/test_adapter_extras.py: one case per extra-gated subpackage (fastapi, litestar, grpc, apscheduler4, apscheduler3, dishka, settings), each a subprocess with a sys.meta_path finder blocking everything the extra installs, asserting the exception is an ImportError — not a bare ModuleNotFoundError — naming servicewright[<extra>]. It failed for fastapi alone before the fix.