jentic-openapi-datamodels 1.0.0a2__py3-none-any.whl

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

@@ -0,0 +1,28 @@
+"""OpenAPI 3.0.x low-level models."""
+
+from .discriminator import Discriminator
+from .external_documentation import ExternalDocumentation
+from .oauth_flow import OAuthFlow
+from .oauth_flows import OAuthFlows
+from .reference import Reference
+from .schema import Schema
+from .security_requirement import SecurityRequirement
+from .security_scheme import SecurityScheme
+from .specification_object import SpecificationObject
+from .tag import Tag
+from .xml import XML
+
+
+__all__ = [
+    "Discriminator",
+    "ExternalDocumentation",
+    "OAuthFlow",
+    "OAuthFlows",
+    "Reference",
+    "Schema",
+    "SecurityRequirement",
+    "SecurityScheme",
+    "SpecificationObject",
+    "Tag",
+    "XML",
+]

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

@@ -0,0 +1,91 @@
+"""
+OpenAPI 3.0.4 Discriminator Object model.
+
+When request bodies or response payloads may be one of a number of different schemas,
+a discriminator object gives a hint about the expected schema.
+"""
+
+from collections.abc import Mapping
+
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["Discriminator"]
+
+
+class Discriminator(SpecificationObject):
+    """
+    Represents a Discriminator Object from OpenAPI 3.0.4.
+
+    Used to support polymorphism by indicating which property in a payload
+    is used to differentiate between schemas.
+
+    Supports specification extensions (x-* fields).
+
+    Example:
+        >>> # Basic discriminator
+        >>> disc = Discriminator({
+        ...     "propertyName": "petType"
+        ... })
+        >>> disc.property_name
+        'petType'
+
+        >>> # With mapping
+        >>> disc = Discriminator({
+        ...     "propertyName": "petType",
+        ...     "mapping": {
+        ...         "dog": "#/components/schemas/Dog",
+        ...         "cat": "#/components/schemas/Cat",
+        ...         "lizard": "https://example.com/schemas/Lizard.json"
+        ...     }
+        ... })
+        >>> disc.property_name
+        'petType'
+        >>> disc.mapping["dog"]
+        '#/components/schemas/Dog'
+    """
+
+    _supports_extensions: bool = True
+    _fixed_fields: frozenset[str] = frozenset({"propertyName", "mapping"})
+
+    @property
+    def property_name(self) -> str | None:
+        """
+        The name of the property in the payload to discriminate schemas.
+
+        REQUIRED field.
+
+        Returns:
+            Property name or None if not present
+        """
+        return self.get("propertyName")
+
+    @property_name.setter
+    def property_name(self, value: str | None) -> None:
+        """Set the property name."""
+        if value is None:
+            self.pop("propertyName", None)
+        else:
+            self["propertyName"] = value
+
+    @property
+    def mapping(self) -> dict[str, str]:
+        """
+        Mapping between payload values and schema names/references.
+
+        Maps discriminator property values to schema names or references.
+        When absent, the value is expected to match a schema name.
+
+        Returns:
+            Dictionary mapping values to schema references (empty dict if not present)
+        """
+        return self.get("mapping", {})
+
+    @mapping.setter
+    def mapping(self, value: Mapping[str, str] | None) -> None:
+        """Set the mapping."""
+        if value is None:
+            self.pop("mapping", None)
+        else:
+            # Convert to plain dict once at storage time
+            self["mapping"] = dict(value) if isinstance(value, Mapping) else value

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

