Chore/type hints and examples

examples/middleware/error_middleware.py

@@ -2,7 +2,7 @@
 from fasthttp.middleware import BaseMiddleware
 from fasthttp.response import Response
 from fasthttp.routing import Route
-from fasthttp.types import RequestsOptinal
+from fasthttp.types import RequestsOptional
 
 
 class ErrorTrackingMiddleware(BaseMiddleware):
@@ -15,7 +15,7 @@ def __init__(self) -> None:
         self.error_count = 0
 
     async def on_error(
-        self, error: Exception, route: Route, config: RequestsOptinal
+        self, error: Exception, route: Route, config: RequestsOptional
     ) -> None:
         self.error_count += 1
         print(f"Error #{self.error_count}: {error.__class__.__name__}")

examples/oauth2/client_credentials.py

@@ -0,0 +1,20 @@
+from fasthttp import FastHTTP, OAuth2ClientCredentials
+from fasthttp.response import Response
+
+app = FastHTTP(debug=True)
+
+auth = OAuth2ClientCredentials(
+    token_url="https://auth.example.com/oauth/token",
+    client_id="your-client-id",
+    client_secret="GAZAN",
+    scopes=["read", "write"]
+)
+
+
+@app.get("https://api.example.com/protected/resource", auth=auth)
+async def get_resource(resp: Response) -> dict:
+    return resp.json()
+
+
+if __name__ == "__main__":
+    app.run()

examples/oauth2/shared_auth.py

@@ -0,0 +1,32 @@
+
+
+from fasthttp import FastHTTP, OAuth2ClientCredentials
+from fasthttp.response import Response
+
+auth = OAuth2ClientCredentials(
+    token_url= "https://auth.example.com/oauth/token",
+    client_id= "example-client",
+    client_secret="67",
+    scopes=["read", "write"],
+)
+
+app = FastHTTP(debug=True)
+
+
+@app.get("https://api.example.com/users", auth=auth)
+async def get_users(resp: Response) -> dict:
+    return resp.json()
+
+
+@app.post("https://api.example.com/users", auth=auth, json={"name": "John"})
+async def create_user(resp: Response) -> dict:
+    return resp.json()
+
+
+@app.delete("https://api.example.com/users/1", auth=auth)
+async def delete_user(resp: Response) -> dict:
+    return resp.json()
+
+
+if __name__ == "__main__":
+    app.run()

fasthttp/app.py

@@ -54,7 +54,7 @@
 
     from .auth import BasicAuth, BearerAuth, DigestAuth, OAuth2ClientCredentials
     from .response import Response
-    from .types import RequestsOptinal
+    from .types import HTTPMethod, RequestsOptional
 
 
 class FastHTTP:
@@ -131,7 +131,7 @@ def __init__(
         ] = False,
         get_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for GET requests.
@@ -144,7 +144,7 @@ def __init__(
         ) = None,
         post_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for POST requests.
@@ -158,7 +158,7 @@ def __init__(
         ) = None,
         put_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for PUT requests.
@@ -172,7 +172,7 @@ def __init__(
         ) = None,
         patch_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                Default configuration for PATCH requests.
@@ -185,7 +185,7 @@ def __init__(
         ) = None,
         delete_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for DELETE requests.
@@ -198,7 +198,7 @@ def __init__(
         ) = None,
         head_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for HEAD requests.
