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

panther/db/queries/mongodb_queries.py

@@ -1,20 +1,29 @@
 from __future__ import annotations
 
+import types
+import typing
 from sys import version_info
-from typing import Iterable, Sequence
+from typing import get_args, get_origin, Iterable, Sequence, Any, Union
+
+from pydantic import BaseModel, ValidationError
 
 from panther.db.connections import db
 from panther.db.cursor import Cursor
+from panther.db.models import Model
 from panther.db.queries.base_queries import BaseQuery
 from panther.db.utils import prepare_id_for_query
+from panther.exceptions import DatabaseError
 
 try:
     from bson.codec_options import CodecOptions
+    from pymongo.results import InsertOneResult, InsertManyResult
 except ImportError:
-    # This 'CodecOptions' is not going to be used,
-    #   If user really wants to use it,
-    #   we are going to force him to install it in `panther.db.connections.MongoDBConnection.init`
+    # MongoDB-related libraries are not required by default.
+    # If the user intends to use MongoDB, they must install the required dependencies explicitly.
+    # This will be enforced in `panther.db.connections.MongoDBConnection.init`.
     CodecOptions = type('CodecOptions', (), {})
+    InsertOneResult = type('InsertOneResult', (), {})
+    InsertManyResult = type('InsertManyResult', (), {})
 
 if version_info >= (3, 11):
     from typing import Self
@@ -24,6 +33,32 @@ else:
     Self = TypeVar('Self', bound='BaseMongoDBQuery')
 
 
+def get_annotation_type(annotation: Any) -> type | None:
+    """
+    Extracts the underlying, non-optional type from a type annotation.
+    Handles basic types, Pydantic BaseModels, lists, and unions (optionals).
+    Returns None if no single underlying type can be determined (e.g., for list[NoneType]).
+    Raises DatabaseError for unsupported annotations.
+    """
+    origin = get_origin(annotation)
+
+    # Handle list[T] and Union[T, None] (T | None or typing.Union[T, None])
+    if origin is list or origin is types.UnionType or origin is Union:
+        # Extracts the first non-None type from a tuple of type arguments.
+        for arg in get_args(annotation):
+            if arg is not type(None):
+                return arg
+        return None
+
+    # Handle basic types (str, int, bool, dict) and Pydantic BaseModel subclasses
+    if isinstance(annotation, type) and (
+            annotation in (str, int, bool, dict) or issubclass(annotation, BaseModel)
+    ):
+        return annotation
+
+    raise DatabaseError(f'Panther does not support {annotation} as a field type for unwrapping.')
+
+
 class BaseMongoDBQuery(BaseQuery):
     @classmethod
     def _merge(cls, *args, is_mongo: bool = True) -> dict:
@@ -34,11 +69,126 @@ class BaseMongoDBQuery(BaseQuery):
     # def collection(cls):
     #     return db.session.get_collection(name=cls.__name__, codec_options=CodecOptions(document_class=cls))
 
+    @classmethod
+    async def _create_list(cls, field_type: type, value: Any) -> Any:
+        # `field_type` is the expected type of items in the list (e.g., int, Model, list[str])
+        # `value` is a single item from the input list that needs processing.
+
+        # Handles list[list[int]], list[dict[str,int]] etc.
+        if isinstance(field_type, (types.GenericAlias, typing._GenericAlias)):
+            element_type = get_annotation_type(field_type)  # Unwrap further (e.g. list[str] -> str)
+            if element_type is None:
+                raise DatabaseError(f"Cannot determine element type for generic list item: {field_type}")
+            if not isinstance(value, list):  # Or check if iterable, matching the structure
+                raise DatabaseError(f"Expected a list for nested generic type {field_type}, got {type(value)}")
+            return [await cls._create_list(field_type=element_type, value=item) for item in value]
+
+        # Make sure Model condition is before BaseModel.
+        if isinstance(field_type, type) and issubclass(field_type, Model):
+            # `value` is assumed to be an ID for the Model instance.
+            return await field_type.first(id=value)
+
+        if isinstance(field_type, type) and issubclass(field_type, BaseModel):
+            if not isinstance(value, dict):
+                raise DatabaseError(f"Expected a dictionary for BaseModel {field_type.__name__}, got {type(value)}")
+
+            return {
+                field_name: await cls._create_field(model=field_type, field_name=field_name, value=value[field_name])
+                for field_name in value
+            }
+
+        # Base case: value is a primitive type (str, int, etc.)
+        return value
+
+    @classmethod
+    async def _create_field(cls, model: type, field_name: str, value: Any) -> Any:
+        # Handle primary key field directly
+        if field_name == '_id':
+            return value
+
+        if field_name not in model.model_fields:
+            # Field from input data is not defined in the model.
+            # Pydantic's `extra` config on the model will handle this upon instantiation.
+            return value
+
+        field_annotation = model.model_fields[field_name].annotation
+        unwrapped_type = get_annotation_type(field_annotation)
+
+        if unwrapped_type is None:
+            raise DatabaseError(
+                f"Could not determine a valid underlying type for field '{field_name}' "
+                f"with annotation {field_annotation} in model {model.__name__}."
+            )
+
+        if get_origin(field_annotation) is list:
+            # Or check for general iterables if applicable
+            if not isinstance(value, list):
+                raise DatabaseError(
+                    f"Field '{field_name}' expects a list, got {type(value)} for model {model.__name__}")
+            return [await cls._create_list(field_type=unwrapped_type, value=item) for item in value]
+
+        if isinstance(unwrapped_type, type) and issubclass(unwrapped_type, Model):
+            if obj := await unwrapped_type.first(id=value):
+                return obj.model_dump(by_alias=True)
+            return None
+
+        if isinstance(unwrapped_type, type) and issubclass(unwrapped_type, BaseModel):
+            if not isinstance(value, dict):
+                raise DatabaseError(
+                    f"Field '{field_name}' expects a dictionary for BaseModel {unwrapped_type.__name__}, "
+                    f"got {type(value)} in model {model.__name__}"
+                )
+            return {
+                nested_field_name: await cls._create_field(
+                    model=unwrapped_type,
+                    field_name=nested_field_name,
+                    value=value[nested_field_name],
+                )
+                for nested_field_name in unwrapped_type.model_fields if nested_field_name in value
+            }
+
+        return value
+
+    @classmethod
+    async def _create_model_instance(cls, document: dict) -> Self:
+        """Prepares document and creates an instance of the model."""
+        processed_document = {
+            field_name: await cls._create_field(model=cls, field_name=field_name, value=field_value)
+            for field_name, field_value in document.items()
+        }
+        try:
+            return cls(**processed_document)
+        except ValidationError as validation_error:
+            error = cls._clean_error_message(validation_error=validation_error)
+            raise DatabaseError(error) from validation_error
+
+    @classmethod
+    def clean_value(cls, field: str | None, value: Any) -> dict[str, Any] | list[Any]:
+        match value:
+            case None:
+                return None
+            case Model() as model:
+                if model.id is None:
+                    raise DatabaseError(f'Model instance{" in " + field if field else ""} has no ID.')
+                # We save full object because user didn't specify the type.
+                return model._id
+            case BaseModel() as model:
+                return {
+                    field_name: cls.clean_value(field=field_name, value=getattr(model, field_name))
+                    for field_name in model.model_fields
+                }
+            case dict() as d:
+                return {k: cls.clean_value(field=k, value=v) for k, v in d.items()}
+            case list() as l:
+                return [cls.clean_value(field=None, value=item) for item in l]
+
+        return value
+
     # # # # # Find # # # # #
     @classmethod
     async def find_one(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         if document := await db.session[cls.__name__].find_one(cls._merge(_filter, kwargs)):
-            return cls._create_model_instance(document=document)
+            return await cls._create_model_instance(document=document)
         return None
 
     @classmethod
@@ -48,14 +198,14 @@ class BaseMongoDBQuery(BaseQuery):
     @classmethod
     async def first(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         cursor = await cls.find(_filter, **kwargs)
-        for result in cursor.sort('_id', 1).limit(-1):
+        async for result in cursor.sort('_id', 1).limit(-1):
             return result
         return None
 
     @classmethod
     async def last(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         cursor = await cls.find(_filter, **kwargs)
-        for result in cursor.sort('_id', -1).limit(-1):
+        async for result in cursor.sort('_id', -1).limit(-1):
             return result
         return None
 
@@ -73,18 +223,32 @@ class BaseMongoDBQuery(BaseQuery):
     async def insert_one(cls, _document: dict | None = None, /, **kwargs) -> Self:
         document = cls._merge(_document, kwargs)
         cls._validate_data(data=document)
-
-        await db.session[cls.__name__].insert_one(document)
-        return cls._create_model_instance(document=document)
+        final_document = {
+            field: cls.clean_value(field=field, value=value)
+            for field, value in document.items()
+        }
+        result = await cls._create_model_instance(document=final_document)
+        insert_one_result: InsertOneResult = await db.session[cls.__name__].insert_one(final_document)
+        result.id = insert_one_result.inserted_id
+        return result
 
     @classmethod
     async def insert_many(cls, documents: Iterable[dict]) -> list[Self]:
+        final_documents = []
+        results = []
         for document in documents:
             prepare_id_for_query(document, is_mongo=True)
             cls._validate_data(data=document)
-
-        await db.session[cls.__name__].insert_many(documents)
-        return [cls._create_model_instance(document=document) for document in documents]
+            cleaned_document = {
+                field: cls.clean_value(field=field, value=value)
+                for field, value in document.items()
+            }
+            final_documents.append(cleaned_document)
+            results.append(await cls._create_model_instance(document=cleaned_document))
+        insert_many_result: InsertManyResult = await db.session[cls.__name__].insert_many(final_documents)
+        for obj, _id in zip(results, insert_many_result.inserted_ids):
+            obj.id = _id
+        return results
 
     # # # # # Delete # # # # #
     async def delete(self) -> None:

panther/db/queries/pantherdb_queries.py

@@ -25,7 +25,7 @@ class BasePantherDBQuery(BaseQuery):
     @classmethod
     async def find_one(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         if document := db.session.collection(cls.__name__).find_one(**cls._merge(_filter, kwargs)):
-            return cls._create_model_instance(document=document)
+            return await cls._create_model_instance(document=document)
         return None
 
     @classmethod
@@ -38,13 +38,13 @@ class BasePantherDBQuery(BaseQuery):
     @classmethod
     async def first(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         if document := db.session.collection(cls.__name__).first(**cls._merge(_filter, kwargs)):
-            return cls._create_model_instance(document=document)
+            return await cls._create_model_instance(document=document)
         return None
 
     @classmethod
     async def last(cls, _filter: dict | None = None, /, **kwargs) -> Self | None:
         if document := db.session.collection(cls.__name__).last(**cls._merge(_filter, kwargs)):
-            return cls._create_model_instance(document=document)
+            return await cls._create_model_instance(document=document)
         return None
 
     @classmethod
@@ -64,7 +64,7 @@ class BasePantherDBQuery(BaseQuery):
         cls._validate_data(data=_document)
 
         document = db.session.collection(cls.__name__).insert_one(**_document)
-        return cls._create_model_instance(document=document)
+        return await cls._create_model_instance(document=document)
 
     @classmethod
     async def insert_many(cls, documents: Iterable[dict]) -> list[Self]:
@@ -74,7 +74,7 @@ class BasePantherDBQuery(BaseQuery):
             cls._validate_data(data=document)
             inserted_document = db.session.collection(cls.__name__).insert_one(**document)
             document['_id'] = inserted_document['_id']
-            result.append(cls._create_model_instance(document=document))
+            result.append(await cls._create_model_instance(document=document))
         return result
 
     # # # # # Delete # # # # #

panther/db/queries/queries.py

@@ -404,7 +404,7 @@ class Query(BaseQuery):
             >>> await user.save()
         """
         document = {
-            field: getattr(self, field).model_dump()
+            field: getattr(self, field).model_dump(by_alias=True)
             if issubclass(type(getattr(self, field)), BaseModel)
             else getattr(self, field)
             for field in self.model_fields.keys() if field != 'request'

panther/events.py

@@ -1,8 +1,11 @@
 import asyncio
+import logging
 
 from panther._utils import is_function_async
 from panther.configs import config
 
+logger = logging.getLogger('panther')
+
 
 class Event:
     @staticmethod
@@ -24,10 +27,13 @@ class Event:
     @staticmethod
     async def run_startups():
         for func in config.STARTUPS:
-            if is_function_async(func):
-                await func()
-            else:
-                func()
+            try:
+                if is_function_async(func):
+                    await func()
+                else:
+                    func()
+            except Exception as e:
+                logger.error(f'{func.__name__}() startup event got error: {e}')
 
     @staticmethod
     def run_shutdowns():

panther/exceptions.py

@@ -9,17 +9,34 @@ class DatabaseError(Exception):
     pass
 
 
-class APIError(Exception):
+class BaseError(Exception):
     detail: str | dict | list = 'Internal Server Error'
     status_code: int = status.HTTP_500_INTERNAL_SERVER_ERROR
 
     def __init__(
             self,
             detail: str | dict | list = None,
-            status_code: int = None
+            status_code: int = None,
+            headers: dict = None
     ):
         self.detail = detail or self.detail
         self.status_code = status_code or self.status_code
+        self.headers = headers
+
+
+class APIError(BaseError):
+    detail: str | dict | list = 'Internal Server Error'
+    status_code: int = status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+class WebsocketError(BaseError):
+    detail: str | dict | list = 'Internal Error'
+    status_code: int = status.WS_1011_INTERNAL_ERROR
+
+
+class RedirectAPIError(APIError):
+    def __init__(self, url: str, status_code: int = status.HTTP_302_FOUND):
+        super().__init__(headers={'Location': url}, status_code=status_code)
 
 
 class BadRequestAPIError(APIError):
@@ -52,6 +69,11 @@ class JSONDecodeAPIError(APIError):
     status_code = status.HTTP_422_UNPROCESSABLE_ENTITY
 
 
+class UpgradeRequiredError(APIError):
+    detail = 'This service requires use of the WebSocket protocol.'
+    status_code = status.HTTP_426_UPGRADE_REQUIRED
+
+
 class ThrottlingAPIError(APIError):
     detail = 'Too Many Request'
     status_code = status.HTTP_429_TOO_MANY_REQUESTS

panther/generics.py

@@ -146,7 +146,7 @@ class UpdateAPI(GenericAPI, ObjectRequired):
 
         await request.validated_data.update(
             instance=instance,
-            validated_data=request.validated_data.model_dump()
+            validated_data=request.validated_data.model_dump(by_alias=True)
         )
         return Response(data=instance, status_code=status.HTTP_200_OK)
 
@@ -156,7 +156,7 @@ class UpdateAPI(GenericAPI, ObjectRequired):
 
         await request.validated_data.partial_update(
             instance=instance,
-            validated_data=request.validated_data.model_dump(exclude_none=True)
+            validated_data=request.validated_data.model_dump(exclude_none=True, by_alias=True)
         )
         return Response(data=instance, status_code=status.HTTP_200_OK)