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

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

@@ -0,0 +1,108 @@
+from dataclasses import dataclass, field
+
+from ruamel import yaml
+
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..sources import KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .path_item import PathItem
+from .path_item import build as build_path_item
+
+
+__all__ = ["Paths", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Paths:
+    """
+    Paths Object representation for OpenAPI 3.1.
+
+    Holds the relative paths to the individual endpoints and their operations.
+    The paths are appended to the server URL to construct the full URL.
+
+    Path field names MUST begin with a forward slash (/). Path templating is supported
+    (e.g., /users/{id}). When matching URLs, concrete (non-templated) paths are matched
+    before templated paths. Templated paths with the same hierarchy but different templated
+    names are not allowed.
+
+    Attributes:
+        root_node: The top-level node representing the entire Paths object in the original source file
+        paths: Map of path strings to Path Item Objects. Each key is a relative path that MUST begin
+               with a forward slash (/). Supports path templating with curly braces.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    paths: dict[KeySource[str], PathItem] = field(default_factory=dict)
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(root: yaml.Node, context: Context | None = None) -> Paths | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Paths 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 Paths 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('''
+        /users:
+          get:
+            summary: Get all users
+            responses:
+              '200':
+                description: Success
+        /users/{id}:
+          get:
+            summary: Get user by ID
+            parameters:
+              - name: id
+                in: path
+                required: true
+                schema:
+                  type: integer
+            responses:
+              '200':
+                description: Success
+        ''')
+        paths = build(root)
+        assert '/users' in {k.value for k in paths.paths.keys()}
+    """
+    context = context or Context()
+
+    # Check if root is a MappingNode, if not return ValueSource with invalid data
+    if not isinstance(root, yaml.MappingNode):
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Extract extensions first
+    extensions = extract_extension_fields(root, context)
+    extension_properties = {k.value for k in extensions.keys()}
+
+    # Process each field to determine if it's a path (not an extension)
+    paths = {}
+
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key not in extension_properties and key.startswith("/"):
+            # Path field (starts with / and not an extension) - build as Path Item
+            paths[KeySource(value=key, key_node=key_node)] = build_path_item(value_node, context)
+
+    # Create and return the Paths object with collected data
+    return Paths(
+        root_node=root,
+        paths=paths,
+        extensions=extensions,
+    )

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

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+
+from ruamel import yaml
+
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, ValueSource, YAMLInvalidValue
+from .builders import build_model
+
+
+__all__ = ["Reference", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Reference:
+    """
+    Reference Object representation for OpenAPI 3.1.
+
+    Allows for a reference to another document.
+
+    Attributes:
+        root_node: The top-level node representing the entire Reference object in the original source file
+        ref: REQUIRED. The reference identifier. This MUST be in the form of a URI.
+        summary: A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not allow a summary field, then this field has no effect.
+        description: A description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.
+    """
+
+    root_node: yaml.Node
+    ref: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "$ref"})
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Reference 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 Reference 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('''
+        $ref: '#/components/schemas/Pet'
+        summary: A Pet reference
+        description: Reference to the Pet schema in components
+        ''')
+        reference = build(root)
+        assert reference.ref.value == '#/components/schemas/Pet'
+        assert reference.summary.value == 'A Pet reference'
+        assert reference.description.value == 'Reference to the Pet schema in components'
+    """
+    return build_model(root, Reference, context=context)

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

@@ -0,0 +1,108 @@
+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 .media_type import MediaType
+from .reference import Reference
+from .reference import build as build_reference
+
+
+__all__ = ["RequestBody", "build", "build_request_body_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class RequestBody:
+    """
+    Request Body Object representation for OpenAPI 3.1.
+
+    Describes a single request body.
+
+    Attributes:
+        root_node: The top-level node representing the entire Request Body object in the original source file
+        description: A brief description of the request body. CommonMark syntax MAY be used for rich text representation.
+        content: The content of the request body. The key is a media type or media type range and the value describes it.
+                For requests that match multiple keys, only the most specific key is applicable.
+        required: Determines if the request body is required in the request. Defaults to false.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    description: FieldSource[str] | None = fixed_field()
+    content: FieldSource[dict[KeySource[str], "MediaType"]] | None = fixed_field()
+    required: FieldSource[bool] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> RequestBody | ValueSource[YAMLInvalidValue]:
+    """
+    Build a RequestBody 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 RequestBody 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('''
+        description: user to add to the system
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+        ''')
+        request_body = build(root)
+        assert request_body.description.value == 'user to add to the system'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    request_body = build_model(root, RequestBody, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(request_body, RequestBody):
+        return request_body
+
+    return request_body
+
+
+def build_request_body_or_reference(
+    node: yaml.Node, context: Context
+) -> RequestBody | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a RequestBody or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a RequestBody object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A RequestBody, 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 RequestBody
+    return build(node, context)

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

@@ -0,0 +1,104 @@
+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 .link import Link
+from .media_type import MediaType
+from .reference import Reference
+from .reference import build as build_reference
+
+
+__all__ = ["Response", "build", "build_response_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    """
+    Response Object representation for OpenAPI 3.1.
+
+    Describes a single response from an API Operation, including design-time, static links
+    to operations based on the response.
+
+    Attributes:
+        root_node: The top-level node representing the entire Response object in the original source file
+        description: A description of the response. CommonMark syntax MAY be used for rich text representation.
+        headers: Maps a header name to its definition.
+        content: A map containing descriptions of potential response payloads. The key is a media type or media type range
+                and the value describes it. For responses that match multiple keys, only the most specific key is applicable.
+        links: A map of operations links that can be followed from the response. The key is a short name for the link,
+              following the naming constraints of the Components Object.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    description: FieldSource[str] | None = fixed_field()
+    headers: FieldSource[dict[KeySource[str], "Header | Reference"]] | None = fixed_field()
+    content: FieldSource[dict[KeySource[str], "MediaType"]] | None = fixed_field()
+    links: FieldSource[dict[KeySource[str], "Link | Reference"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Response | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Response 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 Response 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('''
+        description: successful operation
+        content:
+          application/json:
+            schema:
+              type: object
+        ''')
+        response = build(root)
+        assert response.description.value == 'successful operation'
+    """
+    return build_model(root, Response, context=context)
+
+
+def build_response_or_reference(
+    node: yaml.Node, context: Context
+) -> Response | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Response or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Response object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Response, 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 Response
+    return build(node, context)

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

@@ -0,0 +1,109 @@
+import re
+from dataclasses import dataclass, field
+from typing import cast
+
+from ruamel import yaml
+
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .reference import Reference
+from .response import Response, build_response_or_reference
+
+
+__all__ = ["Responses", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Responses:
+    """
+    Responses Object representation for OpenAPI 3.1.
+
+    A container for the expected responses of an operation. The container maps a HTTP response code
+    to the expected response.
+
+    Attributes:
+        root_node: The top-level node representing the entire Responses object in the original source file
+        default: The documentation of responses other than the ones declared for specific HTTP response codes.
+                Use this field to cover undeclared responses.
+        responses: Maps HTTP status codes to their Response objects. The key is the HTTP status code
+                  (e.g., "200", "404", "4XX") and the value is a Response object or Reference.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    default: FieldSource[Response | Reference] | None = fixed_field()
+    responses: dict[KeySource[str], Response | Reference] = field(default_factory=dict)
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Responses | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Responses 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 Responses 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('''
+        '200':
+          description: successful operation
+        '404':
+          description: not found
+        default:
+          description: unexpected error
+        ''')
+        responses = build(root)
+        assert '200' in {k.value for k in responses.responses.keys()}
+    """
+    context = context or Context()
+
+    # Check if root is a MappingNode, if not return ValueSource with invalid data
+    if not isinstance(root, yaml.MappingNode):
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Process each field to determine if it's default or a status code response
+    responses = {}
+    default: FieldSource[Response | Reference] | None = None
+
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "default":
+            # Handle default response - can be Response or Reference
+            response_or_reference = build_response_or_reference(value_node, context)
+            default = cast(
+                FieldSource[Response | Reference],
+                FieldSource(value=response_or_reference, key_node=key_node, value_node=value_node),
+            )
+        elif _HTTP_STATUS_CODE_PATTERN.match(key):
+            # Valid HTTP status code (100-599) or pattern (1XX-5XX)
+            response_or_reference = build_response_or_reference(value_node, context)
+            responses[KeySource(value=key, key_node=key_node)] = response_or_reference
+
+    # Create and return the Responses object with collected data
+    return Responses(
+        root_node=root,
+        default=default,
+        responses=responses,
+        extensions=extract_extension_fields(root, context),
+    )
+
+
+# Pattern for valid HTTP status codes: 100-599 or wildcard patterns (1XX-5XX)
+_HTTP_STATUS_CODE_PATTERN = re.compile(r"^([1-5]XX|[1-5][0-9]{2})$")