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

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