django-cfg 1.4.46__py3-none-any.whl → 1.5.181__py3-none-any.whl

django_cfg/modules/django_admin/base/pydantic_admin/mixin.py

@@ -0,0 +1,276 @@
+"""
+PydanticAdminMixin - Core mixin providing Pydantic config processing.
+
+This is the main orchestrator that coordinates all the decomposed modules.
+"""
+
+import logging
+from typing import Any
+
+from ...config import AdminConfig
+from ...utils import HtmlBuilder
+from .display_methods import (
+    apply_replacements_to_fieldsets,
+    create_imagefield_display_methods,
+    create_jsonfield_display_methods,
+    create_markdownfield_display_methods,
+    highlight_json,
+)
+from .list_display import build_list_display, build_list_display_links
+from .actions import register_actions
+from .import_export import generate_resource_class
+from .views import ViewMixin
+
+logger = logging.getLogger(__name__)
+
+
+class PydanticAdminMixin(ViewMixin):
+    """
+    Mixin providing Pydantic config processing for ModelAdmin.
+
+    Use this with your preferred ModelAdmin base class.
+
+    Inherits from ViewMixin which provides:
+    - changelist_view, changeform_view overrides
+    - get_fieldsets, get_queryset overrides
+    - formfield_for_dbfield override
+    """
+
+    config: AdminConfig
+    _config_processed = False
+
+    @property
+    def html(self):
+        """Universal HTML builder for display methods."""
+        return HtmlBuilder
+
+    @staticmethod
+    def _highlight_json(json_obj: Any) -> str:
+        """
+        Apply syntax highlighting to JSON using Pygments (Unfold style).
+
+        Returns HTML with Pygments syntax highlighting for light and dark themes.
+        """
+        return highlight_json(json_obj)
+
+    def __init__(self, *args, **kwargs):
+        """Process config on first instantiation."""
+        # Process config once when first admin instance is created
+        if hasattr(self.__class__, '_config_needs_processing') and self.__class__._config_needs_processing:
+            self.__class__._build_from_config()
+            self.__class__._config_needs_processing = False
+            self.__class__._config_processed = True
+
+        super().__init__(*args, **kwargs)
+
+    def __init_subclass__(cls, **kwargs):
+        """Mark class as needing config processing, but defer actual processing."""
+        super().__init_subclass__(**kwargs)
+
+        if hasattr(cls, 'config') and isinstance(cls.config, AdminConfig):
+            cls._config_needs_processing = True
+
+    @classmethod
+    def _build_from_config(cls):
+        """Convert AdminConfig to ModelAdmin attributes."""
+        config = cls.config
+
+        # Basic list display
+        cls.list_display = build_list_display(cls, config)
+        cls.list_filter = config.list_filter
+        cls.search_fields = config.search_fields
+        cls.ordering = config.ordering if config.ordering else []
+
+        # Auto-create display methods for readonly JSONField fields
+        # This modifies readonly_fields to use custom display methods and returns mapping
+        cls.readonly_fields, jsonfield_replacements = create_jsonfield_display_methods(cls, config)
+
+        # Auto-create display methods for readonly ImageField/FileField fields
+        cls.readonly_fields, imagefield_replacements, has_image_preview = create_imagefield_display_methods(
+            cls, cls.readonly_fields, config
+        )
+        cls._has_image_preview = has_image_preview
+
+        # Auto-create display methods for MarkdownField configs
+        cls.readonly_fields, markdownfield_replacements = create_markdownfield_display_methods(
+            cls, cls.readonly_fields, config
+        )
+
+        # List display options
+        # Rename list_display_links to match display method names (field -> field_display)
+        if config.list_display_links:
+            cls.list_display_links = build_list_display_links(config)
+        else:
+            cls.list_display_links = getattr(cls, 'list_display_links', None)
+
+        # Pagination
+        cls.list_per_page = config.list_per_page
+        cls.list_max_show_all = config.list_max_show_all
+
+        # Form options
+        cls.autocomplete_fields = config.autocomplete_fields or getattr(cls, 'autocomplete_fields', [])
+        cls.raw_id_fields = config.raw_id_fields or getattr(cls, 'raw_id_fields', [])
+        cls.prepopulated_fields = config.prepopulated_fields or getattr(cls, 'prepopulated_fields', {})
+        cls.formfield_overrides = config.formfield_overrides or getattr(cls, 'formfield_overrides', {})
+
+        # Inlines
+        cls.inlines = config.inlines or getattr(cls, 'inlines', [])
+
+        # Combine field replacements for fieldsets
+        fieldset_replacements = {
+            **jsonfield_replacements,
+            **imagefield_replacements,
+            **markdownfield_replacements,
+        }
+
+        # Fieldsets - apply field replacements
+        if config.fieldsets:
+            cls.fieldsets = config.to_django_fieldsets()
+            # Apply replacements to fieldsets
+            if fieldset_replacements:
+                cls.fieldsets = apply_replacements_to_fieldsets(cls.fieldsets, fieldset_replacements)
+        # Also convert fieldsets if they're defined directly in the class as FieldsetConfig objects
+        elif hasattr(cls, 'fieldsets') and isinstance(cls.fieldsets, list):
+            from ...config import FieldsetConfig
+            if cls.fieldsets and isinstance(cls.fieldsets[0], FieldsetConfig):
+                cls.fieldsets = tuple(fs.to_django_fieldset() for fs in cls.fieldsets)
+                # Apply replacements to fieldsets
+                if fieldset_replacements:
+                    cls.fieldsets = apply_replacements_to_fieldsets(cls.fieldsets, fieldset_replacements)
+
+        # Collect widget configurations from AdminConfig.widgets for custom JSON widget configs
+        cls._field_widget_configs = {}
+        if config.widgets:
+            for widget_config in config.widgets:
+                if hasattr(widget_config, 'field') and hasattr(widget_config, 'to_widget_kwargs'):
+                    field_name = widget_config.field
+                    cls._field_widget_configs[field_name] = widget_config.to_widget_kwargs()
+                    logger.debug(f"Registered widget config for field '{field_name}' from AdminConfig.widgets")
+                else:
+                    logger.warning(f"Invalid widget config in AdminConfig.widgets: {widget_config}")
+
+        # Actions
+        if config.actions:
+            register_actions(cls, config)
+
+        # Extra options
+        if config.date_hierarchy:
+            cls.date_hierarchy = config.date_hierarchy
+        cls.save_on_top = config.save_on_top
+        cls.save_as = config.save_as
+        cls.preserve_filters = config.preserve_filters
+
+        # Import/Export configuration
+        if config.import_export_enabled:
+            # Set import/export template
+            cls.change_list_template = 'admin/import_export/change_list_import_export.html'
+
+            if config.resource_class:
+                # Use provided resource class
+                cls.resource_class = config.resource_class
+            else:
+                # Auto-generate resource class
+                cls.resource_class = generate_resource_class(config)
+
+            # Override changelist_view to add import/export context
+            original_changelist_view = cls.changelist_view
+
+            def changelist_view_with_import_export(self, request, extra_context=None):
+                if extra_context is None:
+                    extra_context = {}
+                extra_context['has_import_permission'] = self.has_import_permission(request)
+                extra_context['has_export_permission'] = self.has_export_permission(request)
+                return original_changelist_view(self, request, extra_context)
+
+            cls.changelist_view = changelist_view_with_import_export
+
+        # Documentation configuration
+        if config.documentation:
+            cls._setup_documentation(config)
+
+        # Image preview modal (include once if image_preview widget is used)
+        cls._setup_image_preview_modal(config)
+
+    @classmethod
+    def _setup_documentation(cls, config: AdminConfig):
+        """
+        Setup documentation using unfold's template hooks.
+
+        Uses unfold's built-in hooks:
+        - list_before_template: Shows documentation before changelist table
+        - change_form_before_template: Shows documentation before fieldsets
+        """
+        doc_config = config.documentation
+
+        # Set unfold template hooks
+        if doc_config.show_on_changelist:
+            cls.list_before_template = "django_admin/documentation_block.html"
+
+        if doc_config.show_on_changeform:
+            cls.change_form_before_template = "django_admin/documentation_block.html"
+
+        # Store documentation config for access in views
+        cls.documentation_config = doc_config
+
+    @classmethod
+    def _setup_image_preview_modal(cls, config: AdminConfig):
+        """
+        Setup global image preview modal if image_preview widget is used.
+
+        Uses unfold's template hooks to include modal once per page:
+        - list_after_template: for changelist page
+        - change_form_after_template: for change form page
+        """
+        # Check if any display_fields use image_preview widget
+        has_image_preview = getattr(cls, '_has_image_preview', False)
+
+        if not has_image_preview and config.display_fields:
+            for field_config in config.display_fields:
+                if hasattr(field_config, 'ui_widget') and field_config.ui_widget == 'image_preview':
+                    has_image_preview = True
+                    break
+
+        if has_image_preview:
+            cls.list_after_template = "django_admin/widgets/image_preview_modal.html"
+            cls.change_form_after_template = "django_admin/widgets/image_preview_modal.html"
+
+    # Legacy method aliases for backward compatibility
+    @classmethod
+    def _create_jsonfield_display_methods(cls, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return create_jsonfield_display_methods(cls, config)
+
+    @classmethod
+    def _create_imagefield_display_methods(cls, readonly_fields: list, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return create_imagefield_display_methods(cls, readonly_fields, config)
+
+    @classmethod
+    def _create_markdownfield_display_methods(cls, readonly_fields: list, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return create_markdownfield_display_methods(cls, readonly_fields, config)
+
+    @classmethod
+    def _apply_jsonfield_replacements_to_fieldsets(cls, fieldsets, replacements):
+        """Legacy alias for backward compatibility."""
+        return apply_replacements_to_fieldsets(fieldsets, replacements)
+
+    @classmethod
+    def _generate_resource_class(cls, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return generate_resource_class(config)
+
+    @classmethod
+    def _build_list_display(cls, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return build_list_display(cls, config)
+
+    @classmethod
+    def _build_list_display_links(cls, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return build_list_display_links(config)
+
+    @classmethod
+    def _register_actions(cls, config: AdminConfig):
+        """Legacy alias for backward compatibility."""
+        return register_actions(cls, config)

django_cfg/modules/django_admin/base/pydantic_admin/views.py

@@ -0,0 +1,285 @@
+"""
+View overrides for admin.
+
+Provides changelist_view, changeform_view, get_fieldsets, and formfield_for_dbfield.
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from django.utils.safestring import mark_safe
+
+logger = logging.getLogger(__name__)
+
+
+class ViewMixin:
+    """
+    Mixin providing view-related overrides for ModelAdmin.
+
+    Includes:
+    - changelist_view with documentation context
+    - changeform_view with documentation context
+    - get_fieldsets for filtering non-editable fields on add form
+    - formfield_for_dbfield for JSON and encrypted field widgets
+    """
+
+    def _get_app_path(self) -> Optional[Path]:
+        """
+        Detect the app path for relative file resolution.
+
+        Returns:
+            Path to the app directory or None
+        """
+        if not self.model:
+            return None
+
+        try:
+            # Get app label from model
+            app_label = self.model._meta.app_label
+
+            # Try to get app config
+            from django.apps import apps
+            app_config = apps.get_app_config(app_label)
+
+            if app_config and hasattr(app_config, 'path'):
+                return Path(app_config.path)
+        except Exception as e:
+            logger.warning(f"Could not detect app path for {self.model}: {e}")
+
+        return None
+
+    def get_queryset(self, request):
+        """Apply select_related, prefetch_related, and annotations from config."""
+        qs = super().get_queryset(request)
+
+        # Auto-apply optimizations from config
+        if self.config.select_related:
+            qs = qs.select_related(*self.config.select_related)
+
+        if self.config.prefetch_related:
+            qs = qs.prefetch_related(*self.config.prefetch_related)
+
+        # Auto-apply annotations from config
+        if self.config.annotations:
+            qs = qs.annotate(**self.config.annotations)
+
+        return qs
+
+    def get_fieldsets(self, request, obj=None):
+        """
+        Return fieldsets, filtering out non-editable fields from add form.
+
+        For add form (obj=None), we exclude fields that are:
+        - auto_now_add=True (created_at, etc)
+        - auto_now=True (updated_at, etc)
+        - auto-generated (id, uuid, etc)
+        - methods (not actual model fields)
+
+        For change form (obj exists), we show all fieldsets as-is.
+        """
+        fieldsets = super().get_fieldsets(request, obj)
+
+        # For change form, return fieldsets as-is (readonly fields will be shown)
+        if obj is not None:
+            return fieldsets
+
+        # For add form, filter out non-editable fields
+        if not fieldsets:
+            return fieldsets
+
+        # Get all actual model field names
+        model_field_names = set()
+        for field in self.model._meta.get_fields():
+            model_field_names.add(field.name)
+
+        # Get non-editable field names
+        non_editable_fields = set()
+        for field in self.model._meta.get_fields():
+            if hasattr(field, 'editable') and not field.editable:
+                non_editable_fields.add(field.name)
+            # Also check for auto_now and auto_now_add
+            if hasattr(field, 'auto_now') and field.auto_now:
+                non_editable_fields.add(field.name)
+            if hasattr(field, 'auto_now_add') and field.auto_now_add:
+                non_editable_fields.add(field.name)
+
+        # Filter fieldsets
+        filtered_fieldsets = []
+        for name, options in fieldsets:
+            if 'fields' in options:
+                # Filter out non-editable fields and non-model fields from this fieldset
+                filtered_fields = [
+                    f for f in options['fields']
+                    if f in model_field_names and f not in non_editable_fields
+                ]
+
+                # Only include fieldset if it has remaining fields
+                if filtered_fields:
+                    filtered_options = options.copy()
+                    filtered_options['fields'] = tuple(filtered_fields)
+                    filtered_fieldsets.append((name, filtered_options))
+            else:
+                # Keep fieldsets without 'fields' key as-is
+                filtered_fieldsets.append((name, options))
+
+        return tuple(filtered_fieldsets)
+
+    def changelist_view(self, request, extra_context=None):
+        """Override to add documentation context to changelist."""
+        if extra_context is None:
+            extra_context = {}
+
+        # Add documentation context if configured
+        if hasattr(self, 'documentation_config') and self.documentation_config:
+            doc_config = self.documentation_config
+            app_path = self._get_app_path()
+
+            if doc_config.show_on_changelist:
+                extra_context['documentation_config'] = doc_config
+                extra_context['documentation_sections'] = doc_config.get_sections(app_path)
+
+                # Add tree structure for modal view
+                import json
+                tree_structure = doc_config.get_tree_structure(app_path)
+                extra_context['documentation_tree'] = mark_safe(json.dumps(tree_structure))
+                extra_context['documentation_sections_count'] = len(doc_config.get_sections(app_path))
+
+                # Add management commands if enabled
+                if doc_config.show_management_commands:
+                    extra_context['management_commands'] = doc_config._discover_management_commands(app_path)
+
+                # Add Mermaid resources if plugins enabled
+                if doc_config.enable_plugins:
+                    from django_cfg.modules.django_admin.utils.markdown.mermaid_plugin import get_mermaid_resources
+                    extra_context['mermaid_resources'] = get_mermaid_resources()
+
+        return super().changelist_view(request, extra_context)
+
+    def changeform_view(self, request, object_id=None, form_url='', extra_context=None):
+        """Override to add documentation context to changeform."""
+        if extra_context is None:
+            extra_context = {}
+
+        # Store object in request for formfield_for_dbfield (MoneyFieldAdminMixin)
+        if object_id:
+            try:
+                request._editing_obj = self.get_object(request, object_id)
+            except Exception:
+                pass
+
+        # Add documentation context if configured
+        if hasattr(self, 'documentation_config') and self.documentation_config:
+            doc_config = self.documentation_config
+            app_path = self._get_app_path()
+
+            if doc_config.show_on_changeform:
+                extra_context['documentation_config'] = doc_config
+                extra_context['documentation_sections'] = doc_config.get_sections(app_path)
+
+                # Add tree structure for modal view
+                import json
+                tree_structure = doc_config.get_tree_structure(app_path)
+                extra_context['documentation_tree'] = mark_safe(json.dumps(tree_structure))
+                extra_context['documentation_sections_count'] = len(doc_config.get_sections(app_path))
+
+                # Add management commands if enabled
+                if doc_config.show_management_commands:
+                    extra_context['management_commands'] = doc_config._discover_management_commands(app_path)
+
+                # Add Mermaid resources if plugins enabled
+                if doc_config.enable_plugins:
+                    from django_cfg.modules.django_admin.utils.markdown.mermaid_plugin import get_mermaid_resources
+                    extra_context['mermaid_resources'] = get_mermaid_resources()
+
+        return super().changeform_view(request, object_id, form_url, extra_context)
+
+    def formfield_for_dbfield(self, db_field, request, **kwargs):
+        """
+        Override form field for specific database field types.
+
+        Automatically detects and customizes:
+        - JSON fields (applies django-json-widget for editable fields only)
+        - Encrypted fields from django-crypto-fields
+
+        Note: MoneyField is handled by MoneyFieldAdminMixin from django_currency module.
+        """
+        field_class_name = db_field.__class__.__name__
+
+        # Auto-apply JSONEditorWidget for editable JSON fields (not readonly)
+        if field_class_name == 'JSONField':
+            # Check if field is editable (not in readonly_fields)
+            is_readonly = db_field.name in self.readonly_fields
+
+            # Only apply for editable fields
+            if not is_readonly:
+                try:
+                    # Use our custom JSONEditorWidget with Unfold theme support
+                    from ...widgets import JSONEditorWidget
+
+                    # Get field-specific config from AdminConfig.widgets
+                    field_widget_config = getattr(self.__class__, '_field_widget_configs', {}).get(db_field.name, {})
+
+                    # Default widget settings with Unfold theme support
+                    widget_kwargs = {
+                        'mode': 'code',
+                        'height': '400px',
+                        'options': {
+                            'modes': ['code', 'tree', 'view'],
+                            # Unfold dark theme colors
+                            'mainMenuBar': True,
+                            'navigationBar': False,
+                        }
+                    }
+
+                    # Override with field-specific config
+                    if field_widget_config:
+                        widget_kwargs.update(field_widget_config)
+                        logger.debug(f"Applied custom JSONWidget config for '{db_field.name}': {field_widget_config}")
+
+                    # Apply JSONEditorWidget (overrides Unfold's UnfoldAdminTextareaWidget)
+                    kwargs['widget'] = JSONEditorWidget(**widget_kwargs)
+                    logger.debug(f"Auto-applied JSONEditorWidget to editable field '{db_field.name}'")
+                except ImportError:
+                    logger.warning("django-json-widget not available, using default textarea")
+
+        # Check if this is an EncryptedTextField or EncryptedCharField
+        if 'Encrypted' in field_class_name and ('TextField' in field_class_name or 'CharField' in field_class_name):
+            from django import forms
+            from ...widgets import EncryptedFieldWidget, EncryptedPasswordWidget
+
+            # Determine placeholder based on field name
+            placeholder = "Enter value"
+            if 'key' in db_field.name.lower():
+                placeholder = "Enter API Key"
+            elif 'secret' in db_field.name.lower():
+                placeholder = "Enter API Secret"
+            elif 'passphrase' in db_field.name.lower():
+                placeholder = "Enter Passphrase (if required)"
+
+            # Widget attributes
+            widget_attrs = {
+                'placeholder': placeholder,
+            }
+
+            # Decide widget based on config
+            show_plain_text = getattr(self.config, 'show_encrypted_fields_as_plain_text', False)
+
+            if show_plain_text:
+                # Show as plain text with copy button
+                widget = EncryptedFieldWidget(attrs=widget_attrs, show_copy_button=True)
+            else:
+                # Show as password (masked) with copy button
+                # render_value=True shows masked value (••••••) after save
+                widget = EncryptedPasswordWidget(attrs=widget_attrs, render_value=True, show_copy_button=True)
+
+            # Return CharField with appropriate widget
+            return forms.CharField(
+                widget=widget,
+                required=not db_field.blank and not db_field.null,
+                help_text=db_field.help_text or "This field is encrypted at rest",
+                label=db_field.verbose_name if hasattr(db_field, 'verbose_name') else db_field.name.replace('_', ' ').title()
+            )
+
+        # Fall back to default Django behavior
+        return super().formfield_for_dbfield(db_field, request, **kwargs)

django_cfg/modules/django_admin/config/__init__.py

@@ -4,27 +4,66 @@ Configuration models for declarative Django Admin.
 
 from .action_config import ActionConfig
 from .admin_config import AdminConfig
+from .background_task_config import BackgroundTaskConfig
+from .documentation_config import DocumentationConfig, DocumentationSection
 from .field_config import (
-    FieldConfig,
+    AvatarField,
     BadgeField,
+    BadgeRule,
     BooleanField,
+    CounterBadgeField,
     CurrencyField,
     DateTimeField,
+    DecimalField,
+    FieldConfig,
+    ForeignKeyField,
+    ImageField,
+    ImagePreviewField,
+    LinkField,
+    MarkdownField,
+    MoneyFieldDisplay,
+    ShortUUIDField,
+    StatusBadgesField,
     TextField,
     UserField,
+    VideoField,
 )
 from .fieldset_config import FieldsetConfig
+from .resource_config import ResourceConfig
+from .widget_config import ImagePreviewWidgetConfig, JSONWidgetConfig, TextWidgetConfig, WidgetConfig
 
 __all__ = [
     "AdminConfig",
     "FieldConfig",
     "FieldsetConfig",
     "ActionConfig",
-    # Specialized Field Types
+    "ResourceConfig",
+    "BackgroundTaskConfig",
+    "DocumentationConfig",
+    "DocumentationSection",
+    # Specialized Field Types (for display_fields)
+    "AvatarField",
     "BadgeField",
+    "BadgeRule",
     "BooleanField",
+    "CounterBadgeField",
     "CurrencyField",
     "DateTimeField",
+    "DecimalField",
+    "ForeignKeyField",
+    "ImageField",
+    "ImagePreviewField",
+    "LinkField",
+    "MarkdownField",
+    "MoneyFieldDisplay",
+    "ShortUUIDField",
+    "StatusBadgesField",
     "TextField",
     "UserField",
+    "VideoField",
+    # Widget Configs (for AdminConfig.widgets - form fields)
+    "WidgetConfig",
+    "JSONWidgetConfig",
+    "TextWidgetConfig",
+    "ImagePreviewWidgetConfig",
 ]

django_cfg/modules/django_admin/config/action_config.py

@@ -2,7 +2,7 @@
 Action configuration for declarative admin.
 """
 
-from typing import Callable, List, Optional, Union
+from typing import Callable, List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -12,17 +12,31 @@ class ActionConfig(BaseModel):
     Admin action configuration.
 
     Defines custom actions for admin list view.
+
+    Action Types:
+    - bulk: Traditional bulk actions (require selected items in queryset)
+    - changelist: Buttons above the listing (no selection required)
+
     Handler can be either:
     - String: Python path to action handler function (e.g., "myapp.actions.my_action")
     - Callable: Direct reference to action function (e.g., my_action)
+
+    Handler Signatures:
+    - Bulk actions: handler(modeladmin, request, queryset)
+    - Changelist actions: handler(modeladmin, request)
     """
 
     model_config = ConfigDict(validate_assignment=True, extra="forbid", arbitrary_types_allowed=True)
 
     name: str = Field(..., description="Action function name")
     description: str = Field(..., description="Action description shown in UI")
-    variant: str = Field("default", description="Button variant: default, success, warning, danger, primary")
+    action_type: Literal["bulk", "changelist"] = Field(
+        "bulk",
+        description="Type of action: 'bulk' (requires selection) or 'changelist' (button above listing)"
+    )
+    variant: str = Field("default", description="Button variant: default, success, warning, danger, primary, info")
     icon: Optional[str] = Field(None, description="Material icon name")
+    url_path: Optional[str] = Field(None, description="Custom URL path for changelist actions (auto-generated if not provided)")
     confirmation: bool = Field(False, description="Require confirmation before execution")
     handler: Union[str, Callable] = Field(..., description="Python path to action handler function or callable")
     permissions: List[str] = Field(default_factory=list, description="Required permissions")