drf-to-mkdoc 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

drf_to_mkdoc/utils/ai_tools/types.py

@@ -0,0 +1,81 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from drf_to_mkdoc.utils.ai_tools.enums import MessageRole
+
+
+@dataclass
+class TokenUsage:
+    """Standardized token usage across all providers"""
+
+    request_tokens: int
+    response_tokens: int
+    total_tokens: int
+    provider: str
+    model: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "request_tokens": self.request_tokens,
+            "response_tokens": self.response_tokens,
+            "total_tokens": self.total_tokens,
+            "provider": self.provider,
+            "model": self.model,
+        }
+
+
+@dataclass
+class Message:
+    """Chat message"""
+
+    role: MessageRole
+    content: str
+    metadata: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {"role": self.role.value, "content": self.content}
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result
+
+
+@dataclass
+class ChatResponse:
+    """Standardized response from AI providers"""
+
+    content: str
+    usage: TokenUsage | None = None
+    model: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "content": self.content,
+        }
+        if self.usage:
+            result["usage"] = self.usage.to_dict()
+        if self.metadata:
+            result["metadata"] = self.metadata
+        if self.model is not None:
+            result["model"] = self.model
+        return result
+
+
+@dataclass
+class ProviderConfig:
+    """Configuration for AI providers"""
+
+    model_name: str
+    api_key: str
+    temperature: float = 0.7
+    max_tokens: int | None = None
+    extra_params: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "api_key": self.api_key,
+            "model_name": self.model_name,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "extra_params": self.extra_params,
+        }

drf_to_mkdoc/utils/commons/code_extractor.py

@@ -0,0 +1,22 @@
+"""Code extraction utilities."""
+
+from pathlib import Path
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+
+
+def create_ai_code_directories() -> None:
+    """Create the directory structure for AI-generated code files."""
+    # Get base config directory
+    config_dir = Path(drf_to_mkdoc_settings.CONFIG_DIR)
+
+    # Create AI code directory
+    ai_code_dir = config_dir / drf_to_mkdoc_settings.AI_CONFIG_DIR_NAME
+
+    # Create subdirectories
+    subdirs = ["serializers", "views", "permissions"]
+
+    # Create all directories
+    for subdir in subdirs:
+        dir_path = ai_code_dir / subdir
+        Path.mkdir(dir_path, parents=True, exist_ok=True)

drf_to_mkdoc/utils/commons/file_utils.py

