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

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

@@ -0,0 +1,129 @@
+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 .oauth_flows import OAuthFlows
+from .oauth_flows import build as build_oauth_flows
+from .reference import Reference
+from .reference import build as build_reference
+
+
+__all__ = ["SecurityScheme", "build", "build_security_scheme_or_reference"]
+
+
+@dataclass(frozen=True, slots=True)
+class SecurityScheme:
+    """
+    Security Scheme Object representation for OpenAPI 3.1.
+
+    Defines a security scheme that can be used by operations.
+    The security scheme type determines which additional fields are required.
+
+    Attributes:
+        root_node: The top-level node representing the entire Security Scheme object in the original source file
+        type: REQUIRED. The type of the security scheme. Valid values: "apiKey", "http", "oauth2", "openIdConnect"
+        description: A short description for the security scheme. CommonMark syntax MAY be used for rich text representation
+        name: REQUIRED for apiKey. The name of the header, query or cookie parameter to be used
+        in_: REQUIRED for apiKey. The location of the API key. Valid values: "query", "header", "cookie"
+        scheme: REQUIRED for http. The name of the HTTP Authorization scheme (e.g., "basic", "bearer")
+        bearer_format: A hint to the client to identify how the bearer token is formatted (e.g., "JWT")
+        flows: REQUIRED for oauth2. An object containing configuration information for the flow types supported
+        openid_connect_url: REQUIRED for openIdConnect. OpenId Connect URL to discover OAuth2 configuration values
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    type: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    name: FieldSource[str] | None = fixed_field()
+    in_: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "in"})
+    scheme: FieldSource[str] | None = fixed_field()
+    bearer_format: FieldSource[str] | None = fixed_field(metadata={"yaml_name": "bearerFormat"})
+    flows: FieldSource[OAuthFlows] | None = fixed_field()
+    openid_connect_url: FieldSource[str] | None = fixed_field(
+        metadata={"yaml_name": "openIdConnectUrl"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> SecurityScheme | ValueSource[YAMLInvalidValue]:
+    """
+    Build a SecurityScheme 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 SecurityScheme 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("type: apiKey\\nname: api_key\\nin: header")
+        security_scheme = build(root)
+        assert security_scheme.type.value == 'apiKey'
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    security_scheme = build_model(root, SecurityScheme, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(security_scheme, SecurityScheme):
+        return security_scheme
+
+    # Manually handle special fields that build_model can't process (nested objects)
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "flows":
+            # Handle nested OAuthFlows object - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            flows = FieldSource(
+                value=build_oauth_flows(value_node, context=context),
+                key_node=key_node,
+                value_node=value_node,
+            )
+            security_scheme = replace(security_scheme, flows=flows)
+            break
+
+    return security_scheme
+
+
+def build_security_scheme_or_reference(
+    node: yaml.Node, context: Context
+) -> SecurityScheme | Reference | ValueSource[YAMLInvalidValue]:
+    """
+    Build either a SecurityScheme or Reference from a YAML node.
+
+    This helper handles the polymorphic nature of OpenAPI where many fields
+    can contain either a SecurityScheme object or a Reference object ($ref).
+
+    Args:
+        node: The YAML node to parse
+        context: Parsing context
+
+    Returns:
+        A SecurityScheme, 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 SecurityScheme
+    return build(node, context)

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

@@ -0,0 +1,111 @@
+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 .server_variable import ServerVariable
+from .server_variable import build as build_server_variable
+
+
+__all__ = ["Server", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Server:
+    """
+    Server Object representation for OpenAPI 3.1.
+
+    An object representing a Server.
+
+    Attributes:
+        root_node: The top-level node representing the entire Server object in the original source file
+        url: REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
+        description: An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation.
+        variables: A map between a variable name and its value. The value is used for substitution in the server's URL template.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    url: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    variables: FieldSource[dict[KeySource[str], ServerVariable]] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> Server | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Server 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 Server object if the node is valid, or a ValueSource containing
+        the invalid data if the root is not a MappingNode (preserving the invalid data
+        and its source location for validation).
+
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose('''
+        url: https://{environment}.example.com/api/v1
+        description: Production API server
+        variables:
+          environment:
+            default: production
+            enum:
+              - production
+              - staging
+              - development
+            description: The deployment environment
+        ''')
+        server = build(root)
+        assert server.url.value == 'https://{environment}.example.com/api/v1'
+        assert server.description.value == 'Production API server'
+        assert 'environment' in {k.value for k in server.variables.value.keys()}
+    """
+    context = context or Context()
+
+    # Use build_model for initial construction
+    server = build_model(root, Server, context=context)
+
+    # If build_model returned ValueSource (invalid node), return it immediately
+    if not isinstance(server, Server):
+        return server
+
+    # Manually handle nested variables field
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        if key == "variables":
+            # Handle variables field - map of ServerVariable objects
+            if isinstance(value_node, yaml.MappingNode):
+                variables_dict: dict[
+                    KeySource[str], ServerVariable | ValueSource[YAMLInvalidValue]
+                ] = {}
+                for var_key_node, var_value_node in value_node.value:
+                    var_key = context.yaml_constructor.construct_yaml_str(var_key_node)
+                    # Build ServerVariable for each variable - child builder handles invalid nodes
+                    variables_dict[KeySource(value=var_key, key_node=var_key_node)] = (
+                        build_server_variable(var_value_node, context=context)
+                    )
+                variables = FieldSource(
+                    value=variables_dict, key_node=key_node, value_node=value_node
+                )
+                server = replace(server, variables=variables)
+            else:
+                # Not a mapping - preserve as-is for validation
+                variables = build_field_source(key_node, value_node, context)
+                server = replace(server, variables=variables)
+            break
+
+    return server

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

@@ -0,0 +1,70 @@
+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__ = ["ServerVariable", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class ServerVariable:
+    """
+    Server Variable Object representation for OpenAPI 3.1.
+
+    An object representing a Server Variable for server URL template substitution.
+
+    Attributes:
+        root_node: The top-level node representing the entire ServerVariable object in the original source file
+        enum: An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty.
+        default: REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. If the enum is defined, the value SHOULD exist in the enum's values.
+        description: An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    enum: FieldSource[list[ValueSource[str]]] | None = fixed_field()
+    default: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> ServerVariable | ValueSource[YAMLInvalidValue]:
+    """
+    Build a ServerVariable 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 ServerVariable 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('''
+        default: production
+        enum:
+          - production
+          - staging
+          - development
+        description: The deployment environment
+        ''')
+        server_variable = build(root)
+        assert server_variable.default.value == 'production'
+        assert len(server_variable.enum.value) == 3
+        assert server_variable.enum.value[0].value == 'production'
+    """
+    return build_model(root, ServerVariable, context=context)

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

@@ -0,0 +1,63 @@
+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 .external_documentation import ExternalDocumentation
+
+
+__all__ = ["Tag", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class Tag:
+    """
+    Tag Object representation for OpenAPI 3.1.
+
+    Adds metadata to a single tag that is used by the Operation Object. It is not mandatory
+    to have a Tag Object per tag defined in the Operation Object instances.
+
+    Attributes:
+        root_node: The top-level node representing the entire Tag object in the original source file
+        name: The name of the tag. REQUIRED.
+        description: A short description for the tag. CommonMark syntax MAY be used for rich text representation.
+        external_docs: Additional external documentation for this tag.
+        extensions: Specification extensions (x-* fields)
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    description: FieldSource[str] | 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) -> Tag | ValueSource[YAMLInvalidValue]:
+    """
+    Build a Tag 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 Tag 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: pet\\ndescription: Everything about your Pets")
+        tag = build(root)
+        assert tag.name.value == 'pet'
+    """
+    return build_model(root, Tag, context=context)

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

@@ -0,0 +1,54 @@
+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__ = ["XML", "build"]
+
+
+@dataclass(frozen=True, slots=True)
+class XML:
+    """
+    XML Object representation for OpenAPI 3.1.
+
+    Attributes:
+        root_node: The top-level node representing the entire XML object in the original source file
+        name: Name of the XML element
+        namespace: XML namespace
+        prefix: XML namespace prefix
+        attribute: Whether property is an attribute (deprecated in OpenAPI 3.2+)
+        wrapped: Whether array is wrapped
+        extensions: Specification extensions
+    """
+
+    root_node: yaml.Node
+    name: FieldSource[str] | None = fixed_field()
+    namespace: FieldSource[str] | None = fixed_field()
+    prefix: FieldSource[str] | None = fixed_field()
+    attribute: FieldSource[bool] | None = fixed_field()
+    wrapped: FieldSource[bool] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
+
+
+def build(root: yaml.Node, context: Context | None = None) -> XML | ValueSource[YAMLInvalidValue]:
+    """
+    Build an XML 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 XML 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).
+    """
+    return build_model(root, XML, context=context)