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

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:

panther/base_websocket.py

@@ -12,7 +12,7 @@ from panther import status
 from panther.base_request import BaseRequest
 from panther.configs import config
 from panther.db.connections import redis
-from panther.exceptions import InvalidPathVariableAPIError, BaseError
+from panther.exceptions import BaseError, InvalidPathVariableAPIError
 from panther.utils import Singleton
 
 if TYPE_CHECKING:
@@ -83,11 +83,11 @@ class WebsocketConnections(Singleton):
 
     async def _handle_received_message(self, received_message):
         if (
-                isinstance(received_message, dict)
-                and (connection_id := received_message.get('connection_id'))
-                and connection_id in self.connections
-                and 'action' in received_message
-                and 'data' in received_message
+            isinstance(received_message, dict)
+            and (connection_id := received_message.get('connection_id'))
+            and connection_id in self.connections
+            and 'action' in received_message
+            and 'data' in received_message
         ):
             # Check Action of WS
             match received_message['action']:
@@ -96,7 +96,7 @@ class WebsocketConnections(Singleton):
                 case 'close':
                     await self.connections[connection_id].close(
                         code=received_message['data']['code'],
-                        reason=received_message['data']['reason']
+                        reason=received_message['data']['reason'],
                     )
                 case unknown_action:
                     logger.error(f'Unknown Message Action: {unknown_action}')
@@ -124,7 +124,7 @@ class WebsocketConnections(Singleton):
 
         # 3. Put PathVariables and Request(If User Wants It) In kwargs
         try:
-            kwargs = connection.clean_parameters(connection.connect)
+            kwargs = connection.clean_parameters(connection.connect.__annotations__)
         except InvalidPathVariableAPIError as e:
             connection.change_state(state='Rejected', message=e.detail)
             return await connection.close()

panther/caching.py

@@ -1,42 +1,33 @@
-from collections import namedtuple
-from datetime import timedelta, datetime
 import logging
-from types import NoneType
+from collections import namedtuple
+from datetime import datetime, timedelta
 
 import orjson as json
 
-from panther.configs import config
 from panther.db.connections import redis
 from panther.request import Request
 from panther.response import Response
-from panther.throttling import throttling_storage
 from panther.utils import generate_hash_value_from_string, round_datetime
 
 logger = logging.getLogger('panther')
 
-caches = {}
+caches: dict[str, tuple[bytes, dict, int]] = {}
 CachedResponse = namedtuple('CachedResponse', ['data', 'headers', 'status_code'])
 
 
-def api_cache_key(request: Request, cache_exp_time: timedelta | None = None) -> str:
-    client = request.user and request.user.id or request.client.ip
+def api_cache_key(request: Request, duration: timedelta | None = None) -> str:
+    client = (request.user and request.user.id) or request.client.ip
     query_params_hash = generate_hash_value_from_string(request.scope['query_string'].decode('utf-8'))
     key = f'{client}-{request.path}-{query_params_hash}-{request.validated_data}'
 
-    if cache_exp_time:
-        time = round_datetime(datetime.now(), cache_exp_time)
+    if duration:
+        time = round_datetime(datetime.now(), duration)
         return f'{time}-{key}'
 
     return key
 
 
-def throttling_cache_key(request: Request, duration: timedelta) -> str:
-    client = request.user and request.user.id or request.client.ip
-    time = round_datetime(datetime.now(), duration)
-    return f'{time}-{client}-{request.path}'
-
-
-async def get_response_from_cache(*, request: Request, cache_exp_time: timedelta) -> CachedResponse | None:
+async def get_response_from_cache(*, request: Request, duration: timedelta) -> CachedResponse | None:
     """
     If redis.is_connected:
         Get Cached Data From Redis
@@ -47,18 +38,14 @@ async def get_response_from_cache(*, request: Request, cache_exp_time: timedelta
         key = api_cache_key(request=request)
         data = (await redis.get(key) or b'{}').decode()
         if value := json.loads(data):
-            return CachedResponse(
-                data=value[0].encode(),
-                headers=value[1],
-                status_code=value[2]
-            )
+            return CachedResponse(data=value[0].encode(), headers=value[1], status_code=value[2])
     else:
-        key = api_cache_key(request=request, cache_exp_time=cache_exp_time)
+        key = api_cache_key(request=request, duration=duration)
         if value := caches.get(key):
             return CachedResponse(*value)
 
 
-async def set_response_in_cache(*, request: Request, response: Response, cache_exp_time: timedelta | int) -> None:
+async def set_response_in_cache(*, request: Request, response: Response, duration: timedelta | int) -> None:
     """
     If redis.is_connected:
         Cache The Data In Redis
@@ -68,61 +55,10 @@ async def set_response_in_cache(*, request: Request, response: Response, cache_e
 
     if redis.is_connected:
         key = api_cache_key(request=request)
-        cache_data: tuple[str, str, int] = (response.body.decode(), response.headers, response.status_code)
-        cache_exp_time = cache_exp_time or config.DEFAULT_CACHE_EXP
-        cache_data: bytes = json.dumps(cache_data)
-
-        if not isinstance(cache_exp_time, timedelta | int | NoneType):
-            msg = '`cache_exp_time` should be instance of `datetime.timedelta`, `int` or `None`'
-            raise TypeError(msg)
-
-        if cache_exp_time is None:
-            logger.warning(
-                'your response are going to cache in redis forever '
-                '** set DEFAULT_CACHE_EXP in `configs` or set the `cache_exp_time` in `@API.get()` to prevent this **'
-            )
-            await redis.set(key, cache_data)
-        else:
-            await redis.set(key, cache_data, ex=cache_exp_time)
-
-    else:
-        key = api_cache_key(request=request, cache_exp_time=cache_exp_time)
-        cache_data: tuple[bytes, str, int] = (response.body, response.headers, response.status_code)
-
-        caches[key] = cache_data
-
-        if cache_exp_time:
-            logger.info('`cache_exp_time` is not very accurate when `redis` is not connected.')
-
-
-async def get_throttling_from_cache(request: Request, duration: timedelta) -> int:
-    """
-    If redis.is_connected:
-        Get Cached Data From Redis
-    else:
-        Get Cached Data From Memory
-    """
-    key = throttling_cache_key(request=request, duration=duration)
-
-    if redis.is_connected:
-        data = (await redis.get(key) or b'0').decode()
-        return json.loads(data)
-
-    else:
-        return throttling_storage[key]
-
-
-async def increment_throttling_in_cache(request: Request, duration: timedelta) -> None:
-    """
-    If redis.is_connected:
-        Increment The Data In Redis
-    else:
-        Increment The Data In Memory
-    """
-    key = throttling_cache_key(request=request, duration=duration)
-
-    if redis.is_connected:
-        await redis.incrby(key, amount=1)
+        cache_data: tuple[str, dict, int] = (response.body.decode(), response.headers, response.status_code)
+        await redis.set(key, json.dumps(cache_data), ex=duration)
 
     else:
-        throttling_storage[key] += 1
+        key = api_cache_key(request=request, duration=duration)
+        caches[key] = (response.body, response.headers, response.status_code)
+        logger.info('`cache` is not very accurate when `redis` is not connected.')

panther/cli/create_command.py

@@ -1,5 +1,5 @@
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable
 
 from rich import print as rich_print
 from rich.console import Console
@@ -8,15 +8,16 @@ from rich.prompt import Prompt
 
 from panther import version
 from panther.cli.template import (
-    TEMPLATE,
-    SINGLE_FILE_TEMPLATE,
     AUTHENTICATION_PART,
-    MONITORING_PART,
-    LOG_QUERIES_PART,
     AUTO_REFORMAT_PART,
-    DATABASE_PANTHERDB_PART,
     DATABASE_MONGODB_PART,
-    USER_MODEL_PART, REDIS_PART,
+    DATABASE_PANTHERDB_PART,
+    LOG_QUERIES_PART,
+    MONITORING_PART,
+    REDIS_PART,
+    SINGLE_FILE_TEMPLATE,
+    TEMPLATE,
+    USER_MODEL_PART,
 )
 from panther.cli.utils import cli_error
 
@@ -52,7 +53,7 @@ class CreateProject:
                 'message': 'Directory (default is .)',
                 'validation_func': self._check_all_directories,
                 'error_message': '"{}" Directory Already Exists.',
-                'show_validation_error': True
+                'show_validation_error': True,
             },
             {
                 'field': 'single_file',
@@ -69,7 +70,7 @@ class CreateProject:
                 'field': 'database_encryption',
                 'message': 'Do You Want Encryption For Your Database (Required `cryptography`)',
                 'is_boolean': True,
-                'condition': "self.database == '0'"
+                'condition': "self.database == '0'",
             },
             {
                 'field': 'redis',
@@ -90,7 +91,7 @@ class CreateProject:
                 'field': 'log_queries',
                 'message': 'Do You Want To Log Queries',
                 'is_boolean': True,
-                'condition': "self.database != '2'"
+                'condition': "self.database != '2'",
             },
             {
                 'field': 'auto_reformat',
@@ -194,12 +195,12 @@ class CreateProject:
             self.progress(i + 1)
 
     def ask(
-            self,
-            message: str,
-            default: str | bool,
-            error_message: str,
-            validation_func: Callable,
-            show_validation_error: bool = False,
+        self,
+        message: str,
+        default: str | bool,
+        error_message: str,
+        validation_func: Callable,
+        show_validation_error: bool = False,
     ) -> str:
         value = Prompt.ask(message, console=self.input_console).lower() or default
         while not validation_func(value):

panther/cli/main.py

@@ -15,7 +15,7 @@ def shell(args) -> None:
         return cli_error(
             'Not Enough Arguments, Give me a file path that contains `Panther()` app.\n'
             '       * Make sure to run `panther shell` in the same directory as that file!\n'
-            '       * Example: `panther shell main.py`'
+            '       * Example: `panther shell main.py`',
         )
     elif len(args) != 1:
         return cli_error('Too Many Arguments.')