jentic-openapi-datamodels 1.0.0a18__py3-none-any.whl → 1.0.0a19__py3-none-any.whl

jentic/apitools/openapi/datamodels/low/v31/components.py

@@ -0,0 +1,240 @@
+from dataclasses import dataclass, field, replace
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_field_source, build_model
+from .callback import Callback
+from .example import Example, build_example_or_reference
+from .header import Header
+from .link import Link
+from .parameter import Parameter, build_parameter_or_reference
+from .path_item import PathItem
+from .reference import Reference
+from .request_body import RequestBody, build_request_body_or_reference
+from .response import Response, build_response_or_reference
+from .schema import BooleanJSONSchema, Schema
+from .schema import build as build_schema
+from .security_scheme import SecurityScheme, build_security_scheme_or_reference
+
+
+__all__ = ["Components", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Components:
+    r"""
+    Components Object representation for OpenAPI 3.1.
+
+    Holds reusable objects for different aspects of the OAS. All objects defined within
+    the components object have no effect on the API unless they are explicitly referenced
+    from properties outside the components object.
+
+    All component keys MUST match the regex pattern: ^[a-zA-Z0-9\.\-_]+$
+    (Note: This is a validation concern and not enforced by this low-level model)
+
+    Attributes:
+        root_node: The top-level node representing the entire Components object in the original source file
+        schemas: Reusable Schema Objects (can include $ref directly in OpenAPI 3.1)
+        responses: Reusable Response Objects or Reference Objects
+        parameters: Reusable Parameter Objects or Reference Objects
+        examples: Reusable Example Objects or Reference Objects
+        request_bodies: Reusable Request Body Objects or Reference Objects
+        headers: Reusable Header Objects or Reference Objects
+        security_schemes: Reusable Security Scheme Objects or Reference Objects
+        links: Reusable Link Objects or Reference Objects
+        callbacks: Reusable Callback Objects or Reference Objects
+        path_items: Reusable Path Item Objects (new in OpenAPI 3.1)
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    schemas: FieldSource[dict[KeySource[str], Schema | BooleanJSONSchema]] | None = fixed_field()
+    responses: FieldSource[dict[KeySource[str], Response | Reference]] | None = fixed_field()
+    parameters: FieldSource[dict[KeySource[str], Parameter | Reference]] | None = fixed_field()
+    examples: FieldSource[dict[KeySource[str], Example | Reference]] | None = fixed_field()
+    request_bodies: FieldSource[dict[KeySource[str], RequestBody | Reference]] | None = fixed_field(
+        metadata={"yaml_name": "requestBodies"}
+    )
+    headers: FieldSource[dict[KeySource[str], "Header | Reference"]] | None = fixed_field()
+    security_schemes: FieldSource[dict[KeySource[str], SecurityScheme | Reference]] | None = (
+        fixed_field(metadata={"yaml_name": "securitySchemes"})
+    )
+    links: FieldSource[dict[KeySource[str], "Link | Reference"]] | None = fixed_field()
+    callbacks: FieldSource[dict[KeySource[str], "Callback | Reference"]] | None = fixed_field()
+    path_items: FieldSource[dict[KeySource[str], "PathItem"]] | None = fixed_field(
+        metadata={"yaml_name": "pathItems"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Components | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Components 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.
+
+    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 Components 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('''
+        schemas:
+          User:
+            type: object
+            properties:
+              id:
+                type: integer
+              name:
+                type: string
+        responses:
+          NotFound:
+            description: Entity not found
+        ''')
+        components = build(root)
+        assert 'User' in {k.value for k in components.schemas.value.keys()}
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    components_obj = build_model(root, Components, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(components_obj, Components):
+        return components_obj
+
+    # Manually handle nested complex fields that aren't covered by build_model
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "schemas":
+            # Handle schemas field - map of Schema objects (in 3.1, schemas can have $ref directly)
+            if isinstance(value_node, yaml.MappingNode):
+                schemas_dict = {}
+                for schema_key_node, schema_value_node in value_node.value:
+                    schema_key = context.yaml_constructor.construct_yaml_str(schema_key_node)
+                    schema = build_schema(schema_value_node, context)
+                    schemas_dict[KeySource(value=schema_key, key_node=schema_key_node)] = schema
+                replacements["schemas"] = FieldSource(
+                    value=schemas_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["schemas"] = build_field_source(key_node, value_node, context)
+
+        elif key == "responses":
+            # Handle responses field - map of Response or Reference objects
+            if isinstance(value_node, yaml.MappingNode):
+                responses_dict = {}
+                for response_key_node, response_value_node in value_node.value:
+                    response_key = context.yaml_constructor.construct_yaml_str(response_key_node)
+                    response_or_reference = build_response_or_reference(
+                        response_value_node, context
+                    )
+                    responses_dict[KeySource(value=response_key, key_node=response_key_node)] = (
+                        response_or_reference
+                    )
+                replacements["responses"] = FieldSource(
+                    value=responses_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["responses"] = build_field_source(key_node, value_node, context)
+
+        elif key == "parameters":
+            # Handle parameters field - map of Parameter or Reference objects
+            if isinstance(value_node, yaml.MappingNode):
+                parameters_dict = {}
+                for parameter_key_node, parameter_value_node in value_node.value:
+                    parameter_key = context.yaml_constructor.construct_yaml_str(parameter_key_node)
+                    parameter_or_reference = build_parameter_or_reference(
+                        parameter_value_node, context
+                    )
+                    parameters_dict[KeySource(value=parameter_key, key_node=parameter_key_node)] = (
+                        parameter_or_reference
+                    )
+                replacements["parameters"] = FieldSource(
+                    value=parameters_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["parameters"] = build_field_source(key_node, value_node, context)
+
+        elif key == "examples":
+            # Handle examples field - map of Example or Reference objects
+            if isinstance(value_node, yaml.MappingNode):
+                examples_dict = {}
+                for example_key_node, example_value_node in value_node.value:
+                    example_key = context.yaml_constructor.construct_yaml_str(example_key_node)
+                    example_or_reference = build_example_or_reference(example_value_node, context)
+                    examples_dict[KeySource(value=example_key, key_node=example_key_node)] = (
+                        example_or_reference
+                    )
+                replacements["examples"] = FieldSource(
+                    value=examples_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["examples"] = build_field_source(key_node, value_node, context)
+
+        elif key == "requestBodies":
+            # Handle requestBodies field - map of RequestBody or Reference objects
+            if isinstance(value_node, yaml.MappingNode):
+                request_bodies_dict = {}
+                for request_body_key_node, request_body_value_node in value_node.value:
+                    request_body_key = context.yaml_constructor.construct_yaml_str(
+                        request_body_key_node
+                    )
+                    request_body_or_reference = build_request_body_or_reference(
+                        request_body_value_node, context
+                    )
+                    request_bodies_dict[
+                        KeySource(value=request_body_key, key_node=request_body_key_node)
+                    ] = request_body_or_reference
+                replacements["request_bodies"] = FieldSource(
+                    value=request_bodies_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["request_bodies"] = build_field_source(key_node, value_node, context)
+
+        elif key == "securitySchemes":
+            # Handle securitySchemes field - map of SecurityScheme or Reference objects
+            if isinstance(value_node, yaml.MappingNode):
+                security_schemes_dict = {}
+                for security_scheme_key_node, security_scheme_value_node in value_node.value:
+                    security_scheme_key = context.yaml_constructor.construct_yaml_str(
+                        security_scheme_key_node
+                    )
+                    security_scheme_or_reference = build_security_scheme_or_reference(
+                        security_scheme_value_node, context
+                    )
+                    security_schemes_dict[
+                        KeySource(value=security_scheme_key, key_node=security_scheme_key_node)
+                    ] = security_scheme_or_reference
+                replacements["security_schemes"] = FieldSource(
+                    value=security_schemes_dict, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a mapping - preserve as-is for validation
+                replacements["security_schemes"] = build_field_source(key_node, value_node, context)
+
+    # Apply all replacements at once
+    if replacements:
+        components_obj = replace(components_obj, **replacements)
+
+    return components_obj

jentic/apitools/openapi/datamodels/low/v31/contact.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+
+
+__all__ = ["Contact", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Contact:
+    """
+    Contact Object representation for OpenAPI 3.1.
+
+    Contact information for the exposed API.
+
+    Attributes:
+        root_node: The top-level node representing the entire Contact object in the original source file
+        name: The identifying name of the contact person/organization.
+        url: The URL pointing to the contact information. Value MUST be in the format of a URL.
+        email: The email address of the contact person/organization. Value MUST be in the format of an email address.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    url: FieldSource[str] | None = fixed_field()
+    email: FieldSource[str] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Contact | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Contact 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.
+
+    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 Contact 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("name: API Support\\nemail: support@example.com")
+        contact = build(root)
+        assert contact.name.value == 'API Support'
+    """
+    return build_model(root, Contact, context=context)

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

@@ -0,0 +1,62 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+
+
+__all__ = ["Discriminator", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Discriminator:
+    """
+    Discriminator Object representation for OpenAPI 3.1.
+
+    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.
+
+    In OpenAPI 3.1, the Discriminator Object supports Specification Extensions (x-* fields).
+
+    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
+        extensions: Specification extensions (x-* fields)
+    """
+
+    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()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+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.
+
+    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)

jentic/apitools/openapi/datamodels/low/v31/encoding.py

@@ -0,0 +1,81 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .header import Header
+from .reference import Reference
+
+
+__all__ = ["Encoding", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Encoding:
+    """
+    Encoding Object representation for OpenAPI 3.1.
+
+    A single encoding definition applied to a single schema property.
+
+    Attributes:
+        root_node: The top-level node representing the entire Encoding object in the original source file
+        contentType: The Content-Type for encoding a specific property. Default value depends on the property type:
+                     for string with format being binary – application/octet-stream;
+                     for other primitive types – text/plain;
+                     for object - application/json;
+                     for array – the default is defined based on the inner type.
+        headers: A map allowing additional information to be provided as headers. Content-Type is described
+                separately and SHALL be ignored if included.
+        style: Describes how a specific property value will be serialized depending on its type.
+        explode: When this is true, property values of type array or object generate separate parameters
+                for each value of the array, or key-value-pair of the map. For other data types this property
+                has no effect. Default value is true.
+        allowReserved: Determines whether the parameter value SHOULD allow reserved characters, as defined by
+                      RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    contentType: FieldSource[str] | None = fixed_field()
+    headers: FieldSource[dict[KeySource[str], "Header | Reference"]] | None = fixed_field()
+    style: FieldSource[str] | None = fixed_field()
+    explode: FieldSource[bool] | None = fixed_field()
+    allowReserved: FieldSource[bool] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Encoding | ValueSource[YAMLInvalidValue]:
+    """
+    Build an Encoding 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.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An Encoding 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('''
+        contentType: application/xml
+        headers:
+          X-Rate-Limit:
+            schema:
+              type: integer
+        ''')
+        encoding = build(root)
+        assert encoding.contentType.value == 'application/xml'
+    """
+    return build_model(root, Encoding, context=context)

jentic/apitools/openapi/datamodels/low/v31/example.py

@@ -0,0 +1,91 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+from .reference import Reference
+from .reference import build as build_reference
+
+
+__all__ = ["Example", "build", "build_example_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Example:
+    """
+    Example Object representation for OpenAPI 3.1.
+
+    Attributes:
+        root_node: The top-level node representing the entire Example object in the original source file
+        summary: A short description of the example.
+        description: A long description for the example. CommonMark syntax MAY be used for rich text representation.
+        value: Embedded literal example. The value field and externalValue field are mutually exclusive.
+        external_value: A URL that points to the literal example. This provides the capability to reference
+                       examples that cannot be inlined. The value field and externalValue field are mutually exclusive.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    value: FieldSource[YAMLValue] | None = fixed_field()
+    external_value: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "externalValue"})
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Example | ValueSource[YAMLInvalidValue]:
+    """
+    Build an Example 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.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An Example 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("summary: A user example\\nvalue:\\n  id: 1\\n  name: John")
+        example = build(root)
+        assert example.summary.value == 'A user example'
+    """
+    return build_model(root, Example, context=context)
+
+
+def build_example_or_reference(
+    node: yaml.Node, context: Context
+) -> Example | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either an Example or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either an Example object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        An Example, Reference, or ValueSource if the node is invalid
+    """
+    # Check if it's a reference (has $ref key)
+    if isinstance(node, yaml.MappingNode):
+        for key_node, _ in node.value:
+            key = context.yaml_constructor.construct_yaml_str(key_node)
+            if key == "$ref":
+                return build_reference(node, context)
+
+    # Otherwise, try to build as Example
+    return build(node, context)

jentic/apitools/openapi/datamodels/low/v31/external_documentation.py

@@ -0,0 +1,59 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
+
+
+__all__ = ["ExternalDocumentation", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalDocumentation:
+    """
+    External Documentation Object representation for OpenAPI 3.1.
+
+    Allows referencing an external resource for extended documentation.
+
+    Attributes:
+        root_node: The top-level node representing the entire External Documentation object in the original source file
+        description: A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+        url: The URL for the target documentation. REQUIRED. Value MUST be in the format of a URL.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    description: FieldSource[str] | None = fixed_field()
+    url: FieldSource[str] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> ExternalDocumentation | ValueSource[YAMLInvalidValue]:
+    """
+    Build an ExternalDocumentation 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.
+
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
+
+    Returns:
+        An ExternalDocumentation 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("url: https://example.com\\ndescription: Find more info here")
+        external_docs = build(root)
+        assert external_docs.url.value == 'https://example.com'
+    """
+    return build_model(root, ExternalDocumentation, context=context)