panther 5.0.0b3__py3-none-any.whl → 5.0.0b5__py3-none-any.whl

panther/app.py

@@ -2,36 +2,35 @@ import functools
 import logging
 import traceback
 import typing
+from collections.abc import Callable
 from datetime import timedelta
-from typing import Literal, Callable
+from typing import Literal
 
 from orjson import JSONDecodeError
-from pydantic import ValidationError, BaseModel
+from pydantic import BaseModel, ValidationError
 
 from panther._utils import is_function_async
+from panther.base_request import BaseRequest
 from panther.caching import (
     get_response_from_cache,
     set_response_in_cache,
-    get_throttling_from_cache,
-    increment_throttling_in_cache
 )
 from panther.configs import config
 from panther.exceptions import (
     APIError,
     AuthorizationAPIError,
+    BadRequestAPIError,
     JSONDecodeAPIError,
     MethodNotAllowedAPIError,
-    ThrottlingAPIError,
-    BadRequestAPIError
+    PantherError,
 )
-from panther.exceptions import PantherError
 from panther.middlewares import HTTPMiddleware
 from panther.openapi import OutputSchema
 from panther.permissions import BasePermission
 from panther.request import Request
 from panther.response import Response
 from panther.serializer import ModelSerializer
-from panther.throttling import Throttling
+from panther.throttling import Throttle
 
 __all__ = ('API', 'GenericAPI')
 
@@ -40,19 +39,20 @@ logger = logging.getLogger('panther')
 
 class API:
     """
+    methods: Specify the allowed methods.
     input_model: The `request.data` will be validated with this attribute, It will raise an
         `panther.exceptions.BadRequestAPIError` or put the validated data in the `request.validated_data`.
+    output_model: The `response.data` will be passed through this class to filter its attributes.
     output_schema: This attribute only used in creation of OpenAPI scheme which is available in `panther.openapi.urls`
         You may want to add its `url` to your urls.
     auth: It will authenticate the user with header of its request or raise an
         `panther.exceptions.AuthenticationAPIError`.
     permissions: List of permissions that will be called sequentially after authentication to authorize the user.
-    throttling: It will limit the users' request on a specific (time-bucket, path)
-    cache: Response of the request will be cached.
-    cache_exp_time: Specify the expiry time of the cache. (default is `config.DEFAULT_CACHE_EXP`)
-    methods: Specify the allowed methods.
+    throttling: It will limit the users' request on a specific (time-window, path)
+    cache: Specify the duration of the cache (Will be used only in GET requests).
     middlewares: These middlewares have inner priority than global middlewares.
     """
