panther 3.9.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

panther/app.py

@@ -1,32 +1,34 @@
 import functools
-from collections.abc import Callable
-from datetime import datetime, timedelta
 import logging
+from datetime import timedelta
 from typing import Literal
 
 from orjson import JSONDecodeError
-from pydantic import ValidationError
+from pydantic import ValidationError, BaseModel
 
-from panther import status
 from panther._utils import is_function_async
-from panther.caching import cache_key, get_cached_response_data, set_cache_response
+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 (
-    APIException,
-    AuthorizationException,
-    InvalidPathVariableException,
-    JsonDecodeException,
-    MethodNotAllowed,
-    ThrottlingException,
+    APIError,
+    AuthorizationAPIError,
+    JSONDecodeAPIError,
+    MethodNotAllowedAPIError,
+    ThrottlingAPIError,
+    BadRequestAPIError
 )
 from panther.request import Request
 from panther.response import Response
-from panther.throttling import Throttling, throttling_storage
-from panther.utils import round_datetime
+from panther.serializer import ModelSerializer
+from panther.throttling import Throttling
 
 __all__ = ('API', 'GenericAPI')
 
-
 logger = logging.getLogger('panther')
 
 
@@ -34,11 +36,11 @@ class API:
     def __init__(
             self,
             *,
-            input_model=None,
-            output_model=None,
+            input_model: type[ModelSerializer] | type[BaseModel] | None = None,
+            output_model: type[ModelSerializer] | type[BaseModel] | None = None,
             auth: bool = False,
             permissions: list | None = None,
-            throttling: Throttling = None,
+            throttling: Throttling | None = None,
             cache: bool = False,
             cache_exp_time: timedelta | int | None = None,
             methods: list[Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']] | None = None,
@@ -55,21 +57,21 @@ class API:
 
     def __call__(self, func):
         @functools.wraps(func)
-        async def wrapper(request: Request, **path_variables) -> Response:
-            self.request: Request = request  # noqa: Non-self attribute could not be type hinted
+        async def wrapper(request: Request) -> Response:
+            self.request = request
 
             # 1. Check Method
             if self.methods and self.request.method not in self.methods:
-                raise MethodNotAllowed
+                raise MethodNotAllowedAPIError
 
             # 2. Authentication
-            self.handle_authentications()
+            await self.handle_authentication()
 
-            # 3. Throttling
-            self.handle_throttling()
+            # 3. Permissions
+            await self.handle_permission()
 
-            # 4. Permissions
-            self.handle_permissions()
+            # 4. Throttling
+            await self.handle_throttling()
 
             # 5. Validate Input
             if self.request.method in ['POST', 'PUT', 'PATCH']:
@@ -77,37 +79,33 @@ class API:
 
             # 6. Get Cached Response
             if self.cache and self.request.method == 'GET':
-                if cached := get_cached_response_data(request=self.request,  cache_exp_time=self.cache_exp_time):
+                if cached := await get_response_from_cache(request=self.request, cache_exp_time=self.cache_exp_time):
                     return Response(data=cached.data, status_code=cached.status_code)
 
-            # 7. Clean Path Variables
-            self.clean_path_variables(func, path_variables)
-
-            # 8. Put Request In kwargs (If User Wants It)
-            kwargs = {}
-            if req_arg := [k for k, v in func.__annotations__.items() if v == Request]:
-                kwargs[req_arg[0]] = self.request
+            # 7. Put PathVariables and Request(If User Wants It) In kwargs
+            kwargs = self.request.clean_parameters(func)
 
-            # 9. Call Endpoint
+            # 8. Call Endpoint
             if is_function_async(func):
-                response = await func(**kwargs, **path_variables)
+                response = await func(**kwargs)
             else:
-                response = func(**kwargs, **path_variables)
+                response = func(**kwargs)
 
-            # 10. Clean Response
+            # 9. Clean Response
             if not isinstance(response, Response):
                 response = Response(data=response)
-            response._clean_data_with_output_model(output_model=self.output_model)  # noqa: SLF001
+            if self.output_model and response.data:
+                response.data = response.apply_output_model(response.data, output_model=self.output_model)
 
-            # 11. Set New Response To Cache
+            # 10. Set New Response To Cache
             if self.cache and self.request.method == 'GET':
-                set_cache_response(
+                await set_response_in_cache(
                     request=self.request,
                     response=response,
                     cache_exp_time=self.cache_exp_time
                 )
 
-            # 12. Warning CacheExpTime
+            # 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')
 
@@ -115,70 +113,51 @@ class API:
 
         return wrapper
 
-    def handle_authentications(self) -> None:
-        auth_class = config['authentication']
+    async def handle_authentication(self) -> None:
         if self.auth:
-            if not auth_class:
+            if not config.AUTHENTICATION:
                 logger.critical('"AUTHENTICATION" has not been set in configs')
-                raise APIException
-            user = auth_class.authentication(self.request)
-            self.request.set_user(user=user)
+                raise APIError
+            self.request.user = await config.AUTHENTICATION.authentication(self.request)
 
-    def handle_throttling(self) -> None:
-        if throttling := self.throttling or config['throttling']:
-            key = cache_key(self.request)
-            time = round_datetime(datetime.now(), throttling.duration)
-            throttling_key = f'{time}-{key}'
-            if throttling_storage[throttling_key] > throttling.rate:
-                raise ThrottlingException
+    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
 
-            throttling_storage[throttling_key] += 1
+            await increment_throttling_in_cache(self.request, duration=throttling.duration)
 
-    def handle_permissions(self) -> None:
+    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"')
-                continue
-            if perm.authorization(request=self.request) is False:
-                raise AuthorizationException
+                raise AuthorizationAPIError
+            if await perm.authorization(self.request) is False:
+                raise AuthorizationAPIError
 
     def handle_input_validation(self):
         if self.input_model:
-            validated_data = self.validate_input(model=self.input_model, request=self.request)
-            self.request.set_validated_data(validated_data)
+            self.request.validated_data = self.validate_input(model=self.input_model, request=self.request)
 
     @classmethod
     def validate_input(cls, model, request: Request):
+        if isinstance(request.data, bytes):
+            raise BadRequestAPIError(detail='Content-Type is not valid')
+        if request.data is None:
+            raise BadRequestAPIError(detail='Request body is required')
         try:
-            if isinstance(request.data, bytes):
-                raise APIException(detail='Content-Type is not valid', status_code=status.HTTP_400_BAD_REQUEST)
-            return model(**request.data)
+            # `request` will be ignored in regular `BaseModel`
+            return model(**request.data, request=request)
         except ValidationError as validation_error:
             error = {'.'.join(loc for loc in e['loc']): e['msg'] for e in validation_error.errors()}
-            raise APIException(detail=error, status_code=status.HTTP_400_BAD_REQUEST)
+            raise BadRequestAPIError(detail=error)
         except JSONDecodeError:
-            raise JsonDecodeException
-
-    @staticmethod
-    def clean_path_variables(func: Callable, request_path_variables: dict):
-        for name, value in request_path_variables.items():
-            for variable_name, variable_type in func.__annotations__.items():
-                if name == variable_name:
-                    # Check the type and convert the value
-                    if variable_type is bool:
-                        request_path_variables[name] = value.lower() not in ['false', '0']
-
-                    elif variable_type is int:
-                        try:
-                            request_path_variables[name] = int(value)
-                        except ValueError:
-                            raise InvalidPathVariableException(value=value, variable_type=variable_type)
-                    break
+            raise JSONDecodeAPIError
 
 
 class GenericAPI:
-    input_model = None
-    output_model = None
+    input_model: type[ModelSerializer] | type[BaseModel] = None
+    output_model: type[ModelSerializer] | type[BaseModel] = None
     auth: bool = False
     permissions: list | None = None
     throttling: Throttling | None = None
@@ -186,40 +165,41 @@ class GenericAPI:
     cache_exp_time: timedelta | int | None = None
 
     async def get(self, *args, **kwargs):
-        raise MethodNotAllowed
+        raise MethodNotAllowedAPIError
 
     async def post(self, *args, **kwargs):
-        raise MethodNotAllowed
+        raise MethodNotAllowedAPIError
 
     async def put(self, *args, **kwargs):
-        raise MethodNotAllowed
+        raise MethodNotAllowedAPIError
 
     async def patch(self, *args, **kwargs):
-        raise MethodNotAllowed
+        raise MethodNotAllowedAPIError
 
     async def delete(self, *args, **kwargs):
-        raise MethodNotAllowed
+        raise MethodNotAllowedAPIError
 
-    @classmethod
-    async def call_method(cls, *args, **kwargs):
-        match kwargs['request'].method:
+    async def call_method(self, request: Request):
+        match request.method:
             case 'GET':
-                func = cls().get
+                func = self.get
             case 'POST':
-                func = cls().post
+                func = self.post
             case 'PUT':
-                func = cls().put
+                func = self.put
             case 'PATCH':
-                func = cls().patch
+                func = self.patch
             case 'DELETE':
-                func = cls().delete
+                func = self.delete
+            case _:
+                raise MethodNotAllowedAPIError
 
         return await API(
-            input_model=cls.input_model,
-            output_model=cls.output_model,
-            auth=cls.auth,
-            permissions=cls.permissions,
-            throttling=cls.throttling,
-            cache=cls.cache,
-            cache_exp_time=cls.cache_exp_time,
-        )(func)(*args, **kwargs)
+            input_model=self.input_model,
+            output_model=self.output_model,
+            auth=self.auth,
+            permissions=self.permissions,
+            throttling=self.throttling,
+            cache=self.cache,
+            cache_exp_time=self.cache_exp_time,
+        )(func)(request=request)

panther/authentications.py

@@ -1,18 +1,22 @@
 import logging
 import time
 from abc import abstractmethod
+from datetime import timezone, datetime
 from typing import Literal
 
+from panther.base_websocket import Websocket
 from panther.cli.utils import import_error
 from panther.configs import config
+from panther.db.connections import redis
 from panther.db.models import BaseUser, Model
-from panther.exceptions import AuthenticationException
+from panther.exceptions import AuthenticationAPIError
 from panther.request import Request
+from panther.utils import generate_hash_value_from_string
 
 try:
     from jose import JWTError, jwt
 except ModuleNotFoundError as e:
-    import_error(e, package='python-jose')
+    raise import_error(e, package='python-jose')
 
 logger = logging.getLogger('panther')
 
@@ -20,67 +24,79 @@ logger = logging.getLogger('panther')
 class BaseAuthentication:
     @classmethod
     @abstractmethod
-    def authentication(cls, request: Request):
+    async def authentication(cls, request: Request | Websocket):
         """Return Instance of User"""
         msg = f'{cls.__name__}.authentication() is not implemented.'
         raise cls.exception(msg) from None
 
     @staticmethod
-    def exception(message: str, /) -> type[AuthenticationException]:
+    def exception(message: str, /) -> type[AuthenticationAPIError]:
         logger.error(f'Authentication Error: "{message}"')
-        return AuthenticationException
+        return AuthenticationAPIError
 
 
 class JWTAuthentication(BaseAuthentication):
     model = BaseUser
     keyword = 'Bearer'
     algorithm = 'HS256'
-    HTTP_HEADER_ENCODING = 'iso-8859-1'  # Header encoding (see RFC5987)
+    HTTP_HEADER_ENCODING = 'iso-8859-1'  # RFC5987
 
     @classmethod
-    def get_authorization_header(cls, request: Request) -> bytes:
-        auth = request.headers.authorization
+    def get_authorization_header(cls, request: Request | Websocket) -> str:
+        if auth := request.headers.authorization:
+            return auth
+        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()
 
-        if auth is None:
-            msg = 'Authorization is required'
+        if len(auth_header) != 2:
+            msg = 'Authorization should have 2 part'
             raise cls.exception(msg) from None
 
-        if isinstance(auth, str):
-            try:
-                auth = auth.encode(JWTAuthentication.HTTP_HEADER_ENCODING)
-            except UnicodeEncodeError as e:
-                raise cls.exception(e) from None
+        bearer, token = auth_header
 
-        return auth
+        try:
+            token.encode(JWTAuthentication.HTTP_HEADER_ENCODING)
+        except UnicodeEncodeError as e:
+            raise cls.exception(e) from None
 
-    @classmethod
-    def authentication(cls, request: Request) -> Model:
-        auth = cls.get_authorization_header(request).split()
-        if not auth or auth[0].lower() != cls.keyword.lower().encode():
+        if bearer.lower() != cls.keyword.lower():
             msg = 'Authorization keyword is not valid'
             raise cls.exception(msg) from None
-        if len(auth) != 2:
-            msg = 'Authorization should have 2 part'
-            raise cls.exception(msg) from None
 
-        try:
-            token = auth[1].decode()
-        except UnicodeError:
-            msg = 'Unicode Error'
+        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)
-        return cls.get_user(payload)
+        user = await cls.get_user(payload)
+        user._auth_token = token
+        return user
 
     @classmethod
-    def get_user(cls, payload: dict) -> Model:
+    def decode_jwt(cls, token: str) -> dict:
+        """Decode JWT token to user_id (it can return multiple variable ... )"""
+        try:
+            return jwt.decode(
+                token=token,
+                key=config.JWT_CONFIG.key,
+                algorithms=[config.JWT_CONFIG.algorithm],
+            )
+        except JWTError as e:
+            raise cls.exception(e) from None
+
+    @classmethod
+    async def get_user(cls, payload: dict) -> Model:
         """Get UserModel from config, else use default UserModel from cls.model"""
         if (user_id := payload.get('user_id')) is None:
-            msg = 'Payload does not have user_id'
+            msg = 'Payload does not have `user_id`'
             raise cls.exception(msg)
 
-        user_model = config['user_model'] or cls.model
-        if user := user_model.find_one(id=user_id):
+        user_model = config.USER_MODEL or cls.model
+        if user := await user_model.find_one(id=user_id):
             return user
 
         msg = 'User not found'
@@ -89,11 +105,11 @@ class JWTAuthentication(BaseAuthentication):
     @classmethod
     def encode_jwt(cls, user_id: str, token_type: Literal['access', 'refresh'] = 'access') -> str:
         """Encode JWT from user_id."""
-        issued_at = time.time()
+        issued_at = datetime.now(timezone.utc).timestamp()
         if token_type == 'access':
-            expire = issued_at + config['jwt_config'].life_time
+            expire = issued_at + config.JWT_CONFIG.life_time
         else:
-            expire = issued_at + config['jwt_config'].refresh_life_time
+            expire = issued_at + config.JWT_CONFIG.refresh_life_time
 
         claims = {
             'token_type': token_type,
@@ -103,33 +119,48 @@ class JWTAuthentication(BaseAuthentication):
         }
         return jwt.encode(
             claims,
-            key=config['jwt_config'].key,
-            algorithm=config['jwt_config'].algorithm,
+            key=config.JWT_CONFIG.key,
+            algorithm=config.JWT_CONFIG.algorithm,
         )
 
     @classmethod
-    def encode_refresh_token(cls, user_id: str) -> str:
-        """Encode JWT from user_id."""
-        return cls.encode_jwt(user_id=user_id, token_type='refresh')
+    def login(cls, user_id: str) -> dict:
+        """Return dict of access and refresh token"""
+        return {
+            'access_token': cls.encode_jwt(user_id=user_id),
+            'refresh_token': cls.encode_jwt(user_id=user_id, token_type='refresh')
+        }
 
     @classmethod
-    def decode_jwt(cls, token: str) -> dict:
-        """Decode JWT token to user_id (it can return multiple variable ... )"""
-        try:
-            return jwt.decode(
-                token=token,
-                key=config['jwt_config'].key,
-                algorithms=[config['jwt_config'].algorithm],
-            )
-        except JWTError as e:
-            raise cls.exception(e) from None
+    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))
+        else:
+            logger.error('`redis` middleware is required for `logout()`')
+
+    @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)
 
     @classmethod
-    def login(cls, user_id: str) -> str:
-        """Alias of encode_jwt()"""
-        return cls.encode_jwt(user_id=user_id)
+    async def _check_in_cache(cls, token: str) -> bool:
+        key = generate_hash_value_from_string(token)
+        return bool(await redis.exists(key))
 
     @staticmethod
-    def exception(message: str | JWTError | UnicodeEncodeError, /) -> type[AuthenticationException]:
+    def exception(message: str | JWTError | UnicodeEncodeError, /) -> type[AuthenticationAPIError]:
         logger.error(f'JWT Authentication Error: "{message}"')
-        return AuthenticationException
+        return AuthenticationAPIError
+
+
+class QueryParamJWTAuthentication(JWTAuthentication):
+    @classmethod
+    def get_authorization_header(cls, request: Request | Websocket) -> str:
+        if auth := request.query_params.get('authorization'):
+            return auth
+        msg = 'Authorization is required'
+        raise cls.exception(msg) from None

panther/background_tasks.py

@@ -9,7 +9,6 @@ from typing import Callable, Literal
 from panther._utils import is_function_async
 from panther.utils import Singleton
 
-
 __all__ = (
     'BackgroundTask',
     'background_tasks',
@@ -40,6 +39,7 @@ class BackgroundTask:
         self._last_run: datetime.datetime | None = None
         self._timedelta: datetime.timedelta = datetime.timedelta(minutes=1)
         self._time: datetime.time | None = None
+        self._day_of_week: int | None = None
         self._unit: Literal['seconds', 'minutes', 'hours', 'days', 'weeks'] | None = None
 
     def interval(self, interval: int, /) -> Self:
@@ -89,18 +89,24 @@ class BackgroundTask:
         self._timedelta = datetime.timedelta(weeks=weeks)
         return self
 
-    # TODO: Coming Soon
-    # def on(
-    #         self,
-    #         day_of_week: Literal['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
-    #         /
-    # ) -> Self:
-    #     """
-    #     Set day to schedule the task, useful on `.every_weeks()`
-    #     """
-    #     if self._unit != 'weeks':
-    #         logger.warning('`.on()` only useful when you are using `.every_weeks()`')
-    #     return self
+    def on(
+            self,
+            day_of_week: Literal['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
+            /
+    ) -> Self:
+        """
+        Set day to schedule the task, useful on `.every_weeks()`
+        """
+        week_days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']
+        if day_of_week not in week_days:
+            msg = f'Argument should be one of {week_days}'
+            raise TypeError(msg)
+
+        self._day_of_week = week_days.index(day_of_week)
+
+        if self._unit != 'weeks':
+            logger.warning('`.on()` only useful when you are using `.every_weeks()`')
+        return self
 
     def at(self, _time: datetime.time, /) -> Self:
         """
@@ -133,6 +139,11 @@ class BackgroundTask:
         if self._last_run and (self._last_run + self._timedelta) > now:
             return True
 
+        # Check day of week
+        if self._day_of_week is not None:
+            if self._day_of_week != now.weekday():
+                return True
+
         # We don't have time condition, so run
         if self._time is None:
             self._last_run = now
@@ -188,7 +199,7 @@ class BackgroundTasks(Singleton):
 
     def add_task(self, task: BackgroundTask):
         if self._initialized is False:
-            logger.error('Task will be ignored, `BACKGROUND_TASKS` is not True in `core/configs.py`')
+            logger.error('Task will be ignored, `BACKGROUND_TASKS` is not True in `configs`')
             return
 
         if not self._is_instance_of_task(task):