jentic-openapi-datamodels 1.0.0a12__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

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

@@ -1,91 +1,101 @@
-"""
-OpenAPI 3.0.4 Security Requirement Object model.
+from dataclasses import dataclass
 
-The Security Requirement Object defines which security mechanisms can be used for a
-particular operation. Each named security scheme is mapped to a list of scope names
-required for execution (for OAuth2/OIDC) or an empty list (for other schemes).
-"""
+from ruamel import yaml
+from ruamel.yaml import MappingNode, SequenceNode
 
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.context import Context
+from jentic.apitools.openapi.datamodels.low.fields import patterned_field
+from jentic.apitools.openapi.datamodels.low.sources import KeySource, ValueSource
 
 
-__all__ = ["SecurityRequirement"]
+__all__ = ["SecurityRequirement", "build"]
 
 
-class SecurityRequirement(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class SecurityRequirement:
     """
-    Represents a Security Requirement Object from OpenAPI 3.0.4.
+    Security Requirement Object representation for OpenAPI 3.0.
 
-    This IS a mapping. Keys are security scheme names, values are lists of scope strings.
+    Lists the required security schemes to execute an operation. Each named security scheme
+    must correspond to a security scheme declared in the Security Schemes under the Components Object.
 
-    Lists the required security schemes to execute an operation. For each security
-    scheme, a list of scope names is provided. When multiple Security Requirement
-    Objects are defined, only ONE needs to be satisfied to authorize the request.
+    When multiple Security Requirement Objects are specified, only ONE needs to be satisfied
+    to authorize a request. Within a single Security Requirement Object, ALL schemes must be satisfied.
 
-    IMPORTANT: Security Requirement Objects do NOT support specification extensions.
-    Any key starting with "x-" is treated as a security scheme name, not an extension.
+    Note: An empty Security Requirement object ({}) makes security optional for the operation.
+    Note: Specification extensions (x-* fields) are NOT supported for Security Requirement objects.
 
-    Example:
-        >>> # Non-OAuth2 requirement
-        >>> req = SecurityRequirement({"api_key": []})
-        >>> req["api_key"]
-        []
-
-        >>> # OAuth2 requirement with scopes
-        >>> req = SecurityRequirement({"petstore_auth": ["write:pets", "read:pets"]})
-        >>> req["petstore_auth"]
-        ['write:pets', 'read:pets']
-
-        >>> # Empty requirement (makes security optional)
-        >>> req = SecurityRequirement({})
-
-        >>> # Security scheme named "x-custom" (NOT an extension)
-        >>> req = SecurityRequirement({"x-custom": []})
-        >>> "x-custom" in req
-        True
+    Attributes:
+        root_node: The top-level node representing the entire Security Requirement object in the original source file
+        requirements: Dictionary mapping security scheme names to arrays of scope strings.
+                     For OAuth2 schemes, the array contains required scopes.
+                     For other schemes (API key, HTTP), the array is empty.
     """
 
-    _supports_extensions: bool = False
-
-    def __getitem__(self, key: str) -> list[str]:
-        """Get scopes for a security scheme (dict-style access)."""
-        return super().__getitem__(key)  # type: ignore
-
-    def __getattr__(self, name: str) -> list[str]:
-        """Get scopes for a security scheme (attribute-style access)."""
-        return super().__getattr__(name)  # type: ignore
-
-    def get_schemes(self) -> list[str]:
-        """
-        Get the list of security scheme names referenced.
-
-        Returns:
-            List of security scheme names
-        """
-        return list(self.keys())
+    root_node: yaml.Node
+    requirements: ValueSource[dict[KeySource[str], ValueSource[list[ValueSource[str]]]]] | None = (
+        patterned_field()
+    )
 
-    def get_scopes(self, scheme_name: str) -> list[str]:
-        """
-        Get the scopes required for a specific security scheme.
 
-        Args:
-            scheme_name: Name of the security scheme
-
-        Returns:
-            List of scope names (empty for non-OAuth2/OIDC schemes)
+def build(root: yaml.Node, context: Context | None = None) -> SecurityRequirement | None:
+    """
+    Build a SecurityRequirement object from a YAML node.
 
-        Raises:
-            KeyError: If scheme_name is not in this requirement
-        """
-        return self[scheme_name]
+    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.
 
-    def is_empty(self) -> bool:
-        """
-        Check if this is an empty security requirement.
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
 
-        Empty requirements ({}) make security optional for an operation.
+    Returns:
+        A SecurityRequirement object if the node is valid, None otherwise
 
-        Returns:
-            True if requirements mapping is empty
-        """
-        return len(self) == 0
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("api_key: []")
+        security_req = build(root)
+        assert security_req.requirements is not None
+    """
+    if not isinstance(root, MappingNode):
+        return None
+
+    if context is None:
+        context = Context()
+
+    requirements_dict: dict[KeySource[str], ValueSource[list[ValueSource[str]]]] = {}
+
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Skip non-string keys
+        if not isinstance(key, str):
+            continue
+
+        # Security scheme requirement field
+        # For requirements, we need to wrap each scope string in ValueSource
+        if isinstance(value_node, SequenceNode):
+            # Wrap each scope string in the array with its source node
+            scope_list: list[ValueSource[str]] = []
+            for item_node in value_node.value:
+                item_value = context.yaml_constructor.construct_object(item_node, deep=True)
+                scope_list.append(ValueSource(value=item_value, value_node=item_node))
+
+            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+                value=scope_list, value_node=value_node
+            )
+        else:
+            # Not a sequence - preserve as-is for validation to catch
+            value = context.yaml_constructor.construct_object(value_node, deep=True)
+            requirements_dict[KeySource(value=key, key_node=key_node)] = ValueSource(
+                value=value, value_node=value_node
+            )
+
+    return SecurityRequirement(
+        root_node=root,
+        requirements=(
+            ValueSource(value=requirements_dict, value_node=root) if requirements_dict else None
+        ),
+    )

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

@@ -1,301 +1,109 @@
-"""
-OpenAPI 3.0.4 Security Scheme Object model.
-
-Defines a security scheme that can be used by the operations.
-"""
-
-from collections.abc import Mapping
-from typing import Any
-
+from dataclasses import dataclass, field, replace
+
+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 jentic.apitools.openapi.datamodels.low.v30.oauth_flows import OAuthFlows
-from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.v30.oauth_flows import build as build_oauth_flows
 
 
-__all__ = ["SecurityScheme"]
+__all__ = ["SecurityScheme", "build"]
 
 
-class SecurityScheme(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class SecurityScheme:
     """
-    Represents a Security Scheme Object from OpenAPI 3.0.4.
-
-    Defines a security scheme that can be used by the operations. Different
-    scheme types require different combinations of fields.
-
-    Supports specification extensions (x-* fields).
-
-    Example:
-        >>> # API Key scheme
-        >>> scheme = SecurityScheme({
-        ...     "type": "apiKey",
-        ...     "name": "api_key",
-        ...     "in": "header"
-        ... })
-        >>> scheme.type
-        'apiKey'
-        >>> scheme.in_
-        'header'
-
-        >>> # HTTP Bearer scheme
-        >>> scheme = SecurityScheme({
-        ...     "type": "http",
-        ...     "scheme": "bearer",
-        ...     "bearerFormat": "JWT"
-        ... })
-        >>> scheme.is_http()
-        True
-        >>> scheme.bearer_format
-        'JWT'
-
-        >>> # OAuth2 scheme with flows
-        >>> scheme = SecurityScheme({
-        ...     "type": "oauth2",
-        ...     "flows": {
-        ...         "implicit": {
-        ...             "authorizationUrl": "https://example.com/oauth/authorize",
-        ...             "scopes": {"read": "Read access"}
-        ...         }
-        ...     }
-        ... })
-        >>> scheme.is_oauth2()
-        True
-        >>> scheme.flows.implicit.authorization_url
-        'https://example.com/oauth/authorize'
-
-        >>> # OpenID Connect scheme
-        >>> scheme = SecurityScheme({
-        ...     "type": "openIdConnect",
-        ...     "openIdConnectUrl": "https://example.com/.well-known/openid-configuration"
-        ... })
-        >>> scheme.is_openid_connect()
-        True
+    Security Scheme Object representation for OpenAPI 3.0.
+
+    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)
     """
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset(
-        {"type", "description", "name", "in", "scheme", "bearerFormat", "flows", "openIdConnectUrl"}
+    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 __init__(self, data: Mapping[str, Any] | None = None):
-        """
-        Initialize a SecurityScheme object.
-
-        Automatically marshals nested flows data (Mapping) into OAuthFlows instance.
-
-        Args:
-            data: Optional mapping to initialize the object with
-        """
-        super().__init__()
-        if data:
-            for key, value in data.items():
-                # Marshal flows field specifically if it's a raw Mapping (not already OAuthFlows)
-                if (
-                    key == "flows"
-                    and isinstance(value, Mapping)
-                    and not isinstance(value, OAuthFlows)
-                ):
-                    self[key] = OAuthFlows(value)
-                else:
-                    # Store as-is (already OAuthFlows, extension, or other)
-                    self[key] = self._copy_value(value)
-
-    @property
-    def type(self) -> str | None:
-        """
-        The type of the security scheme.
-
-        Valid values: "apiKey", "http", "oauth2", "openIdConnect", "mutualTLS"
-
-        REQUIRED field.
-
-        Returns:
-            Security scheme type or None if not present
-        """
-        return self.get("type")
-
-    @type.setter
-    def type(self, value: str | None) -> None:
-        """Set the security scheme type."""
-        if value is None:
-            self.pop("type", None)
-        else:
-            self["type"] = value
-
-    @property
-    def description(self) -> str | None:
-        """
-        A description for security scheme.
-
-        Returns:
-            Description or None if not present
-        """
-        return self.get("description")
-
-    @description.setter
-    def description(self, value: str | None) -> None:
-        """Set the description."""
-        if value is None:
-            self.pop("description", None)
-        else:
-            self["description"] = value
-
-    @property
-    def name(self) -> str | None:
-        """
-        The name of the header, query or cookie parameter.
-
-        REQUIRED for apiKey type.
-
-        Returns:
-            Parameter name or None if not present
-        """
-        return self.get("name")
-
-    @name.setter
-    def name(self, value: str | None) -> None:
-        """Set the parameter name."""
-        if value is None:
-            self.pop("name", None)
-        else:
-            self["name"] = value
-
-    @property
-    def in_(self) -> str | None:
-        """
-        The location of the API key.
-
-        Valid values: "query", "header", "cookie"
-
-        REQUIRED for apiKey type.
 
-        Note: Uses 'in_' to avoid Python keyword collision.
-
-        Returns:
-            Location or None if not present
-        """
-        return self.get("in")
-
-    @in_.setter
-    def in_(self, value: str | None) -> None:
-        """Set the API key location."""
-        if value is None:
-            self.pop("in", None)
-        else:
-            self["in"] = value
-
-    @property
-    def scheme(self) -> str | None:
-        """
-        The name of the HTTP Authorization scheme.
-
-        Examples: "bearer", "basic", "digest"
-
-        REQUIRED for http type.
-
-        Returns:
-            Scheme name or None if not present
-        """
-        return self.get("scheme")
-
-    @scheme.setter
-    def scheme(self, value: str | None) -> None:
-        """Set the HTTP scheme."""
-        if value is None:
-            self.pop("scheme", None)
-        else:
-            self["scheme"] = value
-
-    @property
-    def bearer_format(self) -> str | None:
-        """
-        A hint to the client to identify how the bearer token is formatted.
-
-        Examples: "JWT", "opaque"
-
-        Returns:
-            Bearer format or None if not present
-        """
-        return self.get("bearerFormat")
-
-    @bearer_format.setter
-    def bearer_format(self, value: str | None) -> None:
-        """Set the bearer format."""
-        if value is None:
-            self.pop("bearerFormat", None)
-        else:
-            self["bearerFormat"] = value
-
-    @property
-    def flows(self) -> OAuthFlows | None:
-        """
-        Configuration information for the OAuth flows.
-
-        REQUIRED for oauth2 type.
-
-        Returns:
-            OAuthFlows instance or None if not present
-        """
-        return self.get("flows")
-
-    @flows.setter
-    def flows(self, value: OAuthFlows | None) -> None:
-        """Set the OAuth flows configuration."""
-        if value is None:
-            self.pop("flows", None)
-        else:
-            self["flows"] = value
-
-    @property
-    def open_id_connect_url(self) -> str | None:
-        """
-        OpenID Connect URL to discover OAuth2 configuration values.
-
-        REQUIRED for openIdConnect type.
-
-        Returns:
-            OpenID Connect URL or None if not present
-        """
-        return self.get("openIdConnectUrl")
-
-    @open_id_connect_url.setter
-    def open_id_connect_url(self, value: str | None) -> None:
-        """Set the OpenID Connect URL."""
-        if value is None:
-            self.pop("openIdConnectUrl", None)
-        else:
-            self["openIdConnectUrl"] = value
-
-    def is_api_key(self) -> bool:
-        """
-        Check if this is an API Key security scheme.
-
-        Returns:
-            True if type is "apiKey"
-        """
-        return self.type == "apiKey"
-
-    def is_http(self) -> bool:
-        """
-        Check if this is an HTTP security scheme.
-
-        Returns:
-            True if type is "http"
-        """
-        return self.type == "http"
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> SecurityScheme | ValueSource[YAMLInvalidValue]:
+    """
+    Build a SecurityScheme object from a YAML node.
 
-    def is_oauth2(self) -> bool:
-        """
-        Check if this is an OAuth2 security scheme.
+    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.
 
-        Returns:
-            True if type is "oauth2"
-        """
-        return self.type == "oauth2"
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
 
-    def is_openid_connect(self) -> bool:
-        """
-        Check if this is an OpenID Connect security scheme.
+    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).
 
-        Returns:
-            True if type is "openIdConnect"
-        """
-        return self.type == "openIdConnect"
+    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'
+    """
+    # Initialize context once at the beginning
+    if context is None:
+        context = Context()
+
+    if not isinstance(root, yaml.MappingNode):
+        # Preserve invalid root data instead of returning None
+        value = context.yaml_constructor.construct_object(root, deep=True)
+        return ValueSource(value=value, value_node=root)
+
+    # Use build_model to handle most fields
+    security_scheme = build_model(root, SecurityScheme, context=context)
+
+    # 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