splent-framework 1.2.8__tar.gz → 1.4.1__tar.gz

{splent_framework-1.2.8/src/splent_framework.egg-info → splent_framework-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_framework
-Version: 1.2.8
+Version: 1.4.1
 Summary: SPLENT-FRAMEWORK is a set of libraries for agile product development within SPLENT.
 Author-email: DiversoLab <diversolab@us.es>
 Project-URL: Homepage, https://github.com/diverso-lab/splent_framework
@@ -21,6 +21,7 @@ Requires-Dist: redis==5.2.1
 Requires-Dist: pymysql==1.1.1
 Requires-Dist: psutil==6.1.1
 Requires-Dist: pytz==2024.2
+Requires-Dist: flask-babel==4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3; extra == "dev"
 Requires-Dist: pytest-cov>=6.0; extra == "dev"

{splent_framework-1.2.8 → splent_framework-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_framework"
-version = "1.2.8"
+version = "1.4.1"
 description = "SPLENT-FRAMEWORK is a set of libraries for agile product development within SPLENT."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -24,7 +24,8 @@ dependencies = [
     "redis==5.2.1",
     "pymysql==1.1.1",
     "psutil==6.1.1",
-    "pytz==2024.2"
+    "pytz==2024.2",
+    "flask-babel==4.0.0"
 ]
 
 [project.optional-dependencies]

splent_framework-1.4.1/src/splent_framework/app_factory.py

@@ -0,0 +1,92 @@
+"""
+SPLENT App Factory — the canonical way to create a SPLENT product application.
+
+Usage in a product's __init__.py::
+
+    from splent_framework import create_splent_app
+
+    def create_app(config_name="development"):
+        return create_splent_app(__name__, config_name)
+
+The factory initialises all framework subsystems in the correct order.
+Products should not import individual managers — the factory handles it.
+"""
+
+import logging
+import os
+
+from flask import Flask
+
+from splent_framework.managers.namespace_manager import NamespaceManager
+from splent_framework.managers.config_manager import ConfigManager
+from splent_framework.managers.migration_manager import MigrationManager
+from splent_framework.managers.session_manager import SessionManager
+from splent_framework.managers.logging_manager import LoggingManager
+from splent_framework.managers.error_handler_manager import ErrorHandlerManager
+from splent_framework.managers.jinja_manager import JinjaManager
+from splent_framework.managers.locale_manager import LocaleManager
+from splent_framework.managers.feature_manager import FeatureManager
+
+logger = logging.getLogger(__name__)
+
+# Initialisation pipeline — order matters.
+# Each step is a (label, callable) pair.  The callable receives (app, **kwargs).
+_PIPELINE = [
+    ("namespaces", lambda app, **kw: NamespaceManager.init_app(app)),
+    ("config", lambda app, **kw: ConfigManager.init_app(app, kw.get("config_name", "development"))),
+    ("database", lambda app, **kw: MigrationManager(app)),
+    ("logging", lambda app, **kw: LoggingManager(app).setup_logging()),
+    ("error_handlers", lambda app, **kw: ErrorHandlerManager(app).register_error_handlers()),
+    ("locale", lambda app, **kw: LocaleManager(app)),
+    ("jinja_context", lambda app, **kw: JinjaManager(app, kw.get("context", {}))),
+    ("features", lambda app, **kw: FeatureManager(app, strict=kw.get("strict", False)).register_features()),
+    ("sessions", lambda app, **kw: SessionManager(app)),
+]
+
+
+def create_splent_app(
+    import_name: str,
+    config_name: str = "development",
+    *,
+    strict: bool = False,
+    extra_context: dict | None = None,
+) -> Flask:
+    """Create and fully initialise a SPLENT Flask application.
+
+    Parameters
+    ----------
+    import_name : str
+        The ``__name__`` of the calling product package.
+    config_name : str
+        Configuration profile: ``"development"``, ``"testing"``, or ``"production"``.
+    strict : bool
+        If True, missing features raise errors instead of warnings.
+    extra_context : dict | None
+        Additional Jinja context variables injected into every template.
+
+    Returns
+    -------
+    Flask
+        A fully configured Flask application with all features loaded.
+    """
+    app = Flask(import_name)
+
+    context = {"SPLENT_APP": os.getenv("SPLENT_APP", "")}
+    if extra_context:
+        context.update(extra_context)
+
+    kwargs = {
+        "config_name": config_name,
+        "context": context,
+        "strict": strict,
+    }
+
+    for label, init_fn in _PIPELINE:
+        try:
+            init_fn(app, **kwargs)
+            logger.debug("Initialised: %s", label)
+        except Exception:
+            logger.exception("Failed to initialise: %s", label)
+            raise
+
+    return app

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/blueprints/base_blueprint.py

@@ -57,15 +57,45 @@ class BaseBlueprint(Blueprint):
                 self.send_file,
             )
 
+    def _resolve_asset_path(self, subfolder, filename):
+        """Find an asset file, checking workspace root first (for compiled assets)."""
+        # Primary: feature_code_path (where the module was imported from)
+        primary = os.path.join(self.feature_code_path, "assets", subfolder, filename)
+        if os.path.isfile(primary):
+            return os.path.realpath(primary), os.path.realpath(
+                os.path.join(self.feature_code_path, "assets", subfolder)
+            )
+
+        # Fallback: workspace root (editable feature may have compiled dist/ here)
+        workspace = os.getenv("WORKING_DIR")
+        if workspace:
+            # feature_code_path looks like .../src/splent_io/splent_feature_X
+            # We need just the feature package name
+            feature_name = os.path.basename(self.feature_code_path)
+            org_name = os.path.basename(os.path.dirname(self.feature_code_path))
+            fallback = os.path.join(
+                workspace, feature_name, "src", org_name, feature_name,
+                "assets", subfolder, filename,
+            )
+            if os.path.isfile(fallback):
+                return os.path.realpath(fallback), os.path.realpath(
+                    os.path.join(
+                        workspace, feature_name, "src", org_name, feature_name,
+                        "assets", subfolder,
+                    )
+                )
+
+        return None, None
+
     def send_file(self, subfolder, filename):
         allowed_subfolders = {"js", "css", "dist"}
         if subfolder not in allowed_subfolders:
             abort(404)
 
-        base_dir = os.path.realpath(
-            os.path.join(self.feature_code_path, "assets", subfolder)
-        )
-        requested_path = os.path.realpath(os.path.join(base_dir, filename))
+        requested_path, base_dir = self._resolve_asset_path(subfolder, filename)
+
+        if not requested_path:
+            abort(404)
 
         # Prevent path traversal: resolved path must stay inside base_dir
         if (
@@ -74,9 +104,6 @@ class BaseBlueprint(Blueprint):
         ):
             abort(403)
 
-        if not os.path.isfile(requested_path):
-            abort(404)
-
         if filename.endswith(".js"):
             mimetype = "application/javascript"
         elif filename.endswith(".css"):

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/configuration/default_config.py

@@ -16,7 +16,8 @@ class Config:
     SQLALCHEMY_TRACK_MODIFICATIONS = False
     TEMPLATES_AUTO_RELOAD = True
     UPLOAD_FOLDER = "uploads"
-    SESSION_TYPE = "filesystem"
+    # SESSION_TYPE is NOT set here — it must come from a session feature
+    # (splent_feature_session_redis or splent_feature_session_filesystem)
 
     def __init__(self):
         # Resolved at instantiation time so runtime env changes are picked up
@@ -34,8 +35,6 @@ class DevelopmentConfig(Config):
 class TestingConfig(Config):
     TESTING = True
     WTF_CSRF_ENABLED = False
-    SESSION_TYPE = "filesystem"
-    SESSION_FILE_DIR = "/tmp/flask_sessions"
 
     def __init__(self):
         super().__init__()

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/fixtures/fixtures.py

@@ -1,8 +1,20 @@
 import pytest
+from sqlalchemy import text
 from splent_framework.db import db
 from splent_framework.utils.app_loader import get_create_app_in_testing_mode
 
 
+def _reset_db():
+    """Drop and recreate all tables. Disables FK checks for MariaDB."""
+    db.session.remove()
+    with db.engine.connect() as conn:
+        conn.execute(text("SET FOREIGN_KEY_CHECKS=0"))
+        db.metadata.drop_all(bind=conn)
+        conn.execute(text("SET FOREIGN_KEY_CHECKS=1"))
+        db.metadata.create_all(bind=conn)
+        conn.commit()
+
+
 @pytest.fixture(scope="session")
 def test_app():
     """
@@ -11,59 +23,43 @@ def test_app():
     """
     app = get_create_app_in_testing_mode()
     with app.app_context():
-        db.drop_all()
-        db.create_all()
+        _reset_db()
     yield app
 
 
 @pytest.fixture(scope="function")
 def test_client(test_app):
     """
-    Provides a test client and resets the DB before and after each test.
-    This ensures test isolation.
+    Provides a test client with a clean database for each test.
+    Tables are dropped and recreated before the test runs.
     """
     with test_app.app_context():
-        db.session.remove()
-        db.drop_all()
-        db.create_all()
+        _reset_db()
     with test_app.test_client() as client:
         yield client
-    with test_app.app_context():
-        db.session.remove()
-        db.drop_all()
-        db.create_all()
 
 
 @pytest.fixture(scope="module")
 def test_client_module(test_app):
     """
     Shared test client for the entire module.
-    Resets the database only at the start and end of the module.
+    Resets the database once at the start of the module.
+    Tests within the module share database state.
     """
     with test_app.app_context():
-        db.session.remove()
-        db.drop_all()
-        db.create_all()
+        _reset_db()
 
         with test_app.test_client() as client:
             yield client
 
-        db.session.remove()
-        db.drop_all()
-        db.create_all()
-
 
 @pytest.fixture(scope="function")
 def clean_database(test_app):
     """
-    Provides a manual DB reset during a test when needed.
-    Useful if you want to control when the DB is cleaned.
+    Manually resets the database within a test.
+    Combine with test_client_module when you need a selective
+    reset inside a module-scoped session.
     """
     with test_app.app_context():
-        db.session.remove()
-        db.drop_all()
-        db.create_all()
+        _reset_db()
         yield
-        db.session.remove()
-        db.drop_all()
-        db.create_all()

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/hooks/template_hooks.py

@@ -9,9 +9,24 @@ _hooks: dict[str, list] = {}
 
 
 def register_template_hook(name: str, func) -> None:
+    """Append a callback to a named hook slot (additive)."""
     _hooks.setdefault(name, []).append(func)
 
 
+def replace_template_hook(name: str, func) -> None:
+    """Replace ALL existing callbacks for a named hook slot.
+
+    Used by refinement features to override a base feature's hook content.
+    """
+    _hooks[name] = [func]
+
+
+def remove_template_hook(name: str, func) -> None:
+    """Remove a specific callback from a hook slot."""
+    if name in _hooks:
+        _hooks[name] = [f for f in _hooks[name] if f is not func]
+
+
 def get_template_hooks(name: str) -> list:
     return _hooks.get(name, [])
 

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/managers/config_manager.py

@@ -47,3 +47,8 @@ class ConfigManager:
                 config_data[k] = getattr(config_instance, k)
 
         self.app.config.from_mapping(config_data)
+
+        # Trace: mark all product-level config keys
+        trace = self.app.extensions.setdefault("splent_config_trace", {})
+        for key, value in config_data.items():
+            trace[key] = {"value": value, "source": f"product ({splent_app})", "action": "set"}

{splent_framework-1.2.8 → splent_framework-1.4.1}/src/splent_framework/managers/feature_loader.py

@@ -28,7 +28,7 @@ from flask import Blueprint
 logger = logging.getLogger(__name__)
 
 # Conventional submodules attempted on every feature package
-FEATURE_SUBMODULES = ("routes", "models", "hooks")
+FEATURE_SUBMODULES = ("routes", "models", "hooks", "signals")
 
 
 # ---------------------------------------------------------------------------
@@ -232,21 +232,76 @@ class FeatureIntegrator:
     Responsibilities (in order):
       1. Inject feature configuration via ``<feature>.config.inject_config(app)``
       2. Call ``<feature>.init_feature(app)`` if present
-      3. Register all Flask Blueprints found in the feature modules
+      3. Apply service overrides from the RefinementRegistry
+      4. Register all Flask Blueprints found in the feature modules
     """
 
-    def __init__(self, app, strict: bool = True) -> None:
+    def __init__(self, app, strict: bool = True, registry=None) -> None:
         self._app = app
         self._strict = strict
+        self._registry = registry
 
     def integrate(self, module, import_name: str) -> None:
         """Run all integration steps for the given feature module."""
         self._inject_config(import_name)
+        self._apply_model_extensions(import_name)
         self._call_init(module, import_name)
+        self._apply_service_overrides(import_name)
         self._register_blueprints(module, import_name)
+        self._register_translations(module, import_name)
+        self._register_commands(import_name)
 
     # ------------------------------------------------------------------
 
+    def _apply_model_extensions(self, import_name: str) -> None:
+        """Apply model mixins declared by refinement features targeting this feature."""
+        if not self._registry:
+            return
+
+        feature_name = import_name.rsplit(".", 1)[-1]
+        overrides = self._registry.get_overrides(feature_name, "model")
+        if not overrides:
+            return
+
+        from splent_framework.refinement.model_extender import apply_model_mixin
+
+        for entry in overrides:
+            # Import the mixin from the refiner's module
+            refiner_org = "splent_io"  # convention
+            mixin_module_name = f"{refiner_org}.{entry.refiner}.models"
+            try:
+                import importlib
+
+                mod = importlib.import_module(mixin_module_name)
+                mixin_cls = getattr(mod, entry.replacement)
+                apply_model_mixin(entry.target, mixin_cls)
+            except (ImportError, AttributeError) as e:
+                logger.warning(
+                    "Cannot apply model mixin %s from %s: %s",
+                    entry.replacement, entry.refiner, e,
+                )
+
+    def _apply_service_overrides(self, import_name: str) -> None:
+        """Log service overrides applied by this feature (if it's a refiner).
+
+        The actual override happens naturally: the refiner's init_feature()
+        calls register_service() with the same key, overwriting the base.
+        Load order (UVL) guarantees the refiner runs after the base.
+        """
+        if not self._registry:
+            return
+
+        feature_name = import_name.rsplit(".", 1)[-1]
+        if not self._registry.is_refiner(feature_name):
+            return
+
+        for entry in self._registry.all_entries():
+            if entry.refiner == feature_name and entry.category == "service":
+                logger.info(
+                    "Service override: %s.%s → %s (by %s)",
+                    entry.base, entry.target, entry.replacement, entry.refiner,
+                )
+
     def _inject_config(self, import_name: str) -> None:
         try:
             config_mod = importlib.import_module(f"{import_name}.config")
@@ -258,15 +313,35 @@ class FeatureIntegrator:
             raise FeatureError(f"Error importing {import_name}.config: {e}") from e
 
         if hasattr(config_mod, "inject_config"):
+            snapshot = dict(self._app.config)
             try:
                 config_mod.inject_config(self._app)
             except Exception as e:
                 raise FeatureError(
                     f"Error in {import_name}.config.inject_config: {e}"
                 ) from e
+            self._trace_config_changes(snapshot, import_name)
         elif self._strict:
             raise FeatureError(f"{import_name}.config lacks inject_config(app)")
 
+    def _trace_config_changes(self, snapshot: dict, source: str) -> None:
+        """Record which config keys were added or changed by *source*."""
+        trace = self._app.extensions.setdefault("splent_config_trace", {})
+        for key, value in self._app.config.items():
+            if not key.isupper():
+                continue
+            if key not in snapshot:
+                trace[key] = {"value": value, "source": source, "action": "added"}
+            elif snapshot[key] != value:
+                prev = trace.get(key, {})
+                trace[key] = {
+                    "value": value,
+                    "source": source,
+                    "action": "overwritten",
+                    "prev_source": prev.get("source", "product"),
+                    "prev_value": snapshot[key],
+                }
+
     def _call_init(self, module, import_name: str) -> None:
         if hasattr(module, "init_feature"):
             try:
@@ -280,7 +355,9 @@ class FeatureIntegrator:
 
     def _register_blueprints(self, module, import_name: str) -> None:
         candidates = self._collect_candidate_modules(module, import_name)
-        registered = sum(self._register_from_module(mod) for mod in candidates)
+        registered = sum(
+            self._register_from_module(mod, import_name) for mod in candidates
+        )
 
         if registered == 0:
             logger.warning("No blueprints registered for %s", import_name)
@@ -297,9 +374,10 @@ class FeatureIntegrator:
             if f"{import_name}.{sub}" in sys.modules
         ]
 
-    def _register_from_module(self, mod: types.ModuleType) -> int:
+    def _register_from_module(self, mod: types.ModuleType, import_name: str) -> int:
         """Register all Blueprint instances found in *mod*. Returns count registered."""
         registered = 0
+        trace = self._app.extensions.setdefault("splent_blueprint_trace", {})
         for attr in dir(mod):
             try:
                 obj = getattr(mod, attr)
@@ -319,12 +397,63 @@ class FeatureIntegrator:
 
             try:
                 self._app.register_blueprint(obj)
+                trace[obj.name] = import_name
                 registered += 1
             except Exception as e:
                 logger.error("Failed to register blueprint '%s': %s", obj.name, e)
 
         return registered
 
+    def _register_translations(self, module, import_name: str) -> None:
+        """Register the feature's translations/ directory with Flask-Babel."""
+        pkg_dir = os.path.dirname(module.__file__) if hasattr(module, "__file__") else None
+        if not pkg_dir:
+            return
+        translations_dir = os.path.join(pkg_dir, "translations")
+        if os.path.isdir(translations_dir):
+            from splent_framework.managers.locale_manager import LocaleManager
+            LocaleManager.register_translation_dir(self._app, translations_dir)
+
+    def _register_commands(self, import_name: str) -> None:
+        """Collect Click commands from the feature's ``commands`` submodule.
+
+        If the feature defines ``<package>.commands`` with a ``cli_commands``
+        list, each Click command is stored in
+        ``app.extensions["splent_feature_commands"]`` keyed by feature short
+        name (e.g. ``"mail"``).  The CLI reads this registry at runtime.
+        """
+        try:
+            cmd_mod = importlib.import_module(f"{import_name}.commands")
+        except ModuleNotFoundError:
+            return
+        except Exception as e:
+            logger.warning("Error importing %s.commands: %s", import_name, e)
+            return
+
+        commands = getattr(cmd_mod, "cli_commands", None)
+        if not commands:
+            return
+
+        # Derive short name: "splent_feature_mail" → "mail"
+        feature_pkg = import_name.rsplit(".", 1)[-1]
+        short = (
+            feature_pkg[len("splent_feature_"):]
+            if feature_pkg.startswith("splent_feature_")
+            else feature_pkg
+        )
+
+        registry = self._app.extensions.setdefault("splent_feature_commands", {})
+        from click import BaseCommand
+        valid = [c for c in commands if isinstance(c, BaseCommand)]
+        if valid:
+            registry[short] = valid
+            logger.info(
+                "Registered %d CLI command(s) for feature '%s': %s",
+                len(valid),
+                short,
+                [c.name for c in valid],
+            )
+
 
 # ---------------------------------------------------------------------------
 # Orchestrator: load a single feature (DIP — collaborators injected)