Add DAO protocol deprecation warnings (GSI-976) (#128)

* Add DAO protocol deprecation warnings

* Add warning specifically for MongoDb provider with instructions

* Update deprecation msg to mention default factory

Co-authored-by: Christoph Zwerschke <c.zwerschke@dkfz-heidelberg.de>

---------

Co-authored-by: Christoph Zwerschke <c.zwerschke@dkfz-heidelberg.de>

src/hexkit/protocols/dao.py

@@ -21,6 +21,7 @@
 # ruff: noqa: PLR0913
 
 import typing
+import warnings
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Collection, Mapping
 from contextlib import AbstractAsyncContextManager
@@ -29,6 +30,7 @@
 from uuid import uuid4
 
 from pydantic import BaseModel
+from typing_extensions import deprecated
 
 from hexkit.utils import FieldNotInModelError, validate_fields_in_model
 
@@ -259,6 +261,9 @@ async def upsert(self, dto: Dto) -> None:
         ...
 
 
+@deprecated(
+    "uuid4_id_generator is deprecated as of v3.6 and will be removed in hexkit v4."
+)
 async def uuid4_id_generator() -> AsyncGenerator[str, None]:
     """Generates a new ID using the UUID4 algorithm.
     This is an AsyncGenerator to be compliant with the id_generator requirements of the
@@ -441,6 +446,15 @@ async def get_dao(
             # instantiate the default ID generator:
             id_generator = uuid4_id_generator()
 
+        if dto_creation_model is not None:
+            dep_msg = (
+                "The DAO API (and existing providers) are deprecated as of v3.6."
+                + " They will be simplified in hexkit v4."
+                + " Please plan to provide IDs during resource creation. The same model"
+                + " should be used for both creation and retrieval."
+            )
+            warnings.warn(dep_msg, category=DeprecationWarning, stacklevel=2)
+
         return await self._get_dao(
             name=name,
             dto_model=dto_model,

src/hexkit/providers/mongodb/provider.py

@@ -22,6 +22,7 @@
 # ruff: noqa: PLR0913
 
 import json
+import warnings
 from abc import ABC
 from collections.abc import AsyncGenerator, AsyncIterator, Collection, Mapping
 from contextlib import AbstractAsyncContextManager
@@ -163,6 +164,17 @@ def __init__(
         self._document_to_dto = document_to_dto
         self._dto_to_document = dto_to_document
 
+        warnings.warn(
+            "The MongoDbDaoBase class and subclasses are deprecated as of v3.6 and will"
+            + " be replaced in hexkit v4 with the new MongoDbDao class. To replace the"
+            + " MongoDbDaoNaturalId: just use the new class. To replace the"
+            + " MongoDbDaoSurrogateId: use the new class, remove the creation model and"
+            + " id_generator parameters, and make sure the supplied DTO model includes"
+            + " the ID field with a default factory for generating new IDs.",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+
     async def get_by_id(self, id_: str) -> Dto:
         """Get a resource by providing its ID.