+
     func: Callable
 
     def __init__(
@@ -60,36 +60,62 @@ class API:
         *,
         methods: list[Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']] | None = None,
         input_model: type[ModelSerializer] | type[BaseModel] | None = None,
-        output_model: type[BaseModel] | None = None,
+        output_model: type[ModelSerializer] | type[BaseModel] | None = None,
         output_schema: OutputSchema | None = None,
         auth: bool = False,
-        permissions: list[BasePermission] | None = None,
-        throttling: Throttling | None = None,
-        cache: bool = False,
-        cache_exp_time: timedelta | int | None = None,
-        middlewares: list[HTTPMiddleware] | None = None,
+        permissions: list[type[BasePermission]] | None = None,
+        throttling: Throttle | None = None,
+        cache: timedelta | None = None,
+        middlewares: list[type[HTTPMiddleware]] | None = None,
+        **kwargs,
     ):
-        self.methods = {m.upper() for m in methods} if methods else None
+        self.methods = {m.upper() for m in methods} if methods else {'GET', 'POST', 'PUT', 'PATCH', 'DELETE'}
         self.input_model = input_model
+        self.output_model = output_model
         self.output_schema = output_schema
         self.auth = auth
         self.permissions = permissions or []
         self.throttling = throttling
         self.cache = cache
-        self.cache_exp_time = cache_exp_time
-        self.middlewares: list[HTTPMiddleware] | None = middlewares
+        self.middlewares = middlewares
         self.request: Request | None = None
-        if output_model:
+        if kwargs.pop('cache_exp_time', None):
+            deprecation_message = (
+                traceback.format_stack(limit=2)[0]
+                + '\nThe `cache_exp_time` argument has been removed in Panther v5 and is no longer available.'
+                '\nYou may want to use `cache` instead.'
+            )
+            raise PantherError(deprecation_message)
+        # Validate Cache
+        if self.cache and not isinstance(self.cache, timedelta):
             deprecation_message = (
-                    traceback.format_stack(limit=2)[0] +
-                    '\nThe `output_model` argument has been removed in Panther v5 and is no longer available.'
-                    '\nPlease update your code to use the new approach. More info: '
-                    'https://pantherpy.github.io/open_api/'
+                traceback.format_stack(limit=2)[0] + '\nThe `cache` argument has been changed in Panther v5, '
+                'it should be an instance of `datetime.timedelta()`.'
             )
             raise PantherError(deprecation_message)
+        assert self.cache is None or isinstance(self.cache, timedelta)
+        # Validate Permissions
+        for perm in self.permissions:
+            if is_function_async(perm.authorization) is False:
+                msg = f'{perm.__name__}.authorization() should be `async`'
+                logger.error(msg)
+                raise PantherError(msg)
+            if type(perm.authorization).__name__ != 'method':
+                msg = f'{perm.__name__}.authorization() should be `@classmethod`'
+                logger.error(msg)
+                raise PantherError(msg)
+        # Check kwargs
+        if kwargs:
+            msg = f'Unknown kwargs: {kwargs.keys()}'
+            logger.error(msg)
+            raise PantherError(msg)
 
     def __call__(self, func):
         self.func = func
+        self.is_function_async = is_function_async(self.func)
+        self.function_annotations = {
+            k: v for k, v in func.__annotations__.items() if v in {BaseRequest, Request, bool, int}
+        }
 
         @functools.wraps(func)
         async def wrapper(request: Request) -> Response:
@@ -110,37 +136,40 @@ class API:
     async def handle_endpoint(self, request: Request) -> Response:
         self.request = request
 
-        # 0. Preflight
-        if self.request.method == 'OPTIONS':
-            return self.options()
-
         # 1. Check Method
-        if self.methods and self.request.method not in self.methods:
+        if self.request.method not in self.methods:
             raise MethodNotAllowedAPIError
 
         # 2. Authentication
-        await self.handle_authentication()
+        if self.auth:
+            if not config.AUTHENTICATION:
+                logger.critical('"AUTHENTICATION" has not been set in configs')
+                raise APIError
+            self.request.user = await config.AUTHENTICATION.authentication(self.request)
 
         # 3. Permissions
-        await self.handle_permission()
+        for perm in self.permissions:
+            if await perm.authorization(self.request) is False:
+                raise AuthorizationAPIError
 
-        # 4. Throttling
-        await self.handle_throttling()
+        # 4. Throttle
+        if throttling := self.throttling or config.THROTTLING:
+            await throttling.check_and_increment(request=self.request)
 
         # 5. Validate Input
-        if self.request.method in {'POST', 'PUT', 'PATCH'}:
-            self.handle_input_validation()
+        if self.input_model and self.request.method in {'POST', 'PUT', 'PATCH'}:
+            self.request.validated_data = self.validate_input(model=self.input_model, request=self.request)
 
         # 6. Get Cached Response
         if self.cache and self.request.method == 'GET':
-            if cached := await get_response_from_cache(request=self.request, cache_exp_time=self.cache_exp_time):
+            if cached := await get_response_from_cache(request=self.request, duration=self.cache):
                 return Response(data=cached.data, headers=cached.headers, status_code=cached.status_code)
 
         # 7. Put PathVariables and Request(If User Wants It) In kwargs
-        kwargs = self.request.clean_parameters(self.func)
+        kwargs = self.request.clean_parameters(self.function_annotations)
 
         # 8. Call Endpoint
-        if is_function_async(self.func):
+        if self.is_function_async:
             response = await self.func(**kwargs)
         else:
             response = self.func(**kwargs)
@@ -148,53 +177,17 @@ class API:
         # 9. Clean Response
         if not isinstance(response, Response):
             response = Response(data=response)
+        if self.output_model and response.data:
+            response.data = await response.serialize_output(output_model=self.output_model)
         if response.pagination:
             response.data = await response.pagination.template(response.data)
 
         # 10. Set New Response To Cache
         if self.cache and self.request.method == 'GET':
-            await set_response_in_cache(request=self.request, response=response, cache_exp_time=self.cache_exp_time)
-
-        # 11. Warning CacheExpTime
-        if self.cache_exp_time and self.cache is False:
-            logger.warning('"cache_exp_time" won\'t work while "cache" is False')
+            await set_response_in_cache(request=self.request, response=response, duration=self.cache)
 
         return response
 
-    async def handle_authentication(self) -> None:
-        if self.auth:
-            if not config.AUTHENTICATION:
-                logger.critical('"AUTHENTICATION" has not been set in configs')
-                raise APIError
-            self.request.user = await config.AUTHENTICATION.authentication(self.request)
-
-    async def handle_throttling(self) -> None:
-        if throttling := self.throttling or config.THROTTLING:
-            if await get_throttling_from_cache(self.request, duration=throttling.duration) + 1 > throttling.rate:
-                raise ThrottlingAPIError
-
-            await increment_throttling_in_cache(self.request, duration=throttling.duration)
-
-    async def handle_permission(self) -> None:
-        for perm in self.permissions:
-            if type(perm.authorization).__name__ != 'method':
-                logger.error(f'{perm.__name__}.authorization should be "classmethod"')
-                raise AuthorizationAPIError
-            if await perm.authorization(self.request) is False:
-                raise AuthorizationAPIError
-
-    def handle_input_validation(self):
-        if self.input_model:
-            self.request.validated_data = self.validate_input(model=self.input_model, request=self.request)
-
-    @classmethod
-    def options(cls):
-        headers = {
-            'Access-Control-Allow-Methods': 'DELETE, GET, PATCH, POST, PUT, OPTIONS, HEAD',
-            'Access-Control-Allow-Headers': 'Accept, Authorization, User-Agent, Content-Type',
-        }
-        return Response(headers=headers)
-
     @classmethod
     def validate_input(cls, model, request: Request):
         if isinstance(request.data, bytes):
@@ -212,21 +205,15 @@ class API:
 
 
 class MetaGenericAPI(type):
-    def __new__(
-            cls,
-            cls_name: str,
-            bases: tuple[type[typing.Any], ...],
-            namespace: dict[str, typing.Any],
-            **kwargs
-    ):
+    def __new__(cls, cls_name: str, bases: tuple[type[typing.Any], ...], namespace: dict[str, typing.Any], **kwargs):
         if cls_name == 'GenericAPI':
             return super().__new__(cls, cls_name, bases, namespace)
         if 'output_model' in namespace:
             deprecation_message = (
-                    traceback.format_stack(limit=2)[0] +
-                    '\nThe `output_model` argument has been removed in Panther v5 and is no longer available.'
-                    '\nPlease update your code to use the new approach. More info: '
-                    'https://pantherpy.github.io/open_api/'
+                traceback.format_stack(limit=2)[0]
+                + '\nThe `output_model` argument has been removed in Panther v5 and is no longer available.'
+                '\nPlease update your code to use the new approach. More info: '
+                'https://pantherpy.github.io/open_api/'
             )
             raise PantherError(deprecation_message)
         return super().__new__(cls, cls_name, bases, namespace)
@@ -236,15 +223,29 @@ class GenericAPI(metaclass=MetaGenericAPI):
     """
     Check out the documentation of `panther.app.API()`.
     """
+
     input_model: type[ModelSerializer] | type[BaseModel] | None = None
+    output_model: type[ModelSerializer] | type[BaseModel] | None = None
     output_schema: OutputSchema | None = None
     auth: bool = False
-    permissions: list | None = None
-    throttling: Throttling | None = None
-    cache: bool = False
-    cache_exp_time: timedelta | int | None = None
+    permissions: list[type[BasePermission]] | None = None
+    throttling: Throttle | None = None
+    cache: timedelta | None = None
     middlewares: list[HTTPMiddleware] | None = None
 
+    def __init_subclass__(cls, **kwargs):
+        # Creating API instance to validate the attributes.
+        API(
+            input_model=cls.input_model,
+            output_model=cls.output_model,
+            output_schema=cls.output_schema,
+            auth=cls.auth,
+            permissions=cls.permissions,
+            throttling=cls.throttling,
+            cache=cls.cache,
+            middlewares=cls.middlewares,
+        )
+
     async def get(self, *args, **kwargs):
         raise MethodNotAllowedAPIError
 
@@ -272,18 +273,16 @@ class GenericAPI(metaclass=MetaGenericAPI):
                 func = self.patch
             case 'DELETE':
                 func = self.delete
-            case 'OPTIONS':
-                func = API.options
             case _:
                 raise MethodNotAllowedAPIError
 
         return await API(
             input_model=self.input_model,
+            output_model=self.output_model,
             output_schema=self.output_schema,
             auth=self.auth,
             permissions=self.permissions,
             throttling=self.throttling,
             cache=self.cache,
-            cache_exp_time=self.cache_exp_time,
             middlewares=self.middlewares,
         )(func)(request=request)

panther/authentications.py

@@ -1,7 +1,7 @@
 import logging
 import time
 from abc import abstractmethod
-from datetime import timezone, datetime
+from datetime import datetime, timezone
 from typing import Literal
 
 from panther.base_websocket import Websocket
@@ -36,24 +36,44 @@ class BaseAuthentication:
 
 
 class JWTAuthentication(BaseAuthentication):
-    model = BaseUser
+    """
+    Retrieve the Authorization from header
+    Example:
+        Headers: {'authorization': 'Bearer the_jwt_token'}
+    """
+
+    model = None
     keyword = 'Bearer'
     algorithm = 'HS256'
     HTTP_HEADER_ENCODING = 'iso-8859-1'  # RFC5987
 
     @classmethod
-    def get_authorization_header(cls, request: Request | Websocket) -> str:
+    def get_authorization_header(cls, request: Request | Websocket) -> list[str]:
+        """Retrieve the Authorization header from the request."""
         if auth := request.headers.authorization:
-            return auth
+            return auth.split()
         msg = 'Authorization is required'
         raise cls.exception(msg) from None
 
     @classmethod
     async def authentication(cls, request: Request | Websocket) -> Model:
-        auth_header = cls.get_authorization_header(request).split()
+        """Authenticate the user based on the JWT token in the Authorization header."""
+        auth_header = cls.get_authorization_header(request)
+        token = cls.get_token(auth_header=auth_header)
+
+        if redis.is_connected and await cls.is_token_revoked(token=token):
+            msg = 'User logged out'
+            raise cls.exception(msg) from None
 
+        payload = await cls.decode_jwt(token)
+        user = await cls.get_user(payload)
+        user._auth_token = token
+        return user
+
+    @classmethod
+    def get_token(cls, auth_header):
         if len(auth_header) != 2:
-            msg = 'Authorization should have 2 part'
+            msg = 'Authorization header must contain 2 parts'
             raise cls.exception(msg) from None
 
         bearer, token = auth_header
@@ -67,18 +87,11 @@ class JWTAuthentication(BaseAuthentication):
             msg = 'Authorization keyword is not valid'
             raise cls.exception(msg) from None
 
-        if redis.is_connected and await cls._check_in_cache(token=token):
-            msg = 'User logged out'
-            raise cls.exception(msg) from None
-
-        payload = cls.decode_jwt(token)
-        user = await cls.get_user(payload)
-        user._auth_token = token
-        return user
+        return token
 
     @classmethod
-    def decode_jwt(cls, token: str) -> dict:
-        """Decode JWT token to user_id (it can return multiple variable ... )"""
+    async def decode_jwt(cls, token: str) -> dict:
+        """Decode a JWT token and return the payload."""
         try:
             return jwt.decode(
                 token=token,
@@ -90,21 +103,21 @@ class JWTAuthentication(BaseAuthentication):
 
     @classmethod
     async def get_user(cls, payload: dict) -> Model:
-        """Get UserModel from config, else use default UserModel from cls.model"""
+        """Fetch the user based on the decoded JWT payload from cls.model or config.UserModel"""
         if (user_id := payload.get('user_id')) is None:
             msg = 'Payload does not have `user_id`'
             raise cls.exception(msg)
 
-        user_model = config.USER_MODEL or cls.model
-        if user := await user_model.find_one(id=user_id):
-            return user
+        user_model = cls.model or config.USER_MODEL
+        user = await user_model.find_one(id=user_id)
+        if user is None:
+            raise cls.exception('User not found')
 
-        msg = 'User not found'
-        raise cls.exception(msg) from None
+        return user
 
     @classmethod
     def encode_jwt(cls, user_id: str, token_type: Literal['access', 'refresh'] = 'access') -> str:
-        """Encode JWT from user_id."""
+        """Generate a JWT token for a given user ID."""
         issued_at = datetime.now(timezone.utc).timestamp()
         if token_type == 'access':
             expire = issued_at + config.JWT_CONFIG.life_time
@@ -124,44 +137,87 @@ class JWTAuthentication(BaseAuthentication):
         )
 
     @classmethod
-    def login(cls, user_id: str) -> dict:
-        """Return dict of access and refresh token"""
+    async def login(cls, user) -> dict:
+        """Generate access and refresh tokens for user login."""
         return {
-            'access_token': cls.encode_jwt(user_id=user_id),
-            'refresh_token': cls.encode_jwt(user_id=user_id, token_type='refresh')
+            'access_token': cls.encode_jwt(user_id=user.id),
+            'refresh_token': cls.encode_jwt(user_id=user.id, token_type='refresh'),
         }
 
     @classmethod
-    async def logout(cls, raw_token: str) -> None:
-        *_, token = raw_token.split()
-        if redis.is_connected:
-            payload = cls.decode_jwt(token=token)
-            remaining_exp_time = payload['exp'] - time.time()
-            await cls._set_in_cache(token=token, exp=int(remaining_exp_time))
+    async def logout(cls, user) -> None:
+        """Log out a user by revoking their JWT token."""
+        payload = await cls.decode_jwt(token=user._auth_token)
+        await cls.revoke_token_in_cache(token=user._auth_token, exp=payload['exp'])
+
+    @classmethod
+    async def refresh(cls, user):
+        if hasattr(user, '_auth_refresh_token'):
+            # It happens in CookieJWTAuthentication
+            token = user._auth_refresh_token
         else:
-            logger.error('`redis` middleware is required for `logout()`')
+            token = user._auth_token
+
+        payload = await cls.decode_jwt(token=token)
+
+        if payload['token_type'] != 'refresh':
+            raise cls.exception('Invalid token type; expected `refresh` token.')
+        # Revoke after use
+        await cls.revoke_token_in_cache(token=token, exp=payload['exp'])
+
+        return await cls.login(user=user)
 
     @classmethod
-    async def _set_in_cache(cls, token: str, exp: int) -> None:
-        key = generate_hash_value_from_string(token)
-        await redis.set(key, b'', ex=exp)
+    async def revoke_token_in_cache(cls, token: str, exp: int) -> None:
+        """Mark the token as revoked in the cache."""
+        if redis.is_connected:
+            key = generate_hash_value_from_string(token)
+            remaining_exp_time = int(exp - time.time())
+            await redis.set(key, b'', ex=remaining_exp_time)
+        else:
+            logger.error('Redis is not connected; token revocation is not effective.')
 
     @classmethod
-    async def _check_in_cache(cls, token: str) -> bool:
+    async def is_token_revoked(cls, token: str) -> bool:
+        """Check if the token is revoked by looking it up in the cache."""
         key = generate_hash_value_from_string(token)
         return bool(await redis.exists(key))
 
 
 class QueryParamJWTAuthentication(JWTAuthentication):
+    """
+    Retrieve the Authorization from query params
+    Example:
+        https://example.com?authorization=the_jwt_without_bearer
+    """
+
     @classmethod
-    def get_authorization_header(cls, request: Request | Websocket) -> str:
+    def get_authorization_header(cls, request: Request | Websocket) -> list[str]:
         if auth := request.query_params.get('authorization'):
             return auth
         msg = '`authorization` query param not found.'
         raise cls.exception(msg) from None
 
+    @classmethod
+    def get_token(cls, auth_header) -> str:
+        return auth_header
+
 
 class CookieJWTAuthentication(JWTAuthentication):
+    """
+    Retrieve the Authorization from cookies
+    Example:
+        Cookies: access_token=the_jwt_without_bearer
+    """
+
+    @classmethod
+    async def authentication(cls, request: Request | Websocket) -> Model:
+        user = await super().authentication(request=request)
+        if refresh_token := request.headers.get_cookies().get('refresh_token'):
+            # It's used in `cls.refresh()`
+            user._auth_refresh_token = refresh_token
+        return user
+
     @classmethod
     def get_authorization_header(cls, request: Request | Websocket) -> str:
         if token := request.headers.get_cookies().get('access_token'):
@@ -170,14 +226,5 @@ class CookieJWTAuthentication(JWTAuthentication):
         raise cls.exception(msg) from None
 
     @classmethod
-    async def authentication(cls, request: Request | Websocket) -> Model:
-        token = cls.get_authorization_header(request)
-
-        if redis.is_connected and await cls._check_in_cache(token=token):
-            msg = 'User logged out'
-            raise cls.exception(msg) from None
-
-        payload = cls.decode_jwt(token)
-        user = await cls.get_user(payload)
-        user._auth_token = token
-        return user
+    def get_token(cls, auth_header) -> str:
+        return auth_header