fix: nullable relationship detection and FileObject nested metadata (#679)

* fix(dto): detect nullable one-to-one relationships on inverse side (#227)

`detect_nullable_relationship()` only checked MANYTOONE direction,
missing ONETOMANY+uselist=False (inverse side of one-to-one). Also
fixed `parse_type_from_element()` to not treat scalar one-to-one
relationships as collections.

* fix(file-object): serialize nested metadata for obstore attributes (#676)

Obstore attributes must be strings. Non-string metadata values (lists,
dicts, numbers) are now serialized via encode_json before passing to
obstore's put(). Fixes TypeError when FileObject has nested metadata.

Author: cofin

advanced_alchemy/extensions/litestar/dto.py

@@ -513,7 +513,10 @@ def parse_type_from_element(elem: ElementType, orm_descriptor: InspectionAttr) -
         return FieldDefinition.from_annotation(elem.type.python_type)
 
     if isinstance(elem, RelationshipProperty):
-        if elem.direction in {RelationshipDirection.ONETOMANY, RelationshipDirection.MANYTOMANY}:
+        if (
+            elem.direction in {RelationshipDirection.ONETOMANY, RelationshipDirection.MANYTOMANY}
+            and elem.uselist is not False
+        ):
             collection_type = FieldDefinition.from_annotation(elem.collection_class or list)  # pyright: ignore[reportUnknownMemberType]
             return FieldDefinition.from_annotation(collection_type.safe_generic_origin[elem.mapper.class_])
 
@@ -535,13 +538,16 @@ def parse_type_from_element(elem: ElementType, orm_descriptor: InspectionAttr) -
 def detect_nullable_relationship(elem: RelationshipProperty[Any]) -> bool:
     """Detects if a relationship is nullable.
 
-    This attempts to decide if we should allow a ``None`` default value for a relationship by looking at the
-    foreign key fields. If all foreign key fields are nullable, then we allow a ``None`` default value.
+    For MANYTOONE relationships (FK on this side), checks if all FK columns are nullable.
+    For ONETOMANY with uselist=False (inverse side of one-to-one), the related object may not
+    exist since no local FK enforces it, so these are always treated as nullable.
 
     Args:
         elem: The relationship to check.
 
     Returns:
         bool: ``True`` if the relationship is nullable, ``False`` otherwise.
     """
-    return elem.direction == RelationshipDirection.MANYTOONE and all(c.nullable for c in elem.local_columns)
+    if elem.direction == RelationshipDirection.MANYTOONE:
+        return all(c.nullable for c in elem.local_columns)
+    return elem.direction == RelationshipDirection.ONETOMANY and elem.uselist is False

advanced_alchemy/types/file_object/backends/obstore.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
+from advanced_alchemy._serialization import encode_json
 from advanced_alchemy.exceptions import MissingDependencyError
 from advanced_alchemy.types.file_object._utils import get_mtime_equivalent, get_or_generate_etag
 from advanced_alchemy.types.file_object.base import (
@@ -54,6 +55,28 @@ def schema_from_type(obj: Any) -> str:  # noqa: PLR0911
     return "file"
 
 
+def _serialize_metadata_for_attributes(metadata: "dict[str, Any]") -> "dict[str, str]":
+    """Serialize metadata values to strings for obstore attributes.
+
+    Obstore attributes must be strings. Non-string values (lists, dicts, etc.)
+    are serialized using the project's ``encode_json`` to avoid TypeError when
+    passed to obstore's ``put()``.
+
+    Args:
+        metadata: The metadata dict from a FileObject.
+
+    Returns:
+        A dict with all values as strings.
+    """
+    result: dict[str, str] = {}
+    for key, value in metadata.items():
+        if isinstance(value, str):
+            result[key] = value
+        else:
+            result[key] = encode_json(value)
+    return result
+
+
 class ObstoreBackend(StorageBackend):
     """Obstore-backed storage backend implementing both sync and async operations."""
 
@@ -132,8 +155,9 @@ def save_object(
             attributes["Content-Type"] = file_object.content_type
 
         # Add any custom metadata from file_object.metadata
+        # Obstore attributes must be strings, so serialize non-string values to JSON
         if file_object.metadata:
-            attributes.update(file_object.metadata)
+            attributes.update(_serialize_metadata_for_attributes(file_object.metadata))
 
         # LocalStore doesn't support attributes parameter - skip it for local filesystem
         put_params: dict[str, Any] = {
@@ -188,8 +212,9 @@ async def save_object_async(
             attributes["Content-Type"] = file_object.content_type
 
         # Add any custom metadata from file_object.metadata
+        # Obstore attributes must be strings, so serialize non-string values to JSON
         if file_object.metadata:
-            attributes.update(file_object.metadata)
+            attributes.update(_serialize_metadata_for_attributes(file_object.metadata))
 
         # LocalStore doesn't support attributes parameter - skip it for local filesystem
         put_params: dict[str, Any] = {

tests/integration/test_file_object.py

@@ -1831,6 +1831,34 @@ async def test_obstore_content_type_and_metadata_passing(storage_registry: Stora
     assert updated_obj_sync.metadata == custom_metadata
 
 
+@pytest.mark.xdist_group("file_object")
+async def test_obstore_nested_metadata_serialization(storage_registry: StorageRegistry) -> None:
+    """Test that nested metadata (lists, dicts) doesn't crash obstore's put().
+
+    Regression test for https://github.com/jolt-org/advanced-alchemy/issues/676.
+    Obstore attributes must be strings; non-string values are JSON-serialized.
+    """
+    remove_listeners()
+    backend = storage_registry.get_backend("memory")
+
+    nested_metadata = {
+        "tags": ["sample", "test"],
+        "nested": {"key": "value", "count": 42},
+        "flat_string": "just-a-string",
+        "number": 123,
+    }
+
+    # Async path
+    obj = FileObject(backend=backend, filename="nested_async.txt", metadata=nested_metadata)
+    updated_obj = await backend.save_object_async(obj, b"async content")
+    assert updated_obj.metadata == nested_metadata
+
+    # Sync path
+    obj_sync = FileObject(backend=backend, filename="nested_sync.txt", metadata=nested_metadata)
+    updated_obj_sync = backend.save_object(obj_sync, b"sync content")
+    assert updated_obj_sync.metadata == nested_metadata
+
+
 @pytest.mark.xdist_group("file_object")
 async def test_obstore_content_type_guessing(storage_registry: StorageRegistry) -> None:
     """Test that content_type is properly guessed when not explicitly set."""

tests/unit/test_extensions/test_litestar/test_dto.py

@@ -540,6 +540,47 @@ class B(Base):
     assert model.a is None
 
 
+async def test_dto_nullable_one_to_one_inverse_relationship(
+    create_module: Callable[[str], ModuleType],
+    asgi_connection: Request[Any, Any, Any],
+) -> None:
+    """Test that nullable one-to-one relationships on the inverse side (no FK) are handled correctly.
+
+    Regression test for https://github.com/jolt-org/advanced-alchemy/issues/227.
+    When the FK is on the other model and uselist=False, the DTO should allow None.
+    """
+    module = create_module(
+        """
+from __future__ import annotations
+
+from typing import Optional
+
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+from typing_extensions import Annotated
+
+from advanced_alchemy.extensions.litestar.dto import SQLAlchemyDTO, SQLAlchemyDTOConfig
+
+class Base(DeclarativeBase):
+    id: Mapped[int] = mapped_column(primary_key=True)
+
+class B(Base):
+    __tablename__ = "b"
+    a_id: Mapped[int] = mapped_column(ForeignKey("a.id"))
+    a: Mapped["A"] = relationship(back_populates="b")
+
+class A(Base):
+    __tablename__ = "a"
+    b: Mapped[Optional[B]] = relationship(back_populates="a")
+
+dto_type = SQLAlchemyDTO[Annotated[A, SQLAlchemyDTOConfig()]]
+""",
+    )
+    model = await get_model_from_dto(module.dto_type, module.A, asgi_connection, b'{"id": 1, "b": null}')
+    assert isinstance(model, module.A)
+    assert model.b is None
+
+
 async def test_forward_ref_relationship_resolution(
     create_module: Callable[[str], ModuleType],
     asgi_connection: Request[Any, Any, Any],