jentic-openapi-datamodels 1.0.0a11__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

jentic/apitools/openapi/datamodels/low/context.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass, field
+
+from ruamel.yaml import YAML
+from ruamel.yaml.constructor import RoundTripConstructor
+
+
+__all__ = ["Context"]
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """
+    Context for parsing OpenAPI documents.
+
+    Contains configuration and dependencies used during parsing operations.
+
+    Attributes:
+        yaml_constructor: The YAML constructor used to deserialize YAML nodes into Python objects
+    """
+
+    yaml_constructor: RoundTripConstructor = field(default=YAML(typ="rt", pure=True).constructor)

jentic/apitools/openapi/datamodels/low/extractors.py

@@ -0,0 +1,126 @@
+from ruamel import yaml
+
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import fixed_fields
+from jentic.apitools.openapi.datamodels.low.sources import KeySource, ValueSource, YAMLValue
+
+
+__all__ = ["extract_extension_fields", "extract_unknown_fields"]
+
+
+def extract_extension_fields(
+    node: yaml.MappingNode, context: Context | None = None
+) -> dict[KeySource[str], ValueSource[YAMLValue]]:
+    """
+    Extract OpenAPI specification extension fields from a YAML mapping node.
+
+    Specification extension fields are any fields that start with "x-" and allow
+    users to add custom properties to OpenAPI definitions.
+
+    Args:
+        node: The YAML mapping node to extract extension fields from
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A dictionary mapping extension field names to their values, or empty dict if no extension fields found
+
+    Example:
+        Given YAML like:
+            name: id
+            x-custom: value
+            x-internal: true
+
+        Returns:
+            {
+                KeySource(value="x-custom", key_node=...): ValueSource(value="value", value_node=...),
+                KeySource(value="x-internal", key_node=...): ValueSource(value=True, value_node=...)
+            }
+    """
+    if not isinstance(node, yaml.MappingNode):
+        return {}
+
+    if context is None:
+        context = Context()
+
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = {}
+
+    for key_node, value_node in node.value:
+        # Construct the key as a Python object (should be a string)
+        py_key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Check if it's an extension (starts with "x-")
+        if isinstance(py_key, str) and py_key.startswith("x-"):
+            # Construct the actual Python value from the YAML node
+            py_value = context.yaml_constructor.construct_object(value_node, deep=True)
+
+            key_ref = KeySource[str](value=py_key, key_node=key_node)
+            value_ref = ValueSource[YAMLValue](value=py_value, value_node=value_node)
+            extensions[key_ref] = value_ref
+
+    return extensions
+
+
+def extract_unknown_fields(
+    node: yaml.MappingNode, dataclass_type: type, context: Context | None = None
+) -> dict[KeySource[str], ValueSource[YAMLValue]]:
+    """
+    Extract unknown fields from a YAML mapping node.
+
+    Unknown fields are fields that are not part of the OpenAPI specification
+    (not fixed fields of the dataclass) and are not extensions (don't start with "x-").
+    These are typically typos or fields from a different specification version.
+
+    Args:
+        node: The YAML mapping node to extract unknown fields from
+        dataclass_type: The dataclass type to get valid field names from
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A dictionary mapping unknown field names to their values, or empty dict if no unknown fields found
+
+    Example:
+        Given YAML like:
+            name: id
+            namspace: http://example.com  # typo - should be "namespace"
+            customField: value             # unknown field
+            x-custom: value                # extension - not unknown
+
+        With dataclass_type=XML (which has fixed fields: name, namespace, prefix, attribute, wrapped)
+        Returns:
+            {
+                KeySource(value="namspace", key_node=...): ValueSource(value="http://example.com", value_node=...),
+                KeySource(value="customField", key_node=...): ValueSource(value="value", value_node=...)
+            }
+    """
+    if not isinstance(node, yaml.MappingNode):
+        return {}
+
+    if context is None:
+        context = Context()
+
+    # Get valid YAML field names from the dataclass (considering yaml_name metadata)
+    _fixed_fields = fixed_fields(dataclass_type)
+    yaml_field_names = {
+        field.metadata.get("yaml_name", fname) for fname, field in _fixed_fields.items()
+    }
+
+    unknown_fields: dict[KeySource[str], ValueSource[YAMLValue]] = {}
+
+    for key_node, value_node in node.value:
+        # Construct the key as a Python object (should be a string)
+        py_key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Check if it's an unknown field (not in valid YAML field names and not an extension)
+        if (
+            isinstance(py_key, str)
+            and py_key not in yaml_field_names
+            and not py_key.startswith("x-")
+        ):
+            # Construct the actual Python value from the YAML node
+            py_value = context.yaml_constructor.construct_object(value_node, deep=True)
+
+            key_ref = KeySource[str](value=py_key, key_node=key_node)
+            value_ref = ValueSource[YAMLValue](value=py_value, value_node=value_node)
+            unknown_fields[key_ref] = value_ref
+
+    return unknown_fields

jentic/apitools/openapi/datamodels/low/fields.py

@@ -0,0 +1,45 @@
+from dataclasses import field, fields
+
+
+__all__ = ["fixed_field", "fixed_fields", "patterned_field", "patterned_fields"]
+
+
+def fixed_field(default=None, metadata=None):
+    """Mark a field as a fixed OpenAPI specification field."""
+    return field(default=default, metadata={**(metadata or {}), "fixed_field": True})
+
+
+def fixed_fields(dataclass_type):
+    """
+    Get all fixed specification fields from a dataclass.
+
+    Args:
+        dataclass_type: The dataclass type to inspect
+
+    Returns:
+        A dictionary mapping field names to field objects for all fields marked with fixed_field()
+    """
+    return {f.name: f for f in fields(dataclass_type) if f.metadata.get("fixed_field")}
+
+
+def patterned_field(default=None, metadata=None):
+    """
+    Mark a field as containing OpenAPI patterned fields.
+
+    Patterned fields have dynamic names that follow a specific pattern (e.g., security scheme names,
+    path patterns, callback expressions, HTTP status codes).
+    """
+    return field(default=default, metadata={**(metadata or {}), "patterned_field": True})
+
+
+def patterned_fields(dataclass_type):
+    """
+    Get all patterned fields from a dataclass.
+
+    Args:
+        dataclass_type: The dataclass type to inspect
+
+    Returns:
+        A dictionary mapping field names to field objects for all fields marked with patterned_field()
+    """
+    return {f.name: f for f in fields(dataclass_type) if f.metadata.get("patterned_field")}

jentic/apitools/openapi/datamodels/low/model_builder.py

@@ -0,0 +1,113 @@
+from dataclasses import fields
+from typing import Any, TypeVar, cast, get_args
+
+from ruamel import yaml
+
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.extractors import extract_extension_fields
+from jentic.apitools.openapi.datamodels.low.fields import fixed_fields
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+    YAMLInvalidValue,
+)
+
+
+__all__ = ["build_model"]
+
+
+T = TypeVar("T")
+
+
+def build_model(
+    root: yaml.Node, dataclass_type: type[T], *, context: Context | None = None
+) -> T | ValueSource[YAMLInvalidValue]:
+    """
+    Generic builder for OpenAPI low model.
+
+    Builds any dataclass that follows the pattern:
+    - Has a required `root_node: yaml.Node` field
+    - Has an optional `extensions: dict[...]` field
+    - Has spec fields marked with `fixed_field()`
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        dataclass_type: The dataclass type to build
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An instance of dataclass_type if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        xml = build_model(root_node, XML, context=context)
+    """
+    # Initialize context once at the beginning
+    if context is None:
+        context = Context()
+
+    if not isinstance(root, yaml.MappingNode):
+        # Preserve invalid root data instead of returning None
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Get fixed specification fields for this dataclass type
+    _fixed_fields = fixed_fields(dataclass_type)
+
+    # Build YAML name to Python field name mapping
+    yaml_to_field = {
+        field.metadata.get("yaml_name", fname): fname for fname, field in _fixed_fields.items()
+    }
+
+    # Extract field values in a single pass (non-recursive, single layer only)
+    field_values: dict[str, Any] = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Map YAML key to Python field name
+        field_name = yaml_to_field.get(key)
+        if field_name:
+            field = _fixed_fields[field_name]
+            field_type_args = set(get_args(field.type))
+
+            if field_type_args & {FieldSource[str], FieldSource[bool], FieldSource[int]}:
+                value = context.yaml_constructor.construct_object(value_node, deep=True)
+                field_values[field_name] = FieldSource(
+                    value=value, key_node=key_node, value_node=value_node
+                )
+            elif field_type_args & {FieldSource[dict[KeySource[str], ValueSource[str]]]}:
+                # Handle dict with KeySource/ValueSource wrapping
+                if isinstance(value_node, yaml.MappingNode):
+                    mapping_dict: dict[KeySource[str], ValueSource[str]] = {}
+                    for map_key_node, map_value_node in value_node.value:
+                        map_key = context.yaml_constructor.construct_yaml_str(map_key_node)
+                        map_value = context.yaml_constructor.construct_object(
+                            map_value_node, deep=True
+                        )
+                        mapping_dict[KeySource(value=map_key, key_node=map_key_node)] = ValueSource(
+                            value=map_value, value_node=map_value_node
+                        )
+                    field_values[field_name] = FieldSource(
+                        value=mapping_dict, key_node=key_node, value_node=value_node
+                    )
+                else:
+                    # Not a mapping - preserve as-is for validation
+                    value = context.yaml_constructor.construct_object(value_node, deep=True)
+                    field_values[field_name] = FieldSource(
+                        value=value, key_node=key_node, value_node=value_node
+                    )
+
+    # Build and return the dataclass instance
+    # Conditionally include extensions field if dataclass supports it
+    # Cast to Any to work around generic type constraints
+    has_extensions = any(f.name == "extensions" for f in fields(cast(Any, dataclass_type)))
+    return cast(
+        T,
+        dataclass_type(
+            root_node=root,  # type: ignore[call-arg]
+            **field_values,
+            **({"extensions": extract_extension_fields(root, context)} if has_extensions else {}),
+        ),
+    )

jentic/apitools/openapi/datamodels/low/sources.py

@@ -0,0 +1,89 @@
+from dataclasses import dataclass
+from typing import Generic, TypeAlias, TypeVar
+
+from ruamel import yaml
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+
+__all__ = ["FieldSource", "KeySource", "ValueSource", "YAMLValue", "YAMLInvalidValue"]
+
+# Type alias for any deserialized YAML value (including mappings)
+YAMLValue: TypeAlias = str | int | float | bool | None | CommentedSeq | CommentedMap
+
+# Type alias for invalid YAML values (subset of YAMLValue, excludes CommentedMap)
+# Used when builders receive non-mapping nodes to preserve data for validation
+YAMLInvalidValue: TypeAlias = str | int | float | bool | None | CommentedSeq
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class FieldSource(Generic[T]):
+    """
+    A field value with associated YAML source location information.
+
+    Used for fixed OpenAPI specification fields to track both the key and value
+    nodes in the original YAML source, enabling precise error reporting.
+
+    Automatically unwraps ValueSource instances passed as the value parameter,
+    allowing child builders to return ValueSource for invalid data while keeping
+    parent code clean.
+
+    Attributes:
+        value: The actual field value of type T
+        key_node: The YAML node containing the field name/key
+        value_node: The YAML node containing the field value (can be None for keys without values)
+    """
+
+    value: T
+    key_node: yaml.Node
+    value_node: yaml.Node | None = None
+
+    def __post_init__(self) -> None:
+        """
+        Auto-unwrap ValueSource if passed as value parameter.
+
+        This allows child builders to return ValueSource[YAMLInvalidValue] for invalid root nodes
+        while parent code can transparently wrap the result in FieldSource without
+        special handling.
+
+        Note: We don't need to update value_node since parent and child work with
+        the same YAML node.
+        """
+        if isinstance(self.value, ValueSource):
+            # Extract the raw value from ValueSource wrapper
+            object.__setattr__(self, "value", self.value.value)
+
+
+@dataclass(frozen=True, slots=True)
+class KeySource(Generic[T]):
+    """
+    A dictionary key with associated YAML source location information.
+
+    Used in extension and unknown field dictionaries to track where keys
+    appear in the original YAML source.
+
+    Attributes:
+        value: The key value of type T
+        key_node: The YAML node that holds this key
+    """
+
+    value: T
+    key_node: yaml.Node
+
+
+@dataclass(frozen=True, slots=True)
+class ValueSource(Generic[T]):
+    """
+    A dictionary value / array item with associated YAML source location information.
+
+    Used in extension and unknown field dictionaries to track where values
+    appear in the original YAML source.
+
+    Attributes:
+        value: The value of type T
+        value_node: The YAML node that holds this value
+    """
+
+    value: T
+    value_node: yaml.Node

jentic/apitools/openapi/datamodels/low/v30/__init__.py

@@ -1,28 +0,0 @@
-"""OpenAPI 3.0.x low-level models."""
-
-from .discriminator import Discriminator
-from .external_documentation import ExternalDocumentation
-from .oauth_flow import OAuthFlow
-from .oauth_flows import OAuthFlows
-from .reference import Reference
-from .schema import Schema
-from .security_requirement import SecurityRequirement
-from .security_scheme import SecurityScheme
-from .specification_object import SpecificationObject
-from .tag import Tag
-from .xml import XML
-
-
-__all__ = [
-    "Discriminator",
-    "ExternalDocumentation",
-    "OAuthFlow",
-    "OAuthFlows",
-    "Reference",
-    "Schema",
-    "SecurityRequirement",
-    "SecurityScheme",
-    "SpecificationObject",
-    "Tag",
-    "XML",
-]

jentic/apitools/openapi/datamodels/low/v30/discriminator.py

@@ -1,91 +1,66 @@
-"""
-OpenAPI 3.0.4 Discriminator Object model.
+from dataclasses import dataclass
 
-When request bodies or response payloads may be one of a number of different schemas,
-a discriminator object gives a hint about the expected schema.
-"""
+from ruamel import yaml
 
-from collections.abc import Mapping
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import fixed_field
+from jentic.apitools.openapi.datamodels.low.model_builder import build_model
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+    YAMLInvalidValue,
+)
 
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
 
+__all__ = ["Discriminator", "build"]
 
-__all__ = ["Discriminator"]
 
+@dataclass(frozen=True, slots=True)
+class Discriminator:
+    """
+    Discriminator Object representation for OpenAPI 3.0.
+
+    When request bodies or response payloads may be one of a number of different schemas,
+    a discriminator object can be used to aid in serialization, deserialization, and validation.
+
+    Note: In OpenAPI 3.0.x, the Discriminator Object does not support Specification Extensions.
+    This changes in OpenAPI 3.1.x where extensions are permitted.
 
-class Discriminator(SpecificationObject):
+    Attributes:
+        root_node: The top-level node representing the entire Discriminator object in the original source file
+        property_name: REQUIRED. The name of the property in the payload that will hold the discriminator value
+        mapping: An optional mapping of discriminator values to schema names or references
     """
-    Represents a Discriminator Object from OpenAPI 3.0.4.
 
-    Used to support polymorphism by indicating which property in a payload
-    is used to differentiate between schemas.
+    root_node: yaml.Node
+    property_name: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "propertyName"})
+    mapping: FieldSource[dict[KeySource[str], ValueSource[str]]] | None = fixed_field()
 
-    Supports specification extensions (x-* fields).
 
-    Example:
-        >>> # Basic discriminator
-        >>> disc = Discriminator({
-        ...     "propertyName": "petType"
-        ... })
-        >>> disc.property_name
-        'petType'
-
-        >>> # With mapping
-        >>> disc = Discriminator({
-        ...     "propertyName": "petType",
-        ...     "mapping": {
-        ...         "dog": "#/components/schemas/Dog",
-        ...         "cat": "#/components/schemas/Cat",
-        ...         "lizard": "https://example.com/schemas/Lizard.json"
-        ...     }
-        ... })
-        >>> disc.property_name
-        'petType'
-        >>> disc.mapping["dog"]
-        '#/components/schemas/Dog'
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Discriminator | ValueSource[YAMLInvalidValue]:
     """
+    Build a Discriminator object from a YAML node.
+
+    Preserves all source data as-is, regardless of type. This is a low-level/plumbing
+    model that provides complete source fidelity for inspection and validation.
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset({"propertyName", "mapping"})
-
-    @property
-    def property_name(self) -> str | None:
-        """
-        The name of the property in the payload to discriminate schemas.
-
-        REQUIRED field.
-
-        Returns:
-            Property name or None if not present
-        """
-        return self.get("propertyName")
-
-    @property_name.setter
-    def property_name(self, value: str | None) -> None:
-        """Set the property name."""
-        if value is None:
-            self.pop("propertyName", None)
-        else:
-            self["propertyName"] = value
-
-    @property
-    def mapping(self) -> dict[str, str]:
-        """
-        Mapping between payload values and schema names/references.
-
-        Maps discriminator property values to schema names or references.
-        When absent, the value is expected to match a schema name.
-
-        Returns:
-            Dictionary mapping values to schema references (empty dict if not present)
-        """
-        return self.get("mapping", {})
-
-    @mapping.setter
-    def mapping(self, value: Mapping[str, str] | None) -> None:
-        """Set the mapping."""
-        if value is None:
-            self.pop("mapping", None)
-        else:
-            # Convert to plain dict once at storage time
-            self["mapping"] = dict(value) if isinstance(value, Mapping) else value
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        A Discriminator object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("propertyName: petType\\nmapping:\\n  dog: Dog\\n  cat: Cat")
+        discriminator = build(root)
+        assert discriminator.property_name.value == 'petType'
+    """
+    return build_model(root, Discriminator, context=context)