splent-framework 1.6.2__tar.gz → 1.7.1__tar.gz

{splent_framework-1.6.2/src/splent_framework.egg-info → splent_framework-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_framework
-Version: 1.6.2
+Version: 1.7.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

{splent_framework-1.6.2 → splent_framework-1.7.1}/pyproject.toml

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

splent_framework-1.7.1/src/splent_framework/__init__.py

@@ -0,0 +1,3 @@
+from splent_framework.app_factory import create_splent_app
+
+__all__ = ["create_splent_app"]

splent_framework-1.7.1/src/splent_framework/admin/__init__.py

@@ -0,0 +1,29 @@
+"""Admin resource registry — declare how models surface in the admin panel.
+
+A content feature registers its model with :func:`register_admin_resource`
+(typically from ``init_feature``); the ``admin`` feature reads the registry to
+build a grouped, wp-admin-style menu and CRUD screens. Mirrors the singleton
+pattern of ``splent_framework.hooks.template_hooks``.
+"""
+
+from splent_framework.admin.registry import (
+    WIDGETS,
+    AdminResource,
+    clear_admin_resources,
+    get_admin_groups,
+    get_admin_resource,
+    get_admin_resource_for_model,
+    get_admin_resources,
+    register_admin_resource,
+)
+
+__all__ = [
+    "WIDGETS",
+    "AdminResource",
+    "register_admin_resource",
+    "get_admin_resource",
+    "get_admin_resource_for_model",
+    "get_admin_resources",
+    "get_admin_groups",
+    "clear_admin_resources",
+]

splent_framework-1.7.1/src/splent_framework/admin/registry.py

@@ -0,0 +1,149 @@
+# splent_framework/admin/registry.py
+#
+# Admin resource registry — the analogue of WordPress `register_post_type`.
+#
+# A content feature registers its model as an *admin resource*, declaring how it
+# should appear in the admin panel (label, icon, menu group, list columns,
+# per-field widgets). The `admin` feature reads this registry to build a curated,
+# grouped, wp-admin-style menu and CRUD screens — instead of dumping every
+# `db.Model` subclass in a flat list.
+#
+# NOTE: _resources is a module-level registry populated once at app startup
+# (during feature registration / init_feature) and read-only during request
+# handling — same contract as template_hooks.py. Not thread-safe for concurrent
+# writes; do not call register_admin_resource() from request handlers.
+
+from dataclasses import dataclass, field
+
+# Widget hints the admin form renderer understands. Features may pass any of
+# these per column via `field_widgets`; unknown columns fall back to an
+# introspection-derived default chosen by the admin feature.
+WIDGETS = (
+    "text",  # single-line string
+    "textarea",  # multi-line plain text
+    "richtext",  # WYSIWYG / HTML body
+    "number",
+    "bool",
+    "date",
+    "datetime",
+    "select",  # enum / fixed choices
+    "fk",  # foreign key -> related record picker
+    "image",  # media id / upload
+    "url",
+    "slug",
+    "color",
+)
+
+
+@dataclass
+class AdminResource:
+    """Metadata describing how a model is administered in the admin panel."""
+
+    model: type
+    name: str  # url-safe key, e.g. "project"
+    label: str  # singular human label, e.g. "Project"
+    label_plural: str  # e.g. "Projects"
+    icon: str = "file"  # feather icon name used in the menu
+    group: str = "Content"  # menu section this resource is filed under
+    order: int = 100  # sort order within the group
+    list_columns: list[str] | None = None  # None -> admin auto-picks
+    search_fields: list[str] = field(default_factory=list)
+    field_widgets: dict[str, str] = field(default_factory=dict)  # column -> WIDGETS
+    readonly_fields: list[str] = field(default_factory=list)
+    scope: dict = field(default_factory=dict)  # query filter — lets one shared
+    #                                                      table back several menu entries
+    #                                                      (e.g. {"collection": "event"})
+    create_defaults: dict = field(
+        default_factory=dict
+    )  # column values forced on create
+    feature: str | None = None  # owning feature short name (provenance)
+
+    @property
+    def model_name(self) -> str:
+        """The SQLAlchemy class name — the key the CRUD routes resolve by."""
+        return self.model.__name__
+
+
+# Module-level singleton registry (keyed by resource `name`).
+_resources: dict[str, AdminResource] = {}
+
+
+def register_admin_resource(
+    model: type,
+    *,
+    name: str | None = None,
+    label: str | None = None,
+    label_plural: str | None = None,
+    icon: str = "file",
+    group: str = "Content",
+    order: int = 100,
+    list_columns: list[str] | None = None,
+    search_fields: list[str] | None = None,
+    field_widgets: dict[str, str] | None = None,
+    readonly_fields: list[str] | None = None,
+    scope: dict | None = None,
+    create_defaults: dict | None = None,
+    feature: str | None = None,
+) -> AdminResource:
+    """Register a model as an administered resource (additive, idempotent by name).
+
+    Call from a feature's ``init_feature(app)``. The owning content feature thus
+    declares its admin surface once; the admin panel renders it. Re-registering
+    the same ``name`` overrides the previous entry (last registration wins), which
+    lets a refinement feature curate another feature's resource.
+    """
+    key = name or model.__name__.lower()
+    resolved_label = label or model.__name__
+    res = AdminResource(
+        model=model,
+        name=key,
+        label=resolved_label,
+        label_plural=label_plural or f"{resolved_label}s",
+        icon=icon,
+        group=group,
+        order=order,
+        list_columns=list_columns,
+        search_fields=search_fields or [],
+        field_widgets=field_widgets or {},
+        readonly_fields=readonly_fields or [],
+        scope=scope or {},
+        create_defaults=create_defaults or {},
+        feature=feature,
+    )
+    _resources[key] = res
+    return res
+
+
+def get_admin_resource(name: str) -> AdminResource | None:
+    """Return a single registered resource by its url-safe name, or None."""
+    return _resources.get(name)
+
+
+def get_admin_resource_for_model(model_name: str) -> AdminResource | None:
+    """Return the resource whose model class name matches ``model_name``."""
+    for res in _resources.values():
+        if res.model_name == model_name:
+            return res
+    return None
+
+
+def get_admin_resources() -> dict[str, AdminResource]:
+    """Return all registered resources keyed by name (insertion order)."""
+    return dict(_resources)
+
+
+def get_admin_groups() -> dict[str, list[AdminResource]]:
+    """Return resources bucketed by menu group, each sorted by (order, label).
+
+    This is what the admin sidebar iterates to render a grouped, wp-admin-style
+    menu (a section per group, content types listed underneath).
+    """
+    groups: dict[str, list[AdminResource]] = {}
+    for res in sorted(_resources.values(), key=lambda r: (r.order, r.label)):
+        groups.setdefault(res.group, []).append(res)
+    return groups
+
+
+def clear_admin_resources() -> None:
+    """Remove all registered resources. Intended for test teardown."""
+    _resources.clear()

splent_framework-1.7.1/src/splent_framework/assets/asset_registry.py

@@ -0,0 +1,68 @@
+# splent_framework/assets/asset_registry.py
+#
+# SPL asset registry. Features DECLARE their stylesheets/scripts here (from
+# init_feature) instead of hand-writing <link>/<script> tags in hooks or
+# inlining JS into templates. The public shell renders get_assets("css") in
+# <head> and get_assets("js") before </body>, DEDUPLICATED and ORDERED — so the
+# cascade is deterministic and asset injection is consistent across features.
+# No ad-hoc tags, no inline scripts: a feature ships a file under its blueprint's
+# assets/ folder (served by the blueprint asset route) and registers it here.
+#
+# Cleared per app at feature-load (like the nav registry) so each product only
+# emits the assets of ITS installed features. Registration is idempotent.
+
+_assets: list = []
+
+
+def register_asset(kind: str, endpoint: str, order: int = 100, **params) -> None:
+    """Declare a static asset served by a feature blueprint's asset route.
+
+    Args:
+        kind: "css" or "js".
+        endpoint: the blueprint asset endpoint, e.g. "slider.assets".
+        order: load order (lower first) — governs the cascade deterministically.
+            Convention: theme base ~0, features ~100, skins ~200 (win last).
+        **params: url_for params for the asset route, e.g.
+            subfolder="css", filename="slider.css".
+    """
+    key = (kind, endpoint, tuple(sorted(params.items())))
+    for a in _assets:
+        if a["key"] == key:
+            return
+    _assets.append(
+        {
+            "key": key,
+            "kind": kind,
+            "endpoint": endpoint,
+            "params": params,
+            "order": order,
+        }
+    )
+
+
+def get_assets(kind: str) -> list:
+    """Resolved asset URLs of a kind, ordered by (order, endpoint) and deduped.
+
+    url_for is resolved at call time, so invoke this from the template (request
+    context). Assets whose route can't be resolved are skipped, not raised.
+    """
+    from flask import url_for
+
+    seen = set()
+    out = []
+    for a in sorted(_assets, key=lambda x: (x["order"], x["endpoint"])):
+        if a["kind"] != kind:
+            continue
+        try:
+            href = url_for(a["endpoint"], **a["params"])
+        except Exception:
+            continue
+        if href not in seen:
+            seen.add(href)
+            out.append(href)
+    return out
+
+
+def clear_assets() -> None:
+    """Drop all registered assets. Called per app before feature load."""
+    _assets.clear()

splent_framework-1.7.1/src/splent_framework/bootstraps/locustfile_bootstrap.py

@@ -0,0 +1,157 @@
+"""Default Locust entry point: load every feature's locustfile at once.
+
+Locust is pointed at this module when no ``-f`` names a specific file. It
+discovers the locustfiles a product ships, imports them, and re-exports the
+``HttpUser`` subclasses it finds so Locust can offer them all.
+
+Discovery covers the layouts SPLENT products actually use:
+
+* ``app/features/<feature>/tests/locustfile.py`` — a product that keeps its
+  features inside the application package.
+* ``features/<namespace>/<feature>/**/tests/load/locustfile.py`` — a product
+  composed from installed feature packages. These entries are symlinks into
+  the workspace or the feature cache, so discovery follows symlinks.
+
+Set ``SPLENT_LOCUSTFILES`` to override discovery entirely: a comma-separated
+list of glob patterns, relative to ``WORKING_DIR`` unless absolute. Use it when
+a product keeps its load tests somewhere else.
+"""
+
+import glob
+import importlib.util
+import inspect
+import logging
+import os
+
+from dotenv import load_dotenv
+from locust import HttpUser
+
+logger = logging.getLogger(__name__)
+
+# Relative to WORKING_DIR. Ordered from cheapest to widest.
+DEFAULT_PATTERNS = (
+    "app/features/*/tests/locustfile.py",
+    "features/*/*/tests/load/locustfile.py",
+    "features/*/*/tests/locustfile.py",
+    "features/*/*/src/*/*/tests/load/locustfile.py",
+)
+
+# Never descend into these while following symlinked feature directories.
+PRUNED_DIRS = frozenset(
+    {
+        ".git",
+        ".venv",
+        "venv",
+        "node_modules",
+        "__pycache__",
+        ".splent_cache",
+        "dist",
+        "build",
+    }
+)
+
+
+def _configured_patterns() -> list[str] | None:
+    raw = os.getenv("SPLENT_LOCUSTFILES", "").strip()
+    if not raw:
+        return None
+    return [p.strip() for p in raw.split(",") if p.strip()]
+
+
+def _walk_for_locustfiles(root: str) -> list[str]:
+    """Find locustfile.py under root, following symlinks.
+
+    glob's ``**`` does not descend into symlinked directories, and a composed
+    product links every feature in, so the recursive search is done by hand.
+    """
+    found = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=True):
+        dirnames[:] = [d for d in dirnames if d not in PRUNED_DIRS]
+        if "locustfile.py" in filenames:
+            found.append(os.path.join(dirpath, "locustfile.py"))
+    return found
+
+
+def discover_locustfiles() -> list[str]:
+    """Return the locustfile paths for this product, deduplicated and sorted."""
+    working_dir = os.getenv("WORKING_DIR", "")
+
+    patterns = _configured_patterns()
+    if patterns is not None:
+        logger.debug("SPLENT_LOCUSTFILES set, using %s", patterns)
+    else:
+        patterns = list(DEFAULT_PATTERNS)
+
+    paths: set[str] = set()
+    for pattern in patterns:
+        absolute = (
+            pattern if os.path.isabs(pattern) else os.path.join(working_dir, pattern)
+        )
+        paths.update(glob.glob(absolute))
+
+    # A composed product links its features in, and the depth of the locustfile
+    # inside each one varies with how the feature was installed, so walk them.
+    features_root = os.path.join(working_dir, "features")
+    if _configured_patterns() is None and os.path.isdir(features_root):
+        paths.update(_walk_for_locustfiles(features_root))
+
+    resolved = sorted({os.path.realpath(p) for p in paths})
+    logger.debug("Discovered locustfiles: %s", resolved)
+    return resolved
+
+
+def _module_name_for(path: str) -> str:
+    """A name unique per feature, so two locustfiles cannot shadow each other.
+
+    Walks up past the test directories, so both
+    ``<feature>/tests/locustfile.py`` and ``<feature>/tests/load/locustfile.py``
+    resolve to the feature's own name.
+    """
+    parts = os.path.dirname(path).split(os.sep)
+    while parts and parts[-1] in ("load", "tests", "test", "src"):
+        parts.pop()
+    name = parts[-1] if parts else "feature"
+    return f"splent_locustfile_{name}"
+
+
+def load_locustfiles():
+    load_dotenv()
+
+    locustfile_paths = discover_locustfiles()
+    found_user_classes = []
+
+    for path in locustfile_paths:
+        logger.debug("Loading locustfile: %s", path)
+        spec = importlib.util.spec_from_file_location(_module_name_for(path), path)
+        locustfile = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(locustfile)
+        except Exception:
+            logger.exception("Skipping locustfile that failed to import: %s", path)
+            continue
+
+        for name, obj in vars(locustfile).items():
+            if (
+                inspect.isclass(obj)
+                and issubclass(obj, HttpUser)
+                and obj is not HttpUser
+            ):
+                unique_name = f"{name}_{_module_name_for(path)}"
+                globals()[unique_name] = obj
+                found_user_classes.append((unique_name, obj))
+                logger.debug("Loaded user class: %s", unique_name)
+
+    if not found_user_classes:
+        raise ValueError(
+            "No User class found. Looked for locustfiles under "
+            f"{os.getenv('WORKING_DIR', '') or '.'} using patterns "
+            f"{_configured_patterns() or list(DEFAULT_PATTERNS)}. "
+            "Set SPLENT_LOCUSTFILES to a comma-separated list of glob patterns "
+            "if this product keeps them somewhere else."
+        )
+
+    return found_user_classes
+
+
+found_user_classes = load_locustfiles()
+logger.info("Total user classes loaded: %d", len(found_user_classes))

{splent_framework-1.6.2 → splent_framework-1.7.1}/src/splent_framework/environment/host.py

@@ -59,7 +59,17 @@ def get_host_for_selenium_testing() -> str:
     """
     Get the host URL for selenium testing.
 
+    ``SELENIUM_TARGET_URL`` wins when set. It is needed whenever the browser
+    runs somewhere other than the machine running the tests, typically a
+    selenium grid node: the URL is resolved by the browser, so the default
+    ``localhost`` would point the browser at itself instead of at the
+    application. Set it to a host the browser container can reach, such as the
+    web or proxy container name.
+
     Returns:
     str: The host URL for selenium testing.
     """
+    override = os.getenv("SELENIUM_TARGET_URL")
+    if override:
+        return override
     return get_host_for_testing("selenium")

splent_framework-1.7.1/src/splent_framework/hooks/template_hooks.py

@@ -0,0 +1,43 @@
+# splent_framework/template_hooks.py
+#
+# NOTE: _hooks is a module-level registry populated once at app startup
+# (during feature registration) and read-only during request handling.
+# It is NOT thread-safe for concurrent writes; do not call
+# register_template_hook() from request handlers or background threads.
+
+# Each slot holds (order, func) pairs; get_template_hooks returns the funcs
+# sorted by order (lower first), so slots like "home.section" compose features
+# in a deterministic order regardless of feature load order.
+_hooks: dict[str, list] = {}
+
+
+def register_template_hook(name: str, func, order: int = 100) -> None:
+    """Append a callback to a named hook slot (additive).
+
+    order: lower renders first within the slot (default 100).
+    """
+    _hooks.setdefault(name, []).append((order, func))
+
+
+def replace_template_hook(name: str, func, order: int = 100) -> None:
+    """Replace ALL existing callbacks for a named hook slot.
+
+    Used by refinement features to override a base feature's hook content.
+    """
+    _hooks[name] = [(order, func)]
+
+
+def remove_template_hook(name: str, func) -> None:
+    """Remove a specific callback from a hook slot."""
+    if name in _hooks:
+        _hooks[name] = [(o, f) for (o, f) in _hooks[name] if f is not func]
+
+
+def get_template_hooks(name: str) -> list:
+    """Callbacks for a slot, ordered by their registration `order`."""
+    return [f for _, f in sorted(_hooks.get(name, []), key=lambda pair: pair[0])]
+
+
+def clear_hooks() -> None:
+    """Remove all registered hooks. Intended for use in test teardown."""
+    _hooks.clear()

{splent_framework-1.6.2 → splent_framework-1.7.1}/src/splent_framework/managers/feature_loader.py

@@ -248,6 +248,7 @@ class FeatureIntegrator:
         self._call_init(module, import_name)
         self._apply_service_overrides(import_name)
         self._register_blueprints(module, import_name)
+        self._register_context_vars(module, import_name)
         self._register_translations(module, import_name)
         self._register_commands(import_name)
 
@@ -358,6 +359,19 @@ class FeatureIntegrator:
         elif self._strict:
             raise FeatureError(f"{import_name} lacks init_feature(app)")
 
+    def _register_context_vars(self, module, import_name: str) -> None:
+        """Collect the feature's ``inject_context_vars`` so the JinjaManager
+        context processor merges its returned dict into every template's context
+        on each request (see docs: framework/template-system, framework/
+        feature-loading). Without this the function is never called.
+        """
+        fn = getattr(module, "inject_context_vars", None)
+        if fn is None:
+            return
+        if not hasattr(self._app, "context_processors"):
+            self._app.context_processors = []
+        self._app.context_processors.append(fn)
+
     def _register_blueprints(self, module, import_name: str) -> None:
         candidates = self._collect_candidate_modules(module, import_name)
         registered = sum(

{splent_framework-1.6.2 → splent_framework-1.7.1}/src/splent_framework/managers/feature_manager.py

@@ -62,6 +62,18 @@ class FeatureManager:
             return
         self._registered = True
 
+        # The nav and asset registries are process-global; clear them before
+        # loading so the composed menu / injected assets reflect ONLY this
+        # product's installed features (no leakage when several products'
+        # create_app() run in one interpreter).
+        from splent_framework.assets.asset_registry import clear_assets
+        from splent_framework.nav.nav_registry import clear_nav_items
+        from splent_framework.settings.settings_schema import clear_settings_schemas
+
+        clear_nav_items()
+        clear_assets()
+        clear_settings_schemas()
+
         splent_app = self._require_splent_app()
         product_dir = os.path.join(PathUtils.get_working_dir(), splent_app)
 
@@ -121,27 +133,33 @@ class FeatureManager:
     # ------------------------------------------------------------------
 
     def _apply_template_overrides(self, registry) -> None:
-        """Reorder Jinja blueprint template loaders so refiner templates win.
+        """Make refiner templates win over the base feature's same-path templates.
 
-        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.
+        Flask's DispatchingJinjaLoader searches blueprints in REGISTRATION order
+        (first registered wins), and a refiner loads AFTER its base — so the base
+        template would win. We prepend each refiner's template folder to the
+        app's Jinja loader so its override is resolved first.
         """
+        from jinja2 import ChoiceLoader, FileSystemLoader
+
         template_overrides = [
             e for e in registry.all_entries() if e.category == "template"
         ]
         if not template_overrides:
             return
 
+        app = self._app
+        folders: list[str] = []
+        seen: set[str] = set()
         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.
+            short = entry.refiner.replace("splent_feature_", "")
+            bp = app.blueprints.get(short)
+            if bp is None or not bp.template_folder:
+                continue
+            folder = os.path.join(bp.root_path, bp.template_folder)
+            if folder not in seen and os.path.isdir(folder):
+                seen.add(folder)
+                folders.append(folder)
             logger.info(
                 "Template override: %s (from %s, by %s)",
                 entry.target,
@@ -149,6 +167,11 @@ class FeatureManager:
                 entry.refiner,
             )
 
+        if folders:
+            app.jinja_env.loader = ChoiceLoader(
+                [FileSystemLoader(folders), app.jinja_env.loader]
+            )
+
     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."""

{splent_framework-1.6.2 → splent_framework-1.7.1}/src/splent_framework/managers/jinja_manager.py

@@ -1,4 +1,5 @@
 from flask import Flask
+from splent_framework.assets.asset_registry import get_assets
 from splent_framework.context.context_manager import build_jinja_context
 from splent_framework.hooks.template_hooks import get_template_hooks
 
@@ -17,3 +18,4 @@ class JinjaManager:
 
     def _register_globals(self):
         self.app.jinja_env.globals["get_template_hooks"] = get_template_hooks
+        self.app.jinja_env.globals["get_assets"] = get_assets

{splent_framework-1.6.2 → splent_framework-1.7.1}/src/splent_framework/managers/locale_manager.py

@@ -72,9 +72,15 @@ class LocaleManager:
         if translations_dir not in dirs:
             dirs.append(translations_dir)
 
-            # Babel supports multiple translation directories
-            babel = app.extensions.get("splent_babel")
-            if babel and hasattr(babel, "translation_directories"):
-                babel.translation_directories.append(translations_dir)
+            # flask-babel computes its translation directories ONCE in init_app
+            # (BabelConfiguration.translation_directories) and never re-reads the
+            # config. Features load AFTER Babel is initialised, so we (1) keep the
+            # config in sync and (2) mutate the live BabelConfiguration list
+            # (app.extensions["babel"]) so the new directory actually takes effect.
+            app.config["BABEL_TRANSLATION_DIRECTORIES"] = ";".join(dirs)
+            babel_cfg = app.extensions.get("babel")
+            live = getattr(babel_cfg, "translation_directories", None)
+            if isinstance(live, list) and translations_dir not in live:
+                live.append(translations_dir)
 
             logger.debug("Registered translations: %s", translations_dir)