@@ -211,7 +211,7 @@ def __init__(
         ) = None,
         options_request: (
             Annotated[
-                RequestsOptinal | None,
+                RequestsOptional | None,
                 Doc(
                     """
                 Default configuration for OPTIONS requests.
@@ -368,7 +368,7 @@ async def lifespan(app: FastHTTP):
             ),
         ] = False,
         startup_uuid_version: Annotated[
-            str,
+            Literal["v4", "v7"],
             Doc(
                 """
                 The version of UUID to generate on startup if `generate_startup_uuid` is True.
@@ -642,15 +642,15 @@ def _resolve_url(self, url: str) -> str:
     def _add_route(
         self,
         *,
-        method: Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+        method: HTTPMethod,
         url: str,
-        params: dict | None = None,
-        json: dict | None = None,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
         data: object | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -717,7 +717,7 @@ def include_router(
             ),
         ] = None,
         dependencies: Annotated[
-            list | None,
+            list[Any] | None,
             Doc(
                 """
                 Optional dependencies prepended before router dependencies.
@@ -778,11 +778,11 @@ def get(
         self,
         url: str,
         *,
-        params: dict | None = None,
+        params: dict[str, Any] | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -804,12 +804,12 @@ def post(
         self,
         url: str,
         *,
-        json: dict | None = None,
+        json: dict[str, Any] | None = None,
         data: object | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -832,12 +832,12 @@ def put(
         self,
         url: str,
         *,
-        json: dict | None = None,
+        json: dict[str, Any] | None = None,
         data: object | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -860,12 +860,12 @@ def patch(
         self,
         url: str,
         *,
-        json: dict | None = None,
+        json: dict[str, Any] | None = None,
         data: object | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -888,12 +888,12 @@ def delete(
         self,
         url: str,
         *,
-        json: dict | None = None,
+        json: dict[str, Any] | None = None,
         data: object | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -916,11 +916,11 @@ def head(
         self,
         url: str,
         *,
-        params: dict | None = None,
+        params: dict[str, Any] | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
@@ -942,11 +942,11 @@ def options(
         self,
         url: str,
         *,
-        params: dict | None = None,
+        params: dict[str, Any] | None = None,
         response_model: type | None = None,
         request_model: type[BaseModel] | None = None,
         tags: list[str] | None = None,
-        dependencies: list | None = None,
+        dependencies: list[Any] | None = None,
         raise_for_status: bool = False,
         auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
         responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,

fasthttp/auth.py

@@ -8,6 +8,8 @@
 if TYPE_CHECKING:
     from collections.abc import Generator
 
+    from .types import OAuth2Scope
+
 
 class BasicAuth:
     """HTTP Basic authentication (username + password)."""
@@ -53,7 +55,7 @@ def __init__(
         token_url: str,
         client_id: str,
         client_secret: str,
-        scopes: list[str] | None = None,
+        scopes: list[OAuth2Scope] | None = None,
         extra: dict[str, str] | None = None,
     ) -> None:
         self.token_url = token_url

fasthttp/client.py

@@ -44,7 +44,7 @@ class HTTPClient:
     def __init__(
         self,
         request_configs: Annotated[
-            dict,
+            dict[str, dict[str, Any]],
             Doc(
                 """
                 Dictionary mapping HTTP methods to default request configurations.

fasthttp/exceptions/base.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 import logging
-from typing import Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
 from annotated_doc import Doc
 
+if TYPE_CHECKING:
+    from fasthttp.types import HTTPMethod
+
 logger = logging.getLogger("fasthttp.exceptions")
 
 
@@ -48,7 +51,7 @@ def __init__(
         ) = None,
         method: (
             Annotated[
-                str,
+                HTTPMethod,
                 Doc(
                     """
                 HTTP method of the failed request.

fasthttp/middleware/base.py

@@ -9,7 +9,7 @@
 
     from fasthttp.response import Response
     from fasthttp.routing import Route
-    from fasthttp.types import RequestsOptinal
+    from fasthttp.types import RequestsOptional
 
 
 class BaseMiddleware:
@@ -110,7 +110,7 @@ async def on_error(
             Doc("The route that failed."),
         ],
         config: Annotated[
-            RequestsOptinal,
+            RequestsOptional,
             Doc("Request configuration that was used."),
         ],
     ) -> Annotated[
@@ -199,7 +199,7 @@ async def process_before_request(
             Doc("The route being executed."),
         ],
         config: Annotated[
-            RequestsOptinal,
+            RequestsOptional,
             Doc("Initial request configuration."),
         ],
     ) -> Annotated[
@@ -226,7 +226,7 @@ async def process_after_response(
             Doc("The route that was executed."),
         ],
         config: Annotated[  # noqa: ARG002
-            RequestsOptinal,
+            RequestsOptional,
             Doc("Request configuration that was used."),
         ],
     ) -> Annotated[
@@ -250,7 +250,7 @@ async def process_on_error(
             Doc("The route that failed."),
         ],
         config: Annotated[
-            RequestsOptinal,
+            RequestsOptional,
             Doc("Request configuration that was used."),
         ],
     ) -> Annotated[

fasthttp/middleware/cache.py

@@ -22,7 +22,7 @@
 if TYPE_CHECKING:
     from fasthttp.response import Response
     from fasthttp.routing import Route
-    from fasthttp.types import RequestsOptinal
+    from fasthttp.types import RequestsOptional
 
 
 class CacheEntry:
@@ -136,7 +136,7 @@ async def on_error(
         self,
         error: Exception,  # noqa: ARG002
         route: Route,  # noqa: ARG002
-        config: RequestsOptinal,  # noqa: ARG002
+        config: RequestsOptional,  # noqa: ARG002
     ) -> None:
         key, _ = self._state.get()
         if key is not None: