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

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

panther/background_tasks.py

@@ -1,23 +1,38 @@
+"""
+Example:
+-------------------------------------------------------------
+>>> import datetime
+
+
+>>> async def hello(name: str):
+>>>     print(f'Hello {name}')
+
+# Run it every 5 seconds for 2 times
+>>> BackgroundTask(hello, 'Ali').interval(2).every_seconds(5).submit()
+
+# Run it every day at 08:00 O'clock forever
+>>> BackgroundTask(hello, 'Saba').interval(-1).every_days().at(datetime.time(hour=8)).submit()
+"""
+
 import asyncio
 import datetime
 import logging
 import sys
 import time
-from threading import Thread
-from typing import Callable, Literal
+from enum import Enum
+from threading import Lock, Thread
+from typing import TYPE_CHECKING, Any, Literal
 
 from panther._utils import is_function_async
-from panther.utils import Singleton
+from panther.utils import Singleton, timezone_now
 
-__all__ = (
-    'BackgroundTask',
-    'background_tasks',
-)
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
+__all__ = ('BackgroundTask', 'WeekDay')
 
 logger = logging.getLogger('panther')
 
-
 if sys.version_info.minor >= 11:
     from typing import Self
 else:
@@ -26,123 +41,102 @@ else:
     Self = TypeVar('Self', bound='BackgroundTask')
 
 
+class WeekDay(Enum):
+    MONDAY = 0
+    TUESDAY = 1
+    WEDNESDAY = 2
+    THURSDAY = 3
+    FRIDAY = 4
+    SATURDAY = 5
+    SUNDAY = 6
+
+
 class BackgroundTask:
     """
-    Default: Task is going to run once,
-    and if you only specify a custom interval, default interval time is 1 minutes
+    Schedules and runs a function periodically in the background.
+
+    Default: Task runs once. If only a custom interval is specified, default interval time is 1 minute.
+    Use submit() to add the task to the background queue.
     """
-    def __init__(self, func, *args, **kwargs):
-        self._func: Callable = func
+
+    def __init__(self, func: 'Callable', *args: Any, **kwargs: Any):
+        self._func: 'Callable' = func
         self._args: tuple = args
         self._kwargs: dict = kwargs
         self._remaining_interval: int = 1
         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._day_of_week: WeekDay | None = None
         self._unit: Literal['seconds', 'minutes', 'hours', 'days', 'weeks'] | None = None
 
     def interval(self, interval: int, /) -> Self:
-        """
-        interval = -1 --> Infinite
-        """
+        """Set how many times to run the task. interval = -1 for infinite."""
         self._remaining_interval = interval
         return self
 
     def every_seconds(self, seconds: int = 1, /) -> Self:
-        """
-        Every How Many Seconds? (Default is 1)
-        """
+        """Run every N seconds (default 1)."""
         self._unit = 'seconds'
         self._timedelta = datetime.timedelta(seconds=seconds)
         return self
 
     def every_minutes(self, minutes: int = 1, /) -> Self:
-        """
-        Every How Many Minutes? (Default is 1)
-        """
+        """Run every N minutes (default 1)."""
         self._unit = 'minutes'
         self._timedelta = datetime.timedelta(minutes=minutes)
         return self
 
     def every_hours(self, hours: int = 1, /) -> Self:
-        """
-        Every How Many Hours? (Default is 1)
-        """
+        """Run every N hours (default 1)."""
         self._unit = 'hours'
         self._timedelta = datetime.timedelta(hours=hours)
         return self
 
     def every_days(self, days: int = 1, /) -> Self:
-        """
-        Every How Many Days? (Default is 1)
-        """
+        """Run every N days (default 1)."""
         self._unit = 'days'
         self._timedelta = datetime.timedelta(days=days)
         return self
 
     def every_weeks(self, weeks: int = 1, /) -> Self:
-        """
-        Every How Many Weeks? (Default is 1)
-        """
+        """Run every N weeks (default 1)."""
         self._unit = 'weeks'
         self._timedelta = datetime.timedelta(weeks=weeks)
         return self
 
