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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invoke-toolkit
-Version: 0.0.62
+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
@@ -36,7 +36,7 @@ Requires-Dist: appdirs
 Requires-Dist: attrs>=24.1.0
 Requires-Dist: cattrs>=24.1.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: invoke>=2.2.1
+Requires-Dist: invoke>=3.0.3
 Requires-Dist: platformdirs>=4.5.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rich>=13

{invoke_toolkit-0.0.62 → invoke_toolkit-0.0.64}/pyproject.toml

@@ -45,7 +45,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "invoke>=2.2.1",
+    "invoke>=3.0.3",
     "rich>=13",
     "typing-extensions>=4.13.2",
     "appdirs",

{invoke_toolkit-0.0.62 → invoke_toolkit-0.0.64}/src/invoke_toolkit/context/context.py

@@ -70,8 +70,10 @@ class ToolkitContext(Context, ConfigProtocol):
         [Union[PathLike[str], str]], _GeneratorContextManager[None, None, None]
     ]
 
-    def __init__(self, config: Optional[ToolkitConfig] = None) -> None:
-        super().__init__(config)
+    def __init__(
+        self, config: Optional[ToolkitConfig] = None, remainder: str = ""
+    ) -> None:
+        super().__init__(config, remainder=remainder)
         self._set("_console", get_console())
         # Check if status is disabled in the config
         disabled = False

{invoke_toolkit-0.0.62 → invoke_toolkit-0.0.64}/src/invoke_toolkit/executor.py

@@ -39,11 +39,16 @@ class ToolkitExecutor(Executor):
 
         :param core:
             An optional `.ParseResult` holding parsed core program arguments.
-            Defaults to ``None``.
+            Defaults to an empty `.ParseResult` if not given.
+
+        .. versionchanged:: invoke 3.0
+            ``self.core`` now defaults to ``ParseResult()`` instead of
+            ``None``, matching upstream ``Executor`` behaviour and ensuring
+            ``core_parse_result.remainder`` is always accessible.
         """
         self.collection = collection
         self.config = config if config is not None else ToolkitConfig()
-        self.core = core
+        self.core = core if core is not None else ParseResult()
 
     def execute(
         self, *tasks: Union[str, Tuple[str, Dict[str, Any]], ParserContext]
@@ -134,7 +139,7 @@ class ToolkitExecutor(Executor):
             # Get final context from the Call (which will know how to generate
             # an appropriate one; e.g. subclasses might use extra data from
             # being parameterized), handing in this config for use there.
-            context = call.make_context(config)  # type: ignore[attr-defined]
+            context = call.make_context(config, core_parse_result=self.core)  # type: ignore[attr-defined]
             args = (context, *call.args)  # type: ignore[attr-defined]
             result = call.task(*args, **call.kwargs)  # type: ignore[attr-defined]
             if autoprint:

{invoke_toolkit-0.0.62 → 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.62 → invoke_toolkit-0.0.64}/src/invoke_toolkit/tasks/tasks.py

@@ -2,10 +2,11 @@
 Type annotated tasks and and overrides over invoke
 """
 
-# pylint: disable=too-many-statements
+# pylint: disable=too-many-statements,duplicate-code
 
 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:
@@ -822,9 +838,16 @@ def task(  # pylint: disable=too-many-arguments,too-many-branches
 
 
 class ToolkitCall(Call):
-    def make_context(self, config):
-        """Generates the Context for the task"""
-        return ToolkitContext(config=config)
+    def make_context(self, config, core_parse_result=None):
+        """Generates the Context for the task.
+
+        .. versionchanged:: invoke 3.0
+            Added the ``core_parse_result`` parameter so that
+            ``Context.remainder`` is populated from the CLI parser's remainder
+            value (text after a standalone ``--``).
+        """
+        remainder = core_parse_result.remainder if core_parse_result is not None else ""
+        return ToolkitContext(config=config, remainder=remainder)
 
 
 def call(task_: "Task", *args: Any, **kwargs: Any) -> "Call":

{invoke_toolkit-0.0.62 → 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_invoke_3_compat.py

@@ -0,0 +1,184 @@
+"""
+Tests for invoke 3.0.x compatibility.
+
+invoke 3.0 introduced two related breaking changes that affect invoke-toolkit:
+
+1. ``Call.make_context`` now requires a second argument ``core_parse_result``
+   (a ``ParseResult`` instance) so that ``Context.remainder`` can be populated
+   from the CLI parser's remainder value (text after a standalone ``--``).
+
+2. ``Context.__init__`` now accepts a ``remainder`` keyword argument and stores
+   it as ``self.remainder``.
+
+These tests verify that:
+- ``ToolkitCall.make_context`` accepts ``core_parse_result`` and propagates
+  ``remainder`` into the resulting ``ToolkitContext``.
+- ``ToolkitContext`` exposes ``ctx.remainder`` correctly.
+- ``ToolkitExecutor`` never passes ``None`` as ``core_parse_result`` (it
+  defaults to an empty ``ParseResult()``).
+- End-to-end: a task can read ``ctx.remainder`` when invoked with ``-- extra``.
+"""
+
+from invoke.parser import ParseResult
+from invoke.tasks import Task
+
+from invoke_toolkit import Context, task
+from invoke_toolkit.collections import ToolkitCollection
+from invoke_toolkit.config import ToolkitConfig
+from invoke_toolkit.context.context import ToolkitContext
+from invoke_toolkit.executor import ToolkitExecutor
+from invoke_toolkit.tasks.tasks import ToolkitCall
+
+
+# ---------------------------------------------------------------------------
+# Unit: ToolkitCall.make_context
+# ---------------------------------------------------------------------------
+
+
+def _dummy_task_func(ctx: Context) -> None:  # pragma: no cover
+    """Minimal real task used as a ToolkitCall target in unit tests."""
+
+
+_DUMMY_TASK: Task = task(_dummy_task_func)  # type: ignore[assignment]
+
+
+def _make_parse_result(remainder: str = "") -> ParseResult:
+    """Return a ParseResult whose .remainder is set to *remainder*."""
+    pr = ParseResult()
+    pr.remainder = remainder
+    return pr
+
+
+def test_make_context_without_core_parse_result():
+    """make_context(config) with no core_parse_result → remainder defaults to ''."""
+    config = ToolkitConfig()
+    c = ToolkitCall(_DUMMY_TASK)
+    ctx = c.make_context(config)
+    assert isinstance(ctx, ToolkitContext)
+    assert ctx.remainder == ""
+
+
+def test_make_context_with_empty_parse_result():
+    """make_context(config, core_parse_result=ParseResult()) → remainder is ''."""
+    config = ToolkitConfig()
+    c = ToolkitCall(_DUMMY_TASK)
+    ctx = c.make_context(config, core_parse_result=_make_parse_result(""))
+    assert isinstance(ctx, ToolkitContext)
+    assert ctx.remainder == ""
+
+
+def test_make_context_propagates_remainder():
+    """make_context passes ParseResult.remainder into ToolkitContext.remainder."""
+    config = ToolkitConfig()
+    c = ToolkitCall(_DUMMY_TASK)
+    ctx = c.make_context(config, core_parse_result=_make_parse_result("extra args"))
+    assert ctx.remainder == "extra args"
+
+
+def test_make_context_with_none_core_parse_result():
+    """Passing core_parse_result=None explicitly is safe (backward compat)."""
+    config = ToolkitConfig()
+    c = ToolkitCall(_DUMMY_TASK)
+    ctx = c.make_context(config, core_parse_result=None)
+    assert ctx.remainder == ""
+
+
+# ---------------------------------------------------------------------------
+# Unit: ToolkitContext.__init__
+# ---------------------------------------------------------------------------
+
+
+def test_toolkit_context_remainder_default():
+    """ToolkitContext() has remainder='' by default."""
+    ctx = ToolkitContext()
+    assert ctx.remainder == ""
+
+
+def test_toolkit_context_remainder_kwarg():
+    """ToolkitContext(remainder=...) stores the value on the instance."""
+    ctx = ToolkitContext(remainder="docker run --rm alpine")
+    assert ctx.remainder == "docker run --rm alpine"
+
+
+def test_toolkit_context_remainder_with_config():
+    """ToolkitContext(config=..., remainder=...) works with both args."""
+    config = ToolkitConfig()
+    ctx = ToolkitContext(config=config, remainder="--verbose")
+    assert ctx.remainder == "--verbose"
+
+
+# ---------------------------------------------------------------------------
+# Unit: ToolkitExecutor.__init__
+# ---------------------------------------------------------------------------
+
+
+def test_executor_core_defaults_to_parse_result():
+    """ToolkitExecutor.core is never None; defaults to ParseResult()."""
+    col = ToolkitCollection()
+    executor = ToolkitExecutor(collection=col)
+    assert executor.core is not None
+    assert isinstance(executor.core, ParseResult)
+
+
+def test_executor_core_accepts_explicit_parse_result():
+    """ToolkitExecutor.core stores an explicitly provided ParseResult."""
+    col = ToolkitCollection()
+    pr = _make_parse_result("some remainder")
+    executor = ToolkitExecutor(collection=col, core=pr)
+    assert executor.core is pr
+    assert executor.core.remainder == "some remainder"
+
+
+def test_executor_core_none_becomes_empty_parse_result():
+    """Passing core=None explicitly still yields a ParseResult(), not None."""
+    col = ToolkitCollection()
+    executor = ToolkitExecutor(collection=col, core=None)
+    assert executor.core is not None
+    assert isinstance(executor.core, ParseResult)
+    assert executor.core.remainder == ""
+
+
+# ---------------------------------------------------------------------------
+# Integration: ctx.remainder is accessible inside a task
+# ---------------------------------------------------------------------------
+
+
+def test_task_receives_remainder_via_context():
+    """A task can read ctx.remainder when the program is given a remainder."""
+    captured: list[str] = []
+
+    ns = ToolkitCollection()
+
+    @task  # type: ignore[arg-type]
+    def wrapper_task(ctx: Context):
+        """Wrapper task that captures ctx.remainder."""
+        captured.append(ctx.remainder)
+
+    ns.add_task(wrapper_task)  # type: ignore[arg-type]
+
+    pr = _make_parse_result("echo hello world")
+    config = ToolkitConfig()
+    executor = ToolkitExecutor(collection=ns, config=config, core=pr)
+    executor.execute("wrapper-task")
+
+    assert len(captured) == 1
+    assert captured[0] == "echo hello world"
+
+
+def test_task_remainder_empty_when_not_provided():
+    """ctx.remainder is '' when no remainder was parsed."""
+    captured: list[str] = []
+
+    ns = ToolkitCollection()
+
+    @task  # type: ignore[arg-type]
+    def simple_task(ctx: Context):
+        """Simple task that captures ctx.remainder."""
+        captured.append(ctx.remainder)
+
+    ns.add_task(simple_task)  # type: ignore[arg-type]
+
+    executor = ToolkitExecutor(collection=ns)
+    executor.execute("simple-task")
+
+    assert captured == [""]