django-cfg 1.4.21__py3-none-any.whl → 1.4.24__py3-none-any.whl

django_cfg/modules/django_client/system/mjs_generator.py

@@ -0,0 +1,219 @@
+"""
+MJS (ES Module) client generator for Django CFG.
+Generates JavaScript modules with JSDoc type annotations.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List
+
+from base_generator import BaseGenerator
+from schema_parser import SchemaParser
+
+
+class MJSGenerator(BaseGenerator):
+    """Generate MJS API clients with JSDoc type annotations."""
+
+    def __init__(self, schema_path: Path, output_dir: Path):
+        """Initialize the MJS generator."""
+        super().__init__(schema_path, output_dir)
+        self.parser = SchemaParser(self.schema)
+
+    def generate(self) -> int:
+        """Generate all MJS client files organized by apps."""
+        # Clean and create output directory
+        if self.output_dir.exists():
+            shutil.rmtree(self.output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate base client
+        self._generate_base_client()
+
+        # Generate type definitions
+        self._generate_types()
+
+        # Group operations by app
+        operations_by_app = self.parser.group_operations_by_app()
+
+        # Generate client for each app
+        generated_apps = []
+        for app_name, operations in sorted(operations_by_app.items()):
+            # Skip certain apps
+            if app_name in ['default', 'endpoints', 'health']:
+                continue
+
+            self._generate_app_client(app_name, operations)
+            generated_apps.append(app_name)
+
+        # Generate main index file
+        self._generate_main_index(generated_apps)
+
+        # Count generated files
+        file_count = len(generated_apps) * 2 + 3  # apps * (client + index) + base + types + main index
+        return file_count
+
+    def _generate_base_client(self):
+        """Generate the base API client class."""
+        content = self.render_template('base_client.js.j2')
+
+        base_file = self.output_dir / 'base.mjs'
+        base_file.write_text(content)
+        print(f"  ✅ Generated: {base_file}")
+
+    def _generate_types(self):
+        """Generate type definitions from schema components."""
+        # Extract all schema definitions
+        schemas = self.schema.get('components', {}).get('schemas', {})
+
+        # Convert schemas to JSDoc typedef format
+        typedefs = []
+        for schema_name, schema_def in schemas.items():
+            typedef = self._schema_to_typedef(schema_name, schema_def)
+            if typedef:
+                typedefs.append(typedef)
+
+        content = self.render_template('types.js.j2', typedefs=typedefs)
+
+        types_file = self.output_dir / 'types.mjs'
+        types_file.write_text(content)
+        print(f"  ✅ Generated: {types_file}")
+
+    def _schema_to_typedef(self, name: str, schema: Dict[str, Any]) -> Dict[str, Any]:
+        """Convert an OpenAPI schema to a JSDoc typedef."""
+        if schema.get('type') != 'object':
+            return None
+
+        properties = []
+        required_props = schema.get('required', [])
+
+        for prop_name, prop_schema in schema.get('properties', {}).items():
+            prop_type = self.parser.get_js_type(prop_schema)
+            is_required = prop_name in required_props
+
+            properties.append({
+                'name': prop_name,
+                'type': prop_type,
+                'required': is_required,
+                'description': prop_schema.get('description', '')
+            })
+
+        return {
+            'name': name,
+            'description': schema.get('description', ''),
+            'properties': properties
+        }
+
+    def _generate_app_client(self, app_name: str, operations: List[Dict]):
+        """Generate client files for a specific app."""
+        # Create app directory
+        app_dir = self.output_dir / app_name
+        app_dir.mkdir(parents=True, exist_ok=True)
+
+        # Prepare operations data
+        methods = []
+        for op in operations:
+            method_data = self._prepare_method_data(op)
+            if method_data:
+                methods.append(method_data)
+
+        # Generate client file
+        class_name = self.to_pascal_case(app_name) + 'API'
+        instance_name = self.to_camel_case(app_name) + 'API'
+
+        content = self.render_template(
+            'api_client.js.j2',
+            app_name=app_name,
+            class_name=class_name,
+            instance_name=instance_name,
+            methods=methods
+        )
+
+        client_file = app_dir / 'client.mjs'
+        client_file.write_text(content)
+        print(f"  ✅ Generated: {client_file}")
+
+        # Generate app index
+        index_content = self.render_template(
+            'app_index.js.j2',
+            app_name=app_name,
+            class_name=class_name,
+            instance_name=instance_name
+        )
+
+        index_file = app_dir / 'index.mjs'
+        index_file.write_text(index_content)
+        print(f"  ✅ Generated: {index_file}")
+
+    def _prepare_method_data(self, operation: Dict[str, Any]) -> Dict[str, Any]:
+        """Prepare method data for template rendering."""
+        operation_id = operation.get('operationId', '')
+        if not operation_id:
+            return None
+
+        method_name = self.parser.extract_method_name(operation_id)
+        method_name = self.to_camel_case(method_name)
+
+        # Extract parameters
+        path_params = []
+        query_params = []
+
+        for param in operation.get('parameters', []):
+            param_info = self.parser.extract_parameter_info(param)
+
+            if param_info['in'] == 'path':
+                path_params.append(param_info)
+            elif param_info['in'] == 'query':
+                query_params.append(param_info)
+
+        # Extract request body
+        request_body = self.parser.extract_request_body_info(
+            operation.get('requestBody')
+        )
+
+        # Extract response type
+        response_type = self.parser.get_response_type(
+            operation.get('responses', {})
+        )
+
+        # Build path with template literals
+        api_path = operation['path']
+        for param in path_params:
+            api_path = api_path.replace(
+                f"{{{param['name']}}}",
+                f"${{{param['name']}}}"
+            )
+
+        return {
+            'name': method_name,
+            'http_method': operation['method'].upper(),
+            'path': api_path,
+            'summary': operation.get('summary', ''),
+            'description': operation.get('description', ''),
+            'path_params': path_params,
+            'query_params': query_params,
+            'request_body': request_body,
+            'response_type': response_type
+        }
+
+    def _generate_main_index(self, apps: List[str]):
+        """Generate the main index file."""
+        # Prepare app data for template
+        app_imports = []
+        for app_name in sorted(apps):
+            class_name = self.to_pascal_case(app_name) + 'API'
+            instance_name = self.to_camel_case(app_name) + 'API'
+
+            app_imports.append({
+                'app_name': app_name,
+                'class_name': class_name,
+                'instance_name': instance_name
+            })
+
+        content = self.render_template(
+            'main_index.js.j2',
+            apps=app_imports
+        )
+
+        index_file = self.output_dir / 'index.mjs'
+        index_file.write_text(content)
+        print(f"  ✅ Generated: {index_file}")

django_cfg/modules/django_client/system/schema_parser.py

@@ -0,0 +1,195 @@
+"""
+OpenAPI schema parser for extracting operation and type information.
+"""
+
+import re
+from typing import Any, Dict, List, Optional
+
+
+class SchemaParser:
+    """Parse OpenAPI schema to extract operation and type information."""
+
+    def __init__(self, schema: Dict[str, Any]):
+        """Initialize with OpenAPI schema."""
+        self.schema = schema
+        self.components = schema.get('components', {})
+        self.schemas = self.components.get('schemas', {})
+
+    def extract_app_from_path(self, path: str) -> str:
+        """Extract app name from API path."""
+        # Pattern: /cfg/{app_name}/...
+        match = re.match(r'/cfg/([^/]+)/', path)
+        if match:
+            return match.group(1)
+        return 'core'  # Default for paths without clear app
+
+    def extract_method_name(self, operation_id: str) -> str:
+        """Extract clean method name from operation ID."""
+        # Remove common prefixes
+        for prefix in ['cfg__', 'api_', 'cfg_']:
+            if operation_id.startswith(prefix):
+                operation_id = operation_id[len(prefix):]
+
+        # Handle double underscores
+        operation_id = operation_id.replace('__', '_')
+
+        return operation_id
+
+    def group_operations_by_app(self) -> Dict[str, List[Dict]]:
+        """Group API operations by Django app based on path patterns."""
+        grouped = {}
+
+        for path, path_item in self.schema.get('paths', {}).items():
+            for method, operation in path_item.items():
+                if method in ['get', 'post', 'put', 'patch', 'delete']:
+                    # Extract app name from path
+                    app_name = self.extract_app_from_path(path)
+
+                    # Add operation info
+                    op_info = {
+                        'path': path,
+                        'method': method,
+                        'operationId': operation.get('operationId', ''),
+                        'summary': operation.get('summary', ''),
+                        'description': operation.get('description', ''),
+                        'parameters': operation.get('parameters', []),
+                        'requestBody': operation.get('requestBody'),
+                        'responses': operation.get('responses', {}),
+                        'tags': operation.get('tags', [])
+                    }
+
+                    if app_name not in grouped:
+                        grouped[app_name] = []
+                    grouped[app_name].append(op_info)
+
+        return grouped
+
+    def extract_parameter_info(self, parameter: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract detailed parameter information."""
+        param_info = {
+            'name': parameter.get('name'),
+            'in': parameter.get('in'),
+            'required': parameter.get('required', False),
+            'description': parameter.get('description', ''),
+            'schema': parameter.get('schema', {})
+        }
+
+        # Extract type information
+        schema = parameter.get('schema', {})
+        param_info['type'] = self.get_js_type(schema)
+        param_info['format'] = schema.get('format')
+
+        return param_info
+
+    def extract_request_body_info(self, request_body: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Extract request body information."""
+        if not request_body:
+            return None
+
+        content = request_body.get('content', {})
+        json_content = content.get('application/json', {})
+        schema = json_content.get('schema', {})
+
+        return {
+            'required': request_body.get('required', False),
+            'description': request_body.get('description', ''),
+            'schema': schema,
+            'type': self.get_js_type(schema)
+        }
+
+    def get_js_type(self, schema: Dict[str, Any]) -> str:
+        """Convert OpenAPI schema to JavaScript/TypeScript type."""
+        if not schema:
+            return 'any'
+
+        # Handle references
+        if '$ref' in schema:
+            ref_name = schema['$ref'].split('/')[-1]
+            return ref_name
+
+        # Handle arrays
+        if schema.get('type') == 'array':
+            items_type = self.get_js_type(schema.get('items', {}))
+            return f'{items_type}[]'
+
+        # Handle objects
+        if schema.get('type') == 'object':
+            # Check if it has specific properties
+            if 'properties' in schema:
+                # Could generate an interface here
+                return 'Object'
+            # Check for additionalProperties (dictionary-like)
+            if 'additionalProperties' in schema:
+                value_type = self.get_js_type(schema['additionalProperties'])
+                return f'Record<string, {value_type}>'
+            return 'Object'
+
+        # Handle enums
+        if 'enum' in schema:
+            # Create a union type from enum values
+            values = schema['enum']
+            if all(isinstance(v, str) for v in values):
+                return ' | '.join(f'"{v}"' for v in values)
+            return 'string'
+
+        # Handle primitive types
+        type_mapping = {
+            'string': 'string',
+            'integer': 'number',
+            'number': 'number',
+            'boolean': 'boolean',
+            'null': 'null'
+        }
+
+        openapi_type = schema.get('type', 'any')
+
+        # Handle special formats
+        format_type = schema.get('format')
+        if openapi_type == 'string' and format_type:
+            format_mapping = {
+                'date': 'string',  # Could be Date
+                'date-time': 'string',  # Could be Date
+                'uuid': 'string',
+                'email': 'string',
+                'uri': 'string',
+                'binary': 'Blob',
+                'byte': 'string'
+            }
+            return format_mapping.get(format_type, 'string')
+
+        return type_mapping.get(openapi_type, 'any')
+
+    def get_response_type(self, responses: Dict[str, Any]) -> str:
+        """Extract the response type from operation responses."""
+        # Look for successful response (200, 201, etc.)
+        for status in ['200', '201', '202']:
+            if status in responses:
+                response = responses[status]
+                content = response.get('content', {})
+
+                if 'application/json' in content:
+                    schema = content['application/json'].get('schema', {})
+                    return self.get_js_type(schema)
+
+        # Check for 204 No Content
+        if '204' in responses:
+            return 'void'
+
+        # Default to any
+        return 'any'
+
+    def resolve_ref(self, ref: str) -> Optional[Dict[str, Any]]:
+        """Resolve a $ref to its schema definition."""
+        if not ref.startswith('#/'):
+            return None
+
+        parts = ref[2:].split('/')
+        current = self.schema
+
+        for part in parts:
+            if isinstance(current, dict) and part in current:
+                current = current[part]
+            else:
+                return None
+
+        return current

django_cfg/modules/django_client/system/templates/api_client.js.j2

@@ -0,0 +1,87 @@
+import { BaseAPIClient } from '../base.mjs';
+
+/**
+ * {{ app_name.replace('_', ' ').title() }} API Client
+ * Auto-generated from OpenAPI schema
+ * @module {{ app_name }}
+ * @extends BaseAPIClient
+ */
+export class {{ class_name }} extends BaseAPIClient {
+    /**
+     * Initialize {{ app_name }} API client
+     * @param {string} [baseURL] - Optional base URL
+     */
+    constructor(baseURL) {
+        super(baseURL);
+    }
+
+{% for method in methods %}
+    /**
+     * {{ method.summary or method.name }}
+{%- if method.description %}
+     * {{ method.description }}
+{%- endif %}
+{%- for param in method.path_params %}
+     * @param {{ '{' }}{{ param.type }}{{ '}' }} {{ param.name }}{% if param.description %} - {{ param.description }}{% endif %}
+{%- endfor %}
+{%- if method.request_body %}
+     * @param {{ '{' }}{{ method.request_body.type }}{{ '}' }} data - Request body{% if method.request_body.description %} - {{ method.request_body.description }}{% endif %}
+{%- endif %}
+{%- if method.query_params %}
+     * @param {{ '{Object}' }} [params={}] - Query parameters
+{%- for param in method.query_params %}
+     * @param {{ '{' }}{{ param.type }}{{ '}' }} [params.{{ param.name }}]{% if param.description %} - {{ param.description }}{% endif %}
+{%- endfor %}
+{%- endif %}
+     * @returns {{ '{Promise<' }}{{ method.response_type }}{{ '>}' }} {{ 'Response data' if method.response_type != 'void' else 'No content' }}
+     */
+    async {{ method.name }}(
+{%- set params = [] %}
+{%- for param in method.path_params %}
+    {%- set _ = params.append(param.name) %}
+{%- endfor %}
+{%- if method.request_body %}
+    {%- set _ = params.append('data') %}
+{%- endif %}
+{%- if method.query_params %}
+    {%- set _ = params.append('params = {}') %}
+{%- endif %}
+{{- params | join(', ') -}}
+) {
+        const path = `{{ method.path }}`;
+{%- if method.http_method == 'GET' %}
+    {%- if method.query_params %}
+        return this.get(path, params);
+    {%- else %}
+        return this.get(path);
+    {%- endif %}
+{%- elif method.http_method == 'POST' %}
+    {%- if method.request_body %}
+        return this.post(path, data);
+    {%- else %}
+        return this.post(path, {});
+    {%- endif %}
+{%- elif method.http_method == 'PUT' %}
+    {%- if method.request_body %}
+        return this.put(path, data);
+    {%- else %}
+        return this.put(path, {});
+    {%- endif %}
+{%- elif method.http_method == 'PATCH' %}
+    {%- if method.request_body %}
+        return this.patch(path, data);
+    {%- else %}
+        return this.patch(path, {});
+    {%- endif %}
+{%- elif method.http_method == 'DELETE' %}
+        return this.delete(path);
+{%- endif %}
+    }
+{% endfor %}
+}
+
+// Default instance for convenience
+export const {{ instance_name }} = new {{ class_name }}();
+
+// Default export
+export default {{ class_name }};

django_cfg/modules/django_client/system/templates/app_index.js.j2

@@ -0,0 +1,13 @@
+/**
+ * {{ app_name.replace('_', ' ').title() }} API Module
+ * Re-exports the API client for convenient importing
+ * @module {{ app_name }}
+ */
+
+import { {{ class_name }}, {{ instance_name }} } from './client.mjs';
+
+// Re-export the class and instance
+export { {{ class_name }}, {{ instance_name }} };
+
+// Default export is the instance for convenience
+export default {{ instance_name }};

django_cfg/modules/django_client/system/templates/base_client.js.j2

@@ -0,0 +1,166 @@
+/**
+ * Base API Client for django-cfg
+ * Lightweight ES Module with JSDoc type annotations
+ * @module base
+ */
+
+/**
+ * Custom error class for API errors
+ * @class APIError
+ * @extends Error
+ */
+class APIError extends Error {
+    /**
+     * @param {string} message - Error message
+     * @param {number} status - HTTP status code
+     * @param {any} data - Additional error data
+     */
+    constructor(message, status, data) {
+        super(message);
+        this.name = 'APIError';
+        this.status = status;
+        this.data = data;
+    }
+}
+
+/**
+ * Get Django CSRF token from cookies
+ * @returns {string} CSRF token value
+ */
+function getCsrfToken() {
+    const cookie = document.cookie.split('; ')
+        .find(row => row.startsWith('csrftoken='));
+    return cookie ? cookie.split('=')[1] : '';
+}
+
+/**
+ * @typedef {Object} RequestOptions
+ * @property {string} [method='GET'] - HTTP method
+ * @property {Object} [headers={}] - Request headers
+ * @property {any} [body] - Request body
+ * @property {string} [credentials='same-origin'] - Credentials mode
+ */
+
+/**
+ * Base API client class with built-in Django CSRF support
+ * @class BaseAPIClient
+ */
+export class BaseAPIClient {
+    /**
+     * Initialize the API client
+     * @param {string} [baseURL=''] - Base URL for API requests (defaults to current origin)
+     */
+    constructor(baseURL = '') {
+        this.baseURL = baseURL || window.location.origin;
+    }
+
+    /**
+     * Make an API request
+     * @param {string} path - API endpoint path
+     * @param {RequestOptions} [options={}] - Request options
+     * @returns {Promise<any>} Response data
+     * @throws {APIError} When request fails
+     */
+    async request(path, options = {}) {
+        const url = `${this.baseURL}${path}`;
+
+        // Default headers with CSRF token
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-CSRFToken': getCsrfToken(),
+            ...options.headers
+        };
+
+        try {
+            const response = await fetch(url, {
+                ...options,
+                headers,
+                credentials: 'same-origin'
+            });
+
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({}));
+                throw new APIError(
+                    error.detail || `HTTP ${response.status}`,
+                    response.status,
+                    error
+                );
+            }
+
+            // Handle empty responses
+            if (response.status === 204) {
+                return null;
+            }
+
+            return await response.json();
+        } catch (error) {
+            if (error instanceof APIError) {
+                throw error;
+            }
+            throw new APIError(error.message, 0, null);
+        }
+    }
+
+    /**
+     * Make a GET request
+     * @param {string} path - API endpoint path
+     * @param {Object} [params={}] - Query parameters
+     * @returns {Promise<any>} Response data
+     */
+    async get(path, params = {}) {
+        const queryString = new URLSearchParams(params).toString();
+        const fullPath = queryString ? `${path}?${queryString}` : path;
+        return this.request(fullPath, { method: 'GET' });
+    }
+
+    /**
+     * Make a POST request
+     * @param {string} path - API endpoint path
+     * @param {any} [data={}] - Request body data
+     * @returns {Promise<any>} Response data
+     */
+    async post(path, data = {}) {
+        return this.request(path, {
+            method: 'POST',
+            body: JSON.stringify(data)
+        });
+    }
+
+    /**
+     * Make a PUT request
+     * @param {string} path - API endpoint path
+     * @param {any} [data={}] - Request body data
+     * @returns {Promise<any>} Response data
+     */
+    async put(path, data = {}) {
+        return this.request(path, {
+            method: 'PUT',
+            body: JSON.stringify(data)
+        });
+    }
+
+    /**
+     * Make a PATCH request
+     * @param {string} path - API endpoint path
+     * @param {any} [data={}] - Request body data
+     * @returns {Promise<any>} Response data
+     */
+    async patch(path, data = {}) {
+        return this.request(path, {
+            method: 'PATCH',
+            body: JSON.stringify(data)
+        });
+    }
+
+    /**
+     * Make a DELETE request
+     * @param {string} path - API endpoint path
+     * @returns {Promise<any>} Response data
+     */
+    async delete(path) {
+        return this.request(path, { method: 'DELETE' });
+    }
+}
+
+// Export the error class as well
+export { APIError };