➕ Migrate internal reference documentation from `typing_extensions.Doc` to `annotated_doc.Doc` (#14222)

fastapi/applications.py

@@ -13,6 +13,7 @@ from typing import (
     Union,
 )
 
+from annotated_doc import Doc
 from fastapi import routing
 from fastapi.datastructures import Default, DefaultPlaceholder
 from fastapi.exception_handlers import (
@@ -43,7 +44,7 @@ from starlette.requests import Request
 from starlette.responses import HTMLResponse, JSONResponse, Response
 from starlette.routing import BaseRoute
 from starlette.types import ASGIApp, ExceptionHandler, Lifespan, Receive, Scope, Send
-from typing_extensions import Annotated, Doc, deprecated
+from typing_extensions import Annotated, deprecated
 
 AppType = TypeVar("AppType", bound="FastAPI")
 

fastapi/background.py

@@ -1,7 +1,8 @@
 from typing import Any, Callable
 
+from annotated_doc import Doc
 from starlette.background import BackgroundTasks as StarletteBackgroundTasks
-from typing_extensions import Annotated, Doc, ParamSpec
+from typing_extensions import Annotated, ParamSpec
 
 P = ParamSpec("P")
 

fastapi/datastructures.py

@@ -10,6 +10,7 @@ from typing import (
     cast,
 )
 
+from annotated_doc import Doc
 from fastapi._compat import (
     CoreSchema,
     GetJsonSchemaHandler,
@@ -22,7 +23,7 @@ from starlette.datastructures import Headers as Headers  # noqa: F401
 from starlette.datastructures import QueryParams as QueryParams  # noqa: F401
 from starlette.datastructures import State as State  # noqa: F401
 from starlette.datastructures import UploadFile as StarletteUploadFile
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class UploadFile(StarletteUploadFile):

fastapi/encoders.py

@@ -17,13 +17,14 @@ from types import GeneratorType
 from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
 from uuid import UUID
 
+from annotated_doc import Doc
 from fastapi._compat import may_v1
 from fastapi.types import IncEx
 from pydantic import BaseModel
 from pydantic.color import Color
 from pydantic.networks import AnyUrl, NameEmail
 from pydantic.types import SecretBytes, SecretStr
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 from ._compat import Url, _is_undefined, _model_dump
 

fastapi/exceptions.py

@@ -1,9 +1,10 @@
 from typing import Any, Dict, Optional, Sequence, Type, Union
 
+from annotated_doc import Doc
 from pydantic import BaseModel, create_model
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from starlette.exceptions import WebSocketException as StarletteWebSocketException
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class HTTPException(StarletteHTTPException):

fastapi/openapi/docs.py

@@ -1,9 +1,10 @@
 import json
 from typing import Any, Dict, Optional
 
+from annotated_doc import Doc
 from fastapi.encoders import jsonable_encoder
 from starlette.responses import HTMLResponse
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 swagger_ui_default_parameters: Annotated[
     Dict[str, Any],

fastapi/param_functions.py

@@ -1,9 +1,10 @@
 from typing import Any, Callable, Dict, List, Optional, Sequence, Union
 
+from annotated_doc import Doc
 from fastapi import params
 from fastapi._compat import Undefined
 from fastapi.openapi.models import Example
-from typing_extensions import Annotated, Doc, deprecated
+from typing_extensions import Annotated, deprecated
 
 _Unset: Any = Undefined
 

fastapi/routing.py

@@ -24,6 +24,7 @@ from typing import (
     Union,
 )
 
+from annotated_doc import Doc
 from fastapi import params, temp_pydantic_v1_params
 from fastapi._compat import (
     ModelField,
@@ -76,7 +77,7 @@ from starlette.routing import (
 from starlette.routing import Mount as Mount  # noqa
 from starlette.types import AppType, ASGIApp, Lifespan, Receive, Scope, Send
 from starlette.websockets import WebSocket
-from typing_extensions import Annotated, Doc, deprecated
+from typing_extensions import Annotated, deprecated
 
 if sys.version_info >= (3, 13):  # pragma: no cover
     from inspect import iscoroutinefunction

fastapi/security/api_key.py

@@ -1,11 +1,12 @@
 from typing import Optional
 
+from annotated_doc import Doc
 from fastapi.openapi.models import APIKey, APIKeyIn
 from fastapi.security.base import SecurityBase
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.status import HTTP_403_FORBIDDEN
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class APIKeyBase(SecurityBase):

fastapi/security/http.py

@@ -2,6 +2,7 @@ import binascii
 from base64 import b64decode
 from typing import Optional
 
+from annotated_doc import Doc
 from fastapi.exceptions import HTTPException
 from fastapi.openapi.models import HTTPBase as HTTPBaseModel
 from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
@@ -10,7 +11,7 @@ from fastapi.security.utils import get_authorization_scheme_param
 from pydantic import BaseModel
 from starlette.requests import Request
 from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class HTTPBasicCredentials(BaseModel):

fastapi/security/oauth2.py

@@ -1,5 +1,6 @@
 from typing import Any, Dict, List, Optional, Union, cast
 
+from annotated_doc import Doc
 from fastapi.exceptions import HTTPException
 from fastapi.openapi.models import OAuth2 as OAuth2Model
 from fastapi.openapi.models import OAuthFlows as OAuthFlowsModel
@@ -10,7 +11,7 @@ from starlette.requests import Request
 from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
 
 # TODO: import from typing when deprecating Python 3.9
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class OAuth2PasswordRequestForm:

fastapi/security/open_id_connect_url.py

@@ -1,11 +1,12 @@
 from typing import Optional
 
+from annotated_doc import Doc
 from fastapi.openapi.models import OpenIdConnect as OpenIdConnectModel
 from fastapi.security.base import SecurityBase
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.status import HTTP_403_FORBIDDEN
-from typing_extensions import Annotated, Doc
+from typing_extensions import Annotated
 
 
 class OpenIdConnect(SecurityBase):

pyproject.toml

@@ -47,6 +47,7 @@ dependencies = [
     "starlette>=0.40.0,<0.49.0",
     "pydantic>=1.7.4,!=1.8,!=1.8.1,!=2.0.0,!=2.0.1,!=2.1.0,<3.0.0",
     "typing-extensions>=4.8.0",
+    "annotated-doc>=0.0.2",
 ]
 
 [project.urls]

requirements-docs.txt

@@ -12,7 +12,7 @@ pillow==11.3.0
 # For image processing by Material for MkDocs
 cairosvg==2.8.2
 mkdocstrings[python]==0.26.1
-griffe-typingdoc==0.2.9
+griffe-typingdoc==0.3.0
 # For griffe, it formats with black
 black==25.1.0
 mkdocs-macros-plugin==1.4.0