panther 4.3.7__py3-none-any.whl → 5.0.0b1__py3-none-any.whl

panther/__init__.py

@@ -1,6 +1,6 @@
 from panther.main import Panther  # noqa: F401
 
-__version__ = '4.3.7'
+__version__ = '5.0.0beta1'
 
 
 def version():

panther/_load_configs.py

@@ -16,7 +16,8 @@ from panther.db.queries.mongodb_queries import BaseMongoDBQuery
 from panther.db.queries.pantherdb_queries import BasePantherDBQuery
 from panther.exceptions import PantherError
 from panther.middlewares.base import WebsocketMiddleware, HTTPMiddleware
-from panther.panel.urls import urls as panel_urls
+from panther.middlewares.monitoring import MonitoringMiddleware, WebsocketMonitoringMiddleware
+from panther.panel.views import HomeView
 from panther.routings import finalize_urls, flatten_urls
 
 __all__ = (
@@ -27,7 +28,6 @@ __all__ = (
     'load_timezone',
     'load_database',
     'load_secret_key',
-    'load_monitoring',
     'load_throttling',
     'load_user_model',
     'load_log_queries',
@@ -36,8 +36,8 @@ __all__ = (
     'load_auto_reformat',
     'load_background_tasks',
     'load_default_cache_exp',
-    'load_authentication_class',
     'load_urls',
+    'load_authentication_class',
     'load_websocket_connections',
     'check_endpoints_inheritance',
 )
@@ -94,7 +94,15 @@ def load_templates_dir(_configs: dict, /) -> None:
     if config.TEMPLATES_DIR == '.':
         config.TEMPLATES_DIR = config.BASE_DIR
 
-    config.JINJA_ENVIRONMENT = jinja2.Environment(loader=jinja2.FileSystemLoader(config.TEMPLATES_DIR))
+    config.JINJA_ENVIRONMENT = jinja2.Environment(
+        loader=jinja2.ChoiceLoader(
+            loaders=(
+                jinja2.FileSystemLoader(searchpath=config.TEMPLATES_DIR),
+                jinja2.PackageLoader(package_name='panther', package_path='panel/templates/'),
+                jinja2.PackageLoader(package_name='panther', package_path='openapi/templates/'),
+            )
+        )
+    )
 
 
 def load_database(_configs: dict, /) -> None:
@@ -126,11 +134,6 @@ def load_secret_key(_configs: dict, /) -> None:
         config.SECRET_KEY = secret_key.encode()
 
 
-def load_monitoring(_configs: dict, /) -> None:
-    if _configs.get('MONITORING'):
-        config.MONITORING = True
-
-
 def load_throttling(_configs: dict, /) -> None:
     if throttling := _configs.get('THROTTLING'):
         config.THROTTLING = throttling
@@ -147,42 +150,45 @@ def load_log_queries(_configs: dict, /) -> None:
 
 
 def load_middlewares(_configs: dict, /) -> None:
-    from panther.middlewares import BaseMiddleware
-
     middlewares = {'http': [], 'ws': []}
 
     # Collect Middlewares
     for middleware in _configs.get('MIDDLEWARES') or []:
-        if not isinstance(middleware, list | tuple):
-            path_or_type = middleware
-            data = {}
-
-        elif len(middleware) == 1:
-            path_or_type = middleware[0]
-            data = {}
-
-        elif len(middleware) > 2:
-            raise _exception_handler(field='MIDDLEWARES', error=f'{middleware} too many arguments')
-
-        else:
-            path_or_type, data = middleware
-
-        if callable(path_or_type):
-            middleware_class = path_or_type
-        else:
+        # This block is for Backward Compatibility
+        if isinstance(middleware, list | tuple):
+            if len(middleware) == 1:
+                middleware = middleware[0]
+            elif len(middleware) == 2:
+                _deprecated_warning(
+                    field='MIDDLEWARES',
+                    message='`data` does not supported in middlewares anymore, as your data is static you may want '
+                            'to pass them to your middleware with config variables'
+                )
+                middleware = middleware[0]
+            else:
+                raise _exception_handler(
+                    field='MIDDLEWARES', error=f'{middleware} should be dotted path or type of a middleware class')
+
+        # `middleware` can be type or path of a class
+        if not callable(middleware):
             try:
-                middleware_class = import_class(path_or_type)
+                middleware = import_class(middleware)
             except (AttributeError, ModuleNotFoundError):
-                raise _exception_handler(field='MIDDLEWARES', error=f'{path_or_type} is not a valid middleware path')
+                raise _exception_handler(
+                    field='MIDDLEWARES', error=f'{middleware} is not a valid middleware path or type')
 
-        if issubclass(middleware_class, BaseMiddleware) is False:
-            raise _exception_handler(field='MIDDLEWARES', error='is not a sub class of BaseMiddleware')
+        if issubclass(middleware, (MonitoringMiddleware, WebsocketMonitoringMiddleware)):
+            config.MONITORING = True
 
-        if middleware_class.__bases__[0] in (BaseMiddleware, HTTPMiddleware):
-            middlewares['http'].append((middleware_class, data))
-
-        if middleware_class.__bases__[0] in (BaseMiddleware, WebsocketMiddleware):
-            middlewares['ws'].append((middleware_class, data))
+        if issubclass(middleware, HTTPMiddleware):
+            middlewares['http'].append(middleware)
+        elif issubclass(middleware, WebsocketMiddleware):
+            middlewares['ws'].append(middleware)
+        else:
+            raise _exception_handler(
+                field='MIDDLEWARES',
+                error='is not a sub class of `HTTPMiddleware` or `WebsocketMiddleware`'
+            )
 
     config.HTTP_MIDDLEWARES = middlewares['http']
     config.WS_MIDDLEWARES = middlewares['ws']
@@ -204,32 +210,6 @@ def load_default_cache_exp(_configs: dict, /) -> None:
         config.DEFAULT_CACHE_EXP = default_cache_exp
 
 
-def load_authentication_class(_configs: dict, /) -> None:
-    """Should be after `load_secret_key()`"""
-    if authentication := _configs.get('AUTHENTICATION'):
-        config.AUTHENTICATION = import_class(authentication)
-
-    if ws_authentication := _configs.get('WS_AUTHENTICATION'):
-        config.WS_AUTHENTICATION = import_class(ws_authentication)
-
-    load_jwt_config(_configs)
-
-
-def load_jwt_config(_configs: dict, /) -> None:
-    """Only Collect JWT Config If Authentication Is JWTAuthentication"""
-    auth_is_jwt = (
-            getattr(config.AUTHENTICATION, '__name__', None) == 'JWTAuthentication' or
-            getattr(config.WS_AUTHENTICATION, '__name__', None) == 'QueryParamJWTAuthentication'
-    )
-    jwt = _configs.get('JWTConfig', {})
-    if auth_is_jwt or jwt:
-        if 'key' not in jwt:
-            if config.SECRET_KEY is None:
-                raise _exception_handler(field='JWTConfig', error='`JWTConfig.key` or `SECRET_KEY` is required.')
-            jwt['key'] = config.SECRET_KEY.decode()
-        config.JWT_CONFIG = JWTConfig(**jwt)
-
-
 def load_urls(_configs: dict, /, urls: dict | None) -> None:
     """
     Return tuple of all urls (as a flat dict) and (as a nested dict)
@@ -261,7 +241,34 @@ def load_urls(_configs: dict, /, urls: dict | None) -> None:
 
     config.FLAT_URLS = flatten_urls(urls)
     config.URLS = finalize_urls(config.FLAT_URLS)
-    config.URLS['_panel'] = finalize_urls(flatten_urls(panel_urls))
+
+
+def load_authentication_class(_configs: dict, /) -> None:
+    """Should be after `load_secret_key()` and `load_urls()`"""
+    if authentication := _configs.get('AUTHENTICATION'):
+        config.AUTHENTICATION = import_class(authentication)
+
+    if ws_authentication := _configs.get('WS_AUTHENTICATION'):
+        config.WS_AUTHENTICATION = import_class(ws_authentication)
+
+    load_jwt_config(_configs)
+
+
+def load_jwt_config(_configs: dict, /) -> None:
+    """Only Collect JWT Config If Authentication Is JWTAuthentication"""
+    auth_is_jwt = (
+            getattr(config.AUTHENTICATION, '__name__', None) == 'JWTAuthentication' or
+            getattr(config.WS_AUTHENTICATION, '__name__', None) == 'QueryParamJWTAuthentication'
+    )
+    jwt = _configs.get('JWTConfig', {})
+
+    using_panel_views = HomeView in config.FLAT_URLS.values()
+    if auth_is_jwt or using_panel_views:
+        if 'key' not in jwt:
+            if config.SECRET_KEY is None:
+                raise _exception_handler(field='JWTConfig', error='`JWTConfig.key` or `SECRET_KEY` is required.')
+            jwt['key'] = config.SECRET_KEY.decode()
+        config.JWT_CONFIG = JWTConfig(**jwt)
 
 
 def load_websocket_connections():
@@ -281,6 +288,9 @@ def load_websocket_connections():
 def check_endpoints_inheritance():
     """Should be after `load_urls()`"""
     for _, endpoint in config.FLAT_URLS.items():
+        if endpoint == {}:
+            continue
+
         if isinstance(endpoint, types.FunctionType):
             check_function_type_endpoint(endpoint=endpoint)
         else:
@@ -289,3 +299,7 @@ def check_endpoints_inheritance():
 
 def _exception_handler(field: str, error: str | Exception) -> PantherError:
     return PantherError(f"Invalid '{field}': {error}")
+
+
+def _deprecated_warning(field: str, message: str):
+    return logger.warning(f"DEPRECATED '{field}': {message}")

panther/_utils.py

@@ -10,7 +10,6 @@ from typing import Any, Generator, Iterator, AsyncGenerator
 
 from panther.exceptions import PantherError
 from panther.file_handler import File
-from panther.websocket import GenericWebsocket
 
 logger = logging.getLogger('panther')
 
@@ -100,6 +99,7 @@ def check_function_type_endpoint(endpoint: types.FunctionType) -> Callable:
 
 def check_class_type_endpoint(endpoint: Callable) -> Callable:
     from panther.app import GenericAPI
+    from panther.websocket import GenericWebsocket
 
     if not issubclass(endpoint, (GenericAPI, GenericWebsocket)):
         raise PantherError(

panther/app.py

@@ -1,7 +1,9 @@
 import functools
 import logging
+import traceback
+import typing
 from datetime import timedelta
-from typing import Literal
+from typing import Literal, Callable
 
 from orjson import JSONDecodeError
 from pydantic import ValidationError, BaseModel
@@ -22,6 +24,10 @@ from panther.exceptions import (
     ThrottlingAPIError,
     BadRequestAPIError
 )
+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
@@ -33,87 +39,127 @@ logger = logging.getLogger('panther')
 
 
 class API:
+    """
+    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_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.
+    middlewares: These middlewares have inner priority than global middlewares.
+    """
+    func: Callable
+
     def __init__(
         self,
         *,
+        methods: list[Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']] | None = None,
         input_model: type[ModelSerializer] | type[BaseModel] | None = None,
-        output_model: type[ModelSerializer] | type[BaseModel] | None = None,
+        output_model: type[BaseModel] | None = None,
+        output_schema: OutputSchema | None = None,
         auth: bool = False,
-        permissions: list | None = None,
+        permissions: list[BasePermission] | None = 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,
+        middlewares: list[HTTPMiddleware] | None = None,
     ):
+        self.methods = {m.upper() for m in methods} if methods else None
         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 # or config.DEFAULT_CACHE_EXP
-        self.methods = methods
+        self.cache_exp_time = cache_exp_time
+        self.middlewares: list[HTTPMiddleware] | None = middlewares
         self.request: Request | None = None
+        if output_model:
+            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/'
+            )
+            raise PantherError(deprecation_message)
 
     def __call__(self, func):
+        self.func = func
+
         @functools.wraps(func)
         async def wrapper(request: Request) -> Response:
-            self.request = request
+            chained_func = self.handle_endpoint
+            if self.middlewares:
+                for middleware in reversed(self.middlewares):
+                    chained_func = middleware(chained_func)
+            return await chained_func(request=request)
+
+        # Store attributes on the function, so have the same behaviour as class-based (useful in `openapi.view.OpenAPI`)
+        wrapper.auth = self.auth
+        wrapper.methods = self.methods
+        wrapper.permissions = self.permissions
+        wrapper.input_model = self.input_model
+        wrapper.output_schema = self.output_schema
+        return wrapper
 
-            # 0. Preflight
-            if self.request.method == 'OPTIONS':
-                return self.options()
+    async def handle_endpoint(self, request: Request) -> Response:
+        self.request = request
 
-            # 1. Check Method
-            if self.methods and self.request.method not in self.methods:
-                raise MethodNotAllowedAPIError
+        # 0. Preflight
+        if self.request.method == 'OPTIONS':
+            return self.options()
 
-            # 2. Authentication
-            await self.handle_authentication()
+        # 1. Check Method
+        if self.methods and self.request.method not in self.methods:
+            raise MethodNotAllowedAPIError
 
-            # 3. Permissions
-            await self.handle_permission()
+        # 2. Authentication
+        await self.handle_authentication()
 
-            # 4. Throttling
-            await self.handle_throttling()
+        # 3. Permissions
+        await self.handle_permission()
 
-            # 5. Validate Input
-            if self.request.method in ['POST', 'PUT', 'PATCH']:
-                self.handle_input_validation()
+        # 4. Throttling
+        await self.handle_throttling()
 
-            # 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):
-                    return Response(data=cached.data, headers=cached.headers, status_code=cached.status_code)
+        # 5. Validate Input
+        if self.request.method in {'POST', 'PUT', 'PATCH'}:
+            self.handle_input_validation()
 
-            # 7. Put PathVariables and Request(If User Wants It) In kwargs
-            kwargs = self.request.clean_parameters(func)
+        # 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):
+                return Response(data=cached.data, headers=cached.headers, status_code=cached.status_code)
 
-            # 8. Call Endpoint
-            if is_function_async(func):
-                response = await func(**kwargs)
-            else:
-                response = func(**kwargs)
+        # 7. Put PathVariables and Request(If User Wants It) In kwargs
+        kwargs = self.request.clean_parameters(self.func)
 
-            # 9. Clean Response
-            if not isinstance(response, Response):
-                response = Response(data=response)
-            if self.output_model and response.data:
-                response.data = await response.apply_output_model(output_model=self.output_model)
-            if response.pagination:
-                response.data = await response.pagination.template(response.data)
+        # 8. Call Endpoint
+        if is_function_async(self.func):
+            response = await self.func(**kwargs)
+        else:
+            response = self.func(**kwargs)
 
-            # 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)
+        # 9. Clean Response
+        if not isinstance(response, Response):
+            response = Response(data=response)
+        if response.pagination:
+            response.data = await response.pagination.template(response.data)
 
-            # 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')
+        # 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)
 
-            return response
+        # 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')
 
-        return wrapper
+        return response
 
     async def handle_authentication(self) -> None:
         if self.auth:
@@ -144,7 +190,7 @@ class API:
     @classmethod
     def options(cls):
         headers = {
-            'Access-Control-Allow-Methods': 'DELETE, GET, PATCH, POST, PUT, OPTIONS',
+            '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)
@@ -165,14 +211,39 @@ class API:
             raise JSONDecodeAPIError
 
 
-class GenericAPI:
+class MetaGenericAPI(type):
+    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/'
+            )
+            raise PantherError(deprecation_message)
+        return super().__new__(cls, cls_name, bases, namespace)
+
+
+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
+    middlewares: list[HTTPMiddleware] | None = None
 
     async def get(self, *args, **kwargs):
         raise MethodNotAllowedAPIError
@@ -189,12 +260,6 @@ class GenericAPI:
     async def delete(self, *args, **kwargs):
         raise MethodNotAllowedAPIError
 
-    async def get_input_model(self, request: Request) -> type[ModelSerializer] | type[BaseModel] | None:
-        return None
-
-    async def get_output_model(self, request: Request) -> type[ModelSerializer] | type[BaseModel] | None:
-        return None
-
     async def call_method(self, request: Request):
         match request.method:
             case 'GET':
@@ -213,11 +278,12 @@ class GenericAPI:
                 raise MethodNotAllowedAPIError
 
         return await API(
-            input_model=self.input_model or await self.get_input_model(request=request),
-            output_model=self.output_model or await self.get_output_model(request=request),
+            input_model=self.input_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

@@ -29,9 +29,9 @@ class BaseAuthentication:
         msg = f'{cls.__name__}.authentication() is not implemented.'
         raise cls.exception(msg) from None
 
-    @staticmethod
-    def exception(message: str, /) -> type[AuthenticationAPIError]:
-        logger.error(f'Authentication Error: "{message}"')
+    @classmethod
+    def exception(cls, message: str | Exception, /) -> type[AuthenticationAPIError]:
+        logger.error(f'{cls.__name__} Error: "{message}"')
         return AuthenticationAPIError
 
 
@@ -151,16 +151,33 @@ class JWTAuthentication(BaseAuthentication):
         key = generate_hash_value_from_string(token)
         return bool(await redis.exists(key))
 
-    @staticmethod
-    def exception(message: str | JWTError | UnicodeEncodeError, /) -> type[AuthenticationAPIError]:
-        logger.error(f'JWT Authentication Error: "{message}"')
-        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'
+        msg = '`authorization` query param not found.'
+        raise cls.exception(msg) from None
+
+
+class CookieJWTAuthentication(JWTAuthentication):
+    @classmethod
+    def get_authorization_header(cls, request: Request | Websocket) -> str:
+        if token := request.headers.get_cookies().get('access_token'):
+            return token
+        msg = '`access_token` Cookie not found.'
         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

panther/base_request.py

@@ -1,4 +1,3 @@
-from collections import namedtuple
 from collections.abc import Callable
 from urllib.parse import parse_qsl
 
@@ -46,14 +45,40 @@ class Headers:
         items = ', '.join(f'{k}={v}' for k, v in self.__headers.items())
         return f'Headers({items})'
 
+    def __contains__(self, item):
+        return (item in self.__headers) or (item in self.__pythonic_headers)
+
     __repr__ = __str__
 
     @property
     def __dict__(self):
         return self.__headers
 
+    def get_cookies(self) -> dict:
+        """
+        request.headers.cookie:
+            'csrftoken=aaa; sessionid=bbb; access_token=ccc; refresh_token=ddd'
+
+        request.headers.get_cookies():
+            {
+                'csrftoken': 'aaa',
+                'sessionid': 'bbb',
+                'access_token': 'ccc',
+                'refresh_token': 'ddd',
+            }
+        """
+        if self.cookie:
+            return {k.strip(): v for k, v in (c.split('=', maxsplit=1) for c in self.cookie.split(';'))}
+        return {}
+
+
+class Address:
+    def __init__(self, ip, port):
+        self.ip = ip
+        self.port = port
 
-Address = namedtuple('Address', ['ip', 'port'])
+    def __str__(self):
+        return f'{self.ip}:{self.port}'
 
 
 class BaseRequest: