Feature: Support requiring anyOf a list of keys (#534)

* Feature: Support requiring anyOf a list of keys

This adds a new feature to Voluptuous, which is somewhat akin to what json-schema does with the special key `anyOf`.

`Schema({Required(Any('color', 'temperature', 'brightness')): str})` will validate that AT LEAST ONE of these three values is present. That doesn't preclude any individual validation on each of those fields to still apply.
That means that in the above example, if `color` is present, brightness doesn't need to be present. But if brightness is present, all other validations of brightness (like checking that its value is a number between 0 and 100) still apply.

* Simplify tests

* Format stuff like black wants it

Author: cibernox

voluptuous/schema_builder.py

@@ -248,6 +248,13 @@ def _compile_mapping(self, schema, invalid_msg=None):
             )
         )
 
+        # Complex required keys that need special validation
+        complex_required_keys = set(
+            key
+            for key in all_required_keys
+            if isinstance(key, Required) and key.is_complex_key
+        )
+
         # Keys that may have defaults
         all_default_keys = set(
             key
@@ -300,6 +307,22 @@ def validate_mapping(path, iterable, out):
                     key_value_map[key.schema] = key.default()
 
             errors = []
+
+            # Check complex required keys - at least one candidate key must be present
+            for complex_key in complex_required_keys:
+                if not any(
+                    candidate in key_value_map
+                    for candidate in complex_key.candidate_keys
+                ):
+                    msg = (
+                        complex_key.msg
+                        if hasattr(complex_key, 'msg') and complex_key.msg
+                        else f'at least one of {complex_key.candidate_keys} is required'
+                    )
+                    errors.append(er.RequiredFieldInvalid(msg, path + [complex_key]))
+                else:
+                    # If at least one candidate key is present, mark this complex requirement as satisfied
+                    required_keys.discard(complex_key)
             for key, value in key_value_map.items():
                 key_path = path + [key]
                 remove_key = False
@@ -1142,6 +1165,17 @@ class Required(Marker):
     >>> schema = Schema({Required('key', default=list): list})
     >>> schema({})
     {'key': []}
+
+    Complex key validation - at least one of the specified keys must be present:
+
+    >>> from voluptuous.validators import Any
+    >>> schema = Schema({Required(Any('color', 'temperature', 'brightness')): str})
+    >>> schema({'color': 'red'})  # Valid - has color
+    {'color': 'red'}
+    >>> schema({'temperature': 'warm'})  # Valid - has temperature
+    {'temperature': 'warm'}
+    >>> schema({'color': 'blue', 'brightness': 'high'})  # Valid - has multiple
+    {'color': 'blue', 'brightness': 'high'}
     """
 
     def __init__(
@@ -1153,6 +1187,31 @@ def __init__(
     ) -> None:
         super(Required, self).__init__(schema, msg=msg, description=description)
         self.default = default_factory(default)
+        self.is_complex_key = self._is_complex_key_validator(schema)
+        self.candidate_keys = (
+            self._extract_candidate_keys(schema) if self.is_complex_key else None
+        )
+
+    def _is_complex_key_validator(self, schema):
+        """Check if schema is a validator that can match multiple keys."""
+        # Import here to avoid circular imports
+        from voluptuous.validators import Any
+
+        return isinstance(schema, Any)
+
+    def _extract_candidate_keys(self, schema):
+        """Extract possible keys from validators like Any("key1", "key2", "key3")."""
+        # Import here to avoid circular imports
+        from voluptuous.validators import Any
+
+        if isinstance(schema, Any):
+            # Extract literal values (strings, ints, etc.) from Any validators
+            return [
+                v
+                for v in schema.validators
+                if isinstance(v, (str, int, float, bool, type(None)))
+            ]
+        return []
 
 
 class Remove(Marker):

voluptuous/tests/tests.py

@@ -2037,3 +2037,140 @@ def test_humanize_error_with_none_data():
 
     error_message = humanize_error(data, ctx.value)
     assert "expected a dictionary" in error_message
+
+
+def test_required_complex_key_any():
+    """Test Required with Any validator for multiple possible keys"""
+    schema = Schema(
+        {Required(Any("color", "temperature", "brightness")): str, "device_id": str}
+    )
+
+    # Should pass - defines one of the required keys
+    result = schema({"color": "red", "device_id": "light1"})
+    assert result == {"color": "red", "device_id": "light1"}
+
+    # Should pass - defines several of the required keys
+    result = schema({"color": "blue", "brightness": "50%", "device_id": "light1"})
+    assert result == {"color": "blue", "brightness": "50%", "device_id": "light1"}
+
+    # Should fail - has none of the required keys
+    with pytest.raises(MultipleInvalid) as ctx:
+        schema({"device_id": "light1"})
+
+    error_msg = str(ctx.value)
+    assert (
+        "at least one of ['color', 'temperature', 'brightness'] is required"
+        in error_msg
+    )
+
+
+def test_required_complex_key_custom_message():
+    """Test Required with Any validator and custom error message"""
+    schema = Schema(
+        {
+            Required(
+                Any("color", "temperature", "brightness"),
+                msg="Please specify a lighting attribute",
+            ): str,
+            "device_id": str,
+        }
+    )
+
+    # Should pass
+    schema({"color": "red", "device_id": "light1"})
+
+    # Should fail with custom message
+    with pytest.raises(MultipleInvalid) as ctx:
+        schema({"device_id": "light1"})
+
+    error_msg = str(ctx.value)
+    assert "Please specify a lighting attribute" in error_msg
+
+
+def test_required_complex_key_mixed_types():
+    """Test Required with Any validator containing mixed key types"""
+    schema = Schema({Required(Any("string_key", 123, 45.6)): str, "other": int})
+
+    # Should work with string key
+    result = schema({"string_key": "value", "other": 1})
+    assert result == {"string_key": "value", "other": 1}
+
+    # Should work with int key
+    result = schema({123: "value", "other": 1})
+    assert result == {123: "value", "other": 1}
+
+    # Should work with float key
+    result = schema({45.6: "value", "other": 1})
+    assert result == {45.6: "value", "other": 1}
+
+    # Should fail with none present
+    with pytest.raises(MultipleInvalid) as ctx:
+        schema({"other": 1})
+
+    error_msg = str(ctx.value)
+    assert "at least one of ['string_key', 123, 45.6] is required" in error_msg
+
+
+def test_required_complex_key_multiple_complex_requirements():
+    """Test multiple Required complex keys in same schema"""
+    schema = Schema(
+        {
+            Required(Any("color", "hue")): str,
+            Required(Any("brightness", "intensity")): str,
+            "device": str,
+        }
+    )
+
+    # Should pass with one from each group
+    result = schema({"color": "red", "brightness": "high", "device": "light"})
+    assert result == {"color": "red", "brightness": "high", "device": "light"}
+
+    # Should fail if missing on any group
+    with pytest.raises(MultipleInvalid) as ctx:
+        schema({"brightness": "high", "device": "light"})
+
+    error_msg = str(ctx.value)
+    assert "at least one of ['color', 'hue'] is required" in error_msg
+
+
+def test_required_complex_key_value_validation():
+    """Test that value validation still works with complex required keys"""
+    schema = Schema({Required(Any("color", "temperature")): str, "device": str})
+
+    # Should pass with valid string value
+    result = schema({"color": "red", "device": "light"})
+    assert result == {"color": "red", "device": "light"}
+
+    # Should fail with invalid value type
+    with pytest.raises(MultipleInvalid) as ctx:
+        schema({"color": 123, "device": "light"})  # color should be str, not int
+
+    error_msg = str(ctx.value)
+    assert "expected str" in error_msg
+
+
+def test_complex_required_keys_with_specific_value_validation():
+    """Test complex required keys combined with specific value validation for brightness range."""
+    schema = Schema(
+        {
+            Required(Any('color', 'temperature', 'brightness')): object,
+            'brightness': All(
+                Coerce(int), Range(min=0, max=100)
+            ),  # Additional validation for brightness specifically
+            'device_id': str,
+        }
+    )
+
+    # Valid - color provided, no brightness validation needed
+    result = schema({'color': 'red', 'device_id': 'light1'})
+    assert result == {'color': 'red', 'device_id': 'light1'}
+
+    # Invalid - brightness provided but out of range (255 > 100)
+    # Should NOT get "required field missing" error, but should get range error
+    with pytest.raises(MultipleInvalid) as exc_info:
+        schema({'brightness': '255', 'device_id': 'light1'})
+
+    # Verify it's a range error, not a missing required field error
+    error_msg = str(exc_info.value)
+    assert "required" not in error_msg.lower()  # No "required field missing" error
+    assert "value must be at most 100" in error_msg  # Range validation error