voluptuous-openapi 0.3.0__tar.gz → 0.4.0__tar.gz

{voluptuous_openapi-0.3.0/voluptuous_openapi.egg-info → voluptuous_openapi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voluptuous-openapi
-Version: 0.3.0
+Version: 0.4.0
 Summary: Convert voluptuous schemas to OpenAPI Schema object
 Author-email: Denis Shulyaka <Shulyaka@gmail.com>
 License-Expression: Apache-2.0
@@ -55,7 +55,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator:

{voluptuous_openapi-0.3.0 → voluptuous_openapi-0.4.0}/README.md

@@ -42,7 +42,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator:

{voluptuous_openapi-0.3.0 → voluptuous_openapi-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools>=77.0"]
 
 [project]
 name = "voluptuous-openapi"
-version = "0.3.0"
+version = "0.4.0"
 license = "Apache-2.0"
 description = "Convert voluptuous schemas to OpenAPI Schema object"
 readme = "README.md"

{voluptuous_openapi-0.3.0 → voluptuous_openapi-0.4.0}/tests/test_lib.py

@@ -1016,3 +1016,302 @@ def test_required_any_of_inner_description():
             ): str,
         }
     )
+
+
+def test_simple_ref_defs() -> None:
+    """Test basic JSON pointer reference resolution using the $defs keyword."""
+    schema = {
+        "$defs": {"MyInt": {"type": "integer"}},
+        "type": "object",
+        "properties": {"age": {"$ref": "#/$defs/MyInt"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    # Check it validates valid input
+    res = validator({"age": 42})
+    assert res == {"age": 42}
+
+    # Check it raises vol.Invalid on invalid input
+    with pytest.raises(vol.Invalid):
+        validator({"age": "hello"})
+
+
+def test_definitions_compatibility() -> None:
+    """Test compatibility with older JSON Schema drafts using definitions instead of $defs."""
+    schema = {
+        "definitions": {"MyInt": {"type": "integer"}},
+        "type": "object",
+        "properties": {"age": {"$ref": "#/definitions/MyInt"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    res = validator({"age": 42})
+    assert res == {"age": 42}
+
+    with pytest.raises(vol.Invalid):
+        validator({"age": "not-an-int"})
+
+
+def test_chained_refs() -> None:
+    """Test chained references where one reference points to another reference."""
+    schema = {
+        "$defs": {"Level2": {"type": "integer"}, "Level1": {"$ref": "#/$defs/Level2"}},
+        "type": "object",
+        "properties": {"num": {"$ref": "#/$defs/Level1"}},
+    }
+    validator = convert_to_voluptuous(schema)
+    res = validator({"num": 42})
+    assert res == {"num": 42}
+
+    with pytest.raises(vol.Invalid):
+        validator({"num": "yes"})
+
+
+def test_root_self_ref_valid() -> None:
+    """Test root self-reference (#) with valid recursively nested structures."""
+    schema = {"type": "object", "properties": {"child": {"$ref": "#"}}}
+    validator = convert_to_voluptuous(schema)
+
+    # Single level
+    assert validator({"child": {}}) == {"child": {}}
+
+    # Nested level
+    assert validator({"child": {"child": {"child": {}}}}) == {
+        "child": {"child": {"child": {}}}
+    }
+
+
+def test_root_self_ref_invalid() -> None:
+    """Test root self-reference (#) with invalid type values."""
+    schema = {"type": "object", "properties": {"child": {"$ref": "#"}}}
+    validator = convert_to_voluptuous(schema)
+
+    with pytest.raises(vol.Invalid):
+        validator({"child": "not-an-object"})
+
+
+def test_recursive_tree_valid() -> None:
+    """Test recursive tree node reference validation with valid structures."""
+    schema = {
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "value": {"type": "string"},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/Node"}},
+                },
+                "required": ["value"],
+            }
+        },
+        "$ref": "#/$defs/Node",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Leaf node
+    assert validator({"value": "leaf"}) == {"value": "leaf"}
+
+    # Deep recursive tree
+    tree = {
+        "value": "root",
+        "children": [
+            {"value": "child1", "children": [{"value": "grandchild1"}]},
+            {"value": "child2"},
+        ],
+    }
+    assert validator(tree) == tree
+
+
+def test_recursive_tree_invalid() -> None:
+    """Test recursive tree node reference validation with invalid type values."""
+    schema = {
+        "$defs": {
+            "Node": {
+                "type": "object",
+                "properties": {
+                    "value": {"type": "string"},
+                    "children": {"type": "array", "items": {"$ref": "#/$defs/Node"}},
+                },
+                "required": ["value"],
+            }
+        },
+        "$ref": "#/$defs/Node",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    invalid_tree = {"value": "root", "children": [{"value": 123}]}  # Should be string
+    with pytest.raises(vol.Invalid):
+        validator(invalid_tree)
+
+
+def test_anonymized_field_definition_valid() -> None:
+    """Test anonymized FieldDefinition schema with valid primitive and complex structures."""
+    schema = {
+        "$defs": {
+            "FieldDefinition": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["BOOLEAN", "STRING", "INTEGER", "STRUCT", "LIST"],
+                    },
+                    "structFields": {
+                        "type": "object",
+                        "additionalProperties": {"$ref": "#/$defs/FieldDefinition"},
+                    },
+                    "listElement": {"$ref": "#/$defs/FieldDefinition"},
+                },
+                "required": ["type"],
+            }
+        },
+        "$ref": "#/$defs/FieldDefinition",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Simple integer type definition
+    assert validator({"type": "INTEGER"}) == {"type": "INTEGER"}
+
+    # Complex struct containing other field definitions (including a list element)
+    complex_def = {
+        "type": "STRUCT",
+        "structFields": {
+            "name": {"type": "STRING"},
+            "tags": {"type": "LIST", "listElement": {"type": "STRING"}},
+        },
+    }
+    assert validator(complex_def) == complex_def
+
+
+def test_anonymized_field_definition_invalid() -> None:
+    """Test anonymized FieldDefinition schema with invalid enum values and recursive types."""
+    schema = {
+        "$defs": {
+            "FieldDefinition": {
+                "type": "object",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["BOOLEAN", "STRING", "INTEGER", "STRUCT", "LIST"],
+                    },
+                    "structFields": {
+                        "type": "object",
+                        "additionalProperties": {"$ref": "#/$defs/FieldDefinition"},
+                    },
+                    "listElement": {"$ref": "#/$defs/FieldDefinition"},
+                },
+                "required": ["type"],
+            }
+        },
+        "$ref": "#/$defs/FieldDefinition",
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Fails if enum value is wrong
+    with pytest.raises(vol.Invalid):
+        validator({"type": "FLOAT"})
+
+    # Fails if recursive validation fails
+    with pytest.raises(vol.Invalid):
+        validator(
+            {
+                "type": "STRUCT",
+                "structFields": {"invalid_field": {"type": 123}},  # type must be string
+            }
+        )
+
+
+def test_anonymized_ghp_home_automation_valid() -> None:
+    """Test anonymized GhpHomeAutomation schema with valid automation rules."""
+    schema = {
+        "$defs": {
+            "Comparison": {
+                "type": "object",
+                "properties": {
+                    "fieldToCompare": {"type": "string"},
+                    "operator": {"type": "string", "enum": ["EQUALS", "LESS_THAN"]},
+                    "nestedComparison": {"$ref": "#/$defs/Comparison"},
+                    "operands": {"type": "array", "items": {"$ref": "#/$defs/Operand"}},
+                },
+            },
+            "Operand": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "value": {"type": "string"},
+                },
+            },
+            "ConditionBlock": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "description": {"type": "string"},
+                },
+            },
+        },
+        "type": "object",
+        "properties": {
+            "conditions": {"type": "array", "items": {"$ref": "#/$defs/ConditionBlock"}}
+        },
+    }
+    validator = convert_to_voluptuous(schema)
+
+    valid_automation = {
+        "conditions": [
+            {
+                "description": "Check temperature",
+                "comparison": {
+                    "fieldToCompare": "temp",
+                    "operator": "LESS_THAN",
+                    "operands": [{"value": "72"}],
+                },
+            }
+        ]
+    }
+    assert validator(valid_automation) == valid_automation
+
+
+def test_anonymized_ghp_home_automation_invalid() -> None:
+    """Test anonymized GhpHomeAutomation schema with invalid operator constraints."""
+    schema = {
+        "$defs": {
+            "Comparison": {
+                "type": "object",
+                "properties": {
+                    "fieldToCompare": {"type": "string"},
+                    "operator": {"type": "string", "enum": ["EQUALS", "LESS_THAN"]},
+                    "nestedComparison": {"$ref": "#/$defs/Comparison"},
+                    "operands": {"type": "array", "items": {"$ref": "#/$defs/Operand"}},
+                },
+            },
+            "Operand": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "value": {"type": "string"},
+                },
+            },
+            "ConditionBlock": {
+                "type": "object",
+                "properties": {
+                    "comparison": {"$ref": "#/$defs/Comparison"},
+                    "description": {"type": "string"},
+                },
+            },
+        },
+        "type": "object",
+        "properties": {
+            "conditions": {"type": "array", "items": {"$ref": "#/$defs/ConditionBlock"}}
+        },
+    }
+    validator = convert_to_voluptuous(schema)
+
+    # Invalid operator in nested comparison
+    invalid_automation = {
+        "conditions": [
+            {
+                "comparison": {
+                    "fieldToCompare": "temp",
+                    "operator": "GREATER_THAN",  # Not in comparison enum ["EQUALS", "LESS_THAN"]
+                }
+            }
+        ]
+    }
+    with pytest.raises(vol.Invalid):
+        validator(invalid_automation)

{voluptuous_openapi-0.3.0 → voluptuous_openapi-0.4.0}/voluptuous_openapi/__init__.py

@@ -28,6 +28,9 @@ OPENAPI_UNSUPPORTED_KEYWORDS = {
     "uniqueItems",
 }
 
+# The standard JSON Schema reference keyword
+JSON_SCHEMA_REF = "$ref"
+
 
 class OpenApiVersion(StrEnum):
     """The OpenAPI version.
@@ -449,12 +452,112 @@ def convert(
     raise ValueError("Unable to convert schema: {}".format(schema))
 
 
-def convert_to_voluptuous(schema: dict) -> vol.Schema:
-    """Convert an OpenAPI Schema object to a voluptuous schema."""
+def resolve_ref(ref: str, root_schema: dict) -> dict:
+    """Resolve a JSON pointer reference within the root_schema.
+
+    A JSON pointer (defined in RFC 6901) is a string syntax for identifying a
+    specific value within a JSON document. It uses '/' to separate keys or list
+    indices. This function resolves local pointer references starting with '#'.
+
+    Example:
+        Given root_schema = {"$defs": {"User": {"type": "object"}}},
+        resolve_ref("#/$defs/User", root_schema) returns {"type": "object"}.
+    """
+    if not ref.startswith("#"):
+        raise ValueError(f"External/relative $ref not supported: {ref}")
+    if ref == "#" or ref == "":
+        return root_schema
+
+    parts = ref.lstrip("#").split("/")
+    # If the ref was '#/something', lstrip('#') is '/something', and split('/')
+    # produces ['', 'something']. We pop the first empty element.
+    if parts[0] == "":
+        parts.pop(0)
+
+    current = root_schema
+    for part in parts:
+        # RFC 6901 specifies '~1' represents '/' and '~0' represents '~'
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        elif isinstance(current, list):
+            try:
+                idx = int(part)
+                current = current[idx]
+            except (ValueError, IndexError):
+                raise ValueError(f"Could not resolve ref {ref} in list at index {part}")
+        else:
+            raise ValueError(f"Could not resolve ref {ref} at key {part}")
+
+    return current
+
+
+class LazySchema:
+    """A wrapper validator that resolves and compiles a schema reference lazily.
+
+    This leverages voluptuous's ability to use any Python callable as a validator.
+    By returning a LazySchema instance during compilation, we avoid infinite
+    recursion/loops for circular or self-referential schemas. The schema is
+    resolved and compiled only on its first invocation, and cached for future runs.
+    """
+
+    def __init__(self, ref: str, root_schema: dict):
+        self.ref = ref
+        self.root_schema = root_schema
+        self._compiled_schema = None
+
+    def __call__(self, value: Any) -> Any:
+        """Validate the value against the lazily compiled schema.
+
+        On the first validation call, this resolves the JSON pointer reference
+        and compiles it into a voluptuous validator. Subsequent validation calls
+        bypass the compilation and reuse the cached validator.
+        """
+        if self._compiled_schema is None:
+            target_schema = resolve_ref(self.ref, self.root_schema)
+            self._compiled_schema = convert_to_voluptuous(
+                target_schema, self.root_schema
+            )
+        return self._compiled_schema(value)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, LazySchema):
+            return False
+        return self.ref == other.ref and self.root_schema == other.root_schema
+
+    def __repr__(self) -> str:
+        return f"LazySchema({self.ref!r})"
+
+
+def convert_to_voluptuous(schema: dict, root_schema: dict | None = None) -> Any:
+    """Convert an OpenAPI/JSON Schema object to a voluptuous schema.
+
+    Args:
+        schema: The OpenAPI/JSON Schema dictionary to convert.
+        root_schema: The root schema document, which is propagated recursively
+            to resolve local JSON pointer references ($ref). If not provided,
+            defaults to the current schema.
+
+    Returns:
+        A voluptuous Schema, a type validator, or a custom validator callable.
+    """
 
     if not isinstance(schema, dict):
         raise ValueError("Invalid schema, expected a dictionary")
 
+    if root_schema is None:
+        root_schema = schema
+
+    if JSON_SCHEMA_REF in schema:
+        return LazySchema(schema[JSON_SCHEMA_REF], root_schema)
+
+    if (enum_values := schema.get("enum")) is not None:
+        if not isinstance(enum_values, list):
+            raise ValueError("Invalid schema, enum should be a list")
+        if schema.get("nullable") is True:
+            return vol.Any(vol.In(enum_values), None)
+        return vol.In(enum_values)
+
     for keyword in OPENAPI_UNSUPPORTED_KEYWORDS:
         if keyword in schema:
             raise ValueError(f"{keyword} is not supported")
@@ -464,7 +567,9 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
             raise ValueError("Invalid schema, oneOf should be a list")
         # This implements anyOf semantics sice it matches any of the subschemas,
         # not just one of them.
-        return vol.Any(*[convert_to_voluptuous(sub_schema) for sub_schema in one_of])
+        return vol.Any(
+            *[convert_to_voluptuous(sub_schema, root_schema) for sub_schema in one_of]
+        )
 
     if (any_of := schema.get("anyOf")) is not None:
         if not isinstance(any_of, list):
@@ -477,7 +582,10 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
         )
         if not (is_required_constraint and schema.get("type") == "object"):
             return vol.Any(
-                *[convert_to_voluptuous(sub_schema) for sub_schema in any_of]
+                *[
+                    convert_to_voluptuous(sub_schema, root_schema)
+                    for sub_schema in any_of
+                ]
             )
 
     if (schema_type := schema.get("type")) is None:
@@ -498,7 +606,7 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
             else:
                 base_schema = schema.copy()
                 base_schema["type"] = t
-                validators.append(convert_to_voluptuous(base_schema))
+                validators.append(convert_to_voluptuous(base_schema, root_schema))
         return vol.Any(*validators)
 
     if (basic_type := TYPES_MAP_REV.get(schema_type)) is not None:
@@ -533,7 +641,7 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
         properties = {}
         required_properties = set(schema.get("required", []))
         for key, value in schema.get("properties", {}).items():
-            value_type = convert_to_voluptuous(value)
+            value_type = convert_to_voluptuous(value, root_schema)
             description: str | None = None
             if isinstance(value, dict):
                 description = value.get("description")
@@ -550,9 +658,12 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
             if any_of_keys:
                 properties[vol.Required(vol.Any(*any_of_keys))] = object
 
-        validator = None
-        if schema.get("additionalProperties") is True:
+        extra_schema = schema.get("additionalProperties")
+        if extra_schema is True:
             validator = vol.Schema(properties, extra=vol.ALLOW_EXTRA)
+        elif isinstance(extra_schema, dict):
+            properties[vol.Extra] = convert_to_voluptuous(extra_schema, root_schema)
+            validator = vol.Schema(properties)
         else:
             validator = vol.Schema(properties)
 
@@ -563,7 +674,7 @@ def convert_to_voluptuous(schema: dict) -> vol.Schema:
         return validator
 
     if schema_type == "array":
-        item_validator = convert_to_voluptuous(schema["items"])
+        item_validator = convert_to_voluptuous(schema["items"], root_schema)
         min_items = schema.get("minItems")
         max_items = schema.get("maxItems")
 

{voluptuous_openapi-0.3.0 → voluptuous_openapi-0.4.0/voluptuous_openapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voluptuous-openapi
-Version: 0.3.0
+Version: 0.4.0
 Summary: Convert voluptuous schemas to OpenAPI Schema object
 Author-email: Denis Shulyaka <Shulyaka@gmail.com>
 License-Expression: Apache-2.0
@@ -55,7 +55,7 @@ You can pass a custom serializer to be able to process custom validators. If the
 
 ```python
 
-from voluptuous_openai import UNSUPPORTED, convert
+from voluptuous_openapi import UNSUPPORTED, convert
 
 def custom_convert(value):
     if value is my_custom_validator: