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

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

@@ -1,79 +1,65 @@
-"""
-OpenAPI 3.0.4 External Documentation Object model.
+from dataclasses import dataclass, field
 
-Allows referencing an external resource for extended documentation.
-"""
+from ruamel import yaml
 
-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 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,
+)
 
 
-__all__ = ["ExternalDocumentation"]
+__all__ = ["ExternalDocumentation", "build"]
 
 
-class ExternalDocumentation(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class ExternalDocumentation:
     """
-    Represents an External Documentation Object from OpenAPI 3.0.4.
+    External Documentation Object representation for OpenAPI 3.0.
 
     Allows referencing an external resource for extended documentation.
 
-    Supports specification extensions (x-* fields).
-
-    Example:
-        >>> # Basic external docs
-        >>> docs = ExternalDocumentation({
-        ...     "url": "https://example.com/docs"
-        ... })
-        >>> docs.url
-        'https://example.com/docs'
-
-        >>> # With description
-        >>> docs = ExternalDocumentation({
-        ...     "description": "Find more info here",
-        ...     "url": "https://example.com/docs/api"
-        ... })
-        >>> docs.description
-        'Find more info here'
-        >>> docs.url
-        'https://example.com/docs/api'
+    Attributes:
+        root_node: The top-level node representing the entire External Documentation object in the original source file
+        description: A short description of the target documentation. CommonMark syntax MAY be used for rich text representation.
+        url: The URL for the target documentation. REQUIRED. Value MUST be in the format of a URL.
+        extensions: Specification extensions (x-* fields)
     """
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset({"description", "url"})
-
-    @property
-    def description(self) -> str | None:
-        """
-        A description of the target documentation.
+    root_node: yaml.Node
+    description: FieldSource[str] | None = fixed_field()
+    url: FieldSource[str] | None = fixed_field()
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
-        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
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> ExternalDocumentation | ValueSource[YAMLInvalidValue]:
+    """
+    Build an ExternalDocumentation object from a YAML node.
 
-    @property
-    def url(self) -> str | None:
-        """
-        The URL for the target documentation.
+    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.
 
-        REQUIRED field.
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
 
-        Returns:
-            URL or None if not present
-        """
-        return self.get("url")
+    Returns:
+        An ExternalDocumentation 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).
 
-    @url.setter
-    def url(self, value: str | None) -> None:
-        """Set the URL."""
-        if value is None:
-            self.pop("url", None)
-        else:
-            self["url"] = value
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("url: https://example.com\\ndescription: Find more info here")
+        external_docs = build(root)
+        assert external_docs.url.value == 'https://example.com'
+    """
+    return build_model(root, ExternalDocumentation, context=context)

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

@@ -1,140 +1,71 @@
-"""
-OpenAPI 3.0.4 OAuth Flow Object model.
+from dataclasses import dataclass, field
 
-Configuration details for a supported OAuth Flow as defined in RFC 6749.
-Different OAuth flows use different combinations of the fields.
-"""
+from ruamel import yaml
 
-from collections.abc import Mapping
+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.specification_object import SpecificationObject
 
+__all__ = ["OAuthFlow", "build"]
 
-__all__ = ["OAuthFlow"]
 
-
-class OAuthFlow(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class OAuthFlow:
     """
-    Represents an OAuth Flow Object from OpenAPI 3.0.4.
-
-    Configuration details for a supported OAuth Flow. Different flow types
-    (authorization code, implicit, password, client credentials) use different
-    combinations of these fields.
-
-    Supports specification extensions (x-* fields).
-
-    Example:
-        >>> # Authorization Code flow
-        >>> flow = OAuthFlow({
-        ...     "authorizationUrl": "https://example.com/oauth/authorize",
-        ...     "tokenUrl": "https://example.com/oauth/token",
-        ...     "scopes": {
-        ...         "read:pets": "Read access to pets",
-        ...         "write:pets": "Write access to pets"
-        ...     }
-        ... })
-        >>> flow.authorization_url
-        'https://example.com/oauth/authorize'
-        >>> flow.scopes
-        {'read:pets': 'Read access to pets', 'write:pets': 'Write access to pets'}
+    OAuth Flow Object representation for OpenAPI 3.0.
 
