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

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

@@ -0,0 +1,207 @@
+"""
+OpenAPI Input Models - Operation types.
+
+These models represent OpenAPI operations (endpoints) as they appear in the spec.
+
+Reference: https://spec.openapis.org/oas/v3.1.0
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .base import ExampleObject, ExternalDocumentationObject, ReferenceObject, ServerObject
+from .schema import SchemaObject
+
+
+class ParameterObject(BaseModel):
+    """
+    OpenAPI Parameter Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#parameter-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(..., description="Parameter name")
+    in_: Literal["query", "header", "path", "cookie"] = Field(
+        ..., alias="in", description="Parameter location"
+    )
+    description: str | None = None
+    required: bool = False
+    deprecated: bool = False
+    allowEmptyValue: bool = False
+
+    # Schema (simplified - can also use content for complex types)
+    schema_: SchemaObject | ReferenceObject | None = Field(None, alias="schema")
+
+    # Style and explode (for serialization)
+    style: str | None = None
+    explode: bool | None = None
+    allowReserved: bool = False
+
+    # Example
+    example: Any | None = None
+    examples: dict[str, ExampleObject | ReferenceObject] | None = None
+
+
+class EncodingObject(BaseModel):
+    """
+    OpenAPI Encoding Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#encoding-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    contentType: str | None = None
+    headers: dict[str, Any] | None = None  # HeaderObject | ReferenceObject
+    style: str | None = None
+    explode: bool | None = None
+    allowReserved: bool = False
+
+
+class MediaTypeObject(BaseModel):
+    """
+    OpenAPI Media Type Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#media-type-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_: SchemaObject | ReferenceObject | None = Field(None, alias="schema")
+    example: Any | None = None
+    examples: dict[str, ExampleObject | ReferenceObject] | None = None
+    encoding: dict[str, EncodingObject] | None = None
+
+
+class RequestBodyObject(BaseModel):
+    """
+    OpenAPI Request Body Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#request-body-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    description: str | None = None
+    content: dict[str, MediaTypeObject] = Field(
+        ..., description="Content by media type (application/json, etc.)"
+    )
+    required: bool = False
+
+
+class ResponseObject(BaseModel):
+    """
+    OpenAPI Response Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#response-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    description: str = Field(..., description="Response description")
+    headers: dict[str, Any] | None = None  # HeaderObject | ReferenceObject
+    content: dict[str, MediaTypeObject] | None = None
+    links: dict[str, Any] | None = None  # LinkObject | ReferenceObject
+
+
+class CallbackObject(BaseModel):
+    """
+    OpenAPI Callback Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#callback-object
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    # Callbacks are PathItemObjects keyed by expression
+    # We'll keep it simple as dict for now
+
+
+class OperationObject(BaseModel):
+    """
+    OpenAPI Operation Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#operation-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    # Identification
+    operationId: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] | None = None
+
+    # External docs
+    externalDocs: ExternalDocumentationObject | None = None
+
+    # Parameters
+    parameters: list[ParameterObject | ReferenceObject] | None = None
+
+    # Request body
+    requestBody: RequestBodyObject | ReferenceObject | None = None
+
+    # Responses
+    responses: dict[str, ResponseObject | ReferenceObject] = Field(
+        ..., description="Responses by status code ('200', '404', 'default', etc.)"
+    )
+
+    # Callbacks
+    callbacks: dict[str, CallbackObject | ReferenceObject] | None = None
+
+    # Security
+    security: list[dict[str, list[str]]] | None = None
+
+    # Servers
+    servers: list[ServerObject] | None = None
+
+    # Deprecation
+    deprecated: bool = False
+
+
+class PathItemObject(BaseModel):
+    """
+    OpenAPI Path Item Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#path-item-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    # Reference (allows $ref at path level)
+    ref: str | None = Field(None, alias="$ref")
+
+    # Summary and description
+    summary: str | None = None
+    description: str | None = None
+
+    # Operations
+    get: OperationObject | None = None
+    put: OperationObject | None = None
+    post: OperationObject | None = None
+    delete: OperationObject | None = None
+    options: OperationObject | None = None
+    head: OperationObject | None = None
+    patch: OperationObject | None = None
+    trace: OperationObject | None = None
+
+    # Servers
+    servers: list[ServerObject] | None = None
+
+    # Parameters (apply to all operations)
+    parameters: list[ParameterObject | ReferenceObject] | None = None
+
+    @property
+    def operations(self) -> dict[str, OperationObject]:
+        """Get all operations in this path."""
+        result = {}
+        for method in ("get", "post", "put", "patch", "delete", "head", "options", "trace"):
+            operation = getattr(self, method, None)
+            if operation:
+                result[method.upper()] = operation
+        return result

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

@@ -0,0 +1,266 @@
+"""
+OpenAPI Input Models - Schema types.
+
+These models represent OpenAPI Schema Objects as they appear in the spec.
+Supports both OpenAPI 3.0.3 and 3.1.0 (with JSON Schema extensions).
+
+Reference: https://spec.openapis.org/oas/v3.1.0#schema-object
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .base import ExternalDocumentationObject, ReferenceObject
+
+
+class Discriminator(BaseModel):
+    """
+    OpenAPI Discriminator Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#discriminator-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    propertyName: str = Field(..., description="Property name for discrimination")
+    mapping: dict[str, str] | None = None
+
+
+class XMLObject(BaseModel):
+    """
+    OpenAPI XML Object.
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#xml-object
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str | None = None
+    namespace: str | None = None
+    prefix: str | None = None
+    attribute: bool = False
+    wrapped: bool = False
+
+
+class SchemaObject(BaseModel):
+    """
+    OpenAPI Schema Object (raw from spec).
+
+    This represents a schema as it appears in the OpenAPI spec, before
+    normalization to IR. Supports both OAS 3.0.3 and 3.1.0.
+
+    Key Differences:
+    - OAS 3.0.3: Uses nullable: true (proprietary extension)
+    - OAS 3.1.0: Uses type: ['string', 'null'] (JSON Schema standard)
+
+    Extensions:
+    - x-enum-varnames: drf-spectacular enum variable names
+    - x-choices: Django choices metadata
+
+    Reference: https://spec.openapis.org/oas/v3.1.0#schema-object
+    """
+
+    model_config = ConfigDict(extra="allow")  # Allow x-* extensions
+
+    # ===== Core JSON Schema Keywords =====
+    type: str | list[str] | None = Field(
+        None,
+        description="JSON Schema type (string, integer, object, array, etc.)",
+    )
+    format: str | None = Field(
+        None,
+        description="Format hint (date-time, email, uuid, binary, etc.)",
+    )
+    title: str | None = None
+    description: str | None = None
+    default: Any | None = None
+    example: Any | None = Field(
+        None, description="Example value (deprecated in OAS 3.1.0, use examples)"
+    )
+    examples: list[Any] | None = Field(
+        None, description="Example values (OAS 3.1.0)"
+    )
+
+    # ===== Nullable (OAS 3.0.3 only) =====
+    nullable: bool | None = Field(
+        None,
+        description="Can be null (OAS 3.0.3 only, use type: ['x', 'null'] in 3.1.0)",
+    )
+
+    # ===== Enum and Const =====
+    enum: list[Any] | None = None
+    const: Any | None = Field(None, description="Constant value (OAS 3.1.0)")
+
+    # ===== Object Properties =====
+    properties: dict[str, SchemaObject | ReferenceObject] | None = None
+    required: list[str] | None = None
+    additionalProperties: bool | SchemaObject | ReferenceObject | None = None
+    maxProperties: int | None = None
+    minProperties: int | None = None
+
+    # ===== Array Items =====
+    items: SchemaObject | ReferenceObject | None = Field(
+        None, description="Array item schema"
+    )
+    prefixItems: list[SchemaObject | ReferenceObject] | None = Field(
+        None, description="Tuple validation (OAS 3.1.0)"
+    )
+    contains: SchemaObject | ReferenceObject | None = Field(
+        None, description="At least one item matches (OAS 3.1.0)"
+    )
+    maxItems: int | None = None
+    minItems: int | None = None
+    uniqueItems: bool | None = None
+
+    # ===== String Validation =====
+    maxLength: int | None = None
+    minLength: int | None = None
+    pattern: str | None = None
+
+    # ===== Numeric Validation =====
+    maximum: float | None = None
+    minimum: float | None = None
+    exclusiveMaximum: float | bool | None = Field(
+        None, description="Exclusive maximum (number in 3.1.0, boolean in 3.0.3)"
+    )
+    exclusiveMinimum: float | bool | None = Field(
+        None, description="Exclusive minimum (number in 3.1.0, boolean in 3.0.3)"
+    )
+    multipleOf: float | None = None
+
+    # ===== Composition =====
+    allOf: list[SchemaObject | ReferenceObject] | None = None
+    oneOf: list[SchemaObject | ReferenceObject] | None = None
+    anyOf: list[SchemaObject | ReferenceObject] | None = None
+    not_: SchemaObject | ReferenceObject | None = Field(None, alias="not")
+
+    # ===== OpenAPI-Specific =====
+    readOnly: bool = False
+    writeOnly: bool = False
+    deprecated: bool = False
+    discriminator: Discriminator | None = None
+    xml: XMLObject | None = None
+    externalDocs: ExternalDocumentationObject | None = None
+
+    # ===== OAS 3.1.0 Content Metadata =====
+    contentMediaType: str | None = Field(
+        None, description="Media type (OAS 3.1.0, e.g., 'application/json')"
+    )
+    contentEncoding: str | None = Field(
+        None, description="Encoding (OAS 3.1.0, e.g., 'base64')"
+    )
+    contentSchema: SchemaObject | ReferenceObject | None = Field(
+        None, description="Schema for content (OAS 3.1.0)"
+    )
+
+    # ===== Django/drf-spectacular Extensions =====
+    x_enum_varnames: list[str] | None = Field(
+        None,
+        alias="x-enum-varnames",
+        description="Enum variable names from drf-spectacular",
+    )
+    x_choices: list[dict[str, Any]] | None = Field(
+        None,
+        alias="x-choices",
+        description="Django choices from drf-spectacular",
+    )
+
+    @property
+    def is_nullable_30(self) -> bool:
+        """Check if nullable via OAS 3.0.3 style (nullable: true)."""
+        return self.nullable is True
+
+    @property
+    def is_nullable_31(self) -> bool:
+        """
+        Check if nullable via OAS 3.1.0 style (type: ['string', 'null']).
+
+        Examples:
+            >>> schema = SchemaObject(type=['string', 'null'])
+            >>> schema.is_nullable_31
+            True
+
+            >>> schema = SchemaObject(type='string')
+            >>> schema.is_nullable_31
+            False
+        """
+        if isinstance(self.type, list):
+            return "null" in self.type
+        return False
+
+    @property
+    def base_type(self) -> str | None:
+        """
+        Get base type (excluding 'null').
+
+        For OAS 3.1.0 type: ['string', 'null'], returns 'string'.
+
+        Examples:
+            >>> SchemaObject(type='string').base_type
+            'string'
+            >>> SchemaObject(type=['string', 'null']).base_type
+            'string'
+            >>> SchemaObject(type=['integer', 'null']).base_type
+            'integer'
+        """
+        if isinstance(self.type, list):
+            types = [t for t in self.type if t != "null"]
+            return types[0] if types else None
+        return self.type
+
+    @property
+    def has_enum_varnames(self) -> bool:
+        """Check if x-enum-varnames extension is present."""
+        return (
+            self.enum is not None
+            and self.x_enum_varnames is not None
+            and len(self.enum) == len(self.x_enum_varnames)
+        )
+
+    @property
+    def is_object(self) -> bool:
+        """Check if schema is object type."""
+        return self.base_type == "object" or self.properties is not None
+
+    @property
+    def is_array(self) -> bool:
+        """Check if schema is array type."""
+        return self.base_type == "array" or self.items is not None
+
+    @property
+    def is_primitive(self) -> bool:
+        """Check if schema is primitive type."""
+        return self.base_type in ("string", "integer", "number", "boolean")
+
+    @property
+    def is_binary(self) -> bool:
+        """
+        Check if schema represents binary data.
+
+        Handles both OAS 3.0.3 (format: binary) and OAS 3.1.0 (contentEncoding).
+        """
+        return self.format == "binary" or self.contentEncoding in ("base64", "binary")
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        parts = ["SchemaObject("]
+
+        if self.type:
+            parts.append(f"type={self.type!r}")
+
+        if self.format:
+            parts.append(f"format={self.format!r}")
+
+        if self.nullable:
+            parts.append("nullable=True")
+
+        if self.enum:
+            parts.append(f"enum={self.enum}")
+
+        if self.x_enum_varnames:
+            parts.append(f"x-enum-varnames={self.x_enum_varnames}")
+
+        return ", ".join(parts) + ")"

django_cfg/modules/django_client/core/parser/openapi30.py

@@ -0,0 +1,56 @@
+"""
+OpenAPI 3.0.3 Parser - Handles nullable: true.
+
+This parser handles OpenAPI 3.0.x specifications which use the proprietary
+`nullable: true` extension for nullable fields.
+
+Reference: https://swagger.io/docs/specification/data-models/data-types/#null
+"""
+
+from .base import BaseParser
+from .models import SchemaObject
+
+
+class OpenAPI30Parser(BaseParser):
+    """
+    Parser for OpenAPI 3.0.x specifications.
+
+    Key differences from 3.1.0:
+    - Uses nullable: true (proprietary extension)
+    - exclusiveMinimum/exclusiveMaximum are booleans (not numbers)
+    - No const keyword
+    - No contentMediaType/contentEncoding
+
+    Examples:
+        >>> from django_cfg.modules.django_client.core.parser.models import OpenAPISpec
+        >>> spec_dict = {...}  # OAS 3.0.3 spec
+        >>> spec = OpenAPISpec.model_validate(spec_dict)
+        >>> parser = OpenAPI30Parser(spec)
+        >>> context = parser.parse()
+        >>> context.openapi_info.version
+        '3.0.3'
+    """
+
+    def _detect_nullable(self, schema: SchemaObject) -> bool:
+        """
+        Detect if schema is nullable using OAS 3.0.3 style.
+
+        In OpenAPI 3.0.x, nullable is indicated by:
+            nullable: true
+
+        Examples:
+            >>> schema = SchemaObject(type='string', nullable=True)
+            >>> parser._detect_nullable(schema)
+            True
+
+            >>> schema = SchemaObject(type='string')
+            >>> parser._detect_nullable(schema)
+            False
+
+        Args:
+            schema: Raw SchemaObject from spec
+
+        Returns:
+            True if nullable, False otherwise
+        """
+        return schema.is_nullable_30

django_cfg/modules/django_client/core/parser/openapi31.py

@@ -0,0 +1,64 @@
+"""
+OpenAPI 3.1.0 Parser - Handles type: ['string', 'null'].
+
+This parser handles OpenAPI 3.1.0 specifications which use JSON Schema 2020-12
+standard for nullable fields (type arrays with 'null').
+
+Reference: https://spec.openapis.org/oas/v3.1.0
+"""
+
+from .base import BaseParser
+from .models import SchemaObject
+
+
+class OpenAPI31Parser(BaseParser):
+    """
+    Parser for OpenAPI 3.1.0 specifications.
+
+    Key differences from 3.0.x:
+    - Uses type: ['string', 'null'] (JSON Schema standard)
+    - exclusiveMinimum/exclusiveMaximum are numbers (not booleans)
+    - Supports const keyword
+    - Supports contentMediaType/contentEncoding
+    - Supports $schema and $vocabulary
+    - Aligned with JSON Schema 2020-12
+
+    Examples:
+        >>> from django_cfg.modules.django_client.core.parser.models import OpenAPISpec
+        >>> spec_dict = {...}  # OAS 3.1.0 spec
+        >>> spec = OpenAPISpec.model_validate(spec_dict)
+        >>> parser = OpenAPI31Parser(spec)
+        >>> context = parser.parse()
+        >>> context.openapi_info.version
+        '3.1.0'
+    """
+
+    def _detect_nullable(self, schema: SchemaObject) -> bool:
+        """
+        Detect if schema is nullable using OAS 3.1.0 style.
+
+        In OpenAPI 3.1.0, nullable is indicated by:
+            type: ['string', 'null']
+            type: ['integer', 'null']
+            etc.
+
+        Examples:
+            >>> schema = SchemaObject(type=['string', 'null'])
+            >>> parser._detect_nullable(schema)
+            True
+
+            >>> schema = SchemaObject(type='string')
+            >>> parser._detect_nullable(schema)
+            False
+
+            >>> schema = SchemaObject(type=['integer', 'null'])
+            >>> parser._detect_nullable(schema)
+            True
+
+        Args:
+            schema: Raw SchemaObject from spec
+
+        Returns:
+            True if nullable, False otherwise
+        """
+        return schema.is_nullable_31

django_cfg/modules/django_client/core/validation/__init__.py

@@ -0,0 +1,22 @@
+"""
+OpenAPI Schema Validation Module.
+
+Provides safe validation and fixing of Django REST Framework serializers
+to improve OpenAPI schema quality.
+"""
+
+from .checker import ValidationChecker
+from .fixer import SafeFixer
+from .reporter import IssueReporter
+from .safety import SafetyManager
+from .rules.base import Issue, Severity, ValidationRule
+
+__all__ = [
+    'ValidationChecker',
+    'SafeFixer',
+    'IssueReporter',
+    'SafetyManager',
+    'Issue',
+    'Severity',
+    'ValidationRule',
+]