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

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

@@ -0,0 +1,123 @@
+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 .example import Example
+from .media_type import MediaType
+from .reference import Reference
+from .reference import build as build_reference
+from .schema import Schema
+
+
+__all__ = ["Parameter", "build", "build_parameter_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Parameter:
+    """
+    Parameter Object representation for OpenAPI 3.0.
+
+    Describes a single operation parameter. A unique parameter is defined by a combination
+    of a name and location (in).
+
+    Attributes:
+        root_node: The top-level node representing the entire Parameter object in the original source file
+        name: The name of the parameter (case-sensitive)
+        in_: The location of the parameter. Possible values are "query", "header", "path", or "cookie"
+        description: A brief description of the parameter (may contain CommonMark syntax)
+        required: Determines whether this parameter is mandatory. For path parameters, must be true.
+                 Default is false for other parameter types.
+        deprecated: Specifies that a parameter is deprecated and should be transitioned out of usage
+        allow_empty_value: Sets the ability to pass empty-valued parameters (valid only for query parameters)
+        style: Describes how the parameter value will be serialized (default depends on 'in' value)
+        explode: When true, parameter values of type array or object generate separate parameters
+        allow_reserved: Determines whether reserved characters are allowed without percent-encoding
+        schema: The schema defining the type used for the parameter
+        example: Example of the parameter's potential value
+        examples: Examples of the parameter's potential value (map of Example objects or References)
+        content: A map containing the representations for the parameter (must contain only one entry)
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    in_: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "in"})
+    description: FieldSource[str] | None = fixed_field()
+    required: FieldSource[bool] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+    allow_empty_value: FieldSource[bool] | None = fixed_field(
+        metadata={"yaml_name": "allowEmptyValue"}
+    )
+    style: FieldSource[str] | None = fixed_field()
+    explode: FieldSource[bool] | None = fixed_field()
+    allow_reserved: FieldSource[bool] | None = fixed_field(metadata={"yaml_name": "allowReserved"})
+    schema: FieldSource["Schema | Reference"] | None = fixed_field()
+    example: FieldSource[YAMLValue] | None = fixed_field()
+    examples: FieldSource[dict[KeySource[str], "Example | Reference"]] | None = fixed_field()
+    content: FieldSource[dict[KeySource[str], "MediaType"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Parameter | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Parameter 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 Parameter 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: userId
+        in: path
+        required: true
+        schema:
+          type: integer
+        ''')
+        parameter = build(root)
+        assert parameter.name.value == 'userId'
+    """
+    return build_model(root, Parameter, context=context)
+
+
+def build_parameter_or_reference(
+    node: yaml.Node, context: Context
+) -> Parameter | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Parameter or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Parameter object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Parameter, 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 Parameter
+    return build(node, context)

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

@@ -0,0 +1,125 @@
+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_model
+from .operation import Operation
+from .operation import build as build_operation
+from .parameter import Parameter
+from .reference import Reference
+from .server import Server
+
+
+__all__ = ["PathItem", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class PathItem:
+    """
+    Path Item Object representation for OpenAPI 3.0.
+
+    Describes the operations available on a single path. A Path Item may be empty,
+    due to ACL constraints.
+
+    Attributes:
+        root_node: The top-level node representing the entire Path Item object in the original source file
+        ref: Allows referencing an external definition of this path item
+        summary: Optional string summary intended to apply to all operations in this path
+        description: Optional string description (may contain CommonMark syntax)
+        get: Definition of a GET operation on this path
+        put: Definition of a PUT operation on this path
+        post: Definition of a POST operation on this path
+        delete: Definition of a DELETE operation on this path
+        options: Definition of an OPTIONS operation on this path
+        head: Definition of a HEAD operation on this path
+        patch: Definition of a PATCH operation on this path
+        trace: Definition of a TRACE operation on this path
+        servers: Alternative server array to service all operations in this path
+        parameters: List of parameters that are applicable for all operations in this path
+        extensions: Specification extensions (x-* fields)
+    """
+
+    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()
+    get: FieldSource[Operation] | None = fixed_field()
+    put: FieldSource[Operation] | None = fixed_field()
+    post: FieldSource[Operation] | None = fixed_field()
+    delete: FieldSource[Operation] | None = fixed_field()
+    options: FieldSource[Operation] | None = fixed_field()
+    head: FieldSource[Operation] | None = fixed_field()
+    patch: FieldSource[Operation] | None = fixed_field()
+    trace: FieldSource[Operation] | None = fixed_field()
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    parameters: FieldSource[list["Parameter | Reference"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> PathItem | ValueSource[YAMLInvalidValue]:
+    """
+    Build a PathItem 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 PathItem 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: User operations
+        get:
+          summary: List users
+          responses:
+            '200':
+              description: successful operation
+        post:
+          summary: Create user
+          responses:
+            '201':
+              description: user created
+        ''')
+        path_item = build(root)
+        assert path_item.get is not None
+        assert path_item.post is not None
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    path_item = build_model(root, PathItem, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(path_item, PathItem):
+        return path_item
+
+    # Manually handle nested complex fields
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Handle HTTP method operation fields
+        if key in ("get", "put", "post", "delete", "options", "head", "patch", "trace"):
+            operation_obj = build_operation(value_node, context)
+            replacements[key] = FieldSource(
+                value=operation_obj, key_node=key_node, value_node=value_node
+            )
+
+    # Apply all replacements at once
+    if replacements:
+        path_item = replace(path_item, **replacements)
+
+    return path_item

jentic/apitools/openapi/datamodels/low/v30/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.0.
+
+    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/v30/reference.py

@@ -2,14 +2,10 @@ from dataclasses import dataclass
 
 from ruamel import yaml
 
-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,
-    ValueSource,
-    YAMLInvalidValue,
-)
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, ValueSource, YAMLInvalidValue
+from .builders import build_model
 
 
 __all__ = ["Reference", "build"]
@@ -20,7 +16,7 @@ class Reference:
     """
     Reference Object representation for OpenAPI 3.0.
 
-    A simple object to allow referencing other components in the OpenAPI document,
+    A simple object to allow referencing other components in the OpenAPI Description,
     internally and externally.
 
     Note: In OpenAPI 3.0, Reference Objects only have the $ref field.

jentic/apitools/openapi/datamodels/low/v30/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.0.
+
+    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/v30/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.0.
+
+    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)