django-cfg 1.4.10__py3-none-any.whl → 1.4.11__py3-none-any.whl

django_cfg/modules/django_client/core/parser/models/__init__.py

@@ -0,0 +1,74 @@
+"""
+OpenAPI Input Models - Pydantic 2 models for raw OpenAPI specs.
+
+These models represent the OpenAPI specification structure as it appears
+in JSON/YAML files, before normalization to IR.
+
+Supports both OpenAPI 3.0.3 and 3.1.0.
+
+Usage:
+    >>> from django_cfg.modules.django_client.core.parser.models import OpenAPISpec
+    >>> spec = OpenAPISpec.model_validate(openapi_dict)
+    >>> spec.openapi_version
+    '3.1.0'
+    >>> spec.all_schema_names
+    ['User', 'UserRequest', 'PatchedUser', ...]
+"""
+
+from .base import (
+    ContactObject,
+    ExampleObject,
+    ExternalDocumentationObject,
+    InfoObject,
+    LicenseObject,
+    LinkObject,
+    ReferenceObject,
+    ServerObject,
+    ServerVariableObject,
+    TagObject,
+)
+from .components import ComponentsObject, SecuritySchemeObject
+from .openapi import OpenAPISpec
+from .operation import (
+    CallbackObject,
+    EncodingObject,
+    MediaTypeObject,
+    OperationObject,
+    ParameterObject,
+    PathItemObject,
+    RequestBodyObject,
+    ResponseObject,
+)
+from .schema import Discriminator, SchemaObject, XMLObject
+
+__all__ = [
+    # Root
+    "OpenAPISpec",
+    # Base
+    "InfoObject",
+    "ContactObject",
+    "LicenseObject",
+    "ServerObject",
+    "ServerVariableObject",
+    "TagObject",
+    "ExternalDocumentationObject",
+    "ReferenceObject",
+    "ExampleObject",
+    "LinkObject",
+    # Schema
+    "SchemaObject",
+    "Discriminator",
+    "XMLObject",
+    # Operation
+    "ParameterObject",
+    "MediaTypeObject",
+    "EncodingObject",
+    "RequestBodyObject",
+    "ResponseObject",
+    "OperationObject",
+    "PathItemObject",
+    "CallbackObject",
+    # Components
+    "ComponentsObject",
+    "SecuritySchemeObject",
+]

django_cfg/modules/django_client/core/parser/models/base.py

@@ -0,0 +1,212 @@
+"""
+OpenAPI Input Models - Base types.
+
+These models represent the raw OpenAPI specification structure as it appears
+in the JSON/YAML file. They are version-agnostic where possible.
+
+Reference: https://spec.openapis.org/oas/v3.1.0
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ContactObject(BaseModel):
+    """
+    OpenAPI Contact Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#contact-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str | None = None
+    url: str | None = None
+    email: str | None = None
+
+
+class LicenseObject(BaseModel):
+    """
+    OpenAPI License Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#license-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(..., description="License name (e.g., 'MIT', 'Apache 2.0')")
+    identifier: str | None = Field(
+        None, description="SPDX license identifier (OAS 3.1.0)"
+    )
+    url: str | None = None
+
+
+class InfoObject(BaseModel):
+    """
+    OpenAPI Info Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#info-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    title: str = Field(..., description="API title")
+    version: str = Field(..., description="API version (e.g., '1.0.0')")
+    summary: str | None = Field(None, description="Short summary (OAS 3.1.0)")
+    description: str | None = None
+    termsOfService: str | None = None
+    contact: ContactObject | None = None
+    license: LicenseObject | None = None
+
+
+class ServerVariableObject(BaseModel):
+    """
+    OpenAPI Server Variable Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#server-variable-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    enum: list[str] | None = None
+    default: str = Field(..., description="Default value for substitution")
+    description: str | None = None
+
+
+class ServerObject(BaseModel):
+    """
+    OpenAPI Server Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#server-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    url: str = Field(..., description="Server URL (e.g., 'https://api.example.com')")
+    description: str | None = None
+    variables: dict[str, ServerVariableObject] | None = None
+
+
+class ExternalDocumentationObject(BaseModel):
+    """
+    OpenAPI External Documentation Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#external-documentation-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    url: str = Field(..., description="Documentation URL")
+    description: str | None = None
+
+
+class TagObject(BaseModel):
+    """
+    OpenAPI Tag Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#tag-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(..., description="Tag name")
+    description: str | None = None
+    externalDocs: ExternalDocumentationObject | None = None
+
+
+class ReferenceObject(BaseModel):
+    """
+    OpenAPI Reference Object ($ref).
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#reference-object
+
+    Examples:
+        >>> ref = ReferenceObject(ref="#/components/schemas/User")
+        >>> ref.ref
+        '#/components/schemas/User'
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    ref: str = Field(..., alias="$ref", description="Reference URI")
+    summary: str | None = Field(None, description="Summary (OAS 3.1.0)")
+    description: str | None = Field(None, description="Description (OAS 3.1.0)")
+
+    @property
+    def ref_name(self) -> str:
+        """
+        Extract referenced name from $ref.
+
+        Examples:
+            >>> ReferenceObject(ref="#/components/schemas/User").ref_name
+            'User'
+            >>> ReferenceObject(ref="#/components/responses/NotFound").ref_name
+            'NotFound'
+        """
+        return self.ref.split("/")[-1]
+
+    @property
+    def ref_type(self) -> str:
+        """
+        Extract reference type from $ref.
+
+        Examples:
+            >>> ReferenceObject(ref="#/components/schemas/User").ref_type
+            'schemas'
+            >>> ReferenceObject(ref="#/components/responses/NotFound").ref_type
+            'responses'
+        """
+        parts = self.ref.split("/")
+        if len(parts) >= 3 and parts[1] == "components":
+            return parts[2]
+        return "unknown"
+
+
+class ExampleObject(BaseModel):
+    """
+    OpenAPI Example Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#example-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    summary: str | None = None
+    description: str | None = None
+    value: Any | None = None
+    externalValue: str | None = None
+
+
+class HeaderObject(BaseModel):
+    """
+    OpenAPI Header Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#header-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    description: str | None = None
+    required: bool = False
+    deprecated: bool = False
+    # Schema will be added as SchemaObject | ReferenceObject in schema.py
+
+
+class LinkObject(BaseModel):
+    """
+    OpenAPI Link Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#link-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    operationRef: str | None = None
+    operationId: str | None = None
+    parameters: dict[str, Any] | None = None
+    requestBody: Any | None = None
+    description: str | None = None
+    server: ServerObject | None = None

django_cfg/modules/django_client/core/parser/models/components.py

@@ -0,0 +1,160 @@
+"""
+OpenAPI Input Models - Components Object.
+
+ComponentsObject holds reusable schemas, responses, parameters, etc.
+
+Reference: https://spec.openapis.org/oas/v3.1.0#components-object
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .base import ExampleObject, LinkObject, ReferenceObject
+from .operation import (
+    CallbackObject,
+    ParameterObject,
+    RequestBodyObject,
+    ResponseObject,
+)
+from .schema import SchemaObject
+
+
+class SecuritySchemeObject(BaseModel):
+    """
+    OpenAPI Security Scheme Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = Field(
+        ...,
+        description="Security type: apiKey, http, oauth2, openIdConnect",
+    )
+    description: str | None = None
+
+    # apiKey
+    name: str | None = Field(None, description="Header/query/cookie name (for apiKey)")
+    in_: str | None = Field(None, alias="in", description="Location: query, header, cookie")
+
+    # http
+    scheme: str | None = Field(None, description="HTTP scheme: basic, bearer, etc.")
+    bearerFormat: str | None = None
+
+    # oauth2
+    flows: dict[str, Any] | None = None  # OAuthFlowsObject
+
+    # openIdConnect
+    openIdConnectUrl: str | None = None
+
+
+class ComponentsObject(BaseModel):
+    """
+    OpenAPI Components Object.
+
+    Contains reusable schemas, responses, parameters, etc.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#components-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    # ===== Schemas (most important for us) =====
+    schemas: dict[str, SchemaObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable schemas (User, UserRequest, PatchedUser, etc.)",
+    )
+
+    # ===== Responses =====
+    responses: dict[str, ResponseObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable responses (NotFound, ValidationError, etc.)",
+    )
+
+    # ===== Parameters =====
+    parameters: dict[str, ParameterObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable parameters",
+    )
+
+    # ===== Examples =====
+    examples: dict[str, ExampleObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable examples",
+    )
+
+    # ===== Request Bodies =====
+    requestBodies: dict[str, RequestBodyObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable request bodies",
+    )
+
+    # ===== Headers =====
+    headers: dict[str, Any] | None = Field(
+        None,
+        description="Reusable headers (HeaderObject | ReferenceObject)",
+    )
+
+    # ===== Security Schemes =====
+    securitySchemes: dict[str, SecuritySchemeObject | ReferenceObject] | None = Field(
+        None,
+        description="Security schemes (basicAuth, bearerAuth, etc.)",
+    )
+
+    # ===== Links =====
+    links: dict[str, LinkObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable links",
+    )
+
+    # ===== Callbacks =====
+    callbacks: dict[str, CallbackObject | ReferenceObject] | None = Field(
+        None,
+        description="Reusable callbacks",
+    )
+
+    # ===== Path Items (OAS 3.1.0) =====
+    pathItems: dict[str, Any] | None = Field(
+        None,
+        description="Reusable path items (OAS 3.1.0)",
+    )
+
+    @property
+    def has_schemas(self) -> bool:
+        """Check if components contain schemas."""
+        return self.schemas is not None and len(self.schemas) > 0
+
+    @property
+    def schema_names(self) -> list[str]:
+        """Get all schema names."""
+        if not self.schemas:
+            return []
+        return list(self.schemas.keys())
+
+    def get_schema(self, name: str) -> SchemaObject | ReferenceObject | None:
+        """Get schema by name."""
+        if not self.schemas:
+            return None
+        return self.schemas.get(name)
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = ["ComponentsObject("]
+
+        if self.schemas:
+            parts.append(f"schemas={len(self.schemas)}")
+
+        if self.responses:
+            parts.append(f"responses={len(self.responses)}")
+
+        if self.parameters:
+            parts.append(f"parameters={len(self.parameters)}")
+
+        if self.securitySchemes:
+            parts.append(f"securitySchemes={len(self.securitySchemes)}")
+
+        return ", ".join(parts) + ")"

django_cfg/modules/django_client/core/parser/models/openapi.py

@@ -0,0 +1,203 @@
+"""
+OpenAPI Input Models - Root OpenAPI Spec.
+
+This module defines the root OpenAPISpec model that represents a complete
+OpenAPI specification (version 3.0.3 or 3.1.0).
+
+Reference: https://spec.openapis.org/oas/v3.1.0
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .base import ExternalDocumentationObject, InfoObject, ServerObject, TagObject
+from .components import ComponentsObject
+from .operation import PathItemObject
+
+
+class OpenAPISpec(BaseModel):
+    """
+    OpenAPI Specification root object.
+
+    This is the top-level object representing a complete OpenAPI specification.
+    Supports both OpenAPI 3.0.3 and 3.1.0.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0
+
+    Examples:
+        >>> spec = OpenAPISpec(
+        ...     openapi="3.1.0",
+        ...     info=InfoObject(title="My API", version="1.0.0"),
+        ...     paths={"/users/": PathItemObject(...)},
+        ... )
+        >>> spec.openapi_version
+        '3.1.0'
+        >>> spec.is_openapi_31
+        True
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Allow x-* extensions
+        validate_assignment=True,
+    )
+
+    # ===== Required Fields =====
+    openapi: str = Field(
+        ...,
+        description="OpenAPI version (3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0)",
+    )
+    info: InfoObject = Field(..., description="API metadata")
+    paths: dict[str, PathItemObject] | None = Field(
+        None,
+        description="API paths (/users/, /tasks/{id}/, etc.)",
+    )
+
+    # ===== Optional Fields =====
+    jsonSchemaDialect: str | None = Field(
+        None,
+        description="JSON Schema dialect (OAS 3.1.0 only)",
+    )
+    servers: list[ServerObject] | None = Field(
+        None,
+        description="Server URLs",
+    )
+    components: ComponentsObject | None = Field(
+        None,
+        description="Reusable components (schemas, responses, etc.)",
+    )
+    security: list[dict[str, list[str]]] | None = Field(
+        None,
+        description="Global security requirements",
+    )
+    tags: list[TagObject] | None = Field(
+        None,
+        description="API tags for grouping operations",
+    )
+    externalDocs: ExternalDocumentationObject | None = None
+
+    # ===== drf-spectacular Extensions =====
+    x_tagGroups: list[dict[str, Any]] | None = Field(
+        None,
+        alias="x-tagGroups",
+        description="Tag groups from drf-spectacular",
+    )
+
+    # ===== Validation =====
+
+    @field_validator("openapi")
+    @classmethod
+    def validate_openapi_version(cls, v: str) -> str:
+        """Validate OpenAPI version is 3.0.x or 3.1.0."""
+        valid_versions = ["3.0.0", "3.0.1", "3.0.2", "3.0.3", "3.1.0"]
+        if v not in valid_versions:
+            raise ValueError(
+                f"Unsupported OpenAPI version: {v}. "
+                f"Supported versions: {', '.join(valid_versions)}"
+            )
+        return v
+
+    # ===== Computed Properties =====
+
+    @property
+    def openapi_version(self) -> str:
+        """Get OpenAPI version string."""
+        return self.openapi
+
+    @property
+    def is_openapi_30(self) -> bool:
+        """Check if OpenAPI 3.0.x."""
+        return self.openapi.startswith("3.0.")
+
+    @property
+    def is_openapi_31(self) -> bool:
+        """Check if OpenAPI 3.1.0."""
+        return self.openapi == "3.1.0"
+
+    @property
+    def normalized_version(self) -> Literal["3.0.3", "3.1.0"]:
+        """
+        Get normalized OpenAPI version (3.0.3 or 3.1.0).
+
+        All 3.0.x versions are normalized to 3.0.3.
+        """
+        if self.is_openapi_30:
+            return "3.0.3"
+        return "3.1.0"
+
+    @property
+    def has_components(self) -> bool:
+        """Check if spec has components."""
+        return self.components is not None and self.components.has_schemas
+
+    @property
+    def has_paths(self) -> bool:
+        """Check if spec has paths."""
+        return self.paths is not None and len(self.paths) > 0
+
+    @property
+    def all_paths(self) -> dict[str, PathItemObject]:
+        """Get all paths (empty dict if none)."""
+        return self.paths or {}
+
+    @property
+    def all_operations(self) -> dict[str, tuple[str, str, Any]]:
+        """
+        Get all operations from all paths.
+
+        Returns:
+            Dict of {operation_id: (http_method, path, OperationObject)}
+
+        Examples:
+            >>> spec = OpenAPISpec(...)
+            >>> ops = spec.all_operations
+            >>> ops['users_list']
+            ('GET', '/api/users/', OperationObject(...))
+        """
+        result = {}
+        if not self.paths:
+            return result
+
+        for path, path_item in self.paths.items():
+            for method, operation in path_item.operations.items():
+                if operation.operationId:
+                    result[operation.operationId] = (method, path, operation)
+
+        return result
+
+    @property
+    def all_schema_names(self) -> list[str]:
+        """Get all schema names from components."""
+        if not self.components or not self.components.schemas:
+            return []
+        return list(self.components.schemas.keys())
+
+    @property
+    def server_urls(self) -> list[str]:
+        """Get all server URLs."""
+        if not self.servers:
+            return []
+        return [server.url for server in self.servers]
+
+    def get_schema(self, name: str) -> Any:
+        """Get schema from components by name."""
+        if not self.components:
+            return None
+        return self.components.get_schema(name)
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = [
+            f"OpenAPISpec(openapi={self.openapi!r}",
+            f"title={self.info.title!r}",
+        ]
+
+        if self.paths:
+            parts.append(f"paths={len(self.paths)}")
+
+        if self.components and self.components.schemas:
+            parts.append(f"schemas={len(self.components.schemas)}")
+
+        return ", ".join(parts) + ")"