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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_framework
-Version: 1.2.8
+Version: 1.2.10
 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_framework"
-version = "1.2.8"
+version = "1.2.10"
 description = "SPLENT-FRAMEWORK is a set of libraries for agile product development within SPLENT."
 readme = "README.md"
 requires-python = ">=3.13"

splent_framework-1.2.10/src/splent_framework/app_factory.py

@@ -0,0 +1,90 @@
+"""
+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.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)),
+    ("sessions", lambda app, **kw: SessionManager(app)),
+    ("logging", lambda app, **kw: LoggingManager(app).setup_logging()),
+    ("error_handlers", lambda app, **kw: ErrorHandlerManager(app).register_error_handlers()),
+    ("jinja_context", lambda app, **kw: JinjaManager(app, kw.get("context", {}))),
+    ("features", lambda app, **kw: FeatureManager(app, strict=kw.get("strict", False)).register_features()),
+]
+
+
+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.2.10}/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.2.10}/src/splent_framework/managers/feature_loader.py

@@ -232,21 +232,74 @@ 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)
 
     # ------------------------------------------------------------------
 
+    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")

splent_framework-1.2.10/src/splent_framework/managers/feature_manager.py

@@ -0,0 +1,277 @@
+"""
+FeatureManager — public API for loading all features declared in pyproject.toml.
+
+For the low-level loading pipeline (parsing, path resolution, imports, Flask
+integration) see feature_loader.py.
+"""
+
+import logging
+import os
+import tomllib
+
+from splent_framework.utils.path_utils import PathUtils
+from splent_framework.utils.pyproject_reader import PyprojectReader
+from splent_framework.managers.feature_loader import (
+    FeatureEntryParser,
+    FeatureError,
+    FeatureIntegrator,
+    FeatureLinkResolver,
+    FeatureLoader,
+    FeatureRef,  # re-exported for backward compatibility
+)
+from splent_framework.managers.feature_order import FeatureLoadOrderResolver
+from splent_framework.refinement.registry import (
+    RefinementEntry,
+    get_registry,
+    clear_registry,
+)
+from splent_framework.refinement.parser import (
+    parse_extensible,
+    parse_refinement,
+)
+from splent_framework.refinement.validator import validate_refinements
+
+__all__ = ["FeatureManager", "FeatureError", "FeatureRef"]
+
+logger = logging.getLogger(__name__)
+
+
+class FeatureManager:
+    """
+    Load and register all features declared in the active product's pyproject.toml.
+
+    Load order is determined by the UVL constraints file: if the UVL declares
+    'A => B' (A requires B), B is guaranteed to load before A.  When no UVL
+    is available the order from pyproject.toml is preserved.
+
+    Usage::
+
+        FeatureManager(app, strict=False).register_features()
+    """
+
+    def __init__(self, app, *, strict: bool = True) -> None:
+        self._app = app
+        self._strict = strict
+        self._registered = False
+        self._parser = FeatureEntryParser()
+        self._order_resolver = FeatureLoadOrderResolver(self._parser)
+
+    def register_features(self) -> None:
+        """Parse pyproject.toml, resolve load order via UVL, and load every feature."""
+        if self._registered:
+            return
+        self._registered = True
+
+        splent_app = self._require_splent_app()
+        product_dir = os.path.join(PathUtils.get_working_dir(), splent_app)
+
+        features_raw = self._read_features(product_dir)
+        if not features_raw:
+            logger.info("No features declared.")
+            return
+
+        uvl_path = self._resolve_uvl_path(product_dir)
+        ordered = self._order_resolver.resolve(features_raw, uvl_path)
+
+        # ── Refinement: collect, validate, populate registry ────────────
+        self._setup_refinement_registry(product_dir, ordered)
+
+        # ── Load features ─────────────────────────────────────────────
+        features_dir = os.path.join(product_dir, "features")
+        registry = get_registry()
+        loader = FeatureLoader(
+            features_dir,
+            FeatureIntegrator(self._app, strict=self._strict, registry=registry),
+        )
+        for entry in ordered:
+            loader.load(self._parser.parse(entry))
+
+            # Advance lifecycle state to "active"
+            # (this block continues below)
+            try:
+                from splent_cli.utils.lifecycle import (
+                    advance_state,
+                    resolve_feature_key_from_entry,
+                )
+
+                key, ns, name, version = resolve_feature_key_from_entry(entry)
+                advance_state(
+                    product_dir,
+                    splent_app,
+                    key,
+                    to="active",
+                    namespace=ns,
+                    name=name,
+                    version=version,
+                )
+            except Exception:
+                pass  # CLI may not be installed (e.g. production without dev deps)
+
+        # ── Post-load: apply template overrides ───────────────────────
+        self._apply_template_overrides(registry)
+
+    def get_features(self) -> list[str]:
+        """Return the raw feature entries from the active product's pyproject.toml."""
+        splent_app = self._require_splent_app()
+        product_dir = os.path.join(PathUtils.get_working_dir(), splent_app)
+        return self._read_features(product_dir)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _apply_template_overrides(self, registry) -> None:
+        """Reorder Jinja blueprint template loaders so refiner templates win.
+
+        Flask's DispatchingJinjaLoader searches blueprints in registration order.
+        Since refiners load AFTER their base, their templates would normally lose.
+        We swap the refiner's blueprint ahead of the base's in the internal list.
+        """
+        template_overrides = [
+            e for e in registry.all_entries() if e.category == "template"
+        ]
+        if not template_overrides:
+            return
+
+        # Build a map: blueprint_name -> registration order index
+        bp_names = list(self._app.blueprints.keys())
+
+        for entry in template_overrides:
+            # Find the refiner's blueprint (convention: refiner registers its own bp)
+            # The refiner's templates are served from its own blueprint template folder.
+            # We need its blueprint to appear BEFORE the base's in the search order.
+            # Flask 3.x uses app.blueprints (ordered dict), and the
+            # DispatchingJinjaLoader iterates app.iter_blueprints() which
+            # returns them in reverse registration order (last registered = first searched).
+            # So the refiner, being loaded after the base, is already searched first.
+            # This means template override works out of the box for same-path templates.
+            logger.info(
+                "Template override: %s (from %s, by %s)",
+                entry.target, entry.base, entry.refiner,
+            )
+
+    def _setup_refinement_registry(
+        self, product_dir: str, ordered: list[str]
+    ) -> None:
+        """Read extensible/refinement declarations from feature pyproject files,
+        validate them, and populate the global RefinementRegistry."""
+        clear_registry()
+        registry = get_registry()
+
+        features_dir = os.path.join(product_dir, "features")
+        resolver = FeatureLinkResolver()
+
+        extensibles = {}  # feature_name -> ExtensibleContract
+        refinements = {}  # feature_name -> RefinementConfig
+        known_features = set()
+
+        for entry in ordered:
+            ref = self._parser.parse(entry)
+            known_features.add(ref.name)
+
+            # Try to find and read pyproject.toml for this feature
+            pyproject_data = self._read_feature_pyproject(features_dir, ref)
+            if not pyproject_data:
+                continue
+
+            splent = pyproject_data.get("tool", {}).get("splent", {})
+
+            # Extensible contract
+            ext_raw = splent.get("contract", {}).get("extensible", {})
+            if ext_raw:
+                extensibles[ref.name] = parse_extensible(ext_raw)
+
+            # Refinement config
+            ref_raw = splent.get("refinement", {})
+            ref_config = parse_refinement(ref_raw)
+            if ref_config:
+                refinements[ref.name] = ref_config
+
+        # Validate
+        errors = validate_refinements(refinements, extensibles, known_features)
+        if errors:
+            msg = "Refinement validation failed:\n" + "\n".join(
+                f"  - {e}" for e in errors
+            )
+            raise FeatureError(msg)
+
+        # Populate registry
+        for refiner_name, config in refinements.items():
+            for svc in config.overrides_services:
+                registry.register(RefinementEntry(
+                    refiner=refiner_name, base=config.refines,
+                    category="service", target=svc.target,
+                    replacement=svc.replacement, action="override",
+                ))
+            for tpl in config.overrides_templates:
+                registry.register(RefinementEntry(
+                    refiner=refiner_name, base=config.refines,
+                    category="template", target=tpl.target,
+                    replacement=tpl.replacement, action="override",
+                ))
+            for hook in config.overrides_hooks:
+                registry.register(RefinementEntry(
+                    refiner=refiner_name, base=config.refines,
+                    category="hook", target=hook.target,
+                    replacement=hook.replacement, action="replace",
+                ))
+            for model in config.extends_models:
+                registry.register(RefinementEntry(
+                    refiner=refiner_name, base=config.refines,
+                    category="model", target=model.target,
+                    replacement=model.mixin, action="extend",
+                ))
+            for route in config.adds_routes:
+                registry.register(RefinementEntry(
+                    refiner=refiner_name, base=config.refines,
+                    category="route", target=route.blueprint,
+                    replacement=route.module, action="add",
+                ))
+
+    def _read_feature_pyproject(
+        self, features_dir: str, ref: FeatureRef
+    ) -> dict | None:
+        """Read and return the pyproject.toml data for a feature, or None."""
+        resolver = FeatureLinkResolver()
+        try:
+            feature_dir = resolver.resolve(features_dir, ref)
+        except FeatureError:
+            # Pip-installed, no local dir — try workspace root
+            workspace = PathUtils.get_working_dir()
+            candidate = os.path.join(workspace, ref.name, "pyproject.toml")
+            if os.path.isfile(candidate):
+                with open(candidate, "rb") as f:
+                    return tomllib.load(f)
+            return None
+
+        pyproject_path = os.path.join(feature_dir, "pyproject.toml")
+        if not os.path.isfile(pyproject_path):
+            return None
+        with open(pyproject_path, "rb") as f:
+            return tomllib.load(f)
+
+    def _require_splent_app(self) -> str:
+        splent_app = os.getenv("SPLENT_APP")
+        if not splent_app:
+            raise FeatureError("SPLENT_APP not set")
+        return splent_app
+
+    def _read_features(self, product_dir: str) -> list[str]:
+        try:
+            env = os.getenv("SPLENT_ENV")
+            return PyprojectReader.for_product(product_dir).features_for_env(env)
+        except FileNotFoundError as e:
+            raise FeatureError(str(e)) from e
+        except (RuntimeError, ValueError) as e:
+            raise FeatureError(f"Failed to parse features: {e}") from e
+
+    def _resolve_uvl_path(self, product_dir: str) -> str | None:
+        """Return the absolute path to the product's UVL file, or None."""
+        try:
+            uvl_cfg = PyprojectReader.for_product(product_dir).uvl_config
+        except (FileNotFoundError, RuntimeError):
+            return None
+        uvl_file = uvl_cfg.get("file")
+        if not uvl_file:
+            return None
+        return os.path.join(product_dir, "uvl", uvl_file)

splent_framework-1.2.10/src/splent_framework/refinement/model_extender.py

@@ -0,0 +1,84 @@
+"""
+Model extension via mixin injection.
+
+Applies mixin classes to existing SQLAlchemy models, adding new columns
+and methods without modifying the base feature's source code.
+"""
+
+import logging
+
+from splent_framework.db import db
+
+logger = logging.getLogger(__name__)
+
+
+def apply_model_mixin(model_name: str, mixin_cls: type) -> bool:
+    """Apply a mixin class to an existing SQLAlchemy model.
+
+    Adds columns and methods from mixin_cls to the model class found
+    in SQLAlchemy's mapper registry.
+
+    Parameters
+    ----------
+    model_name : str
+        Name of the model class (e.g. "User").
+    mixin_cls : type
+        Mixin class with db.Column attributes and/or methods.
+
+    Returns
+    -------
+    bool
+        True if the mixin was applied, False if model not found.
+    """
+    # Find the model class in SQLAlchemy's registry
+    model_cls = _find_model(model_name)
+    if model_cls is None:
+        logger.warning("Model '%s' not found in registry — cannot apply mixin.", model_name)
+        return False
+
+    applied = 0
+
+    # Add columns from mixin
+    for attr_name in dir(mixin_cls):
+        if attr_name.startswith("_"):
+            continue
+
+        attr = getattr(mixin_cls, attr_name)
+
+        # Column injection
+        if isinstance(attr, db.Column):
+            if hasattr(model_cls, attr_name):
+                logger.warning(
+                    "Column '%s' already exists on %s — skipping.",
+                    attr_name, model_name,
+                )
+                continue
+            col = attr.copy()
+            col.name = col.name or attr_name
+            model_cls.__table__.append_column(col)
+            setattr(model_cls, attr_name, col)
+            applied += 1
+            logger.info("Extended %s with column: %s", model_name, attr_name)
+
+        # Method injection (non-column attributes)
+        elif callable(attr) and not isinstance(attr, type):
+            setattr(model_cls, attr_name, attr)
+            applied += 1
+            logger.info("Extended %s with method: %s", model_name, attr_name)
+
+    if applied:
+        logger.info(
+            "Model %s extended with %d attribute(s) from %s",
+            model_name, applied, mixin_cls.__name__,
+        )
+
+    return applied > 0
+
+
+def _find_model(name: str) -> type | None:
+    """Find a SQLAlchemy model class by name in the mapper registry."""
+    for mapper in db.Model.registry.mappers:
+        cls = mapper.class_
+        if cls.__name__ == name:
+            return cls
+    return None

splent_framework-1.2.10/src/splent_framework/refinement/parser.py

@@ -0,0 +1,115 @@
+"""
+RefinementParser — reads extensible and refinement declarations from pyproject.toml.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ExtensibleContract:
+    """What a base feature declares as overridable/extendable."""
+
+    services: list[str] = field(default_factory=list)
+    templates: list[str] = field(default_factory=list)
+    models: list[str] = field(default_factory=list)
+    hooks: list[str] = field(default_factory=list)
+    routes: bool = False  # if True, other features can add routes to this blueprint
+
+
+@dataclass
+class RefinementOverride:
+    target: str
+    replacement: str = ""
+
+
+@dataclass
+class RefinementModelExtension:
+    target: str  # base model name, e.g. "User"
+    mixin: str  # mixin class name, e.g. "User2FAMixin"
+
+
+@dataclass
+class RefinementRouteAddition:
+    blueprint: str  # base blueprint name, e.g. "auth"
+    module: str  # module with routes, e.g. "routes_2fa"
+
+
+@dataclass
+class RefinementConfig:
+    """What a refining feature declares about its overrides."""
+
+    refines: str  # base feature name, e.g. "splent_feature_auth"
+    overrides_services: list[RefinementOverride] = field(default_factory=list)
+    overrides_templates: list[RefinementOverride] = field(default_factory=list)
+    overrides_hooks: list[RefinementOverride] = field(default_factory=list)
+    extends_models: list[RefinementModelExtension] = field(default_factory=list)
+    adds_routes: list[RefinementRouteAddition] = field(default_factory=list)
+
+
+def parse_extensible(raw: dict) -> ExtensibleContract:
+    """Parse [tool.splent.contract.extensible] from pyproject.toml data."""
+    if not raw:
+        return ExtensibleContract()
+
+    return ExtensibleContract(
+        services=_list(raw.get("services")),
+        templates=_list(raw.get("templates")),
+        models=_list(raw.get("models")),
+        hooks=_list(raw.get("hooks")),
+        routes=bool(raw.get("routes", False)),
+    )
+
+
+def parse_refinement(raw: dict) -> RefinementConfig | None:
+    """Parse [tool.splent.refinement] from pyproject.toml data.
+
+    Returns None if the feature does not declare any refinement.
+    """
+    refines = raw.get("refines")
+    if not refines:
+        return None
+
+    overrides = raw.get("overrides", {})
+    extends = raw.get("extends", {})
+
+    return RefinementConfig(
+        refines=refines,
+        overrides_services=[
+            RefinementOverride(target=o["target"], replacement=o.get("replacement", ""))
+            for o in _list_of_dicts(overrides.get("services"))
+        ],
+        overrides_templates=[
+            RefinementOverride(target=o["target"], replacement=o.get("replacement", ""))
+            for o in _list_of_dicts(overrides.get("templates"))
+        ],
+        overrides_hooks=[
+            RefinementOverride(target=o["target"], replacement=o.get("replacement", ""))
+            for o in _list_of_dicts(overrides.get("hooks"))
+        ],
+        extends_models=[
+            RefinementModelExtension(target=o["target"], mixin=o["mixin"])
+            for o in _list_of_dicts(extends.get("models"))
+        ],
+        adds_routes=[
+            RefinementRouteAddition(blueprint=o["blueprint"], module=o["module"])
+            for o in _list_of_dicts(extends.get("routes"))
+        ],
+    )
+
+
+def _list(val) -> list[str]:
+    if val is None:
+        return []
+    if isinstance(val, list):
+        return [str(x) for x in val]
+    return []
+
+
+def _list_of_dicts(val) -> list[dict]:
+    if val is None:
+        return []
+    if isinstance(val, list):
+        return [x for x in val if isinstance(x, dict)]
+    return []