docs: Add doc for creating a custom model (#333)

* docs: fix docs service for service with msgspec

* docs: add example for creation custom model

* docs: fix title

* docs: clean up wording

---------

Co-authored-by: Cody Fincher <[email protected]>

Author: Kumzy

docs/usage/modeling.rst

@@ -242,4 +242,59 @@ Here's how to use these models with the UniqueMixin:
         await session.flush()
         return post
 
+
+
+Customizing Declarative Base
+-----------------------------
+
+In case one of the built in declarative bases do not meet your needs (or you already have your own), Advanced Alchemy already supports customizing the ``DeclarativeBase`` class.
+
+Here's an example showing a class to generate a server-side UUID primary key for `postgres`:
+
+.. code-block:: python
+
+    from datetime import datetime
+    from uuid import UUID, uuid4
+
+    from advanced_alchemy.base import CommonTableAttributes, orm_registry
+    from sqlalchemy import text
+    from sqlalchemy.orm import (
+        DeclarativeBase,
+        Mapped,
+        declared_attr,
+        mapped_column,
+        orm_insert_sentinel,
+    )
+
+
+    class ServerSideUUIDPrimaryKey:
+        """UUID Primary Key Field Mixin."""
+
+        id: Mapped[UUID] = mapped_column(default=uuid4, primary_key=True, server_default=text("gen_random_uuid()"))
+        """UUID Primary key column."""
+
+        # noinspection PyMethodParameters
+        @declared_attr
+        def _sentinel(cls) -> Mapped[int]:
+            """Sentinel value required for SQLAlchemy bulk DML with UUIDs."""
+            return orm_insert_sentinel(name="sa_orm_sentinel")
+
+
+    class ServerSideUUIDBase(ServerSideUUIDPrimaryKey, CommonTableAttributes, DeclarativeBase):
+        """Base for all SQLAlchemy declarative models with the custom UUID primary key ."""
+
+        registry = orm_registry
+
+
+    # Using ServerSideUUIDBase
+    class User(ServerSideUUIDBase):
+        """User model with ServerSideUUIDBase."""
+
+        username: Mapped[str] = mapped_column(unique=True, index=True)
+        email: Mapped[str] = mapped_column(unique=True)
+        full_name: Mapped[str]
+        is_active: Mapped[bool] = mapped_column(default=True)
+        last_login: Mapped[datetime | None] = mapped_column(default=None)
+
+
 With this foundation in place, let's look at the repository pattern.

docs/usage/services.rst

@@ -225,9 +225,9 @@ Services can handle complex business logic involving multiple repositories:
 
         async def to_model(self, data: ModelDictT[Post], operation: str | None = None) -> Post:
             """Convert a dictionary, Msgspec model, or Pydantic model to a Post model."""
-            if (is_msgspec_model(data) or is_pydantic_model(data)) and operation == "create" and data.slug is None:
+            if (is_msgspec_struct(data) or is_pydantic_model(data)) and operation == "create" and data.slug is None:
                 data.slug = await self.repository.get_available_slug(data.name)
-            if (is_msgspec_model(data) or is_pydantic_model(data)) and operation == "update" and data.slug is None:
+            if (is_msgspec_struct(data) or is_pydantic_model(data)) and operation == "update" and data.slug is None:
                 data.slug = await self.repository.get_available_slug(data.name)
             if is_dict(data) and "slug" not in data and operation == "create":
                 data["slug"] = await self.repository.get_available_slug(data["name"])