hotframe 0.0.1__py3-none-any.whl

hotframe/__init__.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+"""hotframe — Modular Python web framework with hot-mount dynamic modules."""
+
+__version__ = "0.0.1"
+
+# ---------------------------------------------------------------------------
+# Lazy imports — only loaded when accessed
+# ---------------------------------------------------------------------------
+
+_LAZY_IMPORTS: dict[str, str] = {
+    # Bootstrap
+    "create_app": "hotframe.bootstrap",
+    # Settings
+    "HotframeSettings": "hotframe.config.settings",
+    "get_settings": "hotframe.config.settings",
+    # Apps
+    "AppConfig": "hotframe.apps.config",
+    "ModuleConfig": "hotframe.apps.config",
+    # Models
+    "Base": "hotframe.models.base",
+    "HubBaseModel": "hotframe.models.base",
+    "TimeStampedModel": "hotframe.models.base",
+    "ActiveModel": "hotframe.models.base",
+    "HubMixin": "hotframe.models.mixins",
+    "TimestampMixin": "hotframe.models.mixins",
+    "AuditMixin": "hotframe.models.mixins",
+    "SoftDeleteMixin": "hotframe.models.mixins",
+    "HubQuery": "hotframe.models.queryset",
+    # Repository
+    "BaseRepository": "hotframe.repository.base",
+    # Signals
+    "AsyncEventBus": "hotframe.signals.dispatcher",
+    "HookRegistry": "hotframe.signals.hooks",
+    "BaseEvent": "hotframe.signals.types",
+    "register_event": "hotframe.signals.types",
+    # ORM
+    "setup_orm_events": "hotframe.orm.events",
+    # Views
+    "htmx_view": "hotframe.views.responses",
+    "is_htmx_request": "hotframe.views.responses",
+    "htmx_redirect": "hotframe.views.responses",
+    "htmx_refresh": "hotframe.views.responses",
+    "htmx_trigger": "hotframe.views.responses",
+    "add_message": "hotframe.views.responses",
+    "sse_stream": "hotframe.views.responses",
+    "TurboStream": "hotframe.views.streams",
+    "StreamResponse": "hotframe.views.streams",
+    "BroadcastHub": "hotframe.views.broadcast",
+    # Templating
+    "SlotRegistry": "hotframe.templating.slots",
+    # Auth
+    "get_session_user_id": "hotframe.auth.auth",
+    "hash_password": "hotframe.auth.auth",
+    "verify_password": "hotframe.auth.auth",
+    "has_permission": "hotframe.auth.permissions",
+    "require_permission": "hotframe.auth.permissions",
+    # Dependencies
+    "DbSession": "hotframe.auth.current_user",
+    "CurrentUser": "hotframe.auth.current_user",
+    "OptionalUser": "hotframe.auth.current_user",
+    "EventBus": "hotframe.auth.current_user",
+    "Hooks": "hotframe.auth.current_user",
+    "Slots": "hotframe.auth.current_user",
+    "get_db": "hotframe.auth.current_user",
+    "get_current_user": "hotframe.auth.current_user",
+    # Services
+    "ModuleService": "hotframe.apps.service_facade",
+    "action": "hotframe.apps.service_facade",
+    # Engine
+    "ModuleStateDB": "hotframe.engine.state",
+    "HotMountPipeline": "hotframe.engine.pipeline",
+    "ImportManager": "hotframe.engine.import_manager",
+    # Forms
+    "FormRenderer": "hotframe.forms.rendering",
+    # Config
+    "get_engine": "hotframe.config.database",
+    "get_session_factory": "hotframe.config.database",
+    # Storage
+    "MediaStorage": "hotframe.storage.media",
+    "get_media_storage": "hotframe.storage.media",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        import importlib
+        module = importlib.import_module(_LAZY_IMPORTS[name])
+        return getattr(module, name)
+    raise AttributeError(f"module 'hotframe' has no attribute {name!r}")
+
+
+__all__ = [*list(_LAZY_IMPORTS.keys()), "__version__"]

hotframe/apps/__init__.py

@@ -0,0 +1,48 @@
+"""
+apps — module configuration and registry.
+
+Defines the declarative contracts that every Hub module must satisfy
+(``AppConfig``, ``ModuleConfig``, ``ModuleManifest``) and the in-memory
+registries (``AppRegistry``, ``ModuleRegistry``) that the engine uses to
+track installed and active modules at runtime.
+
+Key exports::
+
+    from hotframe.apps import AppConfig, ModuleConfig, AppRegistry, ModuleRegistry
+
+Usage::
+
+    registry = AppRegistry()
+    registry.register(my_module_config)
+    mod = registry.get("sales")
+"""
+
+from hotframe.apps.config import (
+    AppConfig,
+    MenuConfig,
+    ModuleConfig,
+    ModuleManifest,
+    NavigationItem,
+    load_manifest,
+    manifest_to_dict,
+)
+from hotframe.apps.registry import (
+    AppRegistry,
+    ModuleRegistry,
+    RegisteredModule,
+)
+
+__all__ = [
+    # New contract
+    "AppConfig",
+    "AppRegistry",
+    "MenuConfig",
+    "ModuleConfig",
+    # Legacy contract (compat durante migracion)
+    "ModuleManifest",
+    "ModuleRegistry",
+    "NavigationItem",
+    "RegisteredModule",
+    "load_manifest",
+    "manifest_to_dict",
+]

hotframe/apps/config.py

@@ -0,0 +1,307 @@
+"""
+Module manifest — Pydantic strict validation of module.py contents.
+
+Every module must have a ``module.py`` at its root with specific attributes.
+This module defines the schema (ModuleManifest) and the loader that extracts
+those attributes into a validated Pydantic model.
+
+If validation fails, the module CANNOT load and its status becomes ``error``.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+logger = logging.getLogger(__name__)
+
+
+# ------------------------------------------------------------------
+# Sub-models
+# ------------------------------------------------------------------
+
+class MenuConfig(BaseModel):
+    """Module sidebar menu entry configuration."""
+
+    label: str
+    icon: str = "cube-outline"
+    order: int = 50
+
+
+class NavigationItem(BaseModel):
+    """A single tab/section inside a module's navigation bar."""
+
+    label: str
+    icon: str
+    id: str
+    view: str = ""
+
+
+# ------------------------------------------------------------------
+# ModuleManifest
+# ------------------------------------------------------------------
+
+class ModuleManifest(BaseModel):
+    """
+    Strict schema for ``module.py`` attributes.
+
+    If any required field is missing or fails validation the module
+    is rejected and its DB status set to ``error``.
+    """
+
+    MODULE_ID: str = Field(pattern=r"^[a-z][a-z0-9_]*$")
+    MODULE_NAME: str
+    MODULE_VERSION: str = Field(pattern=r"^\d+\.\d+\.\d+")
+    MODULE_ICON: str = "cube-outline"
+    MODULE_DESCRIPTION: str = ""
+    MODULE_AUTHOR: str = ""
+    HAS_MODELS: bool = False
+
+    MENU: MenuConfig | None = None
+    NAVIGATION: list[NavigationItem] = []
+    PERMISSIONS: list[str] = []
+    ROLE_PERMISSIONS: dict[str, list[str | tuple]] = {}
+    DEPENDENCIES: list[str] = []
+
+    @field_validator("PERMISSIONS", mode="before")
+    @classmethod
+    def normalize_permissions(cls, v: Any) -> list[str]:
+        """Accept both 'codename' strings and ('codename', 'description') tuples."""
+        result = []
+        for item in v:
+            if isinstance(item, (tuple, list)):
+                result.append(str(item[0]))
+            else:
+                result.append(str(item))
+        return result
+    MIDDLEWARE: str | None = None
+    SCHEDULED_TASKS: list[dict] = []
+    PRICING: dict | None = None
+
+
+# ------------------------------------------------------------------
+# Manifest attributes — the exhaustive list we read from module.py
+# ------------------------------------------------------------------
+
+_MANIFEST_FIELDS: set[str] = set(ModuleManifest.model_fields.keys())
+
+
+# ------------------------------------------------------------------
+# Loader
+# ------------------------------------------------------------------
+
+def load_manifest(module_path: Path) -> ModuleManifest:
+    """
+    Import ``module.py`` from *module_path* and build a validated manifest.
+
+    The file is loaded via ``importlib`` into an isolated spec so it does not
+    pollute ``sys.modules`` with a permanent entry. Attributes listed in
+    :data:`_MANIFEST_FIELDS` are extracted and passed to :class:`ModuleManifest`.
+
+    Args:
+        module_path: Directory containing ``module.py``.
+
+    Returns:
+        A validated :class:`ModuleManifest` instance.
+
+    Raises:
+        FileNotFoundError: If ``module.py`` does not exist.
+        pydantic.ValidationError: If the extracted attributes fail validation.
+    """
+    module_py = module_path / "module.py"
+    if not module_py.exists():
+        raise FileNotFoundError(f"module.py not found in {module_path}")
+
+    # Use a temporary module name to avoid collisions
+    tmp_name = f"_manifest_loader_{module_path.name}"
+
+    spec = importlib.util.spec_from_file_location(tmp_name, str(module_py))
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot create import spec for {module_py}")
+
+    mod = importlib.util.module_from_spec(spec)
+
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        # Clean up the temporary module — never keep it around
+        sys.modules.pop(tmp_name, None)
+
+    # Extract manifest attributes
+    data: dict[str, Any] = {}
+    for attr in _MANIFEST_FIELDS:
+        value = getattr(mod, attr, None)
+        if value is not None:
+            # MenuConfig may be provided as a plain dict
+            data[attr] = value
+
+    return ModuleManifest(**data)
+
+
+def manifest_to_dict(manifest: ModuleManifest) -> dict[str, Any]:
+    """Serialize a manifest to a JSON-safe dict for storing in hub_module.manifest.
+
+    Produces short keys (``name``, ``icon``, ``dependencies``, …) instead of
+    the raw Pydantic field names (``MODULE_NAME``, ``MODULE_ICON``, …) so that
+    templates, routes, and APIs can access them consistently.
+    """
+    raw = manifest.model_dump(mode="json")
+    _KEY_MAP: dict[str, str] = {
+        "MODULE_ID": "module_id",
+        "MODULE_NAME": "name",
+        "MODULE_VERSION": "version",
+        "MODULE_ICON": "icon",
+        "MODULE_DESCRIPTION": "description",
+        "MODULE_AUTHOR": "author",
+        "HAS_MODELS": "has_models",
+        "MENU": "menu",
+        "NAVIGATION": "navigation",
+        "PERMISSIONS": "permissions",
+        "ROLE_PERMISSIONS": "role_permissions",
+        "DEPENDENCIES": "dependencies",
+        "MIDDLEWARE": "middleware",
+        "SCHEDULED_TASKS": "scheduled_tasks",
+        "PRICING": "pricing",
+    }
+    return {_KEY_MAP.get(k, k): v for k, v in raw.items()}
+
+
+# ======================================================================
+# Django-like AppConfig / ModuleConfig (new contract, Fase 3+)
+# ======================================================================
+
+class AppConfig:
+    """
+    Base class for core app configurations.
+
+    A dev writes ``apps/<name>/app.py`` with a subclass of ``AppConfig``.
+    The discovery scanner (hotframe.discovery.scanner) auto-loads it at
+    boot time. Core apps are STATIC: they are registered once and do not
+    unmount in runtime (that is for ``ModuleConfig`` — see below).
+
+    Subclass attributes:
+        name: required, identifier for the app (matches the directory name)
+        verbose_name: human-readable label
+        mount_prefix: where to mount the app's urlpatterns (default ``/<name>/``)
+        version: semver string
+        depends: list of other app names this one requires at boot
+        permissions: list of (code, label) tuples (optional)
+        role_permissions: dict[role_name, list[permission_code | "*"]]
+        menu: dict with ``label``, ``icon``, ``order`` (optional)
+        navigation: list of dicts (optional)
+        is_kernel: True if this app is a system app that cannot be disabled
+
+    Subclass methods:
+        async def ready(self) -> None:
+            Hook called once after all apps are loaded and mounted.
+            Typical use: import signals module to register @receiver
+            decorators.
+
+    Runtime usage (pseudo):
+        cfg = MyAppConfig()
+        registry.register(cfg)
+        await cfg.ready()
+    """
+
+    name: str = ""
+    verbose_name: str = ""
+    mount_prefix: str = ""           # if empty, defaults to f"/{name}/"
+    media_path: str = ""             # Media subdirectory name. If empty, uses app name.
+    version: str = "0.1.0"
+    depends: list[str] = []
+    permissions: list[tuple[str, str]] = []
+    role_permissions: dict[str, list[str]] = {}
+    menu: dict | None = None
+    navigation: list[dict] = []
+    is_kernel: bool = False
+
+    # Abstract/base subclasses (like ModuleConfig) set this to True to
+    # opt out of the required-name check. Concrete subclasses inherit
+    # the default False and must declare 'name'.
+    _abstract: bool = False
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        # Reset the abstract flag for every subclass unless explicitly
+        # declared in the class body. This prevents the flag from
+        # leaking from an abstract base (e.g. ModuleConfig) into concrete
+        # subclasses of it.
+        if "_abstract" not in cls.__dict__:
+            cls._abstract = False
+        if cls._abstract:
+            return
+        if not cls.name:
+            raise ValueError(
+                f"{cls.__name__}: AppConfig subclass must define 'name'"
+            )
+
+    async def ready(self) -> None:
+        """Hook. Default is no-op. Subclasses override to wire signals."""
+        return None
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} name={self.name!r} version={self.version!r}>"
+
+
+class ModuleConfig(AppConfig):
+    """
+    Base class for dynamic modules downloaded from S3.
+
+    A dev writes ``modules/<name>/module.py`` with a subclass of
+    ``ModuleConfig``. The module runtime (hotframe.engine.module_runtime)
+    installs/activates/deactivates/uninstalls these at runtime.
+
+    Additional subclass attributes vs AppConfig:
+        requires_restart: if True, changes to this module cannot be
+            hot-mounted and trigger a GracefulRestartCoordinator swap.
+        is_system: if True, cannot be uninstalled from UI (e.g. assistant).
+        s3_key: optional explicit S3 key override; default is computed
+            from name+version by S3ModuleSource.
+        sha256: optional explicit SHA256 override.
+
+    Additional subclass methods:
+        async def install(self, ctx) -> None:
+            Called once when the module is first installed on a hub.
+            Use for seeding initial data.
+        async def uninstall(self, ctx) -> None:
+            Called when the module is uninstalled.
+            Use for idempotent cleanup.
+        async def activate(self, ctx) -> None:
+            Called when the module is activated (after install or when
+            re-enabled from the disabled state).
+        async def deactivate(self, ctx) -> None:
+            Called when the module is deactivated (user disables it).
+    """
+
+    # ModuleConfig itself is an abstract base — only its subclasses are
+    # expected to carry a name.
+    _abstract: bool = True
+
+    requires_restart: bool = False
+    is_system: bool = False
+    has_views: bool = True
+    has_api: bool = True
+    media_path: str = ""             # Media subdirectory name. If empty, uses module name.
+    s3_key: str | None = None
+    sha256: str | None = None
+
+    async def install(self, ctx) -> None:
+        """Hook. Called once at first install. Default no-op."""
+        return None
+
+    async def uninstall(self, ctx) -> None:
+        """Hook. Idempotent cleanup. Default no-op."""
+        return None
+
+    async def activate(self, ctx) -> None:
+        """Hook. Called on activate. Default no-op."""
+        return None
+
+    async def deactivate(self, ctx) -> None:
+        """Hook. Called on deactivate. Default no-op."""
+        return None