django-cfg 1.4.9__py3-none-any.whl → 1.4.11__py3-none-any.whl

django_cfg/modules/django_client/core/groups/__init__.py

@@ -0,0 +1,13 @@
+"""
+Application Grouping Module.
+
+Smart grouping of Django apps into separate OpenAPI schemas.
+"""
+
+from .manager import GroupManager
+from .detector import GroupDetector
+
+__all__ = [
+    "GroupManager",
+    "GroupDetector",
+]

django_cfg/modules/django_client/core/groups/detector.py

@@ -0,0 +1,178 @@
+"""
+Application Group Detector.
+
+Detects which Django apps belong to which groups, with wildcard support.
+"""
+
+import fnmatch
+import logging
+from typing import Dict, List, Set
+from ..config import OpenAPIConfig, OpenAPIGroupConfig
+
+logger = logging.getLogger(__name__)
+
+
+class GroupDetector:
+    """
+    Detects Django apps for each configured group.
+
+    Supports wildcard patterns like "django_cfg.*" to match multiple apps.
+
+    Example:
+        >>> config = OpenAPIConfig(
+        ...     groups={
+        ...         "cfg": OpenAPIGroupConfig(
+        ...             apps=["django_cfg.*"],
+        ...             title="Framework",
+        ...         ),
+        ...         "custom": OpenAPIGroupConfig(
+        ...             apps=["myapp", "anotherapp"],
+        ...             title="Custom",
+        ...         ),
+        ...     },
+        ... )
+        >>> detector = GroupDetector(config)
+        >>> groups = detector.detect_groups(installed_apps)
+        >>> print(groups["cfg"])  # ['django_cfg.admin', 'django_cfg.logging', ...]
+    """
+
+    def __init__(self, config: OpenAPIConfig):
+        """
+        Initialize detector with configuration.
+
+        Args:
+            config: OpenAPI configuration with groups
+        """
+        self.config = config
+
+    def detect_groups(self, installed_apps: List[str]) -> Dict[str, List[str]]:
+        """
+        Detect which apps belong to which groups.
+
+        Args:
+            installed_apps: List of installed Django apps
+
+        Returns:
+            Dictionary mapping group names to lists of app names
+
+        Example:
+            >>> installed_apps = [
+            ...     "django_cfg.admin",
+            ...     "django_cfg.logging",
+            ...     "myapp",
+            ...     "anotherapp",
+            ... ]
+            >>> result = detector.detect_groups(installed_apps)
+            >>> result["cfg"]
+            ['django_cfg.admin', 'django_cfg.logging']
+            >>> result["custom"]
+            ['myapp', 'anotherapp']
+        """
+        result = {}
+        app_set = set(installed_apps)
+
+        for group in self.config.groups:
+            matched_apps = self._match_apps(group.apps, app_set)
+            result[group.name] = sorted(matched_apps)
+
+            logger.info(
+                f"Group '{group.name}': {len(matched_apps)} apps "
+                f"matched from {len(group.apps)} patterns"
+            )
+            logger.debug(f"Group '{group.name}' apps: {matched_apps}")
+
+        return result
+
+    def _match_apps(self, patterns: List[str], installed_apps: Set[str]) -> List[str]:
+        """
+        Match apps using patterns (supports wildcards).
+
+        Args:
+            patterns: List of app patterns (e.g., ["django_cfg.*", "myapp"])
+            installed_apps: Set of installed app names
+
+        Returns:
+            List of matched app names
+
+        Example:
+            >>> patterns = ["django_cfg.*", "myapp"]
+            >>> installed_apps = {
+            ...     "django_cfg.admin",
+            ...     "django_cfg.logging",
+            ...     "myapp",
+            ...     "otherapp",
+            ... }
+            >>> result = detector._match_apps(patterns, installed_apps)
+            >>> sorted(result)
+            ['django_cfg.admin', 'django_cfg.logging', 'myapp']
+        """
+        matched = []
+
+        for pattern in patterns:
+            if "*" in pattern or "?" in pattern or "[" in pattern:
+                # Wildcard pattern - use fnmatch
+                matches = fnmatch.filter(installed_apps, pattern)
+                matched.extend(matches)
+                logger.debug(f"Pattern '{pattern}' matched {len(matches)} apps")
+            else:
+                # Exact match
+                if pattern in installed_apps:
+                    matched.append(pattern)
+                    logger.debug(f"Exact match: '{pattern}'")
+                else:
+                    logger.warning(f"App '{pattern}' not found in INSTALLED_APPS")
+
+        # Remove duplicates while preserving order
+        seen = set()
+        result = []
+        for app in matched:
+            if app not in seen:
+                seen.add(app)
+                result.append(app)
+
+        return result
+
+    def validate_groups(self, installed_apps: List[str]) -> Dict[str, bool]:
+        """
+        Validate that all groups have at least one matched app.
+
+        Args:
+            installed_apps: List of installed Django apps
+
+        Returns:
+            Dictionary mapping group names to validation status
+
+        Example:
+            >>> validation = detector.validate_groups(installed_apps)
+            >>> if not all(validation.values()):
+            ...     print("Some groups have no apps!")
+        """
+        groups = self.detect_groups(installed_apps)
+        return {name: len(apps) > 0 for name, apps in groups.items()}
+
+    def get_ungrouped_apps(self, installed_apps: List[str]) -> List[str]:
+        """
+        Get list of apps that don't belong to any group.
+
+        Args:
+            installed_apps: List of installed Django apps
+
+        Returns:
+            List of ungrouped app names
+
+        Example:
+            >>> ungrouped = detector.get_ungrouped_apps(installed_apps)
+            >>> if ungrouped:
+            ...     print(f"Ungrouped apps: {ungrouped}")
+        """
+        groups = self.detect_groups(installed_apps)
+        grouped_apps = set()
+        for apps in groups.values():
+            grouped_apps.update(apps)
+
+        return sorted(set(installed_apps) - grouped_apps)
+
+
+__all__ = [
+    "GroupDetector",
+]

