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

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

@@ -0,0 +1,120 @@
+from dataclasses import dataclass, field
+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 .example import Example
+from .reference import Reference
+from .reference import build as build_reference
+from .schema import BooleanJSONSchema, Schema
+
+
+if TYPE_CHECKING:
+    from .media_type import MediaType
+
+
+__all__ = ["Header", "build", "build_header_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class Header:
+    """
+    Header Object representation for OpenAPI 3.1.
+
+    The Header Object follows the structure of the Parameter Object, including determining its
+    serialization strategy based on whether schema or content is present, with the following changes:
+    - name MUST NOT be specified, it is given in the corresponding headers map.
+    - in MUST NOT be specified, it is implicitly in header.
+    - All traits that are affected by the location MUST be applicable to a location of header
+      (for example, style). This means that allowEmptyValue and allowReserved MUST NOT be used,
+      and style, if used, MUST be limited to "simple".
+
+    Attributes:
+        root_node: The top-level node representing the entire Header object in the original source file
+        description: A brief description of the header. CommonMark syntax MAY be used for rich text representation.
+        required: Determines whether this header is mandatory. Default value is false.
+        deprecated: Specifies that a header is deprecated and SHOULD be transitioned out of usage. Default value is false.
+        style: Describes how the header value will be serialized depending on the type of the header value.
+               If used, MUST be limited to "simple".
+        explode: When this is true, header values of type array or object generate separate parameters for each value of the array or key-value pair of the map. Default value is false.
+        schema: The schema defining the type used for the header.
+        example: Example of the header's potential value. The example SHOULD match the specified schema and encoding properties if present.
+        examples: Examples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header encoding.
+        content: A map containing the representations for the header. The key is the media type and the value describes it.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    description: FieldSource[str] | None = fixed_field()
+    required: FieldSource[bool] | None = fixed_field()
+    deprecated: FieldSource[bool] | None = fixed_field()
+    style: FieldSource[str] | None = fixed_field()
+    explode: FieldSource[bool] | None = fixed_field()
+    schema: FieldSource["Schema | BooleanJSONSchema"] | 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
+) -> Header | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Header 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 Header 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: The number of allowed requests in the current period
+        schema:
+          type: integer
+        ''')
+        header = build(root)
+        assert header.description.value == 'The number of allowed requests in the current period'
+    """
+    return build_model(root, Header, context=context)
+
+
+def build_header_or_reference(
+    node: yaml.Node, context: Context
+) -> Header | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a Header or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a Header object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A Header, 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 Header
+    return build(node, context)

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

@@ -0,0 +1,116 @@
+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 .contact import Contact
+from .contact import build as build_contact
+from .license import License
+from .license import build as build_license
+
+
+__all__ = ["Info", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Info:
+    """
+    Info Object representation for OpenAPI 3.1.
+
+    Provides metadata about the API. The metadata MAY be used by the clients if needed,
+    and MAY be presented in editing or documentation generation tools for convenience.
+
+    Attributes:
+        root_node: The top-level node representing the entire Info object in the original source file
+        title: REQUIRED. The title of the API.
+        summary: A short summary of the API (new in OpenAPI 3.1).
+        description: A description of the API. CommonMark syntax MAY be used for rich text representation.
+        termsOfService: A URL to the Terms of Service for the API. This MUST be in the form of a URL.
+        contact: The contact information for the exposed API.
+        license: The license information for the exposed API.
+        version: REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    title: FieldSource[str] | None = fixed_field()
+    summary: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    termsOfService: FieldSource[str] | None = fixed_field()
+    contact: FieldSource[Contact] | None = fixed_field()
+    license: FieldSource[License] | None = fixed_field()
+    version: FieldSource[str] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(root: yaml.Node, context: Context | None = None) -> Info | ValueSource[YAMLInvalidValue]:
+    """
+    Build an Info 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 Info 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('''
+        title: Sample Pet Store App
+        version: 1.0.1
+        description: This is a sample server for a pet store.
+        contact:
+          name: API Support
+          email: support@example.com
+        license:
+          name: Apache 2.0
+          url: https://www.apache.org/licenses/LICENSE-2.0.html
+        ''')
+        info = build(root)
+        assert info.title.value == 'Sample Pet Store App'
+        assert info.version.value == '1.0.1'
+        assert info.contact.value.name.value == 'API Support'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    info = build_model(root, Info, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(info, Info):
+        return info
+
+    # Manually handle nested objects (contact, license)
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "contact":
+            # Handle nested Contact object - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            contact = FieldSource(
+                value=build_contact(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+            info = replace(info, contact=contact)
+        elif key == "license":
+            # Handle nested License object - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            license_obj = FieldSource(
+                value=build_license(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+            info = replace(info, license=license_obj)
+
+    return info

jentic/apitools/openapi/datamodels/low/v31/license.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__ = ["License", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class License:
+    """
+    License Object representation for OpenAPI 3.1.
+
+    License information for the exposed API.
+
+    Attributes:
+        root_node: The top-level node representing the entire License object in the original source file
+        name: REQUIRED. The license name used for the API.
+        identifier: An SPDX license expression for the API. Mutually exclusive with the url field (new in OpenAPI 3.1).
+        url: A URL to the license used for the API. Value MUST be in the format of a URL. Mutually exclusive with the identifier field.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    identifier: 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
+) -> License | ValueSource[YAMLInvalidValue]:
+    """
+    Build a License 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 License 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: MIT\\nurl: https://opensource.org/licenses/MIT")
+        license = build(root)
+        assert license.name.value == 'MIT'
+    """
+    return build_model(root, License, context=context)

jentic/apitools/openapi/datamodels/low/v31/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.1.
+
+    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/v31/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 BooleanJSONSchema, Schema
+
+
+__all__ = ["MediaType", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class MediaType:
+    """
+    Media Type Object representation for OpenAPI 3.1.
+
+    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 | BooleanJSONSchema"] | 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/v31/oauth_flow.py

@@ -0,0 +1,65 @@
+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__ = ["OAuthFlow", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthFlow:
+    """
+    OAuth Flow Object representation for OpenAPI 3.1.
+
+    Configuration details for a supported OAuth Flow.
+
+    Attributes:
+        root_node: The top-level node representing the entire OAuth Flow object in the original source file
+        authorization_url: The authorization URL to be used for this flow. REQUIRED for implicit and authorization_code flows.
+        token_url: The token URL to be used for this flow. REQUIRED for password, client_credentials, and authorization_code flows.
+        refresh_url: The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+        scopes: The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    authorization_url: FieldSource[str] | None = fixed_field(
+        metadata={"yaml_name": "authorizationUrl"}
+    )
+    token_url: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "tokenUrl"})
+    refresh_url: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "refreshUrl"})
+    scopes: 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
+) -> OAuthFlow | ValueSource[YAMLInvalidValue]:
+    """
+    Build an OAuthFlow 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 OAuthFlow 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("tokenUrl: https://example.com/oauth/token\\nscopes:\\n  read: Read access")
+        oauth_flow = build(root)
+        assert oauth_flow.tokenUrl.value == 'https://example.com/oauth/token'
+    """
+    return build_model(root, OAuthFlow, context=context)