mirror of
https://github.com/fastapi/fastapi.git
synced 2026-01-20 20:09:05 -05:00
05ca41cfd1
* ➕ Add mkdocstrings and griffe-typingdoc to dependencies * 🔧 Add mkdocstrings configs to MkDocs * 📝 Add first WIP reference page * ⬆️ Upgrade typing-extensions to the minimum version including Doc() * 📝 Add docs to FastAPI parameters * 📝 Add docstrings for OpenAPI docs utils * 📝 Add docstrings for security utils * 📝 Add docstrings for UploadFile * 📝 Update docstrings in FastAPI class * 📝 Add docstrings for path operation methods * 📝 Add docstring for jsonable_encoder * 📝 Add docstrings for exceptions * 📝 Add docstsrings for parameter functions * 📝 Add docstrings for responses * 📝 Add docstrings for APIRouter * ♻️ Sub-class BackgroundTasks to document it with docstrings * 📝 Update usage of background tasks in dependencies * ✅ Update tests with new deprecation warnings * 📝 Add new reference docs * 🔧 Update MkDocs with new reference docs * ✅ Update pytest fixture, deprecation is raised only once * 🎨 Update format for types in exceptions.py * ♻️ Update annotations in BackgroundTask, `Annotated` can't take ParamSpec's P.args or P.kwargs * ✏️ Fix typos caught by @pawamoy * 🔧 Update and fix MkDocstrings configs from @pawamoy tips * 📝 Update reference docs * ✏️ Fix typos found by @pawamoy * ➕ Add HTTPX as a dependency for docs, for the TestClient * 🔧 Update MkDocs config, rename websockets reference * 🔇 Add type-ignores for Doc as the stubs haven't been released for mypy * 🔥 Remove duplicated deprecated notice * 🔇 Remove typing error for unreleased stub in openapi/docs.py * ✅ Add tests for UploadFile for coverage * ⬆️ Upgrade griffe-typingdoc==0.2.2 * 📝 Refactor docs structure * 🔨 Update README generation with new index frontmatter and style * 🔨 Update generation of languages, remove from top menu, keep in lang menu * 📝 Add OpenAPI Pydantic models * 🔨 Update docs script to not translate Reference and Release Notes * 🔧 Add reference for OpenAPI models * 🔧 Update MkDocs config for mkdocstrings insiders * 👷 Install mkdocstring insiders in CI for docs * 🐛 Fix MkDocstrings insiders install URL * ➕ Move dependencies shared by docs and tests to its own requirements file * 👷 Update cache keys for test and docs dependencies * 📝 Remove no longer needed __init__ placeholder docstrings * 📝 Move docstring for APIRouter to the class level (not __init__ level) * 🔥 Remove no longer needed dummy placeholder __init__ docstring
421 lines
13 KiB
Python
421 lines
13 KiB
Python
import binascii
|
|
from base64 import b64decode
|
|
from typing import Optional
|
|
|
|
from fastapi.exceptions import HTTPException
|
|
from fastapi.openapi.models import HTTPBase as HTTPBaseModel
|
|
from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
|
|
from fastapi.security.base import SecurityBase
|
|
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 # type: ignore [attr-defined]
|
|
|
|
|
|
class HTTPBasicCredentials(BaseModel):
|
|
"""
|
|
The HTTP Basic credendials given as the result of using `HTTPBasic` in a
|
|
dependency.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for HTTP Basic Auth](https://fastapi.tiangolo.com/advanced/security/http-basic-auth/).
|
|
"""
|
|
|
|
username: Annotated[str, Doc("The HTTP Basic username.")]
|
|
password: Annotated[str, Doc("The HTTP Basic password.")]
|
|
|
|
|
|
class HTTPAuthorizationCredentials(BaseModel):
|
|
"""
|
|
The HTTP authorization credentials in the result of using `HTTPBearer` or
|
|
`HTTPDigest` in a dependency.
|
|
|
|
The HTTP authorization header value is split by the first space.
|
|
|
|
The first part is the `scheme`, the second part is the `credentials`.
|
|
|
|
For example, in an HTTP Bearer token scheme, the client will send a header
|
|
like:
|
|
|
|
```
|
|
Authorization: Bearer deadbeef12346
|
|
```
|
|
|
|
In this case:
|
|
|
|
* `scheme` will have the value `"Bearer"`
|
|
* `credentials` will have the value `"deadbeef12346"`
|
|
"""
|
|
|
|
scheme: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The HTTP authorization scheme extracted from the header value.
|
|
"""
|
|
),
|
|
]
|
|
credentials: Annotated[
|
|
str,
|
|
Doc(
|
|
"""
|
|
The HTTP authorization credentials extracted from the header value.
|
|
"""
|
|
),
|
|
]
|
|
|
|
|
|
class HTTPBase(SecurityBase):
|
|
def __init__(
|
|
self,
|
|
*,
|
|
scheme: str,
|
|
scheme_name: Optional[str] = None,
|
|
description: Optional[str] = None,
|
|
auto_error: bool = True,
|
|
):
|
|
self.model = HTTPBaseModel(scheme=scheme, description=description)
|
|
self.scheme_name = scheme_name or self.__class__.__name__
|
|
self.auto_error = auto_error
|
|
|
|
async def __call__(
|
|
self, request: Request
|
|
) -> Optional[HTTPAuthorizationCredentials]:
|
|
authorization = request.headers.get("Authorization")
|
|
scheme, credentials = get_authorization_scheme_param(authorization)
|
|
if not (authorization and scheme and credentials):
|
|
if self.auto_error:
|
|
raise HTTPException(
|
|
status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
|
|
)
|
|
else:
|
|
return None
|
|
return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
|
|
|
|
|
|
class HTTPBasic(HTTPBase):
|
|
"""
|
|
HTTP Basic authentication.
|
|
|
|
## Usage
|
|
|
|
Create an instance object and use that object as the dependency in `Depends()`.
|
|
|
|
The dependency result will be an `HTTPBasicCredentials` object containing the
|
|
`username` and the `password`.
|
|
|
|
Read more about it in the
|
|
[FastAPI docs for HTTP Basic Auth](https://fastapi.tiangolo.com/advanced/security/http-basic-auth/).
|
|
|
|
## Example
|
|
|
|
```python
|
|
from typing import Annotated
|
|
|
|
from fastapi import Depends, FastAPI
|
|
from fastapi.security import HTTPBasic, HTTPBasicCredentials
|
|
|
|
app = FastAPI()
|
|
|
|
security = HTTPBasic()
|
|
|
|
|
|
@app.get("/users/me")
|
|
def read_current_user(credentials: Annotated[HTTPBasicCredentials, Depends(security)]):
|
|
return {"username": credentials.username, "password": credentials.password}
|
|
```
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
scheme_name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme name.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
realm: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
HTTP Basic authentication realm.
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme description.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
auto_error: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
By default, if the HTTP Basic authentication is not provided (a
|
|
header), `HTTPBasic` will automatically cancel the request and send the
|
|
client an error.
|
|
|
|
If `auto_error` is set to `False`, when the HTTP Basic authentication
|
|
is not available, instead of erroring out, the dependency result will
|
|
be `None`.
|
|
|
|
This is useful when you want to have optional authentication.
|
|
|
|
It is also useful when you want to have authentication that can be
|
|
provided in one of multiple optional ways (for example, in HTTP Basic
|
|
authentication or in an HTTP Bearer token).
|
|
"""
|
|
),
|
|
] = True,
|
|
):
|
|
self.model = HTTPBaseModel(scheme="basic", description=description)
|
|
self.scheme_name = scheme_name or self.__class__.__name__
|
|
self.realm = realm
|
|
self.auto_error = auto_error
|
|
|
|
async def __call__( # type: ignore
|
|
self, request: Request
|
|
) -> Optional[HTTPBasicCredentials]:
|
|
authorization = request.headers.get("Authorization")
|
|
scheme, param = get_authorization_scheme_param(authorization)
|
|
if self.realm:
|
|
unauthorized_headers = {"WWW-Authenticate": f'Basic realm="{self.realm}"'}
|
|
else:
|
|
unauthorized_headers = {"WWW-Authenticate": "Basic"}
|
|
if not authorization or scheme.lower() != "basic":
|
|
if self.auto_error:
|
|
raise HTTPException(
|
|
status_code=HTTP_401_UNAUTHORIZED,
|
|
detail="Not authenticated",
|
|
headers=unauthorized_headers,
|
|
)
|
|
else:
|
|
return None
|
|
invalid_user_credentials_exc = HTTPException(
|
|
status_code=HTTP_401_UNAUTHORIZED,
|
|
detail="Invalid authentication credentials",
|
|
headers=unauthorized_headers,
|
|
)
|
|
try:
|
|
data = b64decode(param).decode("ascii")
|
|
except (ValueError, UnicodeDecodeError, binascii.Error):
|
|
raise invalid_user_credentials_exc
|
|
username, separator, password = data.partition(":")
|
|
if not separator:
|
|
raise invalid_user_credentials_exc
|
|
return HTTPBasicCredentials(username=username, password=password)
|
|
|
|
|
|
class HTTPBearer(HTTPBase):
|
|
"""
|
|
HTTP Bearer token authentication.
|
|
|
|
## Usage
|
|
|
|
Create an instance object and use that object as the dependency in `Depends()`.
|
|
|
|
The dependency result will be an `HTTPAuthorizationCredentials` object containing
|
|
the `scheme` and the `credentials`.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from typing import Annotated
|
|
|
|
from fastapi import Depends, FastAPI
|
|
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
|
|
|
|
app = FastAPI()
|
|
|
|
security = HTTPBearer()
|
|
|
|
|
|
@app.get("/users/me")
|
|
def read_current_user(
|
|
credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
|
|
):
|
|
return {"scheme": credentials.scheme, "credentials": credentials.credentials}
|
|
```
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
bearerFormat: Annotated[Optional[str], Doc("Bearer token format.")] = None,
|
|
scheme_name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme name.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme description.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
auto_error: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
By default, if the HTTP Bearer token not provided (in an
|
|
`Authorization` header), `HTTPBearer` will automatically cancel the
|
|
request and send the client an error.
|
|
|
|
If `auto_error` is set to `False`, when the HTTP Bearer token
|
|
is not available, instead of erroring out, the dependency result will
|
|
be `None`.
|
|
|
|
This is useful when you want to have optional authentication.
|
|
|
|
It is also useful when you want to have authentication that can be
|
|
provided in one of multiple optional ways (for example, in an HTTP
|
|
Bearer token or in a cookie).
|
|
"""
|
|
),
|
|
] = True,
|
|
):
|
|
self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
|
|
self.scheme_name = scheme_name or self.__class__.__name__
|
|
self.auto_error = auto_error
|
|
|
|
async def __call__(
|
|
self, request: Request
|
|
) -> Optional[HTTPAuthorizationCredentials]:
|
|
authorization = request.headers.get("Authorization")
|
|
scheme, credentials = get_authorization_scheme_param(authorization)
|
|
if not (authorization and scheme and credentials):
|
|
if self.auto_error:
|
|
raise HTTPException(
|
|
status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
|
|
)
|
|
else:
|
|
return None
|
|
if scheme.lower() != "bearer":
|
|
if self.auto_error:
|
|
raise HTTPException(
|
|
status_code=HTTP_403_FORBIDDEN,
|
|
detail="Invalid authentication credentials",
|
|
)
|
|
else:
|
|
return None
|
|
return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
|
|
|
|
|
|
class HTTPDigest(HTTPBase):
|
|
"""
|
|
HTTP Digest authentication.
|
|
|
|
## Usage
|
|
|
|
Create an instance object and use that object as the dependency in `Depends()`.
|
|
|
|
The dependency result will be an `HTTPAuthorizationCredentials` object containing
|
|
the `scheme` and the `credentials`.
|
|
|
|
## Example
|
|
|
|
```python
|
|
from typing import Annotated
|
|
|
|
from fastapi import Depends, FastAPI
|
|
from fastapi.security import HTTPAuthorizationCredentials, HTTPDigest
|
|
|
|
app = FastAPI()
|
|
|
|
security = HTTPDigest()
|
|
|
|
|
|
@app.get("/users/me")
|
|
def read_current_user(
|
|
credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)]
|
|
):
|
|
return {"scheme": credentials.scheme, "credentials": credentials.credentials}
|
|
```
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
scheme_name: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme name.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
description: Annotated[
|
|
Optional[str],
|
|
Doc(
|
|
"""
|
|
Security scheme description.
|
|
|
|
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
|
|
"""
|
|
),
|
|
] = None,
|
|
auto_error: Annotated[
|
|
bool,
|
|
Doc(
|
|
"""
|
|
By default, if the HTTP Digest not provided, `HTTPDigest` will
|
|
automatically cancel the request and send the client an error.
|
|
|
|
If `auto_error` is set to `False`, when the HTTP Digest is not
|
|
available, instead of erroring out, the dependency result will
|
|
be `None`.
|
|
|
|
This is useful when you want to have optional authentication.
|
|
|
|
It is also useful when you want to have authentication that can be
|
|
provided in one of multiple optional ways (for example, in HTTP
|
|
Digest or in a cookie).
|
|
"""
|
|
),
|
|
] = True,
|
|
):
|
|
self.model = HTTPBaseModel(scheme="digest", description=description)
|
|
self.scheme_name = scheme_name or self.__class__.__name__
|
|
self.auto_error = auto_error
|
|
|
|
async def __call__(
|
|
self, request: Request
|
|
) -> Optional[HTTPAuthorizationCredentials]:
|
|
authorization = request.headers.get("Authorization")
|
|
scheme, credentials = get_authorization_scheme_param(authorization)
|
|
if not (authorization and scheme and credentials):
|
|
if self.auto_error:
|
|
raise HTTPException(
|
|
status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
|
|
)
|
|
else:
|
|
return None
|
|
if scheme.lower() != "digest":
|
|
raise HTTPException(
|
|
status_code=HTTP_403_FORBIDDEN,
|
|
detail="Invalid authentication credentials",
|
|
)
|
|
return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
|