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

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

@@ -0,0 +1,141 @@
+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 .reference import Reference
+from .reference import build as build_reference
+from .server import Server
+from .server import build as build_server
+
+
+__all__ = ["Link", "build", "build_link_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    """
+    Link Object representation for OpenAPI 3.0.
+
+    The Link Object represents a possible design-time link for a response.
+
+    Attributes:
+        root_node: The top-level node representing the entire Link object in the original source file
+        operation_ref: A relative or absolute URI reference to an OAS operation.
+        operation_id: The name of an existing, resolvable OAS operation.
+        parameters: A map representing parameters to pass to an operation as specified with operationId
+                   or identified via operationRef.
+        request_body: A literal value or {expression} to use as a request body when calling the target operation.
+        description: A description of the link. CommonMark syntax MAY be used for rich text representation.
+        server: A server object to be used by the target operation.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    operation_ref: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "operationRef"})
+    operation_id: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "operationId"})
+    parameters: FieldSource[dict[KeySource[str], ValueSource[YAMLValue]]] | None = fixed_field()
+    request_body: FieldSource[YAMLValue] | None = fixed_field(metadata={"yaml_name": "requestBody"})
+    description: FieldSource[str] | None = fixed_field()
+    server: FieldSource[Server] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(root: yaml.Node, context: Context | None = None) -> Link | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Link 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 Link 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("operationId: getUserById\\nparameters:\\n  userId: $response.body#/id")
+        link = build(root)
+        assert link.operation_id.value == 'getUserById'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    link = build_model(root, Link, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(link, Link):
+        return link
+
+    # Manually handle nested server object and parameters dict
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "server":
+            # Handle nested Server object - child builder handles invalid nodes
+            replacements["server"] = FieldSource(
+                value=build_server(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+        elif key == "parameters":
+            # Handle parameters map with KeySource/ValueSource wrapping
+            if isinstance(value_node, yaml.MappingNode):
+                params_dict: dict[KeySource[str], ValueSource[YAMLValue]] = {}
+                for param_key_node, param_value_node in value_node.value:
+                    param_key = context.yaml_constructor.construct_yaml_str(param_key_node)
+                    param_value = context.yaml_constructor.construct_object(
+                        param_value_node, deep=True
+                    )
+                    params_dict[KeySource(value=param_key, key_node=param_key_node)] = ValueSource(
+                        value=param_value, value_node=param_value_node
+                    )
+                replacements["parameters"] = FieldSource(
+                    value=params_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)
+
+    # Apply all replacements at once
+    if replacements:
+        link = replace(link, **replacements)
+
+    return link
+
+
+def build_link_or_reference(
+    node: yaml.Node, context: Context
+) -> Link | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Link or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Link object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Link, 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 Link
+    return build(node, context)

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

@@ -0,0 +1,110 @@
+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 .encoding import Encoding
+from .encoding import build as build_encoding
+from .example import Example
+from .reference import Reference
+from .schema import Schema
+
+
+__all__ = ["MediaType", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class MediaType:
+    """
+    Media Type Object representation for OpenAPI 3.0.
+
+    Each Media Type Object provides schema and examples for the media type identified by its key.
+
+    Attributes:
+        root_node: The top-level node representing the entire Media Type object in the original source file
+        schema: The schema defining the content of the request, response, or parameter.
+        example: Example of the media type. The example SHOULD match the specified schema and encoding properties if present.
+        examples: Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding.
+        encoding: A map between a property name and its encoding information. The key, being the property name,
+                 MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects
+                 when the media type is multipart or application/x-www-form-urlencoded.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    schema: FieldSource["Schema | Reference"] | None = fixed_field()
+    example: FieldSource[YAMLValue] | None = fixed_field()
+    examples: FieldSource[dict[KeySource[str], "Example | Reference"]] | None = fixed_field()
+    encoding: FieldSource[dict[KeySource[str], Encoding]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> MediaType | ValueSource[YAMLInvalidValue]:
+    """
+    Build a MediaType 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 MediaType 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('''
+        schema:
+          type: string
+        examples:
+          user:
+            value: John Doe
+        ''')
+        media_type = build(root)
+        assert media_type.schema.value.type.value == 'string'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    media_type = build_model(root, MediaType, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(media_type, MediaType):
+        return media_type
+
+    # Manually handle nested complex fields
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "encoding":
+            # Handle encoding field - map of Encoding objects
+            if isinstance(value_node, yaml.MappingNode):
+                encoding_dict: dict[KeySource[str], Encoding | ValueSource[YAMLInvalidValue]] = {}
+                for encoding_key_node, encoding_value_node in value_node.value:
+                    encoding_key = context.yaml_constructor.construct_yaml_str(encoding_key_node)
+                    # Build Encoding - child builder handles invalid nodes
+                    encoding_obj = build_encoding(encoding_value_node, context)
+                    encoding_dict[KeySource(value=encoding_key, key_node=encoding_key_node)] = (
+                        encoding_obj
+                    )
+                encoding = FieldSource(
+                    value=encoding_dict, key_node=key_node, value_node=value_node
+                )
+                media_type = replace(media_type, encoding=encoding)
+            else:
+                # Not a mapping - preserve as-is for validation
+                encoding = build_field_source(key_node, value_node, context)
+                media_type = replace(media_type, encoding=encoding)
+            break
+
+    return media_type

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

@@ -2,16 +2,10 @@ from dataclasses import dataclass, field
 
 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,
-    KeySource,
-    ValueSource,
-    YAMLInvalidValue,
-    YAMLValue,
-)
+from ..context import Context
+from ..fields import fixed_field
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .builders import build_model
 
 
 __all__ = ["OAuthFlow", "build"]

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

@@ -3,18 +3,12 @@ from typing import Any
 
 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_field, fixed_fields
-from jentic.apitools.openapi.datamodels.low.sources import (
-    FieldSource,
-    KeySource,
-    ValueSource,
-    YAMLInvalidValue,
-    YAMLValue,
-)
-from jentic.apitools.openapi.datamodels.low.v30.oauth_flow import OAuthFlow
-from jentic.apitools.openapi.datamodels.low.v30.oauth_flow import build as build_oauth_flow
+from ..context import Context
+from ..extractors import extract_extension_fields
+from ..fields import fixed_field, fixed_fields
+from ..sources import FieldSource, KeySource, ValueSource, YAMLInvalidValue, YAMLValue
+from .oauth_flow import OAuthFlow
+from .oauth_flow import build as build_oauth_flow
 
 
 __all__ = ["OAuthFlows", "build"]
@@ -74,9 +68,7 @@ def build(
         flows = build(root)
         assert flows.implicit.value.authorization_url.value == 'https://example.com/auth'
     """
-    # Initialize context once at the beginning
-    if context is None:
-        context = Context()
+    context = context or Context()
 
     if not isinstance(root, yaml.MappingNode):
         # Preserve invalid root data instead of returning None

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

@@ -0,0 +1,149 @@
+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 .components import Components
+from .components import build as build_components
+from .external_documentation import ExternalDocumentation
+from .info import Info
+from .info import build as build_info
+from .paths import Paths
+from .paths import build as build_paths
+from .security_requirement import SecurityRequirement
+from .server import Server
+from .tag import Tag
+from .tag import build as build_tag
+
+
+__all__ = ["OpenAPI30", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAPI30:
+    """
+    OpenAPI Object representation for OpenAPI 3.0.
+
+    This is the root document object of the OpenAPI document.
+
+    Attributes:
+        root_node: The top-level node representing the entire OpenAPI object in the original source file
+        openapi: REQUIRED. The version number of the OpenAPI Specification that the document uses.
+                 Must match the specification version (e.g., "3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4").
+        info: REQUIRED. Provides metadata about the API (title, version, description, etc.)
+        paths: REQUIRED. The available paths and operations for the API
+        servers: An array of Server Objects providing connectivity information to target servers
+        components: An element to hold reusable objects for different aspects of the OAS
+        security: A declaration of which security mechanisms can be used across the API
+        tags: A list of tags used by the specification with additional metadata
+        external_docs: Additional external documentation
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    openapi: FieldSource[str] | None = fixed_field()
+    info: FieldSource[Info] | None = fixed_field()
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    paths: FieldSource[Paths] | None = fixed_field()
+    components: FieldSource[Components] | None = fixed_field()
+    security: FieldSource[list["SecurityRequirement"]] | None = fixed_field()
+    tags: FieldSource[list[Tag]] | None = fixed_field()
+    external_docs: FieldSource["ExternalDocumentation"] | None = fixed_field(
+        metadata={"yaml_name": "externalDocs"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> OpenAPI30 | ValueSource[YAMLInvalidValue]:
+    """
+    Build an OpenAPI 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 OpenAPI 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('''
+        openapi: 3.0.4
+        info:
+          title: Sample API
+          version: 1.0.0
+        paths:
+          /users:
+            get:
+              responses:
+                '200':
+                  description: Success
+        ''')
+        openapi_doc = build(root)
+        assert openapi_doc.openapi.value == '3.0.4'
+        assert openapi_doc.info.value.title.value == 'Sample API'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    openapi_obj = build_model(root, OpenAPI30, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(openapi_obj, OpenAPI30):
+        return openapi_obj
+
+    # Manually handle nested complex fields and list fields with custom builders
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "info":
+            # Handle info field - Info object
+            replacements["info"] = FieldSource(
+                value=build_info(value_node, context), key_node=key_node, value_node=value_node
+            )
+
+        elif key == "paths":
+            # Handle paths field - Paths object
+            replacements["paths"] = FieldSource(
+                value=build_paths(value_node, context), key_node=key_node, value_node=value_node
+            )
+
+        elif key == "components":
+            # Handle components field - Components object
+            replacements["components"] = FieldSource(
+                value=build_components(value_node, context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+
+        elif key == "tags":
+            # Handle tags field - array of Tag objects
+            if isinstance(value_node, yaml.SequenceNode):
+                tags_list = []
+                for tag_node in value_node.value:
+                    tag_obj = build_tag(tag_node, context)
+                    tags_list.append(tag_obj)
+                replacements["tags"] = FieldSource(
+                    value=tags_list, key_node=key_node, value_node=value_node
+                )
+            else:
+                # Not a sequence - preserve as-is for validation
+                replacements["tags"] = build_field_source(key_node, value_node, context)
+
+    # Apply all replacements at once
+    if replacements:
+        openapi_obj = replace(openapi_obj, **replacements)
+
+    return openapi_obj

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

@@ -0,0 +1,134 @@
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+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 .external_documentation import ExternalDocumentation
+
+
+if TYPE_CHECKING:
+    from .callback import Callback
+
+from .parameter import Parameter
+from .reference import Reference
+from .request_body import RequestBody, build_request_body_or_reference
+from .responses import Responses
+from .responses import build as build_responses
+from .security_requirement import SecurityRequirement
+from .server import Server
+
+
+__all__ = ["Operation", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Operation:
+    """
+    Operation Object representation for OpenAPI 3.0.
+
+    Describes a single API operation on a path.
+
+    Attributes:
+        root_node: The top-level node representing the entire Operation object in the original source file
+        tags: List of tags for API documentation control
+        summary: Short summary of what the operation does
+        description: Verbose explanation of the operation behavior (may contain CommonMark syntax)
+        external_docs: Additional external documentation for this operation
+        operation_id: Unique string used to identify the operation
+        parameters: List of parameters that are applicable for this operation
+        request_body: Request body applicable for this operation
+        responses: REQUIRED. The list of possible responses as they are returned from executing this operation
+        callbacks: Map of possible out-of-band callbacks related to the parent operation
+        deprecated: Declares this operation to be deprecated
+        security: Declaration of which security mechanisms can be used for this operation
+        servers: Alternative server array to service this operation
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    tags: FieldSource[list[ValueSource[str]]] | None = fixed_field()
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    external_docs: FieldSource["ExternalDocumentation"] | None = fixed_field(
+        metadata={"yaml_name": "externalDocs"}
+    )
+    operation_id: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "operationId"})
+    parameters: FieldSource[list["Parameter | Reference"]] | None = fixed_field()
+    request_body: FieldSource[RequestBody | Reference] | None = fixed_field(
+        metadata={"yaml_name": "requestBody"}
+    )
+    responses: FieldSource[Responses] | None = fixed_field()
+    callbacks: FieldSource[dict[KeySource[str], "Callback | Reference"]] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+    security: FieldSource[list["SecurityRequirement"]] | None = fixed_field()
+    servers: FieldSource[list["Server"]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Operation | ValueSource[YAMLInvalidValue]:
+    """
+    Build an Operation 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 Operation 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: List users
+        operationId: listUsers
+        responses:
+          '200':
+            description: successful operation
+        ''')
+        operation = build(root)
+        assert operation.summary.value == 'List users'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    operation = build_model(root, Operation, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(operation, Operation):
+        return operation
+
+    # Manually handle nested complex fields
+    replacements = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "requestBody":
+            # Handle requestBody field - RequestBody or Reference
+            request_body_or_reference = build_request_body_or_reference(value_node, context)
+            replacements["request_body"] = FieldSource(
+                value=request_body_or_reference, key_node=key_node, value_node=value_node
+            )
+        elif key == "responses":
+            # Handle responses field - Responses object
+            responses_obj = build_responses(value_node, context)
+            replacements["responses"] = FieldSource(
+                value=responses_obj, key_node=key_node, value_node=value_node
+            )
+
+    # Apply all replacements at once
+    if replacements:
+        operation = replace(operation, **replacements)
+
+    return operation