Update ruff rules to enforce typing

Author: LeanderCS

docs/source/options/condition.rst

@@ -38,13 +38,15 @@ Available Conditions
 
 - `ArrayLengthEqualCondition <#flask_inputfilter.conditions.ArrayLengthEqualCondition>`_
 - `ArrayLongerThanCondition <#flask_inputfilter.conditions.ArrayLongerThanCondition>`_
+- `AtLeastOneRequiredCondition <#flask_inputfilter.conditions.AtLeastOneRequiredCondition>`_
 - `CustomCondition <#flask_inputfilter.conditions.CustomCondition>`_
 - `EqualCondition <#flask_inputfilter.conditions.EqualCondition>`_
 - `ExactlyNOfCondition <#flask_inputfilter.conditions.ExactlyNOfCondition>`_
 - `ExactlyNOfMatchesCondition <#flask_inputfilter.conditions.ExactlyNOfMatchesCondition>`_
 - `ExactlyOneOfCondition <#flask_inputfilter.conditions.ExactlyOneOfCondition>`_
 - `ExactlyOneOfMatchesCondition <#flask_inputfilter.conditions.ExactlyOneOfMatchesCondition>`_
 - `IntegerBiggerThanCondition <#flask_inputfilter.conditions.IntegerBiggerThanCondition>`_
+- `MutuallyExclusiveCondition <#flask_inputfilter.conditions.MutuallyExclusiveCondition>`_
 - `NOfCondition <#flask_inputfilter.conditions.NOfCondition>`_
 - `NOfMatchesCondition <#flask_inputfilter.conditions.NOfMatchesCondition>`_
 - `NotEqualCondition <#flask_inputfilter.conditions.NotEqualCondition>`_

docs/source/options/filter.rst

@@ -42,6 +42,8 @@ Available Filters
 - `Base64ImageResizeFilter <#flask_inputfilter.filters.Base64ImageResizeFilter>`_
 - `BlacklistFilter <#flask_inputfilter.filters.BlacklistFilter>`_
 - `LazyFilterChain <#flask_inputfilter.filters.LazyFilterChain>`_
+- `PhoneNumberNormalizeFilter <#flask_inputfilter.filters.PhoneNumberNormalizeFilter>`_
+- `SanitizeHtmlFilter <#flask_inputfilter.filters.SanitizeHtmlFilter>`_
 - `StringRemoveEmojisFilter <#flask_inputfilter.filters.StringRemoveEmojisFilter>`_
 - `StringSlugifyFilter <#flask_inputfilter.filters.StringSlugifyFilter>`_
 - `StringTrimFilter <#flask_inputfilter.filters.StringTrimFilter>`_

flask_inputfilter/conditions/at_least_one_required_condition.py

@@ -7,10 +7,98 @@
 
 class AtLeastOneRequiredCondition(BaseCondition):
     """
-    Ensures that at least one field from a list is present.
-
-    This condition validates that at least one field from a specified list of
-    fields is present and has a non-empty value.
+    Ensures that at least N fields from a list are present and non-empty.
+
+    **Parameters:**
+
+    - **fields** (*list[str]*): List of field names to check for presence.
+    - **min_required** (*int*, default: ``1``): Minimum number of fields that
+      must be present and non-empty.
+    - **check_empty** (*bool*, default: ``True``): Whether to consider empty
+      strings, empty lists, and other "falsy" values as absent.
+    - **custom_message** (*str*, optional): Custom error message to display
+      when the condition fails.
+
+    **Expected Behavior:**
+
+    - Validates that at least ``min_required`` fields are present
+    - Fields are considered "present" if they exist and are not None
+    - With ``check_empty=True``, empty strings and empty containers count as
+      absent
+    - Provides clear error messages indicating how many fields are required vs.
+      provided
+
+    **Use Cases:**
+
+    - **Contact information**: At least one of phone, email, or address
+    - **Flexible forms**: Multiple optional ways to provide the same
+      information
+    - **Alternative fields**: Primary field or one of several backup fields
+    - **Partial requirements**: At least N out of M total fields
+
+    **Example Usage:**
+
+    .. code-block:: python
+
+        class ProfileCompletionFilter(InputFilter):
+            def __init__(self):
+                super().__init__()
+
+                # All profile fields are optional individually
+                self.add('bio')
+                self.add('avatar_url')
+                self.add('website')
+                self.add('social_links')
+                self.add('skills')
+                self.add('certifications')
+
+                # At least 3 profile fields must be completed for profile visibility
+                self.add_condition(
+                    AtLeastOneRequiredCondition(
+                        [
+                            'bio', 'avatar_url', 'website', 'social_links',
+                            'skills', 'certifications'
+                        ],
+                        min_required=3,
+                        check_empty=True,
+                        custom_message="Complete at least 3 profile sections"
+                    )
+                )
+
+    **Validation Examples:**
+
+    .. code-block:: python
+
+        # Valid: phone provided
+        {"phone": "555-1234", "email": "", "address": ""}
+
+        # Valid: email and address provided (exceeds minimum)
+        {"phone": "", "email": "[email protected]", "address": "123 Main St"}
+
+        # Invalid: all fields empty
+        {"phone": "", "email": "", "address": ""}
+
+        # Invalid: all fields None or missing
+        {"phone": None}
+
+        # With min_required=2:
+        # Valid: 2 fields provided
+        {"bio": "Hello", "avatar_url": "http://...", "website": ""}
+
+        # Invalid: only 1 field provided
+        {"bio": "Hello", "avatar_url": "", "website": ""}
+
+    **Empty Value Handling:**
+
+    When ``check_empty=True`` (default), these values are considered absent:
+    - ``None``
+    - Empty string ``""``
+    - Empty list ``[]``
+    - Empty dict ``{}``
+    - Zero ``0`` (depending on context)
+
+    When ``check_empty=False``, only ``None`` and missing keys are considered
+    absent.
     """
 
     def __init__(
@@ -38,6 +126,39 @@ def __init__(
         self.check_empty = check_empty
         self.custom_message = custom_message
 
+    def _is_empty(self, value: Any) -> bool:
+        """
+        Check if a value is considered empty.
+
+        Args:
+            value: The value to check
+
+        Returns:
+            True if value is empty, False otherwise
+        """
+        if value is None:
+            return True
+        if not self.check_empty:
+            return False
+        if isinstance(value, str) and value.strip() == "":
+            return True
+        return isinstance(value, (list, dict)) and len(value) == 0
+
+    def _count_present_fields(self, data: Dict[str, Any]) -> int:
+        """
+        Count the number of present (non-empty) fields.
+
+        Args:
+            data: The data dictionary
+
+        Returns:
+            Number of present fields
+        """
+        return sum(
+            1 for field in self.fields
+            if field in data and not self._is_empty(data[field])
+        )
+
     def check(self, data: Dict[str, Any]) -> bool:
         """
         Check if at least the minimum required fields are present.
@@ -51,26 +172,7 @@ def check(self, data: Dict[str, Any]) -> bool:
         if not isinstance(data, dict):
             return False
 
-        present_count = 0
-
-        for field in self.fields:
-            if field in data and data[field] is not None:
-                if (
-                    self.check_empty
-                    and isinstance(data[field], str)
-                    and data[field].strip() == ""
-                ):
-                    continue
-
-                if (
-                    self.check_empty
-                    and isinstance(data[field], (list, dict))
-                    and len(data[field]) == 0
-                ):
-                    continue
-
-                present_count += 1
-
+        present_count = self._count_present_fields(data)
         return present_count >= self.min_required
 
     def get_error_message(self, data: Dict[str, Any]) -> str:
@@ -86,35 +188,17 @@ def get_error_message(self, data: Dict[str, Any]) -> str:
         if self.custom_message:
             return self.custom_message
 
-        present_fields = []
-        missing_fields = []
-
-        for field in self.fields:
-            if field in data and data[field] is not None:
-                if self.check_empty:
-                    if (
-                        isinstance(data[field], str)
-                        and data[field].strip() == ""
-                    ) or (
-                        isinstance(data[field], (list, dict))
-                        and len(data[field]) == 0
-                    ):
-                        missing_fields.append(field)
-                    else:
-                        present_fields.append(field)
-                else:
-                    present_fields.append(field)
-            else:
-                missing_fields.append(field)
+        present_count = self._count_present_fields(data)
+        fields_list = ", ".join(self.fields)
 
         if self.min_required == 1:
-            fields_list = ", ".join(self.fields)
             return (
-                f"At least one of the following fields is required: {fields_list}. "
-                f"None were provided or all were empty."
+                f"At least one of the following fields is required: "
+                f"{fields_list}. None were provided or all were empty."
             )
-        fields_list = ", ".join(self.fields)
+
         return (
             f"At least {self.min_required} of the following fields "
-            f"are required: {fields_list}. Only {len(present_fields)} provided."
+            f"are required: {fields_list}. "
+            f"Only {present_count} provided."
         )