@@ -0,0 +1,79 @@
+"""
+OpenAPI 3.0.4 External Documentation Object model.
+
+Allows referencing an external resource for extended documentation.
+"""
+
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["ExternalDocumentation"]
+
+
+class ExternalDocumentation(SpecificationObject):
+    """
+    Represents an External Documentation Object from OpenAPI 3.0.4.
+
+    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'
+    """
+
+    _supports_extensions: bool = True
+    _fixed_fields: frozenset[str] = frozenset({"description", "url"})
+
+    @property
+    def description(self) -> str | None:
+        """
+        A description of the target documentation.
+
+        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 url(self) -> str | None:
+        """
+        The URL for the target documentation.
+
+        REQUIRED field.
+
+        Returns:
+            URL or None if not present
+        """
+        return self.get("url")
+
+    @url.setter
+    def url(self, value: str | None) -> None:
+        """Set the URL."""
+        if value is None:
+            self.pop("url", None)
+        else:
+            self["url"] = value

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

@@ -0,0 +1,140 @@
+"""
+OpenAPI 3.0.4 OAuth Flow Object model.
+
+Configuration details for a supported OAuth Flow as defined in RFC 6749.
+Different OAuth flows use different combinations of the fields.
+"""
+
+from collections.abc import Mapping
+
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["OAuthFlow"]
+
+
+class OAuthFlow(SpecificationObject):
+    """
+    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'}
+
+        >>> # Implicit flow
+        >>> flow = OAuthFlow({
+        ...     "authorizationUrl": "https://example.com/oauth/authorize",
+        ...     "scopes": {"read": "Read access"}
+        ... })
+        >>> print(flow.token_url)
+        None
+
+        >>> # With extensions
+        >>> flow = OAuthFlow({
+        ...     "tokenUrl": "https://example.com/oauth/token",
+        ...     "scopes": {},
+        ...     "x-token-ttl": 3600
+        ... })
+        >>> flow.get_extensions()
+        {'x-token-ttl': 3600}
+    """
+
+    _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
+
+    @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
+
+    @property
+    def scopes(self) -> dict[str, str]:
+        """
+        Available scopes for the OAuth2 security scheme.
+
+        Maps scope names to their descriptions. REQUIRED for all flows.
+
+        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 {}
+
+    @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

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

@@ -0,0 +1,165 @@
+"""
+OpenAPI 3.0.4 OAuth Flows Object model.
+
+Allows configuration of the supported OAuth Flows.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from jentic.apitools.openapi.datamodels.low.v30.oauth_flow import OAuthFlow
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["OAuthFlows"]
+
+
+class OAuthFlows(SpecificationObject):
+    """
+    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.
+
+    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}
+    """
+
+    _supports_extensions: bool = True
+    _fixed_fields: frozenset[str] = frozenset(
+        {"implicit", "password", "clientCredentials", "authorizationCode"}
+    )
+
+    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

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

@@ -0,0 +1,64 @@
+"""
+OpenAPI 3.0.4 Reference Object model.
+
+A simple object to allow referencing other components in the OpenAPI document.
+"""
+
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["Reference"]
+
+
+class Reference(SpecificationObject):
+    """
+    Represents a Reference Object from OpenAPI 3.0.4.
+
+    A simple object to allow referencing other components in the OpenAPI document,
+    internally and externally.
+
+    IMPORTANT: Reference Objects in OpenAPI 3.0.x do NOT support specification extensions.
+
+    Example:
+        >>> # Internal reference
+        >>> ref = Reference({"$ref": "#/components/schemas/Pet"})
+        >>> ref.ref
+        '#/components/schemas/Pet'
+        >>> ref["$ref"]
+        '#/components/schemas/Pet'
+
+        >>> # External reference
+        >>> ref = Reference({"$ref": "https://example.com/schemas/Pet.json"})
+        >>> ref.ref
+        'https://example.com/schemas/Pet.json'
+    """
+
+    _supports_extensions: bool = False
+    _fixed_fields: frozenset[str] = frozenset({"$ref"})
+
+    @property
+    def ref(self) -> str | None:
+        """
+        The reference string identifying the location of the referenced object.
+
+        Maps to the "$ref" field in OpenAPI.
+
+        Can be:
+        - Internal: "#/components/schemas/Pet"
+        - External URL: "https://example.com/schemas/Pet.json"
+        - Relative file: "./schemas/Pet.yaml#/Pet"
+
+        REQUIRED field.
+
+        Returns:
+            Reference string or None if not present
+        """
+        return self.get("$ref")
+
+    @ref.setter
+    def ref(self, value: str | None) -> None:
+        """Set the reference string."""
+        if value is None:
+            self.pop("$ref", None)
+        else:
+            self["$ref"] = value