-        >>> # Implicit flow
-        >>> flow = OAuthFlow({
-        ...     "authorizationUrl": "https://example.com/oauth/authorize",
-        ...     "scopes": {"read": "Read access"}
-        ... })
-        >>> print(flow.token_url)
-        None
+    Configuration details for a supported OAuth Flow.
 
-        >>> # With extensions
-        >>> flow = OAuthFlow({
-        ...     "tokenUrl": "https://example.com/oauth/token",
-        ...     "scopes": {},
-        ...     "x-token-ttl": 3600
-        ... })
-        >>> flow.get_extensions()
-        {'x-token-ttl': 3600}
+    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)
     """
 
-    _supports_extensions: bool = True
-
-    @property
-    def authorization_url(self) -> str | None:
-        """
-        OAuth authorization endpoint URL.
-
-        REQUIRED for: authorizationCode, implicit flows.
-
-        Returns:
-            Authorization URL or None if not present
-        """
-        return self.get("authorizationUrl")
-
-    @authorization_url.setter
-    def authorization_url(self, value: str | None) -> None:
-        """Set the authorization URL."""
-        if value is None:
-            self.pop("authorizationUrl", None)
-        else:
-            self["authorizationUrl"] = value
+    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)
 
-    @property
-    def token_url(self) -> str | None:
-        """
-        OAuth token endpoint URL.
 
-        REQUIRED for: authorizationCode, password, clientCredentials flows.
-
-        Returns:
-            Token URL or None if not present
-        """
-        return self.get("tokenUrl")
-
-    @token_url.setter
-    def token_url(self, value: str | None) -> None:
-        """Set the token URL."""
-        if value is None:
-            self.pop("tokenUrl", None)
-        else:
-            self["tokenUrl"] = value
-
-    @property
-    def refresh_url(self) -> str | None:
-        """
-        OAuth refresh token endpoint URL (optional for all flows).
-
-        Returns:
-            Refresh URL or None if not present
-        """
-        return self.get("refreshUrl")
-
-    @refresh_url.setter
-    def refresh_url(self, value: str | None) -> None:
-        """Set the refresh URL."""
-        if value is None:
-            self.pop("refreshUrl", None)
-        else:
-            self["refreshUrl"] = value
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> OAuthFlow | ValueSource[YAMLInvalidValue]:
+    """
+    Build an OAuthFlow object from a YAML node.
 
-    @property
-    def scopes(self) -> dict[str, str]:
-        """
-        Available scopes for the 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.
 
-        Maps scope names to their descriptions. REQUIRED for all flows.
+    Args:
+        root: The YAML node to parse (should be a MappingNode)
+        context: Optional parsing context. If None, a default context will be created.
 
-        Returns:
-            Dictionary mapping scope names to descriptions (empty dict if not present)
-        """
-        scopes = self.get("scopes")
-        if scopes is None:
-            return {}
-        return dict(scopes) if isinstance(scopes, Mapping) else {}
+    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).
 
-    @scopes.setter
-    def scopes(self, value: dict[str, str] | Mapping[str, str] | None) -> None:
-        """Set the scopes mapping."""
-        if value is None:
-            self.pop("scopes", None)
-        else:
-            self["scopes"] = dict(value) if isinstance(value, Mapping) else value
+    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)

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

@@ -1,165 +1,116 @@
-"""
-OpenAPI 3.0.4 OAuth Flows Object model.
-
-Allows configuration of the supported OAuth Flows.
-"""
-
-from collections.abc import Mapping
+from dataclasses import dataclass, field
 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.specification_object import SpecificationObject