django_cfg/modules/django_client/core/groups/manager.py

@@ -0,0 +1,314 @@
+"""
+Application Group Manager.
+
+Manages application groups and URL pattern generation.
+"""
+
+import logging
+import sys
+from types import ModuleType
+from typing import Dict, List, Optional
+from ..config import OpenAPIConfig
+from .detector import GroupDetector
+
+logger = logging.getLogger(__name__)
+
+
+class GroupManager:
+    """
+    Manages application groups for OpenAPI schema generation.
+
+    Features:
+    - App detection with wildcard matching
+    - Dynamic URL configuration generation per group
+    - Group validation
+
+    Example:
+        >>> config = OpenAPIConfig(
+        ...     groups={
+        ...         "cfg": OpenAPIGroupConfig(
+        ...             apps=["django_cfg.*"],
+        ...             title="Framework API",
+        ...         ),
+        ...     },
+        ... )
+        >>> manager = GroupManager(config, installed_apps)
+        >>> groups = manager.get_groups()
+        >>> print(groups["cfg"])  # ['django_cfg.admin', 'django_cfg.logging', ...]
+    """
+
+    def __init__(
+        self,
+        config: OpenAPIConfig,
+        installed_apps: Optional[List[str]] = None,
+        groups: Optional[Dict[str, 'OpenAPIGroupConfig']] = None,
+    ):
+        """
+        Initialize group manager.
+
+        Args:
+            config: OpenAPI configuration
+            installed_apps: List of installed Django apps (auto-detected if None)
+            groups: Override groups (if None, uses config.groups)
+        """
+        self.config = config
+        self._override_groups = groups
+        self.detector = GroupDetector(config) if not groups else None
+
+        # Get installed apps
+        if installed_apps is None:
+            installed_apps = self._get_installed_apps()
+
+        self.installed_apps = installed_apps
+        self._groups_cache: Optional[Dict[str, List[str]]] = None
+
+    def _get_installed_apps(self) -> List[str]:
+        """
+        Get list of installed Django apps.
+
+        Returns:
+            List of app names from Django settings
+
+        Raises:
+            RuntimeError: If Django is not configured
+        """
+        try:
+            from django.conf import settings
+
+            if not settings.configured:
+                raise RuntimeError("Django settings not configured")
+
+            return list(settings.INSTALLED_APPS)
+
+        except ImportError:
+            raise RuntimeError("Django is not installed")
+
+    def get_groups(self) -> Dict[str, List[str]]:
+        """
+        Get detected groups.
+
+        Returns:
+            Dictionary mapping group names to app lists
+
+        Example:
+            >>> groups = manager.get_groups()
+            >>> print(f"Groups: {list(groups.keys())}")
+            >>> print(f"CFG apps: {groups['cfg']}")
+        """
+        if self._groups_cache is None:
+            if self._override_groups:
+                # Use override groups - manually detect apps for each group
+                self._groups_cache = {}
+                for group_name, group_config in self._override_groups.items():
+                    matched_apps = []
+                    for app_pattern in group_config.apps:
+                        if '*' in app_pattern or '?' in app_pattern:
+                            # Wildcard matching
+                            import fnmatch
+                            matched_apps.extend([
+                                app for app in self.installed_apps
+                                if fnmatch.fnmatch(app, app_pattern)
+                            ])
+                        else:
+                            # Exact match
+                            if app_pattern in self.installed_apps:
+                                matched_apps.append(app_pattern)
+                    self._groups_cache[group_name] = matched_apps
+            else:
+                # Use detector
+                self._groups_cache = self.detector.detect_groups(self.installed_apps)
+
+        return self._groups_cache
+
+    def get_group_apps(self, group_name: str) -> List[str]:
+        """
+        Get apps for specific group.
+
+        Args:
+            group_name: Name of the group
+
+        Returns:
+            List of app names for the group
+
+        Example:
+            >>> apps = manager.get_group_apps("cfg")
+            >>> print(f"CFG group has {len(apps)} apps")
+        """
+        groups = self.get_groups()
+        return groups.get(group_name, [])
+
+    def validate_all_groups(self) -> bool:
+        """
+        Validate that all groups have at least one app.
+
+        Returns:
+            True if all groups are valid
+
+        Raises:
+            ValueError: If any group has no apps
+
+        Example:
+            >>> try:
+            ...     manager.validate_all_groups()
+            ...     print("All groups valid!")
+            ... except ValueError as e:
+            ...     print(f"Validation error: {e}")
+        """
+        validation = self.detector.validate_groups(self.installed_apps)
+        invalid_groups = [name for name, valid in validation.items() if not valid]
+
+        if invalid_groups:
+            raise ValueError(
+                f"Groups with no matched apps: {', '.join(invalid_groups)}"
+            )
+
+        logger.info(f"All {len(validation)} groups validated successfully")
+        return True
+
+    def get_ungrouped_apps(self) -> List[str]:
+        """
+        Get apps that don't belong to any group.
+
+        Returns:
+            List of ungrouped app names
+
+        Example:
+            >>> ungrouped = manager.get_ungrouped_apps()
+            >>> if ungrouped:
+            ...     print(f"Warning: {len(ungrouped)} apps not in any group")
+        """
+        return self.detector.get_ungrouped_apps(self.installed_apps)
+
+    def create_urlconf_module(self, group_name: str) -> ModuleType:
+        """
+        Create dynamic URL configuration module for a group.
+
+        This generates a Python module in memory with URL patterns for all apps
+        in the group. The module can be used with drf-spectacular to generate
+        OpenAPI schemas for specific app groups.
+
+        Args:
+            group_name: Name of the group
+
+        Returns:
+            Dynamic module with URL patterns
+
+        Example:
+            >>> urlconf = manager.create_urlconf_module("cfg")
+            >>> # Use with drf-spectacular:
+            >>> # SpectacularAPIView.as_view(urlconf=urlconf)
+        """
+        apps = self.get_group_apps(group_name)
+
+        if not apps:
+            raise ValueError(f"Group '{group_name}' has no apps")
+
+        # Generate URL patterns
+        urlpatterns = []
+        from django.apps import apps as django_apps
+
+        for app_name in apps:
+            # Try to include app URLs
+            try:
+                # Find app config by full name
+                app_config = None
+                for config in django_apps.get_app_configs():
+                    if config.name == app_name:
+                        app_config = config
+                        break
+
+                if app_config:
+                    # Use actual label from AppConfig
+                    app_label = app_config.label
+                    urlpatterns.append(f'    path("{app_label}/", include("{app_name}.urls")),')
+                else:
+                    logger.debug(f"App '{app_name}' not found in installed apps")
+            except Exception as e:
+                logger.debug(f"App '{app_name}' skipped: {e}")
+                continue
+
+        # Create module code
+        module_code = f'''"""
+Dynamic URL configuration for group: {group_name}
+
+Auto-generated by django-client GroupManager.
+"""
+
+from django.urls import path, include
+
+urlpatterns = [
+{chr(10).join(urlpatterns)}
+]
+'''
+
+        # Create module
+        module_name = f"_django_client_urlconf_{group_name}"
+        module = ModuleType(module_name)
+        module.__file__ = f"<dynamic: {group_name}>"
+
+        # Execute code in module namespace
+        exec(module_code, module.__dict__)
+
+        # Add to sys.modules for import resolution
+        sys.modules[module_name] = module
+
+        logger.info(
+            f"Created dynamic urlconf for group '{group_name}' with {len(apps)} apps"
+        )
+
+        return module
+
+    def get_urlconf_name(self, group_name: str) -> str:
+        """
+        Get URL configuration module name for a group.
+
+        Args:
+            group_name: Name of the group
+
+        Returns:
+            Module name for use in Django settings
+
+        Example:
+            >>> urlconf_name = manager.get_urlconf_name("cfg")
+            >>> # Use in settings:
+            >>> # ROOT_URLCONF = urlconf_name
+        """
+        return f"_django_client_urlconf_{group_name}"
+
+    def get_statistics(self) -> Dict:
+        """
+        Get grouping statistics.
+
+        Returns:
+            Dictionary with statistics
+
+        Example:
+            >>> stats = manager.get_statistics()
+            >>> print(f"Total groups: {stats['total_groups']}")
+            >>> print(f"Total apps: {stats['total_apps']}")
+            >>> print(f"Ungrouped apps: {stats['ungrouped_apps']}")
+        """
+        groups = self.get_groups()
+        ungrouped = self.get_ungrouped_apps()
+
+        total_apps_in_groups = sum(len(apps) for apps in groups.values())
+
+        return {
+            "total_groups": len(groups),
+            "total_apps": len(self.installed_apps),
+            "total_apps_in_groups": total_apps_in_groups,
+            "ungrouped_apps": len(ungrouped),
+            "groups": {
+                name: {
+                    "apps": len(apps),
+                    "apps_list": apps,
+                }
+                for name, apps in groups.items()
+            },
+            "ungrouped_apps_list": ungrouped,
+        }
+
+
+__all__ = [
+    "GroupManager",
+]

django_cfg/modules/django_client/core/ir/__init__.py

@@ -0,0 +1,57 @@
+"""
+IR (Intermediate Representation) - Unified API representation.
+
+This package defines the version-agnostic, language-agnostic intermediate
+representation for Django APIs. All parsers (OpenAPI 3.0.3, 3.1.0) normalize
+to this IR, and all generators (Python, TypeScript) consume this IR.
+
+Key Features:
+- Request/Response split (UserRequest vs User)
+- x-enum-varnames support (strongly typed enums)
+- Nullable normalization (both 3.0 and 3.1 → single nullable field)
+- Django metadata (COMPONENT_SPLIT_REQUEST validation)
+
+Usage:
+    >>> from django_cfg.modules.django_client.core.ir import IRContext, IRSchemaObject, IROperationObject
+    >>> # Create schemas
+    >>> user_schema = IRSchemaObject(name="User", type="object", is_response_model=True)
+    >>> user_request = IRSchemaObject(name="UserRequest", type="object", is_request_model=True)
+    >>> # Create operation
+    >>> operation = IROperationObject(
+    ...     operation_id="users_create",
+    ...     http_method="POST",
+    ...     path="/api/users/",
+    ...     request_body=IRRequestBodyObject(schema_name="UserRequest"),
+    ...     responses={201: IRResponseObject(status_code=201, schema_name="User")},
+    ... )
+    >>> # Create context
+    >>> context = IRContext(
+    ...     openapi_info=OpenAPIInfo(version="3.1.0", title="My API"),
+    ...     django_metadata=DjangoGlobalMetadata(component_split_request=True),
+    ...     schemas={"User": user_schema, "UserRequest": user_request},
+    ...     operations={"users_create": operation},
+    ... )
+"""
+
+from .context import DjangoGlobalMetadata, IRContext, OpenAPIInfo
+from .operation import (
+    IROperationObject,
+    IRParameterObject,
+    IRRequestBodyObject,
+    IRResponseObject,
+)
+from .schema import IRSchemaObject
+
+__all__ = [
+    # Context (root model)
+    "IRContext",
+    "OpenAPIInfo",
+    "DjangoGlobalMetadata",
+    # Schema
+    "IRSchemaObject",
+    # Operation
+    "IROperationObject",
+    "IRParameterObject",
+    "IRRequestBodyObject",
+    "IRResponseObject",
+]