@@ -0,0 +1,35 @@
+"""File operation utilities."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+
+
+def write_file(file_path: str, content: str) -> None:
+    full_path = Path(drf_to_mkdoc_settings.DOCS_DIR) / file_path
+    try:
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = full_path.with_suffix(full_path.suffix + ".tmp")
+
+        with tmp_path.open("w", encoding="utf-8") as f:
+            # Use atomic writes to avoid partially written docs.
+            f.write(content)
+        tmp_path.replace(full_path)
+    except OSError as e:
+        raise OSError(f"Failed to write file {full_path}: {e}") from e
+
+
+def load_json_data(file_path: str, raise_not_found: bool = True) -> dict[str, Any] | None:
+    json_file = Path(file_path)
+    if not json_file.exists():
+        if raise_not_found:
+            raise FileNotFoundError(f"File not found: {json_file}")
+        return None
+
+    with json_file.open("r", encoding="utf-8") as f:
+        try:
+            return json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {json_file}: {e}") from e

drf_to_mkdoc/utils/commons/model_utils.py

@@ -0,0 +1,83 @@
+"""Model-related utilities."""
+
+import importlib
+
+from django.apps import apps
+from django.core.exceptions import AppRegistryNotReady
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.commons.file_utils import load_json_data
+
+
+def get_model_docstring(class_name: str) -> str | None:
+    """Extract docstring from Django model class"""
+    try:
+        # Check if Django is properly initialized
+        apps.check_apps_ready()
+
+        # Common Django app names to search
+        app_names = drf_to_mkdoc_settings.DJANGO_APPS
+
+        for app_name in app_names:
+            try:
+                # Try to import the models module
+                models_module = importlib.import_module(f"{app_name}.models")
+
+                # Check if the class exists in this module
+                if hasattr(models_module, class_name):
+                    model_class = getattr(models_module, class_name)
+
+                    # Get the docstring
+                    docstring = getattr(model_class, "__doc__", None)
+
+                    if docstring:
+                        # Clean up the docstring
+                        docstring = docstring.strip()
+
+                        # Filter out auto-generated or generic docstrings
+                        if (
+                            docstring
+                            and not docstring.startswith(class_name + "(")
+                            and not docstring.startswith("str(object=")
+                            and not docstring.startswith("Return repr(self)")
+                            and "django.db.models" not in docstring.lower()
+                            and len(docstring) > 10
+                        ):  # Minimum meaningful length
+                            return docstring
+
+            except (ImportError, AttributeError):
+                continue
+
+    except (ImportError, AppRegistryNotReady):
+        # Django not initialized or not available - skip docstring extraction
+        pass
+
+    return None
+
+
+def get_model_description(class_name: str) -> str:
+    """Get a brief description for a model with priority-based selection"""
+    # Priority 1: Description from config file
+    config = load_json_data(drf_to_mkdoc_settings.DOC_CONFIG_FILE, raise_not_found=False)
+    if config and "model_descriptions" in config:
+        config_description = config["model_descriptions"].get(class_name, "").strip()
+        if config_description:
+            return config_description
+
+    # Priority 2: Extract docstring from model class
+    docstring = get_model_docstring(class_name)
+    if docstring:
+        return docstring
+
+    # Priority 3: static value
+    return "Not provided"
+
+
+def get_app_descriptions() -> dict[str, str]:
+    """Get descriptions for Django apps from config file"""
+    config = load_json_data(drf_to_mkdoc_settings.DOC_CONFIG_FILE, raise_not_found=False)
+    if config and "app_descriptions" in config:
+        return config["app_descriptions"]
+
+    # Fallback to empty dict if config not available
+    return {}

drf_to_mkdoc/utils/commons/operation_utils.py

@@ -0,0 +1,83 @@
+"""Operation ID and viewset utilities."""
+
+import logging
+from functools import lru_cache
+from typing import Any
+
+from django.urls import Resolver404, resolve
+
+from drf_to_mkdoc.utils.commons.path_utils import substitute_path_params
+from drf_to_mkdoc.utils.commons.schema_utils import get_schema
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache
+def get_operation_id_path_map() -> dict[str, tuple[str, list[dict[str, Any]]]]:
+    schema = get_schema()
+    paths = schema.get("paths", {})
+    mapping = {}
+
+    for path, actions in paths.items():
+        for http_method_name, action_data in actions.items():
+            if http_method_name.lower() == "parameters" or not isinstance(action_data, dict):
+                # Skip path-level parameters entries (e.g., "parameters": [...] in OpenAPI schema)
+                continue
+            operation_id = action_data.get("operationId")
+            if operation_id:
+                mapping[operation_id] = (path, action_data.get("parameters", []))
+
+    return mapping
+
+
+def extract_viewset_from_operation_id(operation_id: str):
+    """Extract the ViewSet class from an OpenAPI operation ID."""
+    operation_map = get_operation_id_path_map()
+    entry = operation_map.get(operation_id)
+    if not entry:
+        raise ValueError(f"Unknown operationId: {operation_id!r}")
+    path, parameters = entry
+
+    resolved_path = substitute_path_params(path, parameters)
+    try:
+        match = resolve(resolved_path)
+        view_func = match.func
+        if hasattr(view_func, "view_class"):
+            # For generic class-based views
+            return view_func.view_class
+
+        if hasattr(view_func, "cls"):
+            # For viewsets
+            return view_func.cls
+
+    except Resolver404:
+        logger.exception(
+            "Failed to resolve path. schema_path=%s tried_path=%s",
+            path,
+            resolved_path,
+        )
+    else:
+        return view_func
+
+
+def extract_viewset_name_from_operation_id(operation_id: str):
+    view_cls = extract_viewset_from_operation_id(operation_id)
+    return view_cls.__name__ if hasattr(view_cls, "__name__") else str(view_cls)
+
+
+def extract_app_from_operation_id(operation_id: str) -> str:
+    view = extract_viewset_from_operation_id(operation_id)
+
+    if isinstance(view, type):
+        module = view.__module__
+    elif hasattr(view, "__class__"):
+        module = view.__class__.__module__
+    else:
+        raise TypeError("Expected a view class or instance")
+
+    return module.split(".")[0]
+
+
+def format_method_badge(method: str) -> str:
+    """Create a colored badge for HTTP method"""
+    return f'<span class="method-badge method-{method.lower()}">{method.upper()}</span>'

drf_to_mkdoc/utils/commons/path_utils.py

@@ -0,0 +1,78 @@
+"""Path manipulation utilities."""
+
+import logging
+import re
+from typing import Any
+
+from django.utils.module_loading import import_string
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+
+logger = logging.getLogger(__name__)
+
+
+def substitute_path_params(path: str, parameters: list[dict[str, Any]]) -> str:
+    django_path = convert_to_django_path(path, parameters)
+
+    django_path = re.sub(r"\{[^}]+\}", "1", django_path)
+    django_path = re.sub(r"<int:[^>]+>", "1", django_path)
+    django_path = re.sub(r"<uuid:[^>]+>", "12345678-1234-5678-9abc-123456789012", django_path)
+    django_path = re.sub(r"<float:[^>]+>", "1.0", django_path)
+    django_path = re.sub(r"<(?:string|str):[^>]+>", "dummy", django_path)
+    django_path = re.sub(r"<path:[^>]+>", "dummy/path", django_path)
+    django_path = re.sub(r"<[^:>]+>", "dummy", django_path)  # Catch remaining simple params
+
+    return django_path  # noqa: RET504
+
+
+def convert_to_django_path(path: str, parameters: list[dict[str, Any]]) -> str:
+    """
+    Convert a path with {param} to a Django-style path with <type:param>.
+    If PATH_PARAM_SUBSTITUTE_FUNCTION is set, call it and merge its returned mapping.
+    """
+    function = None
+    func_path = drf_to_mkdoc_settings.PATH_PARAM_SUBSTITUTE_FUNCTION
+
+    if func_path:
+        try:
+            function = import_string(func_path)
+        except ImportError:
+            logger.warning("Invalid PATH_PARAM_SUBSTITUTE_FUNCTION import path: %r", func_path)
+
+    # If custom function exists and returns a valid value, use it
+    mapping = dict(drf_to_mkdoc_settings.PATH_PARAM_SUBSTITUTE_MAPPING or {})
+    if callable(function):
+        try:
+            result = function(path, parameters)
+            if result and isinstance(result, dict):
+                mapping.update(result)
+        except Exception:
+            logger.exception("Error in custom path substitutor %r for path %r", func_path, path)
+
+    # Default Django path conversion
+    def replacement(match):
+        param_name = match.group(1)
+        custom_param_type = mapping.get(param_name)
+        if custom_param_type and custom_param_type in ("int", "uuid", "str"):
+            converter = custom_param_type
+        else:
+            param_info = next((p for p in parameters if p.get("name") == param_name), {})
+            param_type = param_info.get("schema", {}).get("type")
+            param_format = param_info.get("schema", {}).get("format")
+
+            if param_type == "integer":
+                converter = "int"
+            elif param_type == "string" and param_format == "uuid":
+                converter = "uuid"
+            else:
+                converter = "str"
+
+        return f"<{converter}:{param_name}>"
+
+    return re.sub(r"{(\w+)}", replacement, path)
+
+
+def create_safe_filename(path: str, method: str) -> str:
+    """Create a safe filename from path and method"""
+    safe_path = re.sub(r"[^a-zA-Z0-9_-]", "_", path.strip("/"))
+    return f"{method.lower()}_{safe_path}.md"

drf_to_mkdoc/utils/commons/schema_utils.py

@@ -0,0 +1,230 @@
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from drf_spectacular.generators import SchemaGenerator
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.commons.file_utils import load_json_data
+
+
+class SchemaValidationError(Exception):
+    """Custom exception for schema validation errors."""
+
+    pass
+
+
+class QueryParamTypeError(Exception):
+    """Custom exception for query parameter type errors."""
+
+    pass
+
+
+def load_schema() -> dict[str, Any] | None:
+    """Load the OpenAPI schema from doc-schema.yaml"""
+    schema_file = Path(drf_to_mkdoc_settings.CONFIG_DIR) / "doc-schema.yaml"
+    if not schema_file.exists():
+        return None
+
+    with schema_file.open(encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def get_custom_schema():
+    custom_schema_data = load_json_data(
+        drf_to_mkdoc_settings.CUSTOM_SCHEMA_FILE, raise_not_found=False
+    )
+    if not custom_schema_data:
+        return {}
+
+    for _operation_id, overrides in custom_schema_data.items():
+        parameters = overrides.get("parameters", [])
+        if not parameters:
+            continue
+        for parameter in parameters:
+            if {"name", "in", "description", "required", "schema"} - set(parameter.keys()):
+                raise SchemaValidationError("Required keys are not passed")
+
+            if parameter["in"] == "query":
+                queryparam_type = parameter.get("queryparam_type")
+                if not queryparam_type:
+                    raise QueryParamTypeError("queryparam_type is required for query")
+
+                if queryparam_type not in (
+                    {
+                        "search_fields",
+                        "filter_fields",
+                        "ordering_fields",
+                        "filter_backends",
+                        "pagination_fields",
+                    }
+                ):
+                    raise QueryParamTypeError("Invalid queryparam_type")
+
+    return custom_schema_data
+
+
+def _merge_parameters(
+    base_parameters: list[dict[str, Any]], custom_parameters: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """
+    Merge parameters from base and custom schemas, avoiding duplicates.
+
+    Parameters are considered duplicates if they have the same 'name' and 'in' values.
+    Custom parameters will override base parameters with the same (name, in) key.
+    """
+
+    def _get_param_key(param: dict[str, Any]) -> tuple[str, str] | None:
+        """Extract (name, in) tuple from parameter, return None if invalid."""
+        name = param.get("name")
+        location = param.get("in")
+        return (name, location) if name and location else None
+
+    param_index = {}
+    for param in base_parameters:
+        key = _get_param_key(param)
+        if key:
+            param_index[key] = param
+
+    for param in custom_parameters:
+        key = _get_param_key(param)
+        if key:
+            param_index[key] = param
+
+    return list(param_index.values())
+
+
+def _build_operation_map(base_schema: dict) -> dict[str, tuple[str, str]]:
+    """Build a mapping from operationId → (path, method)."""
+    op_map = {}
+    HTTP_METHODS = {"get", "post", "put", "patch", "delete", "options", "head", "trace"}
+
+    for path, actions in base_schema.get("paths", {}).items():
+        for method, op_data in actions.items():
+            if method.lower() not in HTTP_METHODS or not isinstance(op_data, dict):
+                continue
+            if not op_data.get("x-metadata"):
+                raise ValueError(
+                    "Missing x-metadata in OpenAPI schema. Please ensure you're using the custom AutoSchema in your REST_FRAMEWORK settings:\n"
+                    "REST_FRAMEWORK = {\n"
+                    "    'DEFAULT_SCHEMA_CLASS': 'drf_to_mkdoc.utils.schema.AutoSchema',\n"
+                    "}\n"
+                )
+            operation_id = op_data.get("operationId")
+            if operation_id:
+                op_map[operation_id] = (path, method)
+
+    return op_map
+
+
+def _apply_custom_overrides(
+    base_schema: dict,
+    op_map: dict[str, tuple[str, str]],
+    custom_data: dict,
+) -> None:
+    """Apply custom overrides to the base schema."""
+    allowed_keys = {"description", "parameters", "requestBody", "responses"}
+
+    for operation_id, overrides in custom_data.items():
+        if operation_id not in op_map:
+            continue
+
+        append_fields = set(overrides.get("append_fields", []))
+        path, method = op_map[operation_id]
+        target_schema = base_schema["paths"][path][method]
+
+        for key in allowed_keys:
+            if key not in overrides:
+                continue
+
+            custom_value = overrides[key]
+            base_value = target_schema.get(key)
+
+            if key in append_fields:
+                if isinstance(base_value, list) and isinstance(custom_value, list):
+                    if key == "parameters":
+                        target_schema[key] = _merge_parameters(base_value, custom_value)
+                    else:
+                        target_schema[key].extend(custom_value)
+                else:
+                    target_schema[key] = custom_value
+            else:
+                target_schema[key] = custom_value
+
+
+def get_schema():
+    base_schema = SchemaGenerator().get_schema(request=None, public=True)
+    custom_data = get_custom_schema()
+    if not custom_data:
+        return base_schema
+
+    operation_map = _build_operation_map(base_schema)
+    _apply_custom_overrides(base_schema, operation_map, custom_data)
+
+    return base_schema
+
+
+class OperationExtractor:
+    """Extracts operation IDs and metadata from OpenAPI schema."""
+
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if not self._initialized:
+            self.schema = get_schema()
+            self._operation_map = None
+            self._initialized = True
+
+    def save_operation_map(self) -> None:
+        """Save operation map to file."""
+        if not self._operation_map:
+            self._operation_map = self._build_operation_map()
+
+        operation_map_path = Path(drf_to_mkdoc_settings.AI_OPERATION_MAP_FILE)
+        # Create parent directories if they don't exist
+        operation_map_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with operation_map_path.open("w", encoding="utf-8") as f:
+            json.dump(self._operation_map, f, indent=2)
+
+    @property
+    def operation_map(self) -> dict[str, dict[str, Any]] | None:
+        """
+        Cache and return operation ID mapping.
+         Returns dict: operation_id -> {"path": str, ...metadata}
+        """
+        if self._operation_map is None:
+            # Try to load from file first
+            self._operation_map = load_json_data(
+                drf_to_mkdoc_settings.AI_OPERATION_MAP_FILE, raise_not_found=False
+            )
+
+            # If not found or invalid, build and save
+            if self._operation_map is None:
+                self._operation_map = self._build_operation_map()
+                self.save_operation_map()
+
+        return self._operation_map
+
+    def _build_operation_map(self) -> dict[str, dict[str, Any]] | None:
+        """Build mapping of operation IDs to paths and metadata."""
+        mapping = {}
+        paths = self.schema.get("paths", {})
+
+        for path, methods in paths.items():
+            for _method, operation in methods.items():
+                operation_id = operation.get("operationId")
+                if not operation_id:
+                    continue
+
+                metadata = operation.get("x-metadata", {})
+                mapping[operation_id] = {"path": path, **metadata}
+
+        return mapping

drf_to_mkdoc/utils/endpoint_detail_generator.py

@@ -10,14 +10,14 @@ from django.templatetags.static import static
 from rest_framework import serializers
 
 from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
-from drf_to_mkdoc.utils.common import (
-    create_safe_filename,
+from drf_to_mkdoc.utils.commons.file_utils import write_file
+from drf_to_mkdoc.utils.commons.operation_utils import (
     extract_app_from_operation_id,
     extract_viewset_name_from_operation_id,
     format_method_badge,
-    get_custom_schema,
-    write_file,
 )
+from drf_to_mkdoc.utils.commons.path_utils import create_safe_filename
+from drf_to_mkdoc.utils.commons.schema_utils import get_custom_schema
 from drf_to_mkdoc.utils.extractors.query_parameter_extractors import (
     extract_query_parameters_from_view,
 )
@@ -32,17 +32,17 @@ def analyze_serializer_method_field_schema(serializer_class, field_name: str) ->
     """Analyze a SerializerMethodField to determine its actual return type schema."""
     method_name = f"get_{field_name}"
 
-    # Strategy 2: Check type annotations
+    # Strategy 1: Check type annotations
     schema_from_annotations = _extract_schema_from_type_hints(serializer_class, method_name)
     if schema_from_annotations:
         return schema_from_annotations
 
-    # Strategy 3: Analyze method source code
+    # Strategy 2: Analyze method source code
     schema_from_source = _analyze_method_source_code(serializer_class, method_name)
     if schema_from_source:
         return schema_from_source
 
-    # Strategy 4: Runtime analysis (sample execution)
+    # Strategy 3: Runtime analysis (sample execution)
     schema_from_runtime = _analyze_method_runtime(serializer_class, method_name)
     if schema_from_runtime:
         return schema_from_runtime
@@ -51,33 +51,6 @@ def analyze_serializer_method_field_schema(serializer_class, field_name: str) ->
     return {"type": "string"}
 
 
-def _extract_schema_from_decorator(serializer_class, method_name: str) -> dict:
-    """Extract schema from @extend_schema_field decorator if present."""
-    try:
-        method = getattr(serializer_class, method_name, None)
-        if not method:
-            return {}
-
-        # Check if method has the decorator attribute (drf-spectacular)
-        if hasattr(method, "_spectacular_annotation"):
-            annotation = method._spectacular_annotation
-            # Handle OpenApiTypes
-            if hasattr(annotation, "type"):
-                return {"type": annotation.type}
-            if isinstance(annotation, dict):
-                return annotation
-
-        # Check for drf-yasg decorator
-        if hasattr(method, "_swagger_serializer_method"):
-            swagger_info = method._swagger_serializer_method
-            if hasattr(swagger_info, "many") and hasattr(swagger_info, "child"):
-                return {"type": "array", "items": {"type": "object"}}
-
-    except Exception:
-        logger.exception("Failed to extract schema from decorator")
-    return {}
-
-
 def _extract_schema_from_type_hints(serializer_class, method_name: str) -> dict:
     """Extract schema from method type annotations."""
     try: