splent-cli 1.41.0__tar.gz → 1.42.0__tar.gz

{splent_cli-1.41.0/src/splent_cli.egg-info → splent_cli-1.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.41.0
+Version: 1.42.0
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 License-Expression: LGPL-3.0-or-later

{splent_cli-1.41.0 → splent_cli-1.42.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "splent_cli"
-version = "1.41.0"
+version = "1.42.0"
 description = "SPLENT-CLI is a CLI to be able to work on your development more easily."
 readme = "README.md"
 requires-python = ">=3.13"

{splent_cli-1.41.0 → splent_cli-1.42.0}/src/splent_cli/cli.py

@@ -1,3 +1,4 @@
+import contextlib
 import logging
 import os
 
@@ -20,6 +21,27 @@ def _missing_module(exc: BaseException) -> str | None:
     return None
 
 
+@contextlib.contextmanager
+def _quiet_unless(debug: bool):
+    """The framework's logging muted while the app is built for discovery.
+
+    Discovery runs before every command, including the ones a product that
+    is not built yet (selected, not configured or derived) runs while
+    getting there. Building its app then fails, and the framework logged
+    that failure with a full traceback on every single command, although
+    nothing was wrong. The failure is expected there and handled, so the
+    framework's logging is muted for the attempt.
+    """
+    if debug:
+        yield
+        return
+    logging.disable(logging.CRITICAL)
+    try:
+        yield
+    finally:
+        logging.disable(logging.NOTSET)
+
+
 class SPLENTCLI(click.Group):
     """
     Main SPLENT CLI class.
@@ -27,6 +49,7 @@ class SPLENTCLI(click.Group):
     - Automatically injects the Flask app context for commands marked with `requires_app = True`.
     - Checks DB connectivity for commands marked with `requires_db = True`.
     - Discovers CLI commands contributed by features via ``app.extensions["splent_feature_commands"]``.
+    - Discovers the product's own commands, ``product:<name>`` (services/own_commands.py).
     - Displays commands grouped by category for a cleaner, more readable help output.
     """
 
@@ -49,44 +72,65 @@ class SPLENTCLI(click.Group):
             return self._feature_cmds_cache
 
         self._feature_cmds_cache: dict[str, click.BaseCommand] = {}
-        # Discovery runs before every command, including the ones a product
-        # that is not built yet (selected, not configured or derived) runs
-        # while getting there. Building its app then fails, and the framework
-        # logged that failure with a full traceback on every single command,
-        # although nothing was wrong. The failure is expected here and
-        # handled below, so the framework's logging is muted for the attempt.
         debug = bool(os.getenv("SPLENT_DEBUG"))
-        if not debug:
-            logging.disable(logging.CRITICAL)
         try:
-            from splent_cli.utils.dynamic_imports import get_app
+            with _quiet_unless(debug):
+                from splent_cli.utils.dynamic_imports import get_app
 
-            app = get_app()
-            with app.app_context():
-                registry = app.extensions.get("splent_feature_commands", {})
-                for feature_short, commands in registry.items():
-                    cmd_names = ", ".join(c.name for c in commands if c.name)
-                    group = click.Group(
-                        name=f"feature:{feature_short}",
-                        help=f"Commands contributed by splent_feature_{feature_short}.",
-                        short_help=f"Subcommands: {cmd_names}"
-                        if cmd_names
-                        else f"Commands from splent_feature_{feature_short}.",
-                    )
-                    group.requires_app = True  # type: ignore[attr-defined]
-                    for cmd in commands:
-                        group.add_command(cmd)
-                    self._feature_cmds_cache[group.name] = group
+                app = get_app()
+                with app.app_context():
+                    registry = app.extensions.get("splent_feature_commands", {})
+                    for feature_short, commands in registry.items():
+                        cmd_names = ", ".join(c.name for c in commands if c.name)
+                        group = click.Group(
+                            name=f"feature:{feature_short}",
+                            help=f"Commands contributed by splent_feature_{feature_short}.",
+                            short_help=f"Subcommands: {cmd_names}"
+                            if cmd_names
+                            else f"Commands from splent_feature_{feature_short}.",
+                        )
+                        group.requires_app = True  # type: ignore[attr-defined]
+                        for cmd in commands:
+                            group.add_command(cmd)
+                        self._feature_cmds_cache[group.name] = group
         except Exception as e:
             if debug:
                 click.secho(
                     f"  ⚠ Feature commands not loaded: {e}", fg="yellow", err=True
                 )
-        finally:
-            if not debug:
-                logging.disable(logging.NOTSET)
         return self._feature_cmds_cache
 
+    def load_own_commands(self):
+        """The product's own commands, ``product:<name>``, as an
+        :class:`~splent_cli.services.own_commands.OwnCommands`.
+
+        Found like a feature's: once the product's app is built, which
+        fails quietly here for a product that cannot be built yet. The
+        CLI's own product:* commands win over a product's.
+        """
+        if hasattr(self, "_own_cmds_cache"):
+            return self._own_cmds_cache
+
+        from splent_cli.services import own_commands
+
+        self._own_cmds_cache = own_commands.NONE
+        debug = bool(os.getenv("SPLENT_DEBUG"))
+        try:
+            with _quiet_unless(debug):
+                from splent_cli.utils.dynamic_imports import get_app
+
+                app = get_app()
+                with app.app_context():
+                    self._own_cmds_cache = own_commands.collect(
+                        os.getenv("SPLENT_APP"), set(self.commands)
+                    )
+        except Exception as e:
+            if debug:
+                click.secho(
+                    f"  ⚠ Product commands not loaded: {e}", fg="yellow", err=True
+                )
+        return self._own_cmds_cache
+
     def get_command(self, ctx, cmd_name):
         # "feature:<short>" belongs to the feature called <short> whenever the
         # product installs one. Built-ins win everywhere else.
@@ -100,13 +144,19 @@ class SPLENTCLI(click.Group):
         feat_cmds = self._load_feature_commands()
         if cmd_name in feat_cmds:
             return feat_cmds[cmd_name]
-        return super().get_command(ctx, cmd_name)
+        command = super().get_command(ctx, cmd_name)
+        # "product:<name>" is the product's only where the CLI has no
+        # command of that name, so asking for a built-in never imports it.
+        if command is None and cmd_name and cmd_name.startswith("product:"):
+            command = self.load_own_commands().commands.get(cmd_name)
+        return command
 
     def list_commands(self, ctx):
         builtin = super().list_commands(ctx)
         feat = sorted(self._load_feature_commands().keys())
+        own = sorted(self.load_own_commands().commands)
         # A name a feature claimed is listed once, as the feature's.
-        return [name for name in builtin if name not in feat] + feat
+        return [name for name in builtin if name not in feat] + feat + own
 
     # ── App context injection ─────────────────────────────────────
 
@@ -132,9 +182,14 @@ class SPLENTCLI(click.Group):
         cmd_name = ctx.protected_args[0] if ctx.protected_args else None
         command = self.get_command(ctx, cmd_name)
 
-        # A feature's own commands are only found by building the app, so
-        # here they may be missing although the product has them.
-        if command is None and cmd_name and cmd_name.startswith("feature:"):
+        # A feature's commands, and the product's own, are only found by
+        # building the app, so here they may be missing although the
+        # product has them.
+        if (
+            command is None
+            and cmd_name
+            and cmd_name.startswith(("feature:", "product:"))
+        ):
             self._delegate_to_the_product(ctx)
 
         if command and getattr(command, "requires_app", False):
@@ -169,6 +224,7 @@ class SPLENTCLI(click.Group):
         """Group SPLENT commands by category in the CLI help output."""
         all_cmds = self.list_commands(ctx)
         feat_cmds = self._load_feature_commands()
+        own_cmds = self.load_own_commands().commands
         groups = {
             "🌿 Feature Management": [
                 cmd
@@ -176,7 +232,9 @@ class SPLENTCLI(click.Group):
                 if cmd.startswith("feature:") and cmd not in feat_cmds
             ],
             "🏗️ Product Management": [
-                cmd for cmd in all_cmds if cmd.startswith("product:")
+                cmd
+                for cmd in all_cmds
+                if cmd.startswith("product:") and cmd not in own_cmds
             ],
             "🧬 SPL & Variability": [
                 cmd for cmd in all_cmds if cmd.startswith(("spl:", "uvl:"))
@@ -207,6 +265,7 @@ class SPLENTCLI(click.Group):
                 if cmd in ("lint", "coverage", "selenium", "locust", "locust:stop")
             ],
             "🔌 Feature Commands": [cmd for cmd in all_cmds if cmd in feat_cmds],
+            "🔌 Product Commands": [cmd for cmd in all_cmds if cmd in own_cmds],
         }
         total = 0
         for title, cmds in groups.items():

{splent_cli-1.41.0 → splent_cli-1.42.0}/src/splent_cli/commands/feature/feature_test.py

@@ -150,7 +150,7 @@ def _workspace_owner() -> tuple[int, int] | None:
     return owner.st_uid, owner.st_gid
 
 
-def run_tests_in_web_container(product: str, argv: list[str]) -> int:
+def run_tests_in_web_container(product: str, argv: list[str], env=()) -> int:
     """Run ``splent <argv>`` in PRODUCT's web container, as a test run.
 
     Returns its exit code, or 1 when the container is not running. The run
@@ -158,7 +158,8 @@ def run_tests_in_web_container(product: str, argv: list[str]) -> int:
     process does (see :func:`_tied_to_the_cli`), and runs as the workspace's
     owner (:func:`workspace_user`). feature:test runs there this way, and so
     do the product's own tests (product:test) and the release gate, which
-    runs feature:test.
+    runs feature:test. ``env`` names more variables of this process's
+    environment for the run (product:test's [tool.splent.test] env).
     """
     name = web_container.name(product)
     if not _container_running(name):
@@ -180,6 +181,11 @@ def run_tests_in_web_container(product: str, argv: list[str]) -> int:
         value = os.environ.get(var)
         if value:
             passthrough += ["-e", f"{var}={value}"]
+    # By name alone: docker reads each value from this process's
+    # environment, so a password never shows in the exec's arguments.
+    for var in env:
+        if var in os.environ:
+            passthrough += ["-e", var]
     # The exec reads a pipe only this process writes to, so it sees the end
     # of its input exactly when this process ends, however it ends.
     read_end, write_end = os.pipe()

{splent_cli-1.41.0 → splent_cli-1.42.0}/src/splent_cli/commands/product/product_commands.py

@@ -1,7 +1,9 @@
+import os
+
 import click
 from flask import current_app
 
-from splent_cli.services import context
+from splent_cli.services import context, own_commands
 from splent_cli.utils.decorators import requires_app
 
 
@@ -25,46 +27,20 @@ def _format_flags(cmd) -> str:
     return ", ".join(parts)
 
 
-@requires_app
-@click.command(
-    "product:commands",
-    short_help="List all CLI commands contributed by features.",
-)
-@context.requires_product
-def product_commands():
-    """Show CLI commands registered by features in the active product."""
-    registry = current_app.extensions.get("splent_feature_commands", {})
-
-    if not registry:
-        click.echo()
-        click.secho("  No feature commands registered.", fg="yellow")
-        click.echo()
-        return
-
-    # Build rows: (feature, invocation, flags, description)
-    rows = []
-    for feature_short, commands in sorted(registry.items()):
-        for cmd in sorted(commands, key=lambda c: c.name):
-            desc = cmd.get_short_help_str() or "—"
-            invocation = f"feature:{feature_short} {cmd.name}"
-            flags = _format_flags(cmd)
-            rows.append((feature_short, invocation, flags, desc))
-
-    # Column widths based on visible text
-    col_feat = max(len(r[0]) for r in rows)
-    col_feat = max(col_feat, len("Feature"))
-    col_cmd = max(len(r[1]) for r in rows)
-    col_cmd = max(col_cmd, len("Command"))
-    col_flags = max(len(r[2]) for r in rows)
-    col_flags = max(col_flags, len("Flags"))
+def _table(title: str, owner: str, rows) -> None:
+    """Print ``rows`` of (owner, invocation, flags, description) under TITLE,
+    the owner named once per run of its rows."""
+    col_feat = max(max(len(r[0]) for r in rows), len(owner))
+    col_cmd = max(max(len(r[1]) for r in rows), len("Command"))
+    col_flags = max(max(len(r[2]) for r in rows), len("Flags"))
 
     click.echo()
-    click.secho("  Feature Commands", bold=True, fg="cyan")
+    click.secho(f"  {title}", bold=True, fg="cyan")
     click.echo()
 
     # Header
     click.echo(
-        f"  {'Feature':<{col_feat}}  {'Command':<{col_cmd}}  {'Flags':<{col_flags}}  Description"
+        f"  {owner:<{col_feat}}  {'Command':<{col_cmd}}  {'Flags':<{col_flags}}  Description"
     )
     click.echo(f"  {'-' * col_feat}  {'-' * col_cmd}  {'-' * col_flags}  {'-' * 30}")
 
@@ -85,8 +61,66 @@ def product_commands():
         )
         prev_feat = feat
 
-    click.echo()
-    click.secho(f"  {len(rows)} command(s) from {len(registry)} feature(s).", dim=True)
+
+def _own_commands():
+    """The product's own commands, against the CLI's built-in names."""
+    from splent_cli.cli import cli
+
+    return own_commands.collect(os.getenv("SPLENT_APP"), set(cli.commands))
+
+
+@requires_app
+@click.command(
+    "product:commands",
+    short_help="List the CLI commands of the product's features and its own.",
+)
+@context.requires_product
+def product_commands():
+    """Show the CLI commands the active product's features register, and the
+    product's own (product:<name>, from its commands module)."""
+    registry = current_app.extensions.get("splent_feature_commands", {})
+    own = _own_commands()
+    product = os.getenv("SPLENT_APP", "product")
+
+    if not registry and not own.commands and not own.shadowed and not own.error:
+        click.echo()
+        click.secho("  No feature or product commands registered.", fg="yellow")
+        click.echo()
+        return
+
+    # Build rows: (feature, invocation, flags, description)
+    rows = []
+    for feature_short, commands in sorted(registry.items()):
+        for cmd in sorted(commands, key=lambda c: c.name):
+            desc = cmd.get_short_help_str() or "—"
+            invocation = f"feature:{feature_short} {cmd.name}"
+            rows.append((feature_short, invocation, _format_flags(cmd), desc))
+    if rows:
+        _table("Feature Commands", "Feature", rows)
+        click.echo()
+        click.secho(
+            f"  {len(rows)} command(s) from {len(registry)} feature(s).", dim=True
+        )
+
+    own_rows = [
+        (product, name, _format_flags(cmd), cmd.get_short_help_str() or "—")
+        for name, cmd in sorted(own.commands.items())
+    ]
+    if own_rows:
+        _table("Product Commands", "Product", own_rows)
+        click.echo()
+        click.secho(f"  {len(own_rows)} command(s) of {product}'s own.", dim=True)
+    for name in own.shadowed:
+        click.secho(
+            f"  ⚠ {product} has a command {name}, which is the CLI's own and "
+            "wins: rename it to reach it.",
+            fg="yellow",
+        )
+    if own.error:
+        click.secho(
+            f"  ⚠ {product}'s own commands are not available: {own.error}",
+            fg="yellow",
+        )
     click.echo()
 
 

{splent_cli-1.41.0 → splent_cli-1.42.0}/src/splent_cli/commands/product/product_test.py

@@ -12,16 +12,26 @@ check the configuration the product is, such as the URLs it promises to keep
 serving, which no feature's tests can, so a product that ships them has them
 run wherever its features' tests run: here, in its release checks and in its
 CI. A product without them is tested as before.
+
+Its own tests may need what only the caller has, such as the address of a
+throwaway server the caller started for them. The product names those
+variables in ``[tool.splent.test] env`` and product:test hands them over
+from the caller's environment, into the web container too. It never starts
+anything for them.
 """
 
 import os
+import re
 import sys
 from pathlib import Path
 
 import click
 
 from splent_cli.services import context, web_container
-from splent_cli.utils.feature_utils import load_product_features
+from splent_cli.utils.feature_utils import (
+    load_product_features,
+    load_product_pyproject,
+)
 from splent_cli.utils.proc import run
 
 # Where a product keeps its own tests, and the files pytest collects there
@@ -29,6 +39,56 @@ from splent_cli.utils.proc import run
 OWN_TESTS_DIR = "tests"
 _OWN_TEST_PATTERNS = ("test_*.py", "*_test.py")
 
+# An entry of [tool.splent.test] env: a variable's name, or a prefix of
+# names ending in *.
+_ENV_ENTRY = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\*?")
+# Never handed over, whatever a pattern matches: the run sets SPLENT_APP and
+# the like itself, and the tests use the web container's database settings,
+# so a caller's MARIADB_DATABASE cannot point them at another database.
+_NOT_HANDED = ("SPLENT_", "MARIADB_")
+
+
+def declared_test_env(product_path) -> list[str]:
+    """What ``[tool.splent.test] env`` of the product names; [] without it.
+
+    Raises click.ClickException for an entry that is neither a variable's
+    name nor a prefix ending in ``*``, so a typo is not a test that quietly
+    goes without its server.
+    """
+    try:
+        data = load_product_pyproject(str(product_path))
+    except FileNotFoundError:
+        return []
+    entries = data.get("tool", {}).get("splent", {}).get("test", {}).get("env", [])
+    if not isinstance(entries, list):
+        raise click.ClickException(
+            "[tool.splent.test] env is a list of variable names, such as "
+            '["MY_TESTS_DB_HOST", "MY_TESTS_*"]'
+        )
+    for entry in entries:
+        if not isinstance(entry, str) or not _ENV_ENTRY.fullmatch(entry):
+            raise click.ClickException(
+                f"[tool.splent.test] env names {entry!r}, which is neither a "
+                "variable's name nor a prefix ending in *"
+            )
+    return entries
+
+
+def handed_test_env(product_path, environ=None) -> list[str]:
+    """The variables of ``environ`` (this process's) that the product's own
+    tests are handed: the ones its ``[tool.splent.test] env`` names that are
+    set, but for SPLENT_* and MARIADB_*."""
+    environ = os.environ if environ is None else environ
+    entries = declared_test_env(product_path)
+    names = {e for e in entries if not e.endswith("*")}
+    prefixes = tuple(e[:-1] for e in entries if e.endswith("*"))
+    return sorted(
+        name
+        for name in environ
+        if (name in names or (prefixes and name.startswith(prefixes)))
+        and not name.startswith(_NOT_HANDED)
+    )
+
 
 def own_test_files(product_path) -> list[Path]:
     """The product's own test files, under ``<product>/tests``; [] without any."""
@@ -106,7 +166,8 @@ def _run_own_tests(product, verbose) -> None:
     from the CLI they run in the web container, as feature:test does, one
     test run at a time and stopped with the CLI. There, or in the CI job
     that stands in for it, they run against the test database and against
-    the features as the product's app loads them.
+    the features as the product's app loads them, with the variables of
+    this environment the product declares in ``[tool.splent.test] env``.
     """
     from splent_cli.commands.feature.feature_test import (
         _validate_testing_environment,
@@ -122,7 +183,15 @@ def _run_own_tests(product, verbose) -> None:
     product = context.require_app()
     if not web_container.is_product_container():
         argv = ["product:test", "--own-tests"] + (["-v"] if verbose else [])
-        raise SystemExit(run_tests_in_web_container(product, argv))
+        # Here the variables a product declares are handed over by name; in
+        # the container, and in the CI job, the whole environment is.
+        handed = handed_test_env(context.workspace() / product)
+        if handed:
+            click.secho(
+                f"     handing the tests {', '.join(handed)} ([tool.splent.test] env)",
+                dim=True,
+            )
+        raise SystemExit(run_tests_in_web_container(product, argv, env=handed))
 
     _validate_testing_environment()
 
@@ -196,7 +265,8 @@ def product_test(
     run after the features', in the product's web container, against the
     features as its app loads them (the versions it pins, the working copy
     of an editable one), and only without a level flag. A product without a
-    tests/ folder runs its features' tests alone.
+    tests/ folder runs its features' tests alone. The variables of your
+    environment the product names in [tool.splent.test] env reach them.
 
     \b
     Examples:

splent_cli-1.42.0/src/splent_cli/services/own_commands.py

@@ -0,0 +1,76 @@
+"""A product's own CLI commands, ``splent product:<name>``.
+
+A product declares them as a feature does: a ``commands`` module in its
+package with a ``cli_commands`` list of Click commands. A feature's become
+subcommands of ``feature:<short>``; a product's are commands of their own,
+``product:<name>``, since one product is active at a time. Like a
+feature's, they are found once the product's app is built, and run in its
+context.
+
+The CLI's own ``product:*`` commands win. A product command named like one
+of them cannot be reached, and product:commands says so: a CLI that ships a
+new built-in never takes a product's command away unnoticed.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import NamedTuple
+
+import click
+
+PREFIX = "product:"
+MODULE = "commands"
+
+
+class OwnCommands(NamedTuple):
+    """What a product contributes: ``commands`` by the name they are run
+    with, ``shadowed`` the names a built-in took, and ``error`` why its
+    commands module could not be imported, None when it could."""
+
+    commands: dict[str, click.Command]
+    shadowed: list[str]
+    error: str | None
+
+
+NONE = OwnCommands({}, [], None)
+
+
+def declared(product: str) -> list[click.Command]:
+    """The Click commands ``<product>.commands`` lists in ``cli_commands``.
+
+    [] when the product has no such module. Whatever else importing it
+    raises is raised, so the caller can say why its commands are missing.
+    """
+    name = f"{product}.{MODULE}"
+    try:
+        module = importlib.import_module(name)
+    except ModuleNotFoundError as e:
+        if e.name == name:
+            return []
+        raise
+    commands = getattr(module, "cli_commands", None) or ()
+    return [command for command in commands if isinstance(command, click.Command)]
+
+
+def collect(product: str | None, builtin) -> OwnCommands:
+    """The commands PRODUCT contributes, each under ``product:<its name>``,
+    but for those whose name is in ``builtin`` (the CLI's own)."""
+    if not product:
+        return NONE
+    try:
+        commands = declared(product)
+    except Exception as e:
+        return OwnCommands({}, [], f"{product}.{MODULE}: {e}")
+    found, shadowed = {}, []
+    for command in commands:
+        if not command.name:
+            continue
+        name = PREFIX + command.name
+        if name in builtin:
+            shadowed.append(name)
+            continue
+        # Run in the app's context, as a feature's (cli.py).
+        command.requires_app = True  # type: ignore[attr-defined]
+        found[name] = command
+    return OwnCommands(found, shadowed, None)

{splent_cli-1.41.0 → splent_cli-1.42.0/src/splent_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splent_cli
-Version: 1.41.0
+Version: 1.42.0
 Summary: SPLENT-CLI is a CLI to be able to work on your development more easily.
 Author-email: DiversoLab <diversolab@us.es>
 License-Expression: LGPL-3.0-or-later

{splent_cli-1.41.0 → splent_cli-1.42.0}/src/splent_cli.egg-info/SOURCES.txt

@@ -171,6 +171,7 @@ src/splent_cli/services/marketplace.py
 src/splent_cli/services/marketplace_api.py
 src/splent_cli/services/marketplace_url.py
 src/splent_cli/services/neutral_app.py
+src/splent_cli/services/own_commands.py
 src/splent_cli/services/preflight.py
 src/splent_cli/services/pypi_quota.py
 src/splent_cli/services/registry.py