Check and warn in case the 'hidden' parameter is used

beanie/odm/documents.py

@@ -1,4 +1,5 @@
 import asyncio
+import warnings
 from typing import (
     Any,
     ClassVar,
@@ -83,6 +84,7 @@
 from beanie.odm.utils.parsing import merge_models
 from beanie.odm.utils.pydantic import (
     IS_PYDANTIC_V2,
+    get_extra_field_info,
     get_field_type,
     get_model_dump,
     get_model_fields,
@@ -1043,6 +1045,30 @@ async def inspect_collection(
                 )
         return inspection_result
 
+    @classmethod
+    def check_hidden_fields(cls):
+        hidden_fields = [
+            (name, field)
+            for name, field in get_model_fields(cls).items()
+            if get_extra_field_info(field, "hidden") is True
+        ]
+        if not hidden_fields:
+            return
+        warnings.warn(
+            f"{cls.__name__}: 'hidden=True' is deprecated, please use 'exclude=True'",
+            DeprecationWarning,
+        )
+        if IS_PYDANTIC_V2:
+            for name, field in hidden_fields:
+                field.exclude = True
+                del field.json_schema_extra["hidden"]
+            cls.model_rebuild(force=True)
+        else:
+            for name, field in hidden_fields:
+                field.field_info.exclude = True
+                del field.field_info.extra["hidden"]
+                cls.__exclude_fields__[name] = True
+
     @wrap_with_actions(event_type=EventTypes.VALIDATE_ON_SAVE)
     async def validate_self(self, *args, **kwargs):
         # TODO: it can be sync, but needs some actions controller improvements

beanie/odm/utils/init.py

@@ -373,6 +373,8 @@ def check_nested_links(
                 cls._link_fields[k] = link_info
                 check_nested_links(link_info, prev_models=[])
 
+        cls.check_hidden_fields()
+
     @staticmethod
     def init_actions(cls):
         """

tests/odm/conftest.py

@@ -38,6 +38,7 @@
     DocumentWithCustomIdUUID,
     DocumentWithCustomInit,
     DocumentWithDecimalField,
+    DocumentWithDeprecatedHiddenField,
     DocumentWithExtras,
     DocumentWithIndexMerging1,
     DocumentWithIndexMerging2,
@@ -198,6 +199,7 @@ async def init(db):
         DocumentTestModelWithComplexIndex,
         DocumentTestModelFailInspection,
         DocumentWithBsonEncodersFiledsTypes,
+        DocumentWithDeprecatedHiddenField,
         DocumentWithCustomFiledsTypes,
         DocumentWithCustomIdUUID,
         DocumentWithCustomIdInt,

tests/odm/models.py

@@ -235,6 +235,13 @@ class Settings:
         name = "DocumentTestModel"
 
 
+class DocumentWithDeprecatedHiddenField(Document):
+    if IS_PYDANTIC_V2:
+        test_hidden: List[str] = Field(json_schema_extra={"hidden": True})
+    else:
+        test_hidden: List[str] = Field(hidden=True)
+
+
 class DocumentWithCustomIdUUID(Document):
     id: UUID = Field(default_factory=uuid4)
     name: str

tests/odm/test_fields.py

@@ -16,6 +16,7 @@
     DocumentTestModel,
     DocumentWithBsonEncodersFiledsTypes,
     DocumentWithCustomFiledsTypes,
+    DocumentWithDeprecatedHiddenField,
     Sample,
 )
 
@@ -114,6 +115,16 @@ async def test_excluded(document):
         assert "test_list" not in document.dict()
 
 
+async def test_hidden():
+    document = DocumentWithDeprecatedHiddenField(test_hidden=["abc", "def"])
+    await document.insert()
+    document = await DocumentWithDeprecatedHiddenField.find_one()
+    if IS_PYDANTIC_V2:
+        assert "test_hidden" not in document.model_dump()
+    else:
+        assert "test_hidden" not in document.dict()
+
+
 def test_revision_id_not_in_schema():
     """Check if there is a `revision_id` slipping into the schema."""