fix: correctly set uniquify from new (#424)

- Correctly sets `uniquify` when passed in from `new` or `__init__` 
- Introduced tests for `sync_tools` utilities, including `maybe_async_`, `maybe_async_context`, `SoonValue`, `TaskGroup`, and others.
- Ensured comprehensive coverage for async and sync function handling, context managers, and value management.
- Improved overall test suite reliability and maintainability.

Author: cofin

advanced_alchemy/_serialization.py

@@ -5,7 +5,7 @@
 from typing_extensions import runtime_checkable
 
 try:
-    from pydantic import BaseModel  # type: ignore # noqa: PGH003
+    from pydantic import BaseModel  # type: ignore
 
     PYDANTIC_INSTALLED = True
 except ImportError:
@@ -18,7 +18,11 @@ class BaseModel(Protocol):  # type: ignore[no-redef]
         model_fields: ClassVar[dict[str, Any]]
 
         def model_dump_json(self, *args: Any, **kwargs: Any) -> str:
-            """Placeholder"""
+            """Placeholder for pydantic.BaseModel.model_dump_json
+
+            Returns:
+                The JSON representation of the model.
+            """
             return ""
 
     PYDANTIC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]

advanced_alchemy/alembic/templates/asyncio/env.py

@@ -20,7 +20,7 @@
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
-config: "AlembicCommandConfig" = context.config  # type: ignore  # noqa: PGH003
+config: "AlembicCommandConfig" = context.config  # type: ignore
 writer = rewriter.Rewriter()
 
 
@@ -30,7 +30,16 @@ def order_columns(
     revision: tuple[str, ...],  # noqa: ARG001
     op: ops.CreateTableOp,
 ) -> ops.CreateTableOp:
-    """Orders ID first and the audit columns at the end."""
+    """Orders ID first and the audit columns at the end.
+
+    Args:
+        context: The context of the environment.
+        revision: The revision of the environment.
+        op: The operation to create the table.
+
+    Returns:
+        The operation to create the table.
+    """
     special_names = {"id": -100, "sa_orm_sentinel": 3001, "created_at": 3002, "updated_at": 3003}
     cols_by_key = [  # pyright: ignore[reportUnknownVariableType]
         (
@@ -100,6 +109,9 @@ async def run_migrations_online() -> None:
 
     In this scenario we need to create an Engine and associate a
     connection with the context.
+
+    Raises:
+        RuntimeError: If the engine cannot be created from the config.
     """
     configuration = config.get_section(config.config_ini_section) or {}
     configuration["sqlalchemy.url"] = config.db_url

advanced_alchemy/alembic/templates/sync/env.py

@@ -1,3 +1,4 @@
+import operator
 from typing import TYPE_CHECKING, cast
 
 from sqlalchemy import Column, Engine, engine_from_config, pool
@@ -18,7 +19,7 @@
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
-config: "AlembicCommandConfig" = context.config  # type: ignore  # noqa: PGH003
+config: "AlembicCommandConfig" = context.config  # type: ignore
 writer = rewriter.Rewriter()
 
 
@@ -28,7 +29,16 @@ def order_columns(
     revision: tuple[str, ...],  # noqa: ARG001
     op: ops.CreateTableOp,
 ) -> ops.CreateTableOp:
-    """Orders ID first and the audit columns at the end."""
+    """Orders ID first and the audit columns at the end.
+
+    Args:
+        context: The context of the environment.
+        revision: The revision of the environment.
+        op: The operation to create the table.
+
+    Returns:
+        The operation to create the table.
+    """
     special_names = {"id": -100, "sa_orm_sentinel": 3001, "created_at": 3002, "updated_at": 3003}
     cols_by_key = [  # pyright: ignore[reportUnknownVariableType]
         (
@@ -37,7 +47,7 @@ def order_columns(
         )
         for index, col in enumerate(op.columns)
     ]
-    columns = [col for _, col in sorted(cols_by_key, key=lambda entry: entry[0])]  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType,reportUnknownLambdaType]
+    columns = [col for _, col in sorted(cols_by_key, key=operator.itemgetter(0))]  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType,reportUnknownLambdaType]
     return ops.CreateTableOp(
         op.table_name,
         columns,  # pyright: ignore[reportUnknownArgumentType]
@@ -97,6 +107,9 @@ def run_migrations_online() -> None:
 
     In this scenario we need to create an Engine and associate a
     connection with the context.
+
+    Raises:
+        RuntimeError: If the engine cannot be created from the config.
     """
     configuration = config.get_section(config.config_ini_section) or {}
     configuration["sqlalchemy.url"] = config.db_url

advanced_alchemy/config/common.py

@@ -80,7 +80,7 @@ class GenericSessionConfig(Generic[ConnectionT, EngineT, SessionT]):
     autoflush: "Union[bool, EmptyType]" = Empty
     """When ``True``, all query operations will issue a flush call to this :class:`Session <sqlalchemy.orm.Session>`
     before proceeding"""
-    bind: "Union[EngineT, ConnectionT, None, EmptyType]" = Empty
+    bind: "Optional[Union[EngineT, ConnectionT, EmptyType]]" = Empty
     """The :class:`Engine <sqlalchemy.engine.Engine>` or :class:`Connection <sqlalchemy.engine.Connection>` that new
     :class:`Session <sqlalchemy.orm.Session>` objects will be bound to."""
     binds: "Union[dict[Union[type[Any], Mapper[Any], TableClause, str], Union[EngineT, ConnectionT]], None, EmptyType]" = Empty
@@ -234,6 +234,9 @@ def session_config_dict(self) -> dict[str, Any]:
     def get_engine(self) -> EngineT:
         """Return an engine. If none exists yet, create one.
 
+        Raises:
+            ImproperConfigurationError: if neither `connection_string` nor `engine_instance` are provided.
+
         Returns:
             :class:`sqlalchemy.Engine` or :class:`sqlalchemy.ext.asyncio.AsyncEngine` instance used by the plugin.
         """
@@ -246,12 +249,13 @@ def get_engine(self) -> EngineT:
 
         engine_config = self.engine_config_dict
         try:
-            return self.create_engine_callable(self.connection_string, **engine_config)
+            self.engine_instance = self.create_engine_callable(self.connection_string, **engine_config)
         except TypeError:
             # likely due to a dialect that doesn't support json type
             del engine_config["json_deserializer"]
             del engine_config["json_serializer"]
-            return self.create_engine_callable(self.connection_string, **engine_config)
+            self.engine_instance = self.create_engine_callable(self.connection_string, **engine_config)
+        return self.engine_instance
 
     def create_session_maker(self) -> "Callable[[], SessionT]":  # pragma: no cover
         """Get a session maker. If none exists yet, create one.
@@ -265,7 +269,8 @@ def create_session_maker(self) -> "Callable[[], SessionT]":  # pragma: no cover
         session_kws = self.session_config_dict
         if session_kws.get("bind") is None:
             session_kws["bind"] = self.get_engine()
-        return cast("Callable[[], SessionT]", self.session_maker_class(**session_kws))
+        self.session_maker = cast("Callable[[], SessionT]", self.session_maker_class(**session_kws))
+        return self.session_maker
 
 
 @dataclass

advanced_alchemy/extensions/litestar/dto.py

@@ -294,8 +294,6 @@ def generate_field_definitions(cls, model_type: type[DeclarativeBase]) -> Genera
 
         Raises:
             RuntimeError: If the mapper cannot be found for the model type.
-            NotImplementedError: If an unsupported property or extension type is encountered.
-            ImproperConfigurationError: If a type cannot be parsed from an element.
         """
         if (mapper := inspect(model_type)) is None:  # pragma: no cover # pyright: ignore[reportUnnecessaryComparison]
             msg = "Unexpected `None` value for mapper."  # type: ignore[unreachable]
@@ -330,7 +328,7 @@ def generate_field_definitions(cls, model_type: type[DeclarativeBase]) -> Genera
             should_skip_descriptor = False
             dto_field: Optional[DTOField] = None
             if hasattr(orm_descriptor, "property"):  # pyright: ignore[reportUnknownArgumentType]
-                dto_field = orm_descriptor.property.info.get(DTO_FIELD_META_KEY)  # pyright: ignore  # noqa: PGH003
+                dto_field = orm_descriptor.property.info.get(DTO_FIELD_META_KEY)  # pyright: ignore
 
             # Case 1
             is_field_marked_not_private = dto_field and dto_field.mark is not Mark.PRIVATE  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
@@ -370,7 +368,7 @@ def detect_nested_field(cls, field_definition: FieldDefinition) -> bool:
 
 def _detect_defaults(elem: ElementType) -> tuple[Any, Any]:
     default: Any = Empty
-    default_factory: Any = None  # pyright:ignore  # noqa: PGH003
+    default_factory: Any = None  # pyright:ignore
     if sqla_default := getattr(elem, "default", None):
         if sqla_default.is_scalar:
             default = sqla_default.arg
@@ -402,11 +400,11 @@ def parse_type_from_element(elem: ElementType, orm_descriptor: InspectionAttr) -
         elem: The SQLAlchemy element to parse.
         orm_descriptor: The attribute `elem` was extracted from.
 
+    Raises:
+        ImproperConfigurationError: If the type cannot be parsed.
+
     Returns:
         FieldDefinition: The parsed type.
-
-    Raises:
-        ImproperlyConfiguredException: If the type cannot be parsed.
     """
 
     if isinstance(elem, Column):
@@ -415,7 +413,7 @@ 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}:
             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_])
 
@@ -431,9 +429,7 @@ def parse_type_from_element(elem: ElementType, orm_descriptor: InspectionAttr) -
         return FieldDefinition.from_annotation(orm_descriptor.type.python_type)
 
     msg = f"Unable to parse type from element '{elem}'. Consider adding a type hint."
-    raise ImproperConfigurationError(
-        msg,
-    )
+    raise ImproperConfigurationError(msg)
 
 
 def detect_nullable_relationship(elem: RelationshipProperty[Any]) -> bool:

advanced_alchemy/extensions/litestar/providers.py

@@ -43,6 +43,7 @@
     SQLAlchemyAsyncRepositoryService,
     SQLAlchemySyncRepositoryService,
 )
+from advanced_alchemy.utils.singleton import SingletonMeta
 
 if TYPE_CHECKING:
     from sqlalchemy import Select
@@ -109,17 +110,6 @@ class FilterConfig(TypedDict):
     """When set, updated_at filter is enabled."""
 
 
-class SingletonMeta(type):
-    """Metaclass for singleton pattern."""
-
-    _instances: dict[type, Any] = {}
-
-    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
-        if cls not in cls._instances:  # pyright: ignore[reportUnnecessaryContains]
-            cls._instances[cls] = super().__call__(*args, **kwargs)
-        return cls._instances[cls]
-
-
 class DependencyCache(metaclass=SingletonMeta):
     """Simple dependency cache for the application.  This is used to help memoize dependencies that are generated dynamically."""
 
@@ -175,7 +165,11 @@ def create_service_provider(
     uniquify: Optional[bool] = None,
     count_with_window_function: Optional[bool] = None,
 ) -> Callable[..., Union["AsyncGenerator[AsyncServiceT_co, None]", "Generator[SyncServiceT_co,None, None]"]]:
-    """Create a dependency provider for a service."""
+    """Create a dependency provider for a service.
+
+    Returns:
+        A dependency provider for the service.
+    """
     if issubclass(service_class, SQLAlchemyAsyncRepositoryService) or service_class is SQLAlchemyAsyncRepositoryService:  # type: ignore[comparison-overlap]
 
         async def provide_async_service(

advanced_alchemy/extensions/sanic/config.py

@@ -21,7 +21,7 @@
     SANIC_INSTALLED = True
 except ModuleNotFoundError:  # pragma: no cover
     SANIC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
-    Extend = type("Extend", (), {})  # type: ignore  # noqa: PGH003
+    Extend = type("Extend", (), {})  # type: ignore
 
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
 from sqlalchemy.orm import Session, sessionmaker

advanced_alchemy/extensions/sanic/extension.py

@@ -14,8 +14,8 @@
     SANIC_INSTALLED = True
 except ModuleNotFoundError:  # pragma: no cover
     SANIC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
-    Extension = type("Extension", (), {})  # type: ignore  # noqa: PGH003
-    Extend = type("Extend", (), {})  # type: ignore  # noqa: PGH003
+    Extension = type("Extension", (), {})  # type: ignore
+    Extend = type("Extend", (), {})  # type: ignore
 
 if TYPE_CHECKING:
     from sanic import Sanic