feat: add Enum to default type decoders (#397)

Extends the default type decoders to handle Enum types by converting them to their underlying value during serialization

Author: cofin

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.9.6"
+    rev: "v0.9.7"
     hooks:
       # Run the linter.
     - id: ruff

advanced_alchemy/_serialization.py

@@ -1,22 +1,77 @@
+import datetime
+import enum
 from typing import Any
 
+from typing_extensions import runtime_checkable
+
+try:
+    from pydantic import BaseModel  # type: ignore # noqa: PGH003
+
+    PYDANTIC_INSTALLED = True
+except ImportError:
+    from typing import ClassVar, Protocol
+
+    @runtime_checkable
+    class BaseModel(Protocol):  # type: ignore[no-redef]
+        """Placeholder Implementation"""
+
+        model_fields: ClassVar[dict[str, Any]]
+
+        def model_dump_json(self, *args: Any, **kwargs: Any) -> str:
+            """Placeholder"""
+            return ""
+
+    PYDANTIC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+
+def _type_to_string(value: Any) -> str:  # pragma: no cover
+    if isinstance(value, datetime.datetime):
+        return convert_datetime_to_gmt_iso(value)
+    if isinstance(value, datetime.date):
+        return convert_date_to_iso(value)
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    if PYDANTIC_INSTALLED and isinstance(value, BaseModel):
+        return value.model_dump_json()
+    try:
+        val = str(value)
+    except Exception as exc:
+        raise TypeError from exc
+    return val
+
+
 try:
     from msgspec.json import Decoder, Encoder
 
-    encoder, decoder = Encoder(), Decoder()
+    encoder, decoder = Encoder(enc_hook=_type_to_string), Decoder()
     decode_json = decoder.decode
 
-    def encode_json(data: Any) -> str:
+    def encode_json(data: Any) -> str:  # pragma: no cover
         return encoder.encode(data).decode("utf-8")
 
 except ImportError:
     try:
+        from orjson import OPT_NAIVE_UTC, OPT_SERIALIZE_NUMPY, OPT_SERIALIZE_UUID
         from orjson import dumps as _encode_json
         from orjson import loads as decode_json  # type: ignore[no-redef,assignment]
 
-        def encode_json(data: Any) -> str:
-            return _encode_json(data).decode("utf-8")  # type: ignore[no-any-return]
+        def encode_json(data: Any) -> str:  # pragma: no cover
+            return _encode_json(
+                data, default=_type_to_string, option=OPT_SERIALIZE_NUMPY | OPT_NAIVE_UTC | OPT_SERIALIZE_UUID
+            ).decode("utf-8")  # type: ignore[no-any-return]
 
     except ImportError:
         from json import dumps as encode_json  # type: ignore[assignment] # noqa: F401
         from json import loads as decode_json  # type: ignore[assignment]  # noqa: F401
+
+
+def convert_datetime_to_gmt_iso(dt: datetime.datetime) -> str:  # pragma: no cover
+    """Handle datetime serialization for nested timestamps."""
+    if not dt.tzinfo:
+        dt = dt.replace(tzinfo=datetime.timezone.utc)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def convert_date_to_iso(dt: datetime.date) -> str:  # pragma: no cover
+    """Handle datetime serialization for nested timestamps."""
+    return dt.isoformat()

advanced_alchemy/extensions/litestar/plugins/init/plugin.py

@@ -21,7 +21,7 @@
     OrderBy,
     SearchFilter,
 )
-from advanced_alchemy.service import OffsetPagination
+from advanced_alchemy.service import ModelDictListT, ModelDictT, ModelDTOT, ModelOrRowMappingT, ModelT, OffsetPagination
 
 if TYPE_CHECKING:
     from click import Group
@@ -47,6 +47,11 @@
     "Dependency": Dependency,
     "DTOData": DTOData,
     "Sequence": Sequence,
+    "ModelT": ModelT,
+    "ModelDictT": ModelDictT,
+    "ModelDTOT": ModelDTOT,
+    "ModelDictListT": ModelDictListT,
+    "ModelOrRowMappingT": ModelOrRowMappingT,
 }
 
 

advanced_alchemy/service/_typing.py

@@ -18,7 +18,7 @@
 T_co = TypeVar("T_co", covariant=True)
 
 try:
-    from pydantic import BaseModel, FailFast, TypeAdapter
+    from pydantic import BaseModel, FailFast, TypeAdapter  # pyright: ignore[reportGeneralTypeIssues]
 
     PYDANTIC_INSTALLED = True
 except ImportError:
@@ -72,8 +72,8 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
     from msgspec import (
         UNSET,
         Struct,
-        UnsetType,  # pyright: ignore[reportAssignmentType]
-        convert,
+        UnsetType,  # pyright: ignore[reportAssignmentType,reportGeneralTypeIssues]
+        convert,  # pyright: ignore[reportGeneralTypeIssues]
     )
 
     MSGSPEC_INSTALLED: bool = True

advanced_alchemy/service/_util.py

@@ -6,6 +6,7 @@
 
 import datetime
 from collections.abc import Sequence
+from enum import Enum
 from functools import partial
 from pathlib import Path, PurePath
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union, cast, overload
@@ -38,6 +39,7 @@
     (lambda x: x is datetime.datetime, lambda t, v: t(v.isoformat())),  # pyright: ignore[reportUnknownLambdaType,reportUnknownMemberType]
     (lambda x: x is datetime.date, lambda t, v: t(v.isoformat())),  # pyright: ignore[reportUnknownLambdaType,reportUnknownMemberType]
     (lambda x: x is datetime.time, lambda t, v: t(v.isoformat())),  # pyright: ignore[reportUnknownLambdaType,reportUnknownMemberType]
+    (lambda x: x is Enum, lambda t, v: t(v.value)),  # pyright: ignore[reportUnknownLambdaType,reportUnknownMemberType]
 ]
 
 

docs/conf.py

@@ -15,7 +15,7 @@
 if TYPE_CHECKING:
     from typing import Any
 
-    from sphinx.addnodes import document
+    from sphinx.addnodes import document  # type: ignore[attr-defined,unused-ignore]
     from sphinx.application import Sphinx
 
 # -- Environmental Data ------------------------------------------------------

docs/usage/frameworks/fastapi.rst

@@ -11,32 +11,21 @@ Configure SQLAlchemy with FastAPI:
 
 .. code-block:: python
 
-    from contextlib import asynccontextmanager
     from typing import AsyncGenerator
 
     from fastapi import FastAPI
 
-    from advanced_alchemy.config import AsyncSessionConfig, SQLAlchemyAsyncConfig
-    from advanced_alchemy.base import metadata_registry
-    from advanced_alchemy.extensions.starlette import StarletteAdvancedAlchemy
+    from advanced_alchemy.extensions.fastapi import AdvancedAlchemy, AsyncSessionConfig, SQLAlchemyAsyncConfig
 
-    session_config = AsyncSessionConfig(expire_on_commit=False)
     sqlalchemy_config = SQLAlchemyAsyncConfig(
         connection_string="sqlite+aiosqlite:///test.sqlite",
-        session_config=session_config
+        session_config=AsyncSessionConfig(expire_on_commit=False),
+        create_all=True,
+        commit_mode="autocommit",
     )
 
-    @asynccontextmanager
-    async def on_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
-        """Initializes the database."""
-        metadata = metadata_registry.get(sqlalchemy_config.bind_key)
-        if sqlalchemy_config.create_all:
-            async with sqlalchemy_config.get_engine().begin() as conn:
-                await conn.run_sync(metadata.create_all)
-        yield
-
-    app = FastAPI(lifespan=on_lifespan)
-    alchemy = StarletteAdvancedAlchemy(config=sqlalchemy_config, app=app)
+    app = FastAPI()
+    alchemy = AdvancedAlchemy(config=sqlalchemy_config, app=app)
 
 Models and Schemas
 ------------------
@@ -88,38 +77,40 @@ Create repository and service classes:
 
 .. code-block:: python
 
+    from typing import Annotated, AsyncGenerator, Optional
+
+    from advanced_alchemy.extensions.fastapi import repository, service
+    from fastapi import Depends
     from sqlalchemy.ext.asyncio import AsyncSession
-    from advanced_alchemy.repository import SQLAlchemyAsyncRepository
-    from advanced_alchemy.service import SQLAlchemyAsyncRepositoryService
-    from typing import AsyncGenerator
 
-    class AuthorRepository(SQLAlchemyAsyncRepository[AuthorModel]):
-        """Author repository."""
-        model_type = AuthorModel
 
-    class AuthorService(SQLAlchemyAsyncRepositoryService[AuthorModel]):
+    class AuthorService(service.SQLAlchemyAsyncRepositoryService[AuthorModel]):
         """Author service."""
-        repository_type = AuthorRepository
 
-    async def provide_authors_service(
-        db_session: Annotated[AsyncSession, Depends(provide_db_session)],
-    ) -> AsyncGenerator[AuthorService, None]:
-        """This provides the default Authors repository."""
-        async with AuthorService.new(session=db_session) as service:
-            yield service
+        class Repo(repository.SQLAlchemyAsyncRepository[AuthorModel]):
+            """Author repository."""
+            model_type = AuthorModel
+
+        repository_type = Repo
+
 
 Dependency Injection
 --------------------
 
-Set up dependency injection for the database session:
+Set up dependency injected into the request context.
 
 .. code-block:: python
 
     from fastapi import Request
 
-    async def provide_db_session(request: Request) -> AsyncSession:
-        """Provide a DB session."""
-        return alchemy.get_session(request) # this is the `StarletteAdvancedAlchemy` object
+    DatabaseSession = Annotated[AsyncSession, Depends(alchemy.provide_session())]
+    Authors = Annotated[AuthorService, Depends(provide_authors_service)]
+
+    async def provide_authors_service(db_session: DatabaseSession) -> AsyncGenerator[AuthorService, None]:
+        """This provides the default Authors repository."""
+        async with AuthorService.new(session=db_session) as service:
+            yield service
+
 
 Controllers
 -----------
@@ -130,32 +121,31 @@ Create controllers using the service:
 
     from fastapi import APIRouter, Depends
     from uuid import UUID
-    from advanced_alchemy.filters import LimitOffset
-    from advanced_alchemy.service import OffsetPagination
+    from advanced_alchemy.extensions.fastapi import filters
 
     author_router = APIRouter()
 
-    @author_router.get(path="/authors", response_model=OffsetPagination[Author])
+    @author_router.get(path="/authors", response_model=filters.OffsetPagination[Author])
     async def list_authors(
-        authors_service: Annotated[AuthorService, Depends(provide_authors_service)],
-        limit_offset: Annotated[LimitOffset, Depends(provide_limit_offset_pagination)],
-    ) -> OffsetPagination[AuthorModel]:
+        authors_service: Authors,
+        limit_offset: Annotated[filters.LimitOffset, Depends(provide_limit_offset_pagination)],
+    ) -> filters.OffsetPagination[AuthorModel]:
         """List authors."""
         results, total = await authors_service.list_and_count(limit_offset)
         return authors_service.to_schema(results, total, filters=[limit_offset])
 
     @author_router.post(path="/authors", response_model=Author)
     async def create_author(
-        authors_service: Annotated[AuthorService, Depends(provide_authors_service)],
+        authors_service: Authors,
         data: AuthorCreate,
     ) -> AuthorModel:
         """Create a new author."""
-        obj = await authors_service.create(data.model_dump(exclude_unset=True, exclude_none=True), auto_commit=True)
+        obj = await authors_service.create(data)
         return authors_service.to_schema(obj)
 
     @author_router.get(path="/authors/{author_id}", response_model=Author)
     async def get_author(
-        authors_service: Annotated[AuthorService, Depends(provide_authors_service)],
+        authors_service: Authors,
         author_id: UUID,
     ) -> AuthorModel:
         """Get an existing author."""
@@ -164,25 +154,21 @@ Create controllers using the service:
 
     @author_router.patch(path="/authors/{author_id}", response_model=Author)
     async def update_author(
-        authors_service: Annotated[AuthorService, Depends(provide_authors_service)],
+        authors_service: Authors,
         data: AuthorUpdate,
         author_id: UUID,
     ) -> AuthorModel:
         """Update an author."""
-        obj = await authors_service.update(
-            data.model_dump(exclude_unset=True, exclude_none=True),
-            item_id=author_id,
-            auto_commit=True,
-        )
+        obj = await authors_service.update(data, item_id=author_id)
         return authors_service.to_schema(obj)
 
     @author_router.delete(path="/authors/{author_id}")
     async def delete_author(
-        authors_service: Annotated[AuthorService, Depends(provide_authors_service)],
+        authors_service: Authors,
         author_id: UUID,
     ) -> None:
         """Delete an author from the system."""
-        _ = await authors_service.delete(author_id, auto_commit=True)
+        _ = await authors_service.delete(author_id)
 
 Application Configuration
 -------------------------

examples/standalone_json.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import asyncio
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from sqlalchemy.ext.asyncio import create_async_engine
 
@@ -17,7 +17,7 @@
 class Item(UUIDBase):
     name: Mapped[str]
     # using ``Mapped[dict]`` with an AA provided base will map it to ``JSONB``
-    data: Mapped[dict]
+    data: Mapped[dict[str, Any]]
 
 
 class ItemRepository(SQLAlchemyAsyncRepository[Item]):