+from jentic.apitools.openapi.datamodels.low.v30.oauth_flow import build as build_oauth_flow
 
 
-__all__ = ["OAuthFlows"]
+__all__ = ["OAuthFlows", "build"]
 
 
-class OAuthFlows(SpecificationObject):
+@dataclass(frozen=True, slots=True)
+class OAuthFlows:
+    """
+    OAuth Flows Object representation for OpenAPI 3.0.
+
+    A container for the list of possible OAuth 2.0 authorization flows.
+    Used within Security Scheme Objects when type is set to "oauth2".
+
+    Attributes:
+        root_node: The top-level node representing the entire OAuth Flows object in the original source file
+        implicit: Configuration for the OAuth Implicit flow
+        password: Configuration for the OAuth Resource Owner Password flow
+        client_credentials: Configuration for the OAuth Client Credentials flow (application flow)
+        authorization_code: Configuration for the OAuth Authorization Code flow (three-legged OAuth)
+        extensions: Specification extensions (x-* fields)
     """
-    Represents an OAuth Flows Object from OpenAPI 3.0.4.
 
-    Allows configuration of the supported OAuth Flows. Each property corresponds
-    to a different OAuth 2.0 flow type as defined in RFC 6749.
+    root_node: yaml.Node
+    implicit: FieldSource[OAuthFlow] | None = fixed_field()
+    password: FieldSource[OAuthFlow] | None = fixed_field()
+    client_credentials: FieldSource[OAuthFlow] | None = fixed_field(
+        metadata={"yaml_name": "clientCredentials"}
+    )
+    authorization_code: FieldSource[OAuthFlow] | None = fixed_field(
+        metadata={"yaml_name": "authorizationCode"}
+    )
+    extensions: dict[KeySource[str], ValueSource[YAMLValue]] = field(default_factory=dict)
 
-    Supports specification extensions (x-* fields).
 
-    Example:
-        >>> # Multiple flows
-        >>> flows = OAuthFlows({
-        ...     "implicit": {
-        ...         "authorizationUrl": "https://example.com/oauth/authorize",
-        ...         "scopes": {"read": "Read access", "write": "Write access"}
-        ...     },
-        ...     "authorizationCode": {
-        ...         "authorizationUrl": "https://example.com/oauth/authorize",
-        ...         "tokenUrl": "https://example.com/oauth/token",
-        ...         "scopes": {"read": "Read access", "write": "Write access"}
-        ...     }
-        ... })
-        >>> flows.implicit.authorization_url
-        'https://example.com/oauth/authorize'
-        >>> flows.authorization_code.token_url
-        'https://example.com/oauth/token'
-
-        >>> # Single flow
-        >>> flows = OAuthFlows({
-        ...     "clientCredentials": {
-        ...         "tokenUrl": "https://example.com/oauth/token",
-        ...         "scopes": {"api": "API access"}
-        ...     }
-        ... })
-        >>> flows.client_credentials.scopes
-        {'api': 'API access'}
-        >>> print(flows.implicit)
-        None
-
-        >>> # With extensions
-        >>> flows = OAuthFlows({
-        ...     "password": {
-        ...         "tokenUrl": "https://example.com/oauth/token",
-        ...         "scopes": {}
-        ...     },
-        ...     "x-flow-timeout": 3600
-        ... })
-        >>> flows.get_extensions()
-        {'x-flow-timeout': 3600}
+def build(
+    root: yaml.Node, context: Context | None = None
+) -> OAuthFlows | ValueSource[YAMLInvalidValue]:
     """
+    Build an OAuthFlows object from a YAML node.
 
-    _supports_extensions: bool = True
-    _fixed_fields: frozenset[str] = frozenset(
-        {"implicit", "password", "clientCredentials", "authorizationCode"}
-    )
+    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 OAuthFlows 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).
 
-    def __init__(self, data: Mapping[str, Any] | None = None):
-        """
-        Initialize an OAuthFlows object.
-
-        Automatically marshals nested flow data (Mappings) into OAuthFlow instances.
-
-        Args:
-            data: Optional mapping to initialize the object with
-        """
-        super().__init__()
-        if data:
-            for key, value in data.items():
-                if (
-                    key in self._fixed_fields
-                    and isinstance(value, Mapping)
-                    and not isinstance(value, OAuthFlow)
-                ):
-                    self[key] = OAuthFlow(value)
-                else:
-                    # Store as-is (already OAuthFlow, extension, or other)
-                    self[key] = self._copy_value(value)
-
-    @property
-    def implicit(self) -> OAuthFlow | None:
-        """
-        Configuration for the OAuth Implicit flow.
-
-        Returns:
-            OAuthFlow instance or None if not configured
-        """
-        return self.get("implicit")
-
-    @implicit.setter
-    def implicit(self, value: OAuthFlow | None) -> None:
-        """Set the implicit flow configuration."""
-        if value is None:
-            self.pop("implicit", None)
-        else:
-            self["implicit"] = value
-
-    @property
-    def password(self) -> OAuthFlow | None:
-        """
-        Configuration for the OAuth Resource Owner Password flow.
-
-        Returns:
-            OAuthFlow instance or None if not configured
-        """
-        return self.get("password")
-
-    @password.setter
-    def password(self, value: OAuthFlow | None) -> None:
-        """Set the password flow configuration."""
-        if value is None:
-            self.pop("password", None)
-        else:
-            self["password"] = value
-
-    @property
-    def client_credentials(self) -> OAuthFlow | None:
-        """
-        Configuration for the OAuth Client Credentials flow.
-
-        Returns:
-            OAuthFlow instance or None if not configured
-        """
-        return self.get("clientCredentials")
-
-    @client_credentials.setter
-    def client_credentials(self, value: OAuthFlow | None) -> None:
-        """Set the client credentials flow configuration."""
-        if value is None:
-            self.pop("clientCredentials", None)
-        else:
-            self["clientCredentials"] = value
-
-    @property
-    def authorization_code(self) -> OAuthFlow | None:
-        """
-        Configuration for the OAuth Authorization Code flow.
-
-        Returns:
-            OAuthFlow instance or None if not configured
-        """
-        return self.get("authorizationCode")
-
-    @authorization_code.setter
-    def authorization_code(self, value: OAuthFlow | None) -> None:
-        """Set the authorization code flow configuration."""
-        if value is None:
-            self.pop("authorizationCode", None)
-        else:
-            self["authorizationCode"] = value
+    Example:
+        from ruamel.yaml import YAML
+        yaml = YAML()
+        root = yaml.compose("implicit:\\n  authorizationUrl: https://example.com/auth\\n  scopes: {}")
+        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()
+
+    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)
+
+    # Get fixed specification fields for this dataclass type
+    _fixed_fields = fixed_fields(OAuthFlows)
+
+    # Build YAML name to Python field name mapping
+    yaml_to_field = {
+        field.metadata.get("yaml_name", fname): fname for fname, field in _fixed_fields.items()
+    }
+
+    # Extract field values in a single pass
+    field_values: dict[str, Any] = {}
+    for key_node, value_node in root.value:
+        key = context.yaml_constructor.construct_yaml_str(key_node)
+
+        # Map YAML key to Python field name
+        field_name = yaml_to_field.get(key)
+        if field_name:
+            # Build OAuthFlow for this field - child builder handles invalid nodes
+            # FieldSource will auto-unwrap ValueSource if child returns it for invalid data
+            oauth_flow = build_oauth_flow(value_node, context=context)
+            field_values[field_name] = FieldSource(
+                value=oauth_flow, key_node=key_node, value_node=value_node
+            )
+
+    return OAuthFlows(
+        root_node=root,
+        implicit=field_values.get("implicit"),
+        password=field_values.get("password"),
+        client_credentials=field_values.get("client_credentials"),
+        authorization_code=field_values.get("authorization_code"),
+        extensions=extract_extension_fields(root, context),
+    )