feat: add uniqueness, returned and case_exact filters to iter_paths

Author: azmeuk

scim2_models/path.py

@@ -18,8 +18,11 @@
 from .utils import _to_camel
 
 if TYPE_CHECKING:
+    from .annotations import CaseExact
     from .annotations import Mutability
     from .annotations import Required
+    from .annotations import Returned
+    from .annotations import Uniqueness
     from .resources.resource import Resource
 
 from .exceptions import InvalidPathException
@@ -666,6 +669,9 @@ def iter_paths(
         include_extensions: bool = True,
         required: "list[Required] | None" = None,
         mutability: "list[Mutability] | None" = None,
+        uniqueness: "list[Uniqueness] | None" = None,
+        returned: "list[Returned] | None" = None,
+        case_exact: "list[CaseExact] | None" = None,
     ) -> "Iterator[Path[ResourceT]]":
         """Iterate over all paths for the bound model and its extensions.
 
@@ -675,10 +681,16 @@ def iter_paths(
         :param include_extensions: Whether to include extension attributes.
         :param required: Filter by Required annotation values (e.g., [Required.true]).
         :param mutability: Filter by Mutability annotation values (e.g., [Mutability.read_write]).
+        :param uniqueness: Filter by Uniqueness annotation values (e.g., [Uniqueness.server]).
+        :param returned: Filter by Returned annotation values (e.g., [Returned.always]).
+        :param case_exact: Filter by CaseExact annotation values (e.g., [CaseExact.true]).
         :yields: Path instances for each attribute matching the filters.
         """
+        from .annotations import CaseExact
         from .annotations import Mutability
         from .annotations import Required
+        from .annotations import Returned
+        from .annotations import Uniqueness
         from .attributes import ComplexAttribute
         from .resources.resource import Extension
         from .resources.resource import Resource
@@ -698,6 +710,22 @@ def matches_filters(target_model: type[BaseModel], field_name: str) -> bool:
                 )
                 if field_mutability not in mutability:
                     return False
+            if uniqueness is not None:
+                field_uniqueness = target_model.get_field_annotation(
+                    field_name, Uniqueness
+                )
+                if field_uniqueness not in uniqueness:
+                    return False
+            if returned is not None:
+                field_returned = target_model.get_field_annotation(field_name, Returned)
+                if field_returned not in returned:
+                    return False
+            if case_exact is not None:
+                field_case_exact = target_model.get_field_annotation(
+                    field_name, CaseExact
+                )
+                if field_case_exact not in case_exact:
+                    return False
             return True
 
         def iter_model_paths(

tests/test_path.py

@@ -5,6 +5,7 @@
 import pydantic
 import pytest
 
+from scim2_models import CaseExact
 from scim2_models import Email
 from scim2_models import EnterpriseUser
 from scim2_models import Group
@@ -14,6 +15,8 @@
 from scim2_models import Name
 from scim2_models import PathNotFoundException
 from scim2_models import Required
+from scim2_models import Returned
+from scim2_models import Uniqueness
 from scim2_models import User
 from scim2_models.base import BaseModel
 from scim2_models.path import Path
@@ -1419,6 +1422,44 @@ def test_iter_paths_filter_skips_non_matching_subattributes():
     assert len(paths_with_filter) < len(paths_no_filter)
 
 
+def test_iter_paths_filter_by_uniqueness():
+    """iter_paths with uniqueness filter only yields matching paths."""
+    paths = list(
+        Path[User].iter_paths(
+            include_subattributes=False, uniqueness=[Uniqueness.server]
+        )
+    )
+    path_strings = [str(p) for p in paths]
+
+    assert "userName" in path_strings
+    for path in paths:
+        assert path.get_annotation(Uniqueness) == Uniqueness.server
+
+
+def test_iter_paths_filter_by_returned():
+    """iter_paths with returned filter only yields matching paths."""
+    paths = list(
+        Path[User].iter_paths(include_subattributes=False, returned=[Returned.never])
+    )
+    path_strings = [str(p) for p in paths]
+
+    assert "password" in path_strings
+    for path in paths:
+        assert path.get_annotation(Returned) == Returned.never
+
+
+def test_iter_paths_filter_by_case_exact():
+    """iter_paths with case_exact filter only yields matching paths."""
+    paths = list(
+        Path[User].iter_paths(include_subattributes=False, case_exact=[CaseExact.true])
+    )
+    path_strings = [str(p) for p in paths]
+
+    assert "externalId" in path_strings
+    for path in paths:
+        assert path.get_annotation(CaseExact) == CaseExact.true
+
+
 def test_path_init_with_path_object():
     """Path can be initialized with another Path object."""
     original = Path("userName")