diff --git a/docs/usage/dependency-callables.md b/docs/usage/dependency-callables.md index 94617b23..a74b4240 100644 --- a/docs/usage/dependency-callables.md +++ b/docs/usage/dependency-callables.md @@ -1,11 +1,72 @@ # Dependency callables -**FastAPI Users** provides dependency callables to easily inject users in your routes. They are available from your `FastAPIUsers` instance. +**FastAPI Users** provides a dependency callable to easily inject authenticated user in your routes. They are available from your `FastAPIUsers` instance. !!! tip For more information about how to make an authenticated request to your API, check the documentation of your [Authentication method](../configuration/authentication/index.md). -## `get_current_user` +## `current_user` + +Return a dependency callable to retrieve currently authenticated user, passing the following parameters: + +* `optional`: If `True`, `None` is returned if there is no authenticated user or if it doesn't pass the other requirements. Otherwise, throw `401 Unauthorized`. Defaults to `False`. +* `active`: If `True`, throw `401 Unauthorized` if the authenticated user is inactive. Defaults to `False`. +* `verified`: If `True`, throw `401 Unauthorized` if the authenticated user is not verified. Defaults to `False`. +* `superuser`: If `True`, throw `403 Forbidden` if the authenticated user is not a superuser. Defaults to `False`. + +### Examples + +#### Get the current user (**active or not **) + +```py +@app.get("/protected-route") +def protected_route(user: User = Depends(fastapi_users.current_user())): + return f"Hello, {user.email}" +``` + +#### Get the current active user + +```py +@app.get("/protected-route") +def protected_route(user: User = Depends(fastapi_users.current_user(active=True))): + return f"Hello, {user.email}" +``` + +#### Get the current active and verified user + +```py +@app.get("/protected-route") +def protected_route(user: User = Depends(fastapi_users.current_user(active=True, verified=True))): + return f"Hello, {user.email}" +``` + +#### Get the current active superuser + +```py +@app.get("/protected-route") +def protected_route(user: User = Depends(fastapi_users.current_user(active=True, superuser=True))): + return f"Hello, {user.email}" +``` + +#### Reuse it + +If you use it often, you can of course set it in a variable and reuse it at will: + +```py +current_active_user = fastapi_users.current_user(active=True) + + +@app.get("/protected-route") +def protected_route(user: User = Depends(current_active_user)): + return f"Hello, {user.email}" +``` + +## Deprecated + +!!! warning + Those ones are still provided for backward compatibility but are deprecated and will be removed in a future release. + +### `get_current_user` Get the current user (**active or not**). Will throw a `401 Unauthorized` if missing or wrong credentials. @@ -15,7 +76,7 @@ def protected_route(user: User = Depends(fastapi_users.get_current_user)): return f"Hello, {user.email}" ``` -## `get_current_active_user` +### `get_current_active_user` Get the current active user. Will throw a `401 Unauthorized` if missing or wrong credentials or if the user is not active. @@ -25,7 +86,7 @@ def protected_route(user: User = Depends(fastapi_users.get_current_active_user)) return f"Hello, {user.email}" ``` -## `get_current_verified_user` +### `get_current_verified_user` Get the current active and verified user. Will throw a `401 Unauthorized` if missing or wrong credentials or if the user is not active and verified. @@ -35,7 +96,7 @@ def protected_route(user: User = Depends(fastapi_users.get_current_verified_user return f"Hello, {user.email}" ``` -## `get_current_superuser` +### `get_current_superuser` Get the current superuser. Will throw a `401 Unauthorized` if missing or wrong credentials or if the user is not active. Will throw a `403 Forbidden` if the user is not a superuser. @@ -45,7 +106,7 @@ def protected_route(user: User = Depends(fastapi_users.get_current_superuser)): return f"Hello, {user.email}" ``` -## `get_current_verified_superuser` +### `get_current_verified_superuser` Get the current verified superuser. Will throw a `401 Unauthorized` if missing or wrong credentials or if the user is not active and verified. Will throw a `403 Forbidden` if the user is not a superuser. @@ -55,7 +116,7 @@ def protected_route(user: User = Depends(fastapi_users.get_current_verified_supe return f"Hello, {user.email}" ``` -## `get_optional_current_user` +### `get_optional_current_user` Get the current user (**active or not**). Will return `None` if missing or wrong credentials. It can be useful if you wish to change the behaviour of your endpoint if a user is logged in or not. @@ -68,7 +129,7 @@ def optional_user_route(user: Optional[User] = Depends(fastapi_users.get_optiona return "Hello, anonymous" ``` -## `get_optional_current_active_user` +### `get_optional_current_active_user` Get the current active user. Will return `None` if missing or wrong credentials or if the user is not active. It can be useful if you wish to change the behaviour of your endpoint if a user is logged in or not. @@ -81,7 +142,7 @@ def optional_user_route(user: User = Depends(fastapi_users.get_optional_current_ return "Hello, anonymous" ``` -## `get_optional_current_verified_user` +### `get_optional_current_verified_user` Get the current active and verified user. Will return `None` if missing or wrong credentials or if the user is not active and verified. It can be useful if you wish to change the behaviour of your endpoint if a user is logged in or not. @@ -94,7 +155,7 @@ def optional_user_route(user: User = Depends(fastapi_users.get_optional_current_ return "Hello, anonymous" ``` -## `get_optional_current_superuser` +### `get_optional_current_superuser` Get the current superuser. Will return `None` if missing or wrong credentials or if the user is not active. It can be useful if you wish to change the behaviour of your endpoint if a user is logged in or not. @@ -107,7 +168,7 @@ def optional_user_route(user: User = Depends(fastapi_users.get_optional_current_ return "Hello, anonymous" ``` -## `get_optional_current_verified_superuser` +### `get_optional_current_verified_superuser` Get the current active and verified superuser. Will return `None` if missing or wrong credentials or if the user is not active and verified. It can be useful if you wish to change the behaviour of your endpoint if a user is logged in or not. diff --git a/fastapi_users/authentication/__init__.py b/fastapi_users/authentication/__init__.py index 43241ff5..61f06a1e 100644 --- a/fastapi_users/authentication/__init__.py +++ b/fastapi_users/authentication/__init__.py @@ -97,15 +97,16 @@ class Authenticator: """ Return a dependency callable to retrieve currently authenticated user. - :param optional: If `true`, `None` is returned if there is no - authenticated user or if it doesn't pass the other requirements. - Otherwise, an exception is raised. Defaults to `false`. - :param active: If `true`, raise an exception if - the authenticated user is inactive. Defaults to `false`. - :param verified: If `true`, raise an exception if - the authenticated user is not verified. Defaults to `false`. - :param superuser: If `true`, raise an exception if - the authenticated user is not a superuser. Defaults to `false`. + :param optional: If `True`, `None` is returned if there is no authenticated user + or if it doesn't pass the other requirements. + Otherwise, throw `401 Unauthorized`. Defaults to `False`. + Otherwise, an exception is raised. Defaults to `False`. + :param active: If `True`, throw `401 Unauthorized` if + the authenticated user is inactive. Defaults to `False`. + :param verified: If `True`, throw `401 Unauthorized` if + the authenticated user is not verified. Defaults to `False`. + :param superuser: If `True`, throw `403 Forbidden` if + the authenticated user is not a superuser. Defaults to `False`. """ # Here comes some blood magic 🧙‍♂️ # Thank to "makefun", we are able to generate callable diff --git a/mkdocs.yml b/mkdocs.yml index 16931a71..a7f7b8be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,3 +57,4 @@ nav: - migration/1x_to_2x.md - migration/2x_to_3x.md - migration/3x_to_4x.md + - migration/4x_to_5x.md