django-cfg 1.4.119__py3-none-any.whl → 1.5.1__py3-none-any.whl

django_cfg/models/api/grpc/config.py

@@ -0,0 +1,364 @@
+"""
+gRPC Configuration Models
+
+Type-safe Pydantic v2 models for gRPC server, authentication, and proto generation.
+
+Example:
+    >>> from django_cfg.models.api.grpc import GRPCConfig
+    >>> config = GRPCConfig(
+    ...     enabled=True,
+    ...     server=GRPCServerConfig(port=50051),
+    ...     auth=GRPCAuthConfig(require_auth=True)
+    ... )
+"""
+
+import warnings
+from typing import Dict, List, Optional
+
+from pydantic import Field, field_validator, model_validator
+
+from django_cfg.models.base import BaseConfig
+
+
+class GRPCServerConfig(BaseConfig):
+    """
+    gRPC server configuration.
+
+    Configures the gRPC server including host, port, workers, compression,
+    message limits, and keepalive settings.
+
+    Example:
+        >>> config = GRPCServerConfig(
+        ...     host="0.0.0.0",
+        ...     port=50051,
+        ...     max_workers=10,
+        ...     compression="gzip"
+        ... )
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable gRPC server",
+    )
+
+    host: str = Field(
+        default="[::]",
+        description="Server bind address (IPv6 by default, use 0.0.0.0 for IPv4)",
+    )
+
+    port: int = Field(
+        default=50051,
+        description="Server port",
+        ge=1024,
+        le=65535,
+    )
+
+    max_workers: int = Field(
+        default=10,
+        description="ThreadPoolExecutor max workers",
+        ge=1,
+        le=1000,
+    )
+
+    enable_reflection: bool = Field(
+        default=False,
+        description="Enable server reflection for dynamic clients (grpcurl, etc.)",
+    )
+
+    enable_health_check: bool = Field(
+        default=True,
+        description="Enable gRPC health check service",
+    )
+
+    compression: Optional[str] = Field(
+        default=None,
+        description="Compression algorithm: 'gzip', 'deflate', or None",
+    )
+
+    max_send_message_length: int = Field(
+        default=4 * 1024 * 1024,  # 4 MB
+        description="Maximum outbound message size in bytes",
+        ge=1024,  # Min 1KB
+        le=100 * 1024 * 1024,  # Max 100MB
+    )
+
+    max_receive_message_length: int = Field(
+        default=4 * 1024 * 1024,  # 4 MB
+        description="Maximum inbound message size in bytes",
+        ge=1024,
+        le=100 * 1024 * 1024,
+    )
+
+    keepalive_time_ms: int = Field(
+        default=7200000,  # 2 hours
+        description="Keepalive ping interval in milliseconds",
+        ge=1000,  # Min 1 second
+    )
+
+    keepalive_timeout_ms: int = Field(
+        default=20000,  # 20 seconds
+        description="Keepalive ping timeout in milliseconds",
+        ge=1000,
+    )
+
+    interceptors: List[str] = Field(
+        default_factory=list,
+        description="Server interceptor import paths (e.g., 'myapp.interceptors.AuthInterceptor')",
+    )
+
+    @field_validator("compression")
+    @classmethod
+    def validate_compression(cls, v: Optional[str]) -> Optional[str]:
+        """Validate compression algorithm."""
+        if v and v not in ("gzip", "deflate"):
+            raise ValueError(
+                f"Invalid compression: {v}. Must be 'gzip', 'deflate', or None"
+            )
+        return v
+
+    @field_validator("host")
+    @classmethod
+    def validate_host(cls, v: str) -> str:
+        """Validate host format."""
+        if not v or not v.strip():
+            raise ValueError("Host cannot be empty")
+        return v.strip()
+
+
+class GRPCAuthConfig(BaseConfig):
+    """
+    gRPC authentication configuration.
+
+    Supports JWT authentication with configurable token handling.
+
+    Example:
+        >>> config = GRPCAuthConfig(
+        ...     enabled=True,
+        ...     require_auth=True,
+        ...     jwt_algorithm="HS256"
+        ... )
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable authentication",
+    )
+
+    require_auth: bool = Field(
+        default=True,
+        description="Require authentication for all services (except public_methods)",
+    )
+
+    token_header: str = Field(
+        default="authorization",
+        description="Metadata key for auth token",
+    )
+
+    token_prefix: str = Field(
+        default="Bearer",
+        description="Token prefix (e.g., 'Bearer' for JWT)",
+    )
+
+    jwt_secret_key: Optional[str] = Field(
+        default=None,
+        description="JWT secret key (defaults to Django SECRET_KEY if None)",
+    )
+
+    jwt_algorithm: str = Field(
+        default="HS256",
+        description="JWT signing algorithm",
+    )
+
+    jwt_verify_exp: bool = Field(
+        default=True,
+        description="Verify JWT expiration",
+    )
+
+    jwt_leeway: int = Field(
+        default=0,
+        description="JWT expiration leeway in seconds",
+        ge=0,
+    )
+
+    public_methods: List[str] = Field(
+        default_factory=lambda: [
+            "/grpc.health.v1.Health/Check",
+            "/grpc.health.v1.Health/Watch",
+        ],
+        description="RPC methods that don't require authentication",
+    )
+
+    @field_validator("jwt_algorithm")
+    @classmethod
+    def validate_jwt_algorithm(cls, v: str) -> str:
+        """Validate JWT algorithm."""
+        valid_algorithms = {
+            "HS256",
+            "HS384",
+            "HS512",
+            "RS256",
+            "RS384",
+            "RS512",
+            "ES256",
+            "ES384",
+            "ES512",
+        }
+        if v not in valid_algorithms:
+            raise ValueError(
+                f"Invalid JWT algorithm: {v}. "
+                f"Must be one of: {', '.join(sorted(valid_algorithms))}"
+            )
+        return v
+
+
+class GRPCProtoConfig(BaseConfig):
+    """
+    Proto file generation configuration.
+
+    Controls automatic proto file generation from Django models.
+
+    Example:
+        >>> config = GRPCProtoConfig(
+        ...     auto_generate=True,
+        ...     output_dir="protos",
+        ...     package_prefix="mycompany"
+        ... )
+    """
+
+    auto_generate: bool = Field(
+        default=True,
+        description="Auto-generate proto files from Django models",
+    )
+
+    output_dir: str = Field(
+        default="protos",
+        description="Proto files output directory (relative to BASE_DIR)",
+    )
+
+    package_prefix: str = Field(
+        default="",
+        description="Package prefix for all generated protos (e.g., 'mycompany')",
+    )
+
+    include_services: bool = Field(
+        default=True,
+        description="Include service definitions in generated protos",
+    )
+
+    field_naming: str = Field(
+        default="snake_case",
+        description="Proto field naming convention",
+    )
+
+    @field_validator("field_naming")
+    @classmethod
+    def validate_field_naming(cls, v: str) -> str:
+        """Validate field naming convention."""
+        if v not in ("snake_case", "camelCase"):
+            raise ValueError(
+                f"Invalid field_naming: {v}. Must be 'snake_case' or 'camelCase'"
+            )
+        return v
+
+    @field_validator("output_dir")
+    @classmethod
+    def validate_output_dir(cls, v: str) -> str:
+        """Validate output directory."""
+        if not v or not v.strip():
+            raise ValueError("output_dir cannot be empty")
+        # Remove leading/trailing slashes
+        return v.strip().strip("/")
+
+
+class GRPCConfig(BaseConfig):
+    """
+    Main gRPC configuration.
+
+    Combines server, authentication, and proto generation settings.
+
+    Example:
+        Basic setup:
+        >>> config = GRPCConfig(enabled=True)
+
+        Advanced setup:
+        >>> config = GRPCConfig(
+        ...     enabled=True,
+        ...     server=GRPCServerConfig(port=8080, max_workers=50),
+        ...     auth=GRPCAuthConfig(require_auth=True),
+        ...     auto_register_apps=["accounts", "support"]
+        ... )
+    """
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable gRPC integration",
+    )
+
+    server: GRPCServerConfig = Field(
+        default_factory=GRPCServerConfig,
+        description="Server configuration",
+    )
+
+    auth: GRPCAuthConfig = Field(
+        default_factory=GRPCAuthConfig,
+        description="Authentication configuration",
+    )
+
+    proto: GRPCProtoConfig = Field(
+        default_factory=GRPCProtoConfig,
+        description="Proto generation configuration",
+    )
+
+    handlers_hook: str = Field(
+        default="{ROOT_URLCONF}.grpc_handlers",
+        description="Import path to grpc_handlers function",
+    )
+
+    auto_register_apps: bool = Field(
+        default=True,
+        description="Auto-register gRPC services for Django-CFG apps",
+    )
+
+    enabled_apps: List[str] = Field(
+        default_factory=lambda: [
+            "accounts",
+            "support",
+            "knowbase",
+            "agents",
+            "payments",
+            "leads",
+        ],
+        description="Django-CFG apps to expose via gRPC (if auto_register_apps=True)",
+    )
+
+    custom_services: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Custom service import paths: {service_name: 'path.to.Service'}",
+    )
+
+    @model_validator(mode="after")
+    def validate_grpc_config(self) -> "GRPCConfig":
+        """Cross-field validation."""
+        # Check dependencies if enabled
+        if self.enabled:
+            from django_cfg.config import require_feature
+
+            require_feature("grpc")
+
+            # Validate server enabled
+            if not self.server.enabled:
+                raise ValueError(
+                    "Cannot enable gRPC with server disabled. "
+                    "Set server.enabled=True or grpc.enabled=False"
+                )
+
+        # Warn if auto_register but no apps
+        if self.auto_register_apps and not self.enabled_apps:
+            warnings.warn(
+                "auto_register_apps is True but enabled_apps is empty. "
+                "No services will be auto-registered.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        return self

django_cfg/modules/base.py

@@ -206,6 +206,21 @@ class BaseCfgModule(ABC):
 
         return False
 
+    def is_grpc_enabled(self) -> bool:
+        """
+        Check if django-cfg gRPC is enabled.
+
+        Returns:
+            True if gRPC is enabled, False otherwise
+        """
+        grpc_config = self._get_config_key('grpc', None)
+
+        # Check if grpc config exists and is enabled
+        if grpc_config and hasattr(grpc_config, 'enabled'):
+            return grpc_config.enabled
+
+        return False
+
 
 # Export the base class
 __all__ = [

django_cfg/modules/django_admin/__init__.py

@@ -57,6 +57,7 @@ from .config import (
     ImageField,
     MarkdownField,
     ResourceConfig,
+    ShortUUIDField,
     TextField,
     UserField,
 )
@@ -116,6 +117,7 @@ __all__ = [
     "DateTimeField",
     "ImageField",
     "MarkdownField",
+    "ShortUUIDField",
     "TextField",
     "UserField",
     # Advanced

django_cfg/modules/django_admin/base/pydantic_admin.py

@@ -523,7 +523,7 @@ class PydanticAdminMixin:
 
                 # Add Mermaid resources if plugins enabled
                 if doc_config.enable_plugins:
-                    from django_cfg.modules.django_admin.utils.mermaid_plugin import get_mermaid_resources
+                    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)
@@ -548,7 +548,7 @@ class PydanticAdminMixin:
 
                 # Add Mermaid resources if plugins enabled
                 if doc_config.enable_plugins:
-                    from django_cfg.modules.django_admin.utils.mermaid_plugin import get_mermaid_resources
+                    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)

django_cfg/modules/django_admin/config/__init__.py

@@ -14,6 +14,7 @@ from .field_config import (
     DateTimeField,
     ImageField,
     MarkdownField,
+    ShortUUIDField,
     TextField,
     UserField,
 )
@@ -36,6 +37,7 @@ __all__ = [
     "DateTimeField",
     "ImageField",
     "MarkdownField",
+    "ShortUUIDField",
     "TextField",
     "UserField",
 ]

django_cfg/modules/django_admin/config/field_config.py

@@ -341,3 +341,27 @@ class MarkdownField(FieldConfig):
             config['header_icon'] = self.header_icon
 
         return config
+
+
+class ShortUUIDField(FieldConfig):
+    """
+    Short UUID widget configuration for displaying shortened UUIDs.
+
+    Examples:
+        ShortUUIDField(name="id", length=8)
+        ShortUUIDField(name="uuid", length=12, copy_on_click=True)
+    """
+
+    ui_widget: Literal["short_uuid"] = "short_uuid"
+
+    length: int = Field(8, description="Number of characters to display from UUID")
+    copy_on_click: bool = Field(True, description="Enable click-to-copy functionality")
+    show_full_on_hover: bool = Field(True, description="Show full UUID in tooltip on hover")
+
+    def get_widget_config(self) -> Dict[str, Any]:
+        """Extract short UUID widget configuration."""
+        config = super().get_widget_config()
+        config['length'] = self.length
+        config['copy_on_click'] = self.copy_on_click
+        config['show_full_on_hover'] = self.show_full_on_hover
+        return config

django_cfg/modules/django_admin/utils/__init__.py

@@ -1,17 +1,46 @@
 """
-Display and badge utilities for Django Admin.
+Display and utility modules for Django Admin.
+
+Refactored structure with logical organization:
+- badges/ - Status badges, progress badges, counter badges
+- displays/ - User displays, money displays, datetime displays
+- html/ - HTML building utilities (organized by functionality)
+- markdown/ - Markdown rendering with Mermaid support
+- decorators.py - Admin field decorators
+- html_builder.py - Backward-compatible facade for self.html.* API
 """
 
+# Badges
 from .badges import CounterBadge, ProgressBadge, StatusBadge
+
+# Decorators
 from .decorators import (
     annotated_field,
     badge_field,
     computed_field,
     currency_field,
 )
+
+# Displays
 from .displays import DateTimeDisplay, MoneyDisplay, UserDisplay
+
+# HTML Builders (organized by functionality)
+from .html import (
+    BadgeElements,
+    BaseElements,
+    CodeElements,
+    CompositionElements,
+    FormattingElements,
+    KeyValueElements,
+    MarkdownIntegration,
+    ProgressElements,
+)
+
+# HtmlBuilder - Backward-compatible facade
 from .html_builder import HtmlBuilder
-from .markdown_renderer import MarkdownRenderer
+
+# Markdown
+from .markdown import MarkdownRenderer
 
 __all__ = [
     # Display utilities
@@ -22,7 +51,16 @@ __all__ = [
     "StatusBadge",
     "ProgressBadge",
     "CounterBadge",
-    # HTML Builder
+    # HTML Builders (modular)
+    "BaseElements",
+    "CodeElements",
+    "BadgeElements",
+    "CompositionElements",
+    "FormattingElements",
+    "KeyValueElements",
+    "ProgressElements",
+    "MarkdownIntegration",
+    # HTML Builder (backward-compatible facade)
     "HtmlBuilder",
     # Markdown Renderer
     "MarkdownRenderer",

django_cfg/modules/django_admin/utils/badges/__init__.py

@@ -0,0 +1,13 @@
+"""
+Badge utilities for Django Admin.
+
+Provides StatusBadge, ProgressBadge, and CounterBadge classes.
+"""
+
+from .status_badges import CounterBadge, ProgressBadge, StatusBadge
+
+__all__ = [
+    "StatusBadge",
+    "ProgressBadge",
+    "CounterBadge",
+]

django_cfg/modules/django_admin/utils/{badges.py → badges/status_badges.py}

@@ -9,9 +9,9 @@ from django.contrib.humanize.templatetags.humanize import intcomma
 from django.utils.html import escape, format_html
 from django.utils.safestring import SafeString
 
-from ..icons import Icons
-from ..models.badge_models import StatusBadgeConfig
-from ..models.base import BadgeVariant
+from ...icons import Icons
+from ...models.badge_models import StatusBadgeConfig
+from ...models.base import BadgeVariant
 
 logger = logging.getLogger(__name__)
 

django_cfg/modules/django_admin/utils/displays/__init__.py

@@ -0,0 +1,13 @@
+"""
+Display utilities for Django Admin.
+
+Provides UserDisplay, MoneyDisplay, and DateTimeDisplay classes.
+"""
+
+from .data_displays import DateTimeDisplay, MoneyDisplay, UserDisplay
+
+__all__ = [
+    "UserDisplay",
+    "MoneyDisplay",
+    "DateTimeDisplay",
+]

django_cfg/modules/django_admin/utils/{displays.py → displays/data_displays.py}

@@ -12,8 +12,8 @@ from django.utils import timezone
 from django.utils.html import escape, format_html
 from django.utils.safestring import SafeString
 
-from ..icons import Icons
-from ..models.display_models import DateTimeDisplayConfig, MoneyDisplayConfig, UserDisplayConfig
+from ...icons import Icons
+from ...models.display_models import DateTimeDisplayConfig, MoneyDisplayConfig, UserDisplayConfig
 
 logger = logging.getLogger(__name__)
 

django_cfg/modules/django_admin/utils/html/__init__.py

@@ -0,0 +1,26 @@
+"""
+HTML builder module - organized and modular.
+
+Exports all HTML building classes for easy access.
+"""
+
+from .badges import BadgeElements
+from .base import BaseElements
+from .code import CodeElements
+from .composition import CompositionElements
+from .formatting import FormattingElements
+from .keyvalue import KeyValueElements
+from .markdown_integration import MarkdownIntegration
+from .progress import ProgressElements
+
+__all__ = [
+    # Core elements
+    "BaseElements",
+    "CodeElements",
+    "BadgeElements",
+    "CompositionElements",
+    "FormattingElements",
+    "KeyValueElements",
+    "ProgressElements",
+    "MarkdownIntegration",
+]

django_cfg/modules/django_admin/utils/html/badges.py

@@ -0,0 +1,47 @@
+"""
+Badge elements for Django Admin.
+
+Provides badge rendering with variants and icons.
+"""
+
+from typing import Optional
+
+from django.utils.html import escape, format_html
+from django.utils.safestring import SafeString
+
+
+class BadgeElements:
+    """Badge display elements."""
+
+    @staticmethod
+    def badge(text: any, variant: str = "primary", icon: Optional[str] = None) -> SafeString:
+        """
+        Render badge with optional icon.
+
+        Args:
+            text: Badge text
+            variant: primary, success, warning, danger, info, secondary
+            icon: Optional Material Icon
+
+        Usage:
+            html.badge("Active", variant="success", icon=Icons.CHECK_CIRCLE)
+        """
+        variant_classes = {
+            'success': 'bg-success-100 text-success-800 dark:bg-success-900 dark:text-success-200',
+            'warning': 'bg-warning-100 text-warning-800 dark:bg-warning-900 dark:text-warning-200',
+            'danger': 'bg-danger-100 text-danger-800 dark:bg-danger-900 dark:text-danger-200',
+            'info': 'bg-info-100 text-info-800 dark:bg-info-900 dark:text-info-200',
+            'primary': 'bg-primary-100 text-primary-800 dark:bg-primary-900 dark:text-primary-200',
+            'secondary': 'bg-base-100 text-font-default-light dark:bg-base-800 dark:text-font-default-dark',
+        }
+
+        css_classes = variant_classes.get(variant, variant_classes['primary'])
+
+        icon_html = ""
+        if icon:
+            icon_html = format_html('<span class="material-symbols-outlined text-xs mr-1">{}</span>', icon)
+
+        return format_html(
+            '<span class="inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium {}">{}{}</span>',
+            css_classes, icon_html, escape(str(text))
+        )