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

drf_to_mkdoc/templates/model_detail/choices.html

@@ -0,0 +1,12 @@
+{% load custom_filters %}
+## Choices
+
+{% for field_name, field_info in fields.items %}{% if field_info.choices %}
+### {{ field_name }} Choices
+
+| Label | Value |
+|-------|-------|
+{% for choice in field_info.choices %}| {{ choice.display }} | `{{ choice.value }}` |
+{% endfor %}
+
+{% endif %}{% endfor %}

drf_to_mkdoc/templates/model_detail/fields.html

@@ -0,0 +1,11 @@
+{% load custom_filters %}
+## Fields
+
+| Field | Type | Description | Extra |
+|-------|------|-------------|-------|
+{% for field_name, field_info in fields.items %}{% with field_type=field_info.type|default:"Unknown" %}{% if field_type == "TextField" %}| `{{ field_name }}` | TextField | {{ field_name }} | {% if field_info.max_length %}max_length={{ field_info.max_length }}{% endif %} |
+{% elif field_type == "BigAutoField" %}| `{{ field_name }}` | BigAutoField | ID | {% if field_info.blank %}blank=True{% endif %}{% if field_info.unique %}, unique=True{% endif %}{% if field_info.primary_key %}, primary_key=True{% endif %} |
+{% elif field_type == "CharField" %}| `{{ field_name }}` | CharField | {{ field_name }} | {% if field_info.max_length %}max_length={{ field_info.max_length }}{% endif %}{% if field_info.null %}, null=True{% endif %}{% if field_info.blank %}, blank=True{% endif %} |
+{% elif field_type == "ForeignKey" %}| `{{ field_name }}` | ForeignKey | {{ field_info.field_specific.to|default:"" }} | |
+{% else %}| `{{ field_name }}` | {{ field_type }} | {{ field_name }} | {{ field_info|format_field_extra }} |
+{% endif %}{% endwith %}{% endfor %}

drf_to_mkdoc/templates/model_detail/meta.html

@@ -0,0 +1,6 @@
+## Meta Options
+
+{% for option, value in meta_options.items %}
+- **{{ option }}:** {{ value }}
+{% endfor %}
+

drf_to_mkdoc/templates/model_detail/methods.html

@@ -0,0 +1,9 @@
+## Methods
+
+{% for method in methods %}
+### `{{ method.name }}()`
+
+{{ method.docstring|default:"No documentation available." }}
+
+{% endfor %}
+

drf_to_mkdoc/templates/model_detail/relationships.html

