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

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

@@ -0,0 +1,91 @@
+"""
+OpenAPI 3.0.4 Security Requirement Object model.
+
+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 jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["SecurityRequirement"]
+
+
+class SecurityRequirement(SpecificationObject):
+    """
+    Represents a Security Requirement Object from OpenAPI 3.0.4.
+
+    This IS a mapping. Keys are security scheme names, values are lists of scope strings.
+
+    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.
+
+    IMPORTANT: Security Requirement Objects do NOT support specification extensions.
+    Any key starting with "x-" is treated as a security scheme name, not an extension.
+
+    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
+    """
+
+    _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())
+
+    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)
+
+        Raises:
+            KeyError: If scheme_name is not in this requirement
+        """
+        return self[scheme_name]
+
+    def is_empty(self) -> bool:
+        """
+        Check if this is an empty security requirement.
+
+        Empty requirements ({}) make security optional for an operation.
+
+        Returns:
+            True if requirements mapping is empty
+        """
+        return len(self) == 0

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

@@ -0,0 +1,301 @@
+"""
+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 jentic.apitools.openapi.datamodels.low.v30.oauth_flows import OAuthFlows
+from jentic.apitools.openapi.datamodels.low.v30.specification_object import SpecificationObject
+
+
+__all__ = ["SecurityScheme"]
+
+
+class SecurityScheme(SpecificationObject):
+    """
+    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
+    """
+
+    _supports_extensions: bool = True
+    _fixed_fields: frozenset[str] = frozenset(
+        {"type", "description", "name", "in", "scheme", "bearerFormat", "flows", "openIdConnectUrl"}
+    )
+
+    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 is_oauth2(self) -> bool:
+        """
+        Check if this is an OAuth2 security scheme.
+
+        Returns:
+            True if type is "oauth2"
+        """
+        return self.type == "oauth2"
+
+    def is_openid_connect(self) -> bool:
+        """
+        Check if this is an OpenID Connect security scheme.
+
+        Returns:
+            True if type is "openIdConnect"
+        """
+        return self.type == "openIdConnect"

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

@@ -0,0 +1,217 @@
+"""Base class for OpenAPI specification objects."""
+
+from abc import ABC
+from collections.abc import Mapping, MutableMapping, Sequence
+from copy import copy
+from typing import Any, Iterator, TypeVar
+
+
+__all__ = ["SpecificationObject"]
+
+
+T = TypeVar("T", bound="SpecificationObject")
+
+
+class SpecificationObject(ABC, MutableMapping[str, Any]):
+    """
+    Base class for OpenAPI specification objects.
+
+    Implements a MutableMapping interface with data stored in __dict__.
+    Subclasses become dict-like objects where all attributes are accessible
+    via both attribute access (obj.foo) and item access (obj["foo"]).
+
+    Class Attributes:
+        _supports_extensions: Whether this object type supports x-* specification extensions.
+                             Default is True. Set to False for objects like Security Requirement
+                             that are pure maps where x-* are regular keys.
+    """
+
+    _supports_extensions: bool = False
+
+    def __init__(self, data: Mapping[str, Any] | None = None):
+        """
+        Initialize a SpecificationObject.
+
+        Args:
+            data: Optional mapping to initialize the object with
+        """
+        if data:
+            for key, value in data.items():
+                self[key] = self._copy_value(value)
+
+    # MutableMapping abstract methods
+    def __getitem__(self, key: str) -> Any:
+        """Get an item."""
+        return self.__dict__[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set an item."""
+        self.__dict__[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        """Delete an item."""
+        del self.__dict__[key]
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over keys."""
+        return iter(self.__dict__)
+
+    def __len__(self) -> int:
+        """Return the number of items."""
+        return len(self.__dict__)
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Get an attribute via attribute access.
+
+        This allows both dict-style (obj["key"]) and attribute-style (obj.key) access.
+        Called only when the attribute is not found through normal lookup.
+        """
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """
+        Set an attribute via attribute access.
+
+        This allows both dict-style (obj["key"] = val) and attribute-style (obj.key = val).
+        For properties and other descriptors, delegates to the descriptor.
+        """
+        # Check if this is a data descriptor (property, etc.) on the class
+        cls = type(self)
+        if hasattr(cls, name):
+            attr = getattr(cls, name)
+            # If it's a data descriptor (has __set__), use normal attribute setting
+            if hasattr(attr, "__set__"):
+                object.__setattr__(self, name, value)
+                return
+        # Otherwise, store in the dict
+        self[name] = value
+
+    def get_extensions(self) -> Mapping[str, Any]:
+        """
+        Get specification extensions (x-* fields).
+
+        Returns a filtered view of fields starting with 'x-'.
+        If this object type doesn't support extensions (_supports_extensions=False),
+        returns an empty mapping.
+
+        Returns:
+            Mapping of extension fields (keys starting with 'x-')
+        """
+        if not type(self)._supports_extensions:
+            return {}
+        return {k: v for k, v in self.items() if isinstance(k, str) and k.startswith("x-")}
+
+    def get_fields(self) -> Mapping[str, Any]:
+        """
+        Get regular fields (non-extension fields).
+
+        Returns a filtered view excluding fields starting with 'x-'.
+        If this object type doesn't support extensions (_supports_extensions=False),
+        returns all fields (x-* are treated as regular fields).
+
+        Returns:
+            Mapping of regular fields (excluding x-* if extensions are supported)
+        """
+        if not type(self)._supports_extensions:
+            return dict(self)
+        return {k: v for k, v in self.items() if isinstance(k, str) and not k.startswith("x-")}
+
+    @classmethod
+    def from_mapping(cls: type[T], data: Mapping[str, Any]) -> T:
+        """
+        Create an instance from a mapping.
+
+        This method does not validate the structure. Use a separate
+        validator to ensure the data conforms to the OpenAPI specification.
+
+        Args:
+            data: Mapping to create the object from
+
+        Returns:
+            Instance of the class
+
+        Raises:
+            TypeError: If data is not a Mapping
+        """
+        if not isinstance(data, Mapping):
+            raise TypeError(f"Expected Mapping, got {type(data).__name__}")
+        return cls(data=data)
+
+    def to_mapping(self) -> dict[str, Any]:
+        """
+        Convert to a plain dictionary representation.
+
+        Recursively converts nested SpecificationObject instances to plain dicts.
+        Useful for serialization to JSON/YAML.
+
+        Returns:
+            Plain dictionary with all nested objects converted
+        """
+        return {key: self._marshal_value(value) for key, value in MutableMapping.items(self)}
+
+    @classmethod
+    def _marshal_value(cls, value: Any) -> Any:
+        """
+        Helper to recursively marshal values to plain types.
+
+        Uses the actual class (or subclass) to support custom marshaling behavior.
+        """
+        if isinstance(value, SpecificationObject):
+            return value.to_mapping()
+        elif isinstance(value, (list, tuple)):
+            return type(value)(cls._marshal_value(item) for item in value)
+        elif isinstance(value, dict):
+            return {k: cls._marshal_value(v) for k, v in value.items()}
+        else:
+            return value
+
+    @staticmethod
+    def _copy_value(value: Any) -> Any:
+        """
+        Defensive shallow copy for mutable collections.
+
+        Copies mutable types (list, dict, etc.) to prevent unintended mutation
+        of input data. Does not copy SpecificationObjects (already defensive).
+
+        Args:
+            value: Value to potentially copy
+
+        Returns:
+            Copy of value if mutable collection, otherwise value itself
+        """
+
+        # Don't copy SpecificationObjects (already create new instances)
+        if isinstance(value, SpecificationObject):
+            return value
+
+        # Copy mutable collections (dict, list, etc.)
+        # Exclude strings (they're Sequence but immutable)
+        if isinstance(value, (Mapping, Sequence)) and not isinstance(value, str):
+            return copy(value)
+
+        # Primitives and immutables - no copy needed
+        return value
+
+    def __repr__(self) -> str:
+        """Return a developer-friendly string representation."""
+        class_name = self.__class__.__name__
+
+        # Count regular fields and extensions separately
+        extensions = self.get_extensions()
+        ext_count = len(extensions)
+        field_count = len(self) - ext_count
+
+        # Build field part
+        field_word = "field" if field_count == 1 else "fields"
+        parts = [f"{field_count} {field_word}"]
+
+        # Add extensions part if any
+        if ext_count > 0:
+            ext_word = "specification extension" if ext_count == 1 else "specification extensions"
+            parts.append(f"{ext_count} {ext_word}")
+
+        return f"<{class_name} {', '.join(parts)}>"