invoke-toolkit 0.0.63__tar.gz → 0.0.64__tar.gz

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/.gitignore

@@ -18,3 +18,4 @@ invoke.yaml
 # Makrdowns
 *.md
 !docs/**/*.md
+.worktrees/

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invoke-toolkit
-Version: 0.0.63
+Version: 0.0.64
 Summary: Extended APIs for PyInvoke: composable task plugins, typed CLI args, Rich output, shell completion, and PEP 723 script support
 Project-URL: Documentation, https://github.com/D3f0/invoke-toolkit#readme
 Project-URL: Issues, https://github.com/D3f0/invoke-toolkit/issues

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/src/invoke_toolkit/program/program.py

@@ -15,7 +15,7 @@ from importlib import metadata
 from importlib.util import module_from_spec
 from logging import getLogger
 from pathlib import Path
-from typing import Dict, List, Optional, Sequence, Tuple, Union
+from typing import Dict, List, Literal, Optional, Sequence, Tuple, Union
 
 from rich.table import Table
 
@@ -81,6 +81,9 @@ class ToolkitProgram(Program):
             config_class,
             binary_names,
         )
+        # Names of sub-collections that were loaded from entry-point plugins.
+        # Populated in load_collection(); used by --list-tasks / --list-plugins.
+        self._plugin_collection_names: set[str] = set()
 
     def get_version(self) -> str:
         """Compute version
@@ -368,10 +371,92 @@ class ToolkitProgram(Program):
                 default=False,
                 help="Initializes shell for runner via CLI flag",
             ),
+            ToolkitArgument(
+                names=("list-tasks", "lt"),
+                kind=bool,
+                default=False,
+                help="List only the main tasks discovered in the current directory (excludes plugins)",
+            ),
+            ToolkitArgument(
+                names=("list-plugins", "lp"),
+                kind=bool,
+                default=False,
+                help="List only the plugin-provided task collections (excludes main tasks)",
+            ),
         ]
         args.extend(toolkit_program_arguments)
         return args
 
+    def _handle_list_flags(self) -> None:
+        """
+        Handle --list, --list-tasks, and --list-plugins flags.
+
+        Sets ``list_format`` / ``list_depth`` / ``scoped_collection`` as needed
+        and raises `Exit` when any listing flag is active.
+        """
+        self.list_format = self.args["list-format"].value
+        self.list_depth = self.args["list-depth"].value
+
+        # --list [root]: standard task listing (optionally scoped to a sub-collection)
+        list_root = self.args.list.value  # True or a string namespace
+        if list_root:
+            if isinstance(list_root, str):
+                self.list_root = list_root
+                try:
+                    sub = self.collection.subcollection_from_path(list_root)
+                    self.scoped_collection = sub
+                except KeyError:
+                    msg = "Sub-collection '{}' not found!"
+                    raise Exit(msg.format(list_root))
+            self.list_tasks()
+            raise Exit
+
+        # --list-tasks: show only main (non-plugin) tasks
+        if self.args["list-tasks"].value:
+            debug("Saw --list-tasks, listing main tasks only & exiting")
+            self.scoped_collection = self._make_filtered_collection("tasks")
+            self.list_tasks()
+            raise Exit
+
+        # --list-plugins: show only plugin-provided collections
+        if self.args["list-plugins"].value:
+            debug("Saw --list-plugins, listing plugin collections only & exiting")
+            if not self._plugin_collection_names:
+                raise Exit("No plugin collections found.")
+            self.scoped_collection = self._make_filtered_collection("plugins")
+            self.list_tasks()
+            raise Exit
+
+    def _make_filtered_collection(
+        self, mode: "Literal['tasks', 'plugins']"
+    ) -> "ToolkitCollection":
+        """
+        Return a shallow copy of ``self.scoped_collection`` containing only
+        the subset of tasks and sub-collections appropriate for *mode*.
+
+        - ``'tasks'``   – direct tasks + non-plugin sub-collections only
+        - ``'plugins'`` – plugin sub-collections only (no direct tasks)
+        """
+        source = self.scoped_collection
+        filtered = ToolkitCollection(source.name or "")
+        if mode == "tasks":
+            # Include all direct tasks on the scoped collection
+            for task_name, task in source.tasks.items():
+                filtered.add_task(task, name=task_name)
+            # Include sub-collections that are NOT from plugins
+            for coll_name, coll in source.collections.items():
+                if coll_name not in self._plugin_collection_names:
+                    filtered.add_collection(coll, name=coll_name)
+        else:  # mode == "plugins"
+            # Include only the plugin sub-collections
+            for coll_name, coll in source.collections.items():
+                if coll_name in self._plugin_collection_names:
+                    filtered.add_collection(coll, name=coll_name)
+        # Preserve the default task pointer when it still makes sense
+        if source.default and source.default in filtered.tasks:
+            filtered.default = source.default
+        return filtered
+
     def _load_entry_points_collection(self, start: str) -> "ToolkitCollection | None":
         """
         Load task collections from entry points.
@@ -453,6 +538,7 @@ class ToolkitProgram(Program):
                 debug("Merging entry point collections with tasks.py")
                 for name, collection in ep_collection.collections.items():
                     self.collection.add_collection(collection, name=name)
+                    self._plugin_collection_names.add(name)
         except CollectionNotFound as e:
             start = self.args["search-root"].value or "."
             # First try to load entry points (for packages without tasks.py)
@@ -460,6 +546,7 @@ class ToolkitProgram(Program):
             if ep_collection is not None:
                 debug("Loading collections from entry points")
                 self.collection = ep_collection
+                self._plugin_collection_names.update(ep_collection.collections.keys())
             else:
                 # If entry points weren't found, try local_tasks or fail
                 if not (Path(start) / "local_tasks.py").exists():
@@ -571,23 +658,8 @@ class ToolkitProgram(Program):
                 # should?
                 raise ParseError("No idea what '{}' is!".format(halp))
 
-        # Print discovered tasks if necessary
-        list_root = self.args.list.value  # will be True or string
-
-        self.list_format = self.args["list-format"].value
-        self.list_depth = self.args["list-depth"].value
-        if list_root:
-            # Not just --list, but --list some-root - do moar work
-            if isinstance(list_root, str):
-                self.list_root = list_root
-                try:
-                    sub = self.collection.subcollection_from_path(list_root)
-                    self.scoped_collection = sub
-                except KeyError:
-                    msg = "Sub-collection '{}' not found!"
-                    raise Exit(msg.format(list_root))
-            self.list_tasks()
-            raise Exit
+        # Handle --list / --list-tasks / --list-plugins (raises Exit if triggered)
+        self._handle_list_flags()
 
         # Print completion helpers if necessary
         if self.args.complete.value:

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/src/invoke_toolkit/tasks/tasks.py

@@ -6,6 +6,7 @@ Type annotated tasks and and overrides over invoke
 
 import inspect
 import os
+import warnings
 import subprocess
 import types
 from enum import Enum
@@ -774,7 +775,22 @@ def task(  # pylint: disable=too-many-arguments,too-many-branches
         if name is not None:
             task_kwargs["name"] = name
         if aliases:
-            task_kwargs["aliases"] = aliases
+            # Normalize a name to invoke's canonical form (underscores → hyphens).
+            effective_name = (name or getattr(f, "__name__", "")).replace("_", "-")
+            filtered_aliases = [
+                a for a in aliases if a.replace("_", "-") != effective_name
+            ]
+            skipped = set(aliases) - set(filtered_aliases)
+            if skipped:
+                warnings.warn(
+                    f"Task '{effective_name}': alias(es) {sorted(skipped)!r} "
+                    "match the task name and will be ignored to prevent a "
+                    "RecursionError at runtime.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            if filtered_aliases:
+                task_kwargs["aliases"] = filtered_aliases
         if positional:
             task_kwargs["positional"] = positional
         if optional:

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/tests/script/test_script.py

@@ -146,10 +146,12 @@ def test_script_loads_project_config(tmp_path: Path, capsys, monkeypatch):
     # Create a temporary directory with a script and config file
     monkeypatch.chdir(tmp_path)
 
-    # Create invoke.yml config file with echo=true and pty=true
+    # Create invoke.yml config file with echo=true
+    # Note: pty=true is intentionally omitted — a PTY requires a real terminal
+    # and would cause pytest to raise OSError when output is captured.
     config_file = tmp_path / "invoke.yml"
     config_file.write_text(
-        "run:\n  echo: true\n  pty: true\n",
+        "run:\n  echo: true\n",
         encoding="utf-8",
     )
 
@@ -158,8 +160,7 @@ def test_script_loads_project_config(tmp_path: Path, capsys, monkeypatch):
     def check_config(c):
         # Check that config was loaded
         assert c.config.run.echo is True, "echo should be True from invoke.yml"
-        assert c.config.run.pty is True, "pty should be True from invoke.yml"
-        c.run("echo 'Config loaded successfully'")
+        c.run("echo 'Config loaded successfully'", in_stream=False)
 
     # Run script and verify config was loaded
     # Note: need to pass script name as first arg for invoke

invoke_toolkit-0.0.64/tests/test_alias_self_reference.py

@@ -0,0 +1,108 @@
+"""Tests for self-referential alias guard in @task."""
+
+import warnings
+
+import pytest
+from invoke import Collection
+
+from invoke_toolkit.tasks.tasks import task
+
+
+def _make_collection(*tasks):
+    c = Collection()
+    for t in tasks:
+        c.add_task(t)
+    return c
+
+
+# ---------------------------------------------------------------------------
+# Warning is emitted
+# ---------------------------------------------------------------------------
+
+
+def test_warns_when_alias_matches_function_name_underscore():
+    """Alias equal to the function name (underscore form) triggers a UserWarning."""
+    with pytest.warns(UserWarning, match="match the task name"):
+
+        @task(aliases=["my_task"])
+        def my_task(ctx):
+            pass
+
+
+def test_warns_when_alias_matches_function_name_hyphen():
+    """Alias equal to the hyphenated function name triggers a UserWarning."""
+    with pytest.warns(UserWarning, match="match the task name"):
+
+        @task(aliases=["my-task"])
+        def my_task(ctx):
+            pass
+
+
+def test_warns_when_alias_matches_explicit_name():
+    """Alias equal to an explicit name= override triggers a UserWarning."""
+    with pytest.warns(UserWarning, match="match the task name"):
+
+        @task(name="deploy", aliases=["deploy"])
+        def run_deploy(ctx):
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Self-referential alias is stripped (no RecursionError)
+# ---------------------------------------------------------------------------
+
+
+def test_self_alias_stripped_task_is_reachable():
+    """After stripping the self-alias the task is still reachable by its name."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", UserWarning)
+
+        @task(aliases=["my_task"])
+        def my_task(ctx):
+            pass
+
+    c = _make_collection(my_task)
+    # Must not raise RecursionError
+    resolved = c["my-task"]
+    assert resolved is not None
+
+
+def test_self_alias_stripped_valid_aliases_kept():
+    """Valid aliases are preserved; only the self-referential one is removed."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", UserWarning)
+
+        @task(aliases=["my_task", "mt"])
+        def my_task(ctx):
+            pass
+
+    c = _make_collection(my_task)
+    assert c["mt"] is not None
+    assert c["my-task"] is not None
+
+
+def test_all_aliases_self_referential_no_aliases_registered():
+    """When every alias is self-referential the task has no aliases."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", UserWarning)
+
+        @task(aliases=["my_task3"])
+        def my_task3(ctx):
+            pass
+
+    c = _make_collection(my_task3)
+    # task_names maps canonical name → list of aliases; list should be empty
+    assert c.task_names["my-task3"] == []
+
+
+def test_no_warning_for_distinct_alias():
+    """A genuinely distinct alias produces no warning."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", UserWarning)  # would raise if a warning fires
+
+        @task(aliases=["mt"])
+        def my_task(ctx):
+            pass
+
+    c = _make_collection(my_task)
+    assert c["mt"] is not None

invoke_toolkit-0.0.64/tests/test_list_filter_flags.py

@@ -0,0 +1,208 @@
+"""Tests for --list-tasks and --list-plugins filter flags."""
+
+import json
+
+
+from invoke_toolkit import Context, task
+from invoke_toolkit.collections import ToolkitCollection
+from invoke_toolkit.testing import TestingToolkitProgram
+
+
+# ---------------------------------------------------------------------------
+# Shared task/collection factories
+# ---------------------------------------------------------------------------
+
+
+@task()
+def main_task_a(ctx: Context):
+    """Main task A"""
+
+
+@task()
+def main_task_b(ctx: Context):
+    """Main task B"""
+
+
+@task()
+def plugin_task_x(ctx: Context):
+    """Plugin task X"""
+
+
+@task()
+def plugin_task_y(ctx: Context):
+    """Plugin task Y"""
+
+
+def _make_collection_with_plugins() -> tuple[ToolkitCollection, set[str]]:
+    """
+    Build a ToolkitCollection that looks like 'tasks.py + two plugin sub-collections'.
+    Returns the collection and the set of plugin sub-collection names.
+    """
+    coll = ToolkitCollection("root")
+    coll.add_task(main_task_a)
+    coll.add_task(main_task_b)
+
+    plugin_coll = ToolkitCollection("myplugin")
+    plugin_coll.add_task(plugin_task_x)
+    plugin_coll.add_task(plugin_task_y)
+    coll.add_collection(plugin_coll, name="myplugin")
+
+    another_plugin = ToolkitCollection("otherplugin")
+    coll.add_collection(another_plugin, name="otherplugin")
+
+    return coll, {"myplugin", "otherplugin"}
+
+
+def _program_with_plugins(
+    plugin_names: set[str] | None = None,
+) -> tuple[TestingToolkitProgram, ToolkitCollection]:
+    """Return a configured TestingToolkitProgram with a plugin-aware collection."""
+    coll, plugin_set = _make_collection_with_plugins()
+    p = TestingToolkitProgram(namespace=coll)
+    if plugin_names is None:
+        p._plugin_collection_names = plugin_set
+    else:
+        p._plugin_collection_names = plugin_names
+    return p, coll
+
+
+# ---------------------------------------------------------------------------
+# --list-tasks
+# ---------------------------------------------------------------------------
+
+
+def test_list_tasks_shows_main_tasks(capsys, suppress_stderr_logging):
+    """--list-tasks output contains the direct main tasks."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-tasks", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    task_names = {t["name"] for t in data["tasks"]}
+    assert "main-task-a" in task_names
+    assert "main-task-b" in task_names
+
+
+def test_list_tasks_excludes_plugin_collections(capsys, suppress_stderr_logging):
+    """--list-tasks must NOT include plugin sub-collections."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-tasks", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    coll_names = {c["name"] for c in data.get("collections", [])}
+    assert "myplugin" not in coll_names
+    assert "otherplugin" not in coll_names
+
+
+def test_list_tasks_flat_format(capsys, suppress_stderr_logging):
+    """--list-tasks works with the default flat format (no JSON)."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-tasks"])
+    out, _ = capsys.readouterr()
+    assert "main-task-a" in out
+    assert "main-task-b" in out
+    assert "myplugin" not in out
+
+
+def test_list_tasks_no_plugins_registered(capsys, suppress_stderr_logging):
+    """--list-tasks when there are no plugins still shows the main tasks."""
+    coll = ToolkitCollection("root")
+    coll.add_task(main_task_a)
+    p = TestingToolkitProgram(namespace=coll)
+    # _plugin_collection_names starts empty (no plugins)
+    p.run(["", "--list-tasks", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    task_names = {t["name"] for t in data["tasks"]}
+    assert "main-task-a" in task_names
+
+
+def test_list_tasks_preserves_non_plugin_subcollections(
+    capsys, suppress_stderr_logging
+):
+    """Non-plugin sub-collections (e.g. from tasks.py namespace) are kept by --list-tasks."""
+    coll = ToolkitCollection("root")
+    coll.add_task(main_task_a)
+
+    sub = ToolkitCollection("utils")
+    sub.add_task(main_task_b)
+    coll.add_collection(sub, name="utils")
+
+    plugin_coll = ToolkitCollection("myplugin")
+    plugin_coll.add_task(plugin_task_x)
+    coll.add_collection(plugin_coll, name="myplugin")
+
+    p = TestingToolkitProgram(namespace=coll)
+    p._plugin_collection_names = {"myplugin"}
+
+    p.run(["", "--list-tasks", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    coll_names = {c["name"] for c in data.get("collections", [])}
+    assert "utils" in coll_names
+    assert "myplugin" not in coll_names
+
+
+# ---------------------------------------------------------------------------
+# --list-plugins
+# ---------------------------------------------------------------------------
+
+
+def test_list_plugins_shows_plugin_collections(capsys, suppress_stderr_logging):
+    """--list-plugins output contains the plugin sub-collections."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-plugins", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    coll_names = {c["name"] for c in data.get("collections", [])}
+    assert "myplugin" in coll_names
+    assert "otherplugin" in coll_names
+
+
+def test_list_plugins_excludes_main_tasks(capsys, suppress_stderr_logging):
+    """--list-plugins must NOT include the direct main tasks."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-plugins", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    task_names = {t["name"] for t in data.get("tasks", [])}
+    assert "main-task-a" not in task_names
+    assert "main-task-b" not in task_names
+
+
+def test_list_plugins_flat_format(capsys, suppress_stderr_logging):
+    """--list-plugins works with the default flat format."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-plugins"])
+    out, _ = capsys.readouterr()
+    assert "myplugin" in out
+    assert "main-task-a" not in out
+
+
+def test_list_plugins_no_plugins_exits_with_message(capsys, suppress_stderr_logging):
+    """--list-plugins when there are no plugins exits with a clear message."""
+    coll = ToolkitCollection("root")
+    coll.add_task(main_task_a)
+    p = TestingToolkitProgram(namespace=coll)
+    # _plugin_collection_names is empty — no plugins loaded
+    p.run(["", "--list-plugins"])
+    # run(..., exit=False) so no sys.exit — just check stderr for the message
+    _, err = capsys.readouterr()
+    assert "No plugin collections found" in err
+
+
+# ---------------------------------------------------------------------------
+# Mutual exclusion sanity (using both flags at once: first one wins)
+# ---------------------------------------------------------------------------
+
+
+def test_list_tasks_takes_precedence_over_list_plugins(capsys, suppress_stderr_logging):
+    """When both --list-tasks and --list-plugins are given, --list-tasks runs first."""
+    p, _ = _program_with_plugins()
+    p.run(["", "--list-tasks", "--list-plugins", "--list-format", "json"])
+    out, _ = capsys.readouterr()
+    data = json.loads(out)
+    # Should behave like --list-tasks
+    task_names = {t["name"] for t in data["tasks"]}
+    assert "main-task-a" in task_names
+    coll_names = {c["name"] for c in data.get("collections", [])}
+    assert "myplugin" not in coll_names

{invoke_toolkit-0.0.63 → invoke_toolkit-0.0.64}/tests/test_proctitle.py

@@ -176,22 +176,25 @@ def test_proctitle_visible_in_ps(tmp_path: Path):
     tasks_file.write_text(tasks_content)
 
     # Start the task in a subprocess
-    with subprocess.Popen(
+    proc = subprocess.Popen(  # pylint: disable=consider-using-with
         [sys.executable, "-m", "invoke_toolkit", "-r", str(tmp_path), "test-proctitle"],
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
-    ) as proc:
+    )
+    try:
         # Wait for the task to signal it's ready
-        timeout = 10
+        startup_timeout = 10
         start = time.time()
         while not signal_file.exists():
-            if time.time() - start > timeout:
-                raise TimeoutError("Task did not start in time")
+            if time.time() - start > startup_timeout:
+                proc.kill()
+                proc.wait(timeout=5)
+                pytest.fail("Task did not start in time")
             if proc.poll() is not None:
                 stdout, stderr = proc.communicate()
-                raise RuntimeError(
+                pytest.fail(
                     f"Process exited early: {proc.returncode}\n"
-                    + f"stdout: {stdout.decode()}\nstderr: {stderr.decode()}"
+                    f"stdout: {stdout.decode()}\nstderr: {stderr.decode()}"
                 )
             time.sleep(0.05)
 
@@ -210,7 +213,12 @@ def test_proctitle_visible_in_ps(tmp_path: Path):
 
         # Signal the task to finish
         done_file.write_text("done")
-        proc.wait(timeout=5)
+        proc.wait(timeout=10)
+    finally:
+        # Ensure the subprocess is always cleaned up
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait(timeout=5)
 
 
 @pytest.fixture