@@ -0,0 +1,8 @@
+{% load custom_filters %}
+## Relationships
+
+| Field | Type | Related Model |
+|-------|------|---------------|
+{% for field_name, field_info in relationships.items %}{% with field_type=field_info.type|default:"Unknown" %}{% if field_info.field_specific.to %}| `{{ field_name }}` | {{ field_type }} | {% if "." in field_info.field_specific.to %}[{{ field_info.field_specific.to|cut:"." }}](../{{ field_info.field_specific.to|cut:"." }}/{% else %}[{{ field_info.field_specific.to }}]({{ field_info.field_specific.to|lower }}/{% endif %} |
+{% endif %}{% endwith %}{% endfor %}{% for rel_name, rel_info in relationships.items %}| `{{ rel_name }}` | {{ rel_info.type|default:"Unknown" }} | [{{ rel_info.verbose_name|capfirst }}](../../{{ rel_info.app_label }}/{{ rel_info.table_name }}/) |
+{% endfor %}

drf_to_mkdoc/templates/models_index.html

@@ -0,0 +1,24 @@
+{% load custom_filters %}
+# Django Models
+
+This section contains documentation for all Django models in the system, organized by Django application.
+
+<!-- inject CSS directly -->
+{% for css in stylesheets %}
+<link rel="stylesheet" href="{{ css }}">
+{% endfor %}
+
+<div class="models-container">
+{% for app_name, models in sorted_models %}
+    <div class="app-header">{{ app_name|title|cut:"_"|safe }}</div>
+    <div class="app-description">{{ app_descriptions|get_item:app_name }}</div>
+
+    <div class="model-cards">
+    {% for verbose_name, table_name in models %}
+        <a href="{{ app_name|urlencode }}/{{ table_name|urlencode }}/" class="model-card">{{ verbose_name }}</a>
+    {% endfor %}
+    </div>
+{% endfor %}
+</div>
+
+Each model page contains detailed field documentation, method signatures, and relationships to other models.

drf_to_mkdoc/templatetags/custom_filters.py

@@ -0,0 +1,116 @@
+import html
+import json
+
+from django import template
+from django.templatetags.static import static as django_static
+from django.utils.safestring import mark_safe
+
+from drf_to_mkdoc.utils.commons.operation_utils import (
+    format_method_badge as format_method_badge_util,
+)
+
+register = template.Library()
+
+
+@register.filter
+def is_foreign_key(field_type):
+    return field_type in ["ForeignKey", "OneToOneField"]
+
+
+@register.simple_tag
+def static_with_prefix(path, prefix=""):
+    """Add prefix to static path"""
+    return django_static(prefix + path)
+
+
+@register.filter
+def format_method_badge(method):
+    """Format HTTP method as badge"""
+    return format_method_badge_util(method)
+
+
+@register.filter
+def get_display_name(field_name, field_type):
+    if field_type in ["ForeignKey", "OneToOneField"]:
+        return f"{field_name}_id"
+    return field_name
+
+
+@register.filter
+def split(value, delimiter=","):
+    return value.split(delimiter)
+
+
+@register.filter
+def cut(value, arg):
+    return value.split(arg)[1] if "." in value else value
+
+
+@register.filter
+def get_item(dictionary, key):
+    return dictionary.get(key, "")
+
+
+@register.filter
+def format_field_type(field_info):
+    field_type = field_info.get("type", "")
+    if field_type == "ForeignKey":
+        return f"ForeignKey | {field_info.get('field_specific', {}).get('to', '')}"
+    if field_type == "CharField":
+        max_length = field_info.get("max_length", "")
+        return f"CharField | {field_info.get('verbose_name', '')} | max_length={max_length}"
+    return field_type
+
+
+@register.filter
+def format_field_extra(field_info):
+    extras = []
+    if field_info.get("null"):
+        extras.append("null=True")
+    if field_info.get("blank"):
+        extras.append("blank=True")
+    if field_info.get("unique"):
+        extras.append("unique=True")
+    if field_info.get("primary_key"):
+        extras.append("primary_key=True")
+    if field_info.get("max_length"):
+        extras.append(f"max_length={field_info['max_length']}")
+    return ", ".join(extras)
+
+
+@register.filter
+def yesno(value, arg=None):
+    """
+    Given a string mapping values for true, false and (optionally) None,
+    return one of those strings according to the value.
+    """
+    if arg is None:
+        arg = "yes,no,maybe"
+    bits = arg.split(",")
+    if len(bits) < 2:
+        return value  # Invalid arg.
+    try:
+        yes, no, maybe = bits
+    except ValueError:
+        yes, no, maybe = bits[0], bits[1], bits[1]
+
+    if value is None:
+        return maybe
+    if value:
+        return yes
+    return no
+
+
+@register.filter
+def format_json(value):
+    if isinstance(value, str):
+        value = html.unescape(value)
+        try:
+            parsed = json.loads(value)
+            value = json.dumps(parsed, indent=2)
+        except (json.JSONDecodeError, TypeError):
+            pass
+    elif isinstance(value, dict | list):
+        value = json.dumps(value, indent=2)
+
+    return mark_safe(value)  # noqa: S308

drf_to_mkdoc/utils/ai_tools/enums.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class MessageRole(Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    FUNCTION = "function"
+    TOOL = "tool"
+    MODEL = "model"
+
+    def __str__(self) -> str:
+        return self.value

drf_to_mkdoc/utils/ai_tools/exceptions.py

@@ -0,0 +1,19 @@
+class AIProviderError(Exception):
+    """Base exception for AI provider errors"""
+
+    def __init__(self, message: str, provider: str | None = None, model: str | None = None):
+        self.provider = provider
+        self.model = model
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        meta = ", ".join(
+            part
+            for part in (
+                f"provider={self.provider}" if self.provider else None,
+                f"model={self.model}" if self.model else None,
+            )
+            if part
+        )
+        return f"{base} ({meta})" if meta else base

drf_to_mkdoc/utils/ai_tools/providers/base_provider.py

@@ -0,0 +1,123 @@
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+from django.template import RequestContext
+
+from drf_to_mkdoc.conf.settings import drf_to_mkdoc_settings
+from drf_to_mkdoc.utils.ai_tools.exceptions import AIProviderError
+from drf_to_mkdoc.utils.ai_tools.types import (
+    ChatResponse,
+    Message,
+    ProviderConfig,
+    TokenUsage,
+)
+from drf_to_mkdoc.utils.commons.schema_utils import OperationExtractor
+
+
+class BaseProvider(ABC):
+    """Abstract base class for AI providers"""
+
+    def __init__(self, config: ProviderConfig):
+        self.config = config
+        self._client = None
+
+    @property
+    def client(self):
+        """Lazy load client"""
+        if self._client is None:
+            if not hasattr(self, "_client_lock"):
+                # If providers are shared across threads, guard initialization.
+                self._client_lock = Lock()
+            with self._client_lock:
+                if self._client is None:
+                    self._client = self._initialize_client()
+        return self._client
+
+    @abstractmethod
+    def _initialize_client(self) -> Any:
+        """Initialize provider-specific client"""
+        pass
+
+    @abstractmethod
+    def _send_chat_request(self, formatted_messages: Any, **kwargs) -> Any:
+        """Send request to provider's API"""
+        pass
+
+    @abstractmethod
+    def _parse_provider_response(self, response: Any) -> ChatResponse:
+        """Parse provider response to standard ChatResponse"""
+        pass
+
+    @abstractmethod
+    def _extract_token_usage(self, response: Any) -> TokenUsage:
+        """Extract token usage from provider response"""
+        pass
+
+    def format_messages_for_provider(self, messages: list[Message]) -> Any:
+        """
+        Convert your Message objects into a single string for chat.send_message().
+        This is a default behavior. You can override it your self as you want.
+        """
+        lines = []
+        for message in messages:
+            lines.append(f"{message.role.value}: {message.content}")
+
+        return "\n".join(lines)
+
+    def chat_completion(self, messages: list[Message], **kwargs) -> ChatResponse:
+        """
+        Send chat completion request without functions
+
+        Args:
+            messages: List of chat messages
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            ChatResponse with AI's response
+        """
+        try:
+            formatted_messages = self.format_messages_for_provider(messages)
+
+            raw_response = self._send_chat_request(formatted_messages, **kwargs)
+
+            response = self._parse_provider_response(raw_response)
+
+            response.usage = self._extract_token_usage(raw_response)
+            response.model = self.config.model_name
+
+        except Exception as e:
+            raise AIProviderError(
+                f"Chat completion failed: {e!s}",
+                provider=self.__class__.__name__,
+                model=self.config.model_name,
+            ) from e
+        else:
+            return response
+
+    def _get_operation_info(
+        self, operation_id: str, context: RequestContext | None = None
+    ) -> dict[str, Any]:
+        return OperationExtractor().operation_map.get(operation_id)
+
+    def _get_model_info(self, app_label: str, model_name: str) -> dict[str, Any]:
+        docs_file = Path(drf_to_mkdoc_settings.MODEL_DOCS_FILE)
+
+        if not docs_file.exists():
+            raise FileNotFoundError(f"Model documentation file not found: {docs_file}")
+
+        with docs_file.open("r", encoding="utf-8") as f:
+            model_docs = json.load(f)
+
+        if app_label not in model_docs:
+            raise LookupError(f"App '{app_label}' not found in model documentation.")
+
+        if model_name not in model_docs[app_label]:
+            raise LookupError(f"Model '{model_name}' not found in model documentation.")
+
+        return model_docs[app_label][model_name]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(provider={self.__class__.__name__}, model={self.config.model_name})"

drf_to_mkdoc/utils/ai_tools/providers/gemini_provider.py

@@ -0,0 +1,80 @@
+from google import genai
+from google.genai.types import GenerateContentConfig, GenerateContentResponse
+
+from drf_to_mkdoc.utils.ai_tools.exceptions import AIProviderError
+from drf_to_mkdoc.utils.ai_tools.providers.base_provider import BaseProvider
+from drf_to_mkdoc.utils.ai_tools.types import (
+    ChatResponse,
+    TokenUsage,
+)
+
+
+class GeminiProvider(BaseProvider):
+    def _initialize_client(self) -> genai.Client:
+        try:
+            client = genai.Client(api_key=self.config.api_key)
+
+        except Exception as e:
+            raise AIProviderError(
+                f"Failed to initialize Gemini client: {e!s}",
+                provider="GeminiProvider",
+                model=self.config.model_name,
+            ) from e
+        else:
+            return client
+
+    def _send_chat_request(
+        self, formatted_messages, *args, **kwargs
+    ) -> GenerateContentResponse:
+        client: genai.Client = self.client
+        try:
+            return client.models.generate_content(
+                model=self.config.model_name,
+                contents=formatted_messages,
+                config=GenerateContentConfig(
+                    temperature=self.config.temperature,
+                    max_output_tokens=self.config.max_tokens,
+                    **(self.config.extra_params or {}).get("generate_content_config", {}),
+                ),
+            )
+
+        except Exception as e:
+            raise AIProviderError(
+                f"Chat completion failed: Gemini API request failed: {e!s}",
+                provider="GeminiProvider",
+                model=self.config.model_name,
+            ) from e
+
+    def _parse_provider_response(self, response: GenerateContentResponse) -> ChatResponse:
+        try:
+            return ChatResponse(
+                content=(getattr(response, "text", "") or "").strip(),
+                model=self.config.model_name,
+            )
+
+        except Exception as e:
+            raise AIProviderError(
+                f"Failed to parse Gemini response: {e!s}",
+                provider="GeminiProvider",
+                model=self.config.model_name,
+            ) from e
+
+    def _extract_token_usage(self, response: GenerateContentResponse) -> TokenUsage:
+        usage = getattr(response, "usage_metadata", None)
+        if not usage:
+            return TokenUsage(
+                request_tokens=0,
+                response_tokens=0,
+                total_tokens=0,
+                provider=self.__class__.__name__,
+                model=self.config.model_name,
+            )
+        request_tokens = int(getattr(usage, "prompt_token_count", 0) or 0)
+        response_tokens = int(getattr(usage, "candidates_token_count", 0) or 0)
+        return TokenUsage(
+            request_tokens=request_tokens,
+            response_tokens=response_tokens,
+            total_tokens=request_tokens + response_tokens,
+            provider=self.__class__.__name__,
+            model=self.config.model_name,
+        )

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 {}