-    def on(
-            self,
-            day_of_week: Literal['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
-            /
-    ) -> Self:
+    def on(self, day_of_week: WeekDay, /) -> Self:
         """
-        Set day to schedule the task, useful on `.every_weeks()`
+        Set day to schedule the task. Accepts string like 'monday', 'tuesday', etc.
         """
-        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()`')
+        self._day_of_week = day_of_week
         return self
 
     def at(self, _time: datetime.time, /) -> Self:
-        """
-        Set a time to schedule the task,
-        Only useful on `.every_days()` and `.every_weeks()`
-        """
+        """Set a time to schedule the task."""
         if isinstance(_time, datetime.time):
             self._time = _time
         elif isinstance(_time, datetime.datetime):
-            _time = _time.time()
+            self._time = _time.time()
         else:
             raise TypeError(
-                f'Argument should be instance of `datetime.time()` or `datetime.datetime()` not `{type(_time)}`')
-
-        if self._unit not in ['days', 'weeks']:
-            logger.warning('`.at()` only useful when you are using `.every_days()` or `.every_weeks()`')
-
+                f'Argument should be instance of `datetime.time()` or `datetime.datetime()` not `{type(_time)}`',
+            )
         return self
 
     def _should_wait(self) -> bool:
         """
-        Return:
-        ------
-            True: Wait and do nothing
-            False: Don't wait and Run this task
+        Returns True if the task should wait (not run yet), False if it should run now.
         """
-        now = datetime.datetime.now()
+        now = timezone_now()
 
         # Wait
         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
+        if self._day_of_week is not None and self._day_of_week.value != now.weekday():
+            return True
 
         # We don't have time condition, so run
         if self._time is None:
@@ -150,31 +144,21 @@ class BackgroundTask:
             return False
 
         # Time is ok, so run
-        if bool(
-                now.hour == self._time.hour and
-                now.minute == self._time.minute and
-                now.second == self._time.second,
-        ):
+        if now.hour == self._time.hour and now.minute == self._time.minute and now.second == self._time.second:
             self._last_run = now
             return False
 
-        # Time was not ok
+        # Time was not ok, wait
         return True
 
     def __call__(self) -> bool:
         """
-        Return:
-        ------
-            True: Everything is ok
-            False: This task is done, remove it from `BackgroundTasks.tasks`
+        Executes the task if it's time. Returns True if the task should remain scheduled, False if done.
         """
         if self._remaining_interval == 0:
             return False
-
         if self._should_wait():
-            # Just wait, it's not your time yet :)
             return True
-
         logger.info(
             f'{self._func.__name__}('
             f'{", ".join(str(a) for a in self._args)}, '
@@ -183,51 +167,62 @@ class BackgroundTask:
         )
         if self._remaining_interval != -1:
             self._remaining_interval -= 1
-        if is_function_async(self._func):
-            asyncio.run(self._func(*self._args, **self._kwargs))
-        else:
-            self._func(*self._args, **self._kwargs)
-
+        try:
+            if is_function_async(self._func):
+                asyncio.run(self._func(*self._args, **self._kwargs))
+            else:
+                self._func(*self._args, **self._kwargs)
+        except Exception as e:
+            logger.error(f'Exception in background task {self._func.__name__}: {e}', exc_info=True)
         return True
 
+    def submit(self) -> Self:
+        """Add this task to the background task queue."""
+        _background_tasks.add_task(self)
+        return self
+
 
 class BackgroundTasks(Singleton):
     _initialized: bool = False
 
     def __init__(self):
-        self.tasks = []
+        self.tasks: list[BackgroundTask] = []
+        self._lock = Lock()
 
     def add_task(self, task: BackgroundTask):
         if self._initialized is False:
             logger.error('Task will be ignored, `BACKGROUND_TASKS` is not True in `configs`')
             return
-
         if not self._is_instance_of_task(task):
             return
-
-        if task not in self.tasks:
-            self.tasks.append(task)
+        with self._lock:
+            if task not in self.tasks:
+                self.tasks.append(task)
+                logger.info(f'Task {task._func.__name__} submitted.')
 
     def initialize(self):
-        """
-        We only call initialize() once in the panther.main.Panther.load_configs()
-        """
-
-        def __run_task(task):
-            if task() is False:
-                self.tasks.remove(task)
-
-        def __run_tasks():
-            while True:
-                [Thread(target=__run_task, args=(task,)).start() for task in self.tasks[:]]
-                time.sleep(1)
-
+        """Call once to start background task processing."""
         if self._initialized is False:
             self._initialized = True
-            Thread(target=__run_tasks, daemon=True).start()
+            Thread(target=self._run_tasks, daemon=True).start()
+
+    def _run_task(self, task: BackgroundTask):
+        should_continue = task()
+        if should_continue is False:
+            with self._lock:
+                if task in self.tasks:
+                    self.tasks.remove(task)
+
+    def _run_tasks(self):
+        while True:
+            with self._lock:
+                tasks_snapshot = self.tasks[:]
+            for task in tasks_snapshot:
+                Thread(target=self._run_task, args=(task,)).start()
+            time.sleep(1)
 
     @classmethod
-    def _is_instance_of_task(cls, task, /):
+    def _is_instance_of_task(cls, task: Any, /) -> bool:
         if not isinstance(task, BackgroundTask):
             name = getattr(task, '__name__', task.__class__.__name__)
             logger.error(f'`{name}` should be instance of `background_tasks.BackgroundTask`')
@@ -235,25 +230,4 @@ class BackgroundTasks(Singleton):
         return True
 
 
-background_tasks = BackgroundTasks()
-
-"""
--------------------------------------------------------------
-Example:
--------------------------------------------------------------
->>> import datetime
-
-
->>> async def hello(name: str):
->>>     print(f'Hello {name}')
-
-# Run it every 5 seconds for 2 times
-
->>> task1 = BackgroundTask(hello, 'Ali').interval(2).every_seconds(5)
->>> background_tasks.add_task(task1)
-
-# Run it every day at 08:00 O'clock forever
-
->>> task2 = BackgroundTask(hello, 'Saba').interval(-1).every_days().at(datetime.time(hour=8))
->>> background_tasks.add_task(task2)
-"""
+_background_tasks = BackgroundTasks()

panther/base_request.py

@@ -1,9 +1,12 @@
+import typing
 from collections.abc import Callable
 from urllib.parse import parse_qsl
 
-from panther.db import Model
 from panther.exceptions import InvalidPathVariableAPIError
 
+if typing.TYPE_CHECKING:
+    from panther.db import Model
+
 
 class Headers:
     accept: str
@@ -56,10 +59,10 @@ class Headers:
 
     def get_cookies(self) -> dict:
         """
-        request.headers.cookie:
+        Example of `request.headers.cookie`:
             'csrftoken=aaa; sessionid=bbb; access_token=ccc; refresh_token=ddd'
 
-        request.headers.get_cookies():
+        Example of `request.headers.get_cookies()`:
             {
                 'csrftoken': 'aaa',
                 'sessionid': 'bbb',
@@ -126,17 +129,14 @@ class BaseRequest:
     def collect_path_variables(self, found_path: str):
         self.path_variables = {
             variable.strip('< >'): value
-            for variable, value in zip(
-                found_path.strip('/').split('/'),
-                self.path.strip('/').split('/')
-            )
+            for variable, value in zip(found_path.strip('/').split('/'), self.path.strip('/').split('/'))
             if variable.startswith('<')
         }
 
-    def clean_parameters(self, func: Callable) -> dict:
+    def clean_parameters(self, function_annotations: dict) -> dict:
         kwargs = self.path_variables.copy()
 
-        for variable_name, variable_type in func.__annotations__.items():
+        for variable_name, variable_type in function_annotations.items():
             # Put Request/ Websocket In kwargs (If User Wants It)
             if issubclass(variable_type, BaseRequest):
                 kwargs[variable_name] = self
@@ -144,7 +144,13 @@ class BaseRequest:
             elif variable_name in kwargs:
                 # Cast To Boolean
                 if variable_type is bool:
-                    kwargs[variable_name] = kwargs[variable_name].lower() not in ['false', '0']
+                    value = kwargs[variable_name].lower()
+                    if value in ['false', '0']:
+                        kwargs[variable_name] = False
+                    elif value in ['true', '1']:
+                        kwargs[variable_name] = True
+                    else:
+                        raise InvalidPathVariableAPIError(value=kwargs[variable_name], variable_type=variable_type)
 
                 # Cast To Int
                 elif variable_type is int: