chore: docs

Author: cofin

docs/changelog.rst

@@ -11,31 +11,13 @@
         :pr: 482
         :issue: 481
 
-        <!--
-        By submitting this pull request, you agree to:
-        - follow [Litestar's Code of Conduct](https://github.com/litestar-org/.github/blob/main/CODE_OF_CONDUCT.md)
-        - follow [Litestar's contribution guidelines](https://github.com/litestar-org/.github/blob/main/CONTRIBUTING.md)
-        - follow the [PSFs's Code of Conduct](https://www.python.org/psf/conduct/)
-        -->
-        ## Description
-
         Adds [`DefaultBase`](https://github.com/litestar-org/advanced-alchemy/blob/6cc26ef8d53bc04f89a070337f8b0ab07a1bac46/advanced_alchemy/base.py#L517) class to `__all__` to match other public classes in the module.
 
-        <!--
-        Please add in issue numbers this pull request will close, if applicable
-        Examples: Fixes #4321 or Closes #1234
-
-        Ensure you are using a supported keyword to properly link an issue:
-        https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
-        -->
-        ## Fixes
-
-        #481
-
     .. change:: Update list and count
         :type: bugfix
         :pr: 487
 
+        Minor adjustment to the list and count method
 
 
 .. changelog:: 1.4.4

docs/usage/services.rst

@@ -12,11 +12,12 @@ Understanding Services
 Services provide:
 
 - Business logic abstraction
-- Data transformation using Pydantic or Msgspec models
-- Input validation
+- Data transformation using Pydantic, Msgspec, or attrs models
+- Input validation and type-safe schema conversion
 - Complex operations involving multiple repositories
 - Consistent error handling
 - Automatic schema validation and transformation
+- Support for SQLAlchemy query results (Row types) and RowMapping objects
 
 Basic Service Usage
 -------------------
@@ -210,6 +211,91 @@ The code below shows a service coordinating posts and tags.
                 data["slug"] = await self.repository.get_available_slug(data["name"])
             return await super().to_model(data, operation)
 
+Schema Integration
+------------------
+
+Advanced Alchemy services support multiple schema libraries for data transformation and validation:
+
+Pydantic Models
+***************
+
+.. code-block:: python
+
+    from pydantic import BaseModel
+    from typing import Optional
+
+    class UserSchema(BaseModel):
+        name: str
+        email: str
+        age: Optional[int] = None
+
+        model_config = {"from_attributes": True}
+
+    # Convert database model to Pydantic schema
+    user_data = service.to_schema(user_model, schema_type=UserSchema)
+
+Msgspec Structs
+***************
+
+.. code-block:: python
+
+    from msgspec import Struct
+    from typing import Optional
+
+    class UserStruct(Struct):
+        name: str
+        email: str
+        age: Optional[int] = None
+
+    # Convert database model to Msgspec struct
+    user_data = service.to_schema(user_model, schema_type=UserStruct)
+
+Attrs Classes
+*************
+
+.. code-block:: python
+
+    from attrs import define
+    from typing import Optional
+
+    @define
+    class UserAttrs:
+        name: str
+        email: str
+        age: Optional[int] = None
+
+    # Convert database model to attrs class
+    user_data = service.to_schema(user_model, schema_type=UserAttrs)
+
+.. note::
+
+    **Enhanced attrs Support with cattrs**: When both ``attrs`` and ``cattrs`` are installed,
+    Advanced Alchemy automatically uses ``cattrs.structure()`` and ``cattrs.unstructure()``
+    for improved performance and type-aware serialization. This provides better handling of
+    complex types, nested structures, and custom converters.
+
+SQLAlchemy Query Result Support
+*******************************
+
+Services now provide comprehensive support for SQLAlchemy query results:
+
+.. code-block:: python
+
+    from sqlalchemy import select
+
+    # Direct support for SQLAlchemy Row objects
+    query_results = await session.execute(select(User))
+    rows = query_results.fetchall()  # Returns list[Row[Any]]
+
+    # Convert Row objects to schema types
+    user_data = service.to_schema(rows[0], schema_type=UserSchema)
+    users_paginated = service.to_schema(rows, schema_type=UserSchema)
+
+    # Also supports RowMapping objects
+    row_mapping_results = await session.execute(select(User)).mappings()
+    mapping_data = service.to_schema(row_mapping_results.first(), schema_type=UserSchema)
+
+
 Framework Integration
 ---------------------
 

tests/unit/test_attrs_integration.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Optional
 
 import pytest
 from attrs import define, field
@@ -40,7 +40,7 @@ class AttrsWithOptional:
     """attrs class with optional fields."""
 
     name: str
-    email: str | None = None
+    email: Optional[str] = None  # noqa: UP045
     active: bool = True