invoke-toolkit 0.0.56__tar.gz → 0.0.58__tar.gz

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invoke-toolkit
-Version: 0.0.56
+Version: 0.0.58
 Summary: A set of extended APIs for PyInvoke for composable scripts, plugins and richer output
 Project-URL: Documentation, https://github.com/D3f0/invoke-toolkit#readme
 Project-URL: Issues, https://github.com/D3f0/invoke-toolkit/issues

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/src/invoke_toolkit/completion.py

@@ -20,7 +20,7 @@ from invoke.completion.complete import (
 from invoke.exceptions import Exit, ParseError
 from invoke.parser import Parser, ParserContext
 
-from invoke_toolkit.config import get_config_value
+from invoke_toolkit.config import ToolkitConfig
 from invoke_toolkit.context import ToolkitContext
 from invoke_toolkit.tasks.tasks import (
     _extract_enum_params,
@@ -176,11 +176,11 @@ def get_choices_for_argument(
         if arg_name in callbacks:
             try:
                 # Try to call the callback with context and incomplete
-                ctx = ToolkitContext()
+                ctx = ToolkitContext(config=ToolkitConfig())
 
                 # Get timeout from config (default: 10 seconds)
-                timeout = get_config_value(
-                    ctx, "completion.callback_timeout", default=10.0
+                timeout = ctx.get_config_value(
+                    "completion.callback_timeout", default=10.0
                 )
 
                 # Execute callback with timeout

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/src/invoke_toolkit/config/config.py

@@ -391,32 +391,30 @@ def get_config_value(  # pylint: disable=inconsistent-return-statements
         SystemExit: Raised via ctx.rich_exit() if required value is missing.
 
     Examples:
-        >>> from invoke_toolkit import task, Context
-        >>> from invoke_toolkit.config import get_config_value
-        >>> @task()
-        >>> def my_task(ctx: Context, db_host: str = "") -> None:
-        >>>     # Simple usage
-        >>>     db_host = db_host or get_config_value(
-        >>>         ctx, "database.host", default="localhost"
-        >>>     )
-        >>>
-        >>>     # With nested path and default
-        >>>     db_port = get_config_value(
-        >>>         ctx, "database.settings.port", default=5432
-        >>>     )
-        >>>
-        >>>     # Required value with custom message
-        >>>     api_key = get_config_value(
-        >>>         ctx, "api.key",
-        >>>         exit_code=2,
-        >>>         exit_message="API key must be configured in 'api.key'"
-        >>>     )
-        >>>
-        >>>     # Required value with auto-detected argument name
-        >>>     secret = get_config_value(
-        >>>         ctx, "secrets.token",
-        >>>         exit_code=1  # Auto-detects 'secret' parameter name
-        >>>     )
+        Preferred: Use the context method (no import needed)::
+
+            @task()
+            def my_task(ctx: Context) -> None:
+                # Simple usage with default
+                db_host = ctx.get_config_value("database.host", default="localhost")
+
+                # Required value - exits if missing
+                api_key = ctx.get_config_value("api.key", required=True)
+
+                # Required with custom exit code and message
+                secret = ctx.get_config_value(
+                    "secrets.token",
+                    exit_code=2,
+                    exit_message="Token must be configured"
+                )
+
+        Alternative: Use the standalone function (backward compatible)::
+
+            from invoke_toolkit.config import get_config_value
+
+            @task()
+            def my_task(ctx: Context) -> None:
+                db_host = get_config_value(ctx, "database.host", default="localhost")
     """
     # Mark as required if exit parameters are provided or if required=True
     has_exit_params = (exit_message is not None) or (exit_code is not None) or required

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/src/invoke_toolkit/context/context.py

@@ -7,6 +7,7 @@ from contextlib import _GeneratorContextManager, contextmanager
 from os import PathLike
 from typing import (
     TYPE_CHECKING,
+    Any,
     Callable,
     Generator,
     Iterator,
@@ -16,6 +17,7 @@ from typing import (
     Protocol,
     TypeVar,
     Union,
+    overload,
 )
 
 import setproctitle
@@ -329,3 +331,87 @@ class ToolkitContext(Context, ConfigProtocol):
                     ["tmux", "rename-window", previous_tmux_title],
                     check=False,
                 )
+
+    # Type overloads for get_config_value - returns T when no exit params
+    @overload
+    def get_config_value(
+        self,
+        path: str,
+        default: T = ...,  # type: ignore[assignment]
+        exit_message: None = None,
+        exit_code: None = None,
+        required: bool = False,
+    ) -> Any | T: ...
+
+    # Type hints NoReturn when exit_message provided
+    @overload
+    def get_config_value(
+        self,
+        path: str,
+        default: Any = ...,
+        exit_message: str = ...,
+        exit_code: Optional[int] = None,
+        required: bool = False,
+    ) -> Any | NoReturn: ...
+
+    # Type hints NoReturn when exit_code provided
+    @overload
+    def get_config_value(
+        self,
+        path: str,
+        default: Any = ...,
+        exit_message: None = None,
+        exit_code: int = ...,
+        required: bool = False,
+    ) -> Any | NoReturn: ...
+
+    # Type hints NoReturn when required=True
+    @overload
+    def get_config_value(
+        self,
+        path: str,
+        default: Any = ...,
+        exit_message: Optional[str] = None,
+        exit_code: Optional[int] = None,
+        required: bool = True,
+    ) -> Any | NoReturn: ...
+
+    def get_config_value(
+        self,
+        path: str,
+        default: Any = ...,
+        exit_message: Optional[str] = None,
+        exit_code: Optional[int] = None,
+        required: bool = False,
+    ) -> Any:
+        """Get a configuration value from config with dot notation support.
+
+        This is a convenience method that wraps invoke_toolkit.config.get_config_value.
+        See that function for full documentation.
+
+        Args:
+            path: Dot-separated path to the config value (e.g., 'database.host')
+            default: Default value if path not found
+            exit_message: Custom message when value required but missing
+            exit_code: Exit code for ctx.rich_exit() when missing
+            required: Whether value is required (exits if missing)
+
+        Returns:
+            The config value if found, otherwise default value.
+
+        Example:
+            @task()
+            def my_task(ctx: Context) -> None:
+                db_host = ctx.get_config_value("database.host", default="localhost")
+                api_key = ctx.get_config_value("api.key", required=True)
+        """
+        # Import here to avoid circular imports
+        from invoke_toolkit.config.config import (  # pylint: disable=import-outside-toplevel
+            _UNDEFINED_DEFAULT,
+            get_config_value as _get_config_value,
+        )
+
+        # Handle the default sentinel - ellipsis means "use undefined default"
+        if default is ...:
+            default = _UNDEFINED_DEFAULT
+        return _get_config_value(self, path, default, exit_message, exit_code, required)

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/src/invoke_toolkit/extensions/tasks/config.py

@@ -404,10 +404,8 @@ def _complete_config_path(ctx: Context, incomplete: str) -> list[str]:
 
         def _complete_my_items(ctx: Context, incomplete: str) -> list[str]:
             '''Completion callback for my custom items.'''
-            from invoke_toolkit.config import get_config_value
-
-            # Get data from context or config
-            items = get_config_value(ctx, "my.items", default=[])
+            # Get data from config using context method (no import needed)
+            items = ctx.get_config_value("my.items", default=[])
 
             # Filter by incomplete prefix
             matching = [i for i in items if i.startswith(incomplete)]

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/src/invoke_toolkit/extensions/tasks/create.py

@@ -65,7 +65,7 @@ def _get_template() -> str:
     script_template = dedent(rf"""
     #!/usr/bin/env -S uv run --script
     # /// script
-    # requires-python = ">=3.10"
+    # requires-python = ">=3.11"
     # dependencies = [
     #     "invoke-toolkit{version_for_template}",
     # ]
@@ -322,9 +322,9 @@ def package(
         template_data = {
             "package_name": actual_name,
             "package_slug": package_slug,
-            "collection_name": package_slug,
+            "collection_name": extension_short_name,
             "extension_short_name": extension_short_name,
-            "python_version": "3.10",
+            "python_version": "3.11",
         }
 
         run_copy(
@@ -342,9 +342,10 @@ def package(
             dedent(
                 f"""
                 [yellow]Next steps:[/yellow]
-                  cd {actual_name}
+                  cd {target_path}
                   uv sync
-                  uv pip install -e .
+                  # Test your package
+                  uv run --directory {target_path} -m invoke-toolkit -l
                 """
             ).strip()
         )

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/templates/package-template/pyproject.toml.jinja

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "{{ package_name }}"
-dynamic = ["version"]
+version = "0.1.0"
 description = "{{ project_description }}"
 readme = "README.md"
 requires-python = ">={{ python_version }}"
@@ -17,9 +17,10 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
     "invoke-toolkit",  # Requires invoke-toolkit, any version
@@ -28,8 +29,5 @@ dependencies = [
 [project.entry-points."invoke_toolkit.collection"]
 "{{ extension_short_name }}" = "{{ package_slug }}:collection"
 
-[tool.hatch.version]
-path = "src/{{ package_slug }}/__init__.py"
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/{{ package_slug }}"]

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/tests/extensions/test_create.py

@@ -274,7 +274,7 @@ def _verify_python_requirement(lines):
     """Verify requires-python field exists and has correct value."""
     for line in lines:
         if "requires-python" in line:
-            assert ">=3.10" in line, f"Expected requires-python >=3.10, got: '{line}'"
+            assert ">=3.11" in line, f"Expected requires-python >=3.11, got: '{line}'"
             return
 
     raise AssertionError("requires-python field not found in metadata")
@@ -658,6 +658,144 @@ def test_package_uses_git_config_template(
     assert (pkg_dir / "pyproject.toml").exists(), "pyproject.toml should exist"
 
 
+def _assert_cli_examples_use_name(
+    short_name: str, pkg_dir: Path, package_slug: str
+) -> None:
+    """
+    Helper: asserts that the rendered README.md and __init__.py use ``short_name``
+    (the intk-visible collection name) in all CLI usage examples, and that no
+    raw Jinja placeholders leaked through.
+    """
+    # --- README.md checks ---
+    readme_path = pkg_dir / "README.md"
+    assert readme_path.exists(), "README.md was not generated"
+    readme = readme_path.read_text(encoding="utf-8")
+
+    assert f"collection named `{short_name}`" in readme, (
+        f"README should reference '{short_name}' in the collection listing sentence, "
+        f"but got:\n{readme}"
+    )
+    assert f"`{short_name}.hello`" in readme, (
+        f"README should reference '{short_name}' in the task list entry, "
+        f"but got:\n{readme}"
+    )
+    assert f"intk {short_name}.hello" in readme, (
+        f"README should reference '{short_name}' in the example command, "
+        f"but got:\n{readme}"
+    )
+    assert "{{ collection_name }}" not in readme, (
+        "Jinja variable {{ collection_name }} was not rendered in README.md"
+    )
+    assert "{{ package_name }}" not in readme, (
+        "Jinja variable {{ package_name }} was not rendered in README.md"
+    )
+
+    # --- __init__.py comment checks ---
+    init_path = pkg_dir / "src" / package_slug / "__init__.py"
+    assert init_path.exists(), "__init__.py was not generated"
+    init = init_path.read_text(encoding="utf-8")
+
+    assert f"intk {short_name}.hello" in init, (
+        f"__init__.py example comment should reference '{short_name}' for 'hello', "
+        f"but got:\n{init}"
+    )
+    assert f"intk {short_name}.my_task" in init, (
+        f"__init__.py example comment should reference '{short_name}' for 'my_task', "
+        f"but got:\n{init}"
+    )
+    assert f"intk {short_name}.tasks.hello" in init, (
+        f"__init__.py 'NOT' comment should reference '{short_name}' for nested 'tasks.hello', "
+        f"but got:\n{init}"
+    )
+    assert f"intk {short_name}.utils.my_task" in init, (
+        f"__init__.py 'NOT' comment should reference '{short_name}' for nested 'utils.my_task', "
+        f"but got:\n{init}"
+    )
+    assert "{{ collection_name }}" not in init, (
+        "Jinja variable {{ collection_name }} was not rendered in __init__.py"
+    )
+    assert "{{ package_name }}" not in init, (
+        "Jinja variable {{ package_name }} was not rendered in __init__.py"
+    )
+
+
+def test_template_cli_examples_use_collection_name_unprefixed(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """
+    Regression test (non-prefixed package): verifies that the CLI usage examples
+    in README.md and __init__.py use the package slug as the collection name.
+
+    For a package named ``my-readme-pkg`` (no ``invoke-toolkit-`` prefix) the
+    intk-visible name is the full slug ``my_readme_pkg``.
+    """
+    import invoke_toolkit
+
+    invoke_toolkit_path = Path(invoke_toolkit.__file__).parent
+    default_template = (
+        invoke_toolkit_path.parent.parent / "templates" / "package-template"
+    )
+    if not default_template.exists():
+        pytest.skip("Default template not found in development setup")
+
+    monkeypatch.chdir(tmp_path)
+
+    package_name = "my-readme-pkg"
+    package_slug = package_name.replace("-", "_")
+    # Non-prefixed: collection_name == package_slug
+    expected_short_name = package_slug
+
+    x = TestingToolkitProgram()
+    x.run(["", "-x", "create.package", "--name", package_name])
+
+    _assert_cli_examples_use_name(
+        expected_short_name, tmp_path / package_name, package_slug
+    )
+
+
+def test_template_cli_examples_use_collection_name_prefixed(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """
+    Regression test (invoke-toolkit-prefixed package): verifies that the CLI
+    usage examples use only the short name after stripping the ``invoke-toolkit-``
+    prefix, not the full package name.
+
+    For ``--name my-pkg --ext-name myext`` the full package name becomes
+    ``invoke-toolkit-myext``, but intk exposes it as ``myext``.
+    """
+    import invoke_toolkit
+
+    invoke_toolkit_path = Path(invoke_toolkit.__file__).parent
+    default_template = (
+        invoke_toolkit_path.parent.parent / "templates" / "package-template"
+    )
+    if not default_template.exists():
+        pytest.skip("Default template not found in development setup")
+
+    monkeypatch.chdir(tmp_path)
+
+    ext_name = "myext"
+    full_package_name = f"invoke-toolkit-{ext_name}"
+    package_slug = full_package_name.replace("-", "_")
+    # Prefixed: collection_name == ext_name (the part after "invoke-toolkit-")
+    expected_short_name = ext_name
+
+    x = TestingToolkitProgram()
+    x.run(["", "-x", "create.package", "--name", "ignored", "--ext-name", ext_name])
+
+    pkg_dir = tmp_path / full_package_name
+    _assert_cli_examples_use_name(expected_short_name, pkg_dir, package_slug)
+
+    # Extra guard: the full package name must NOT appear as the collection name
+    readme = (pkg_dir / "README.md").read_text(encoding="utf-8")
+    assert f"intk {full_package_name}.hello" not in readme, (
+        "README must not use the full prefixed package name as the collection name"
+    )
+
+
 def test_package_template_priority_explicit_over_git_config(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/collection.py

@@ -0,0 +1,10 @@
+from invoke import Collection, ctask  # pylint: disable=no-name-in-module
+
+
+@ctask
+def go(c):
+    c.run("false")  # Ensures a kaboom if mocking fails
+
+
+ns = Collection(go)
+ns.configure({"run": {"echo": True}})

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/echo.yaml

@@ -0,0 +1,2 @@
+run:
+  echo: true

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/no-dedupe.yaml

@@ -0,0 +1,2 @@
+tasks:
+  dedupe: false

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/no-echo.yaml

@@ -0,0 +1,2 @@
+run:
+  echo: false

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/package/invoke.yml

@@ -0,0 +1,3 @@
+outer:
+  inner:
+    hooray: "package"

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/package/tasks/__init__.py

@@ -0,0 +1,6 @@
+from invoke import task
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "package"

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/runtime.py

@@ -0,0 +1,6 @@
+from invoke import task
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "yaml"

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/underscores/tasks.py

@@ -0,0 +1,6 @@
+from invoke import task
+
+
+@task
+def i_have_underscores(c):
+    pass

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/yaml/explicit.py

@@ -0,0 +1,9 @@
+from invoke import task, Collection
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "yaml"
+
+
+ns = Collection(mytask)

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/yaml/tasks.py

@@ -0,0 +1,6 @@
+from invoke import task
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "yaml"

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/yml/explicit.py

@@ -0,0 +1,9 @@
+from invoke import task, Collection
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "yml"
+
+
+ns = Collection(mytask)

invoke_toolkit-0.0.58/tests/original_invoke/_support/configs/yml/tasks.py

@@ -0,0 +1,6 @@
+from invoke import task
+
+
+@task
+def mytask(c):
+    assert c.outer.inner.hooray == "yml"

{invoke_toolkit-0.0.56 → invoke_toolkit-0.0.58}/tests/test_completion_with_choices.py

@@ -1126,3 +1126,47 @@ def test_completion_callback_cached_decorator_without_diskcache():
     # Check cache info shows no backend
     cache_info = no_cache_callback.cache_info()
     assert cache_info["backend"] == "none"
+
+
+def test_completion_callback_has_access_to_config():
+    """Test that completion callbacks have access to ToolkitConfig.
+
+    This test demonstrates that the fix for instantiating ToolkitConfig in completion
+    callbacks allows them to access the config object and read config values like
+    completion.callback_timeout with the correct defaults.
+
+    Before the fix, ctx.get_config_value() would only return default values because
+    ToolkitContext was instantiated without any config, causing it to use the
+    base invoke.config.Config instead of ToolkitConfig.
+    """
+
+    def config_aware_callback(ctx: Context, incomplete: str) -> list[str]:
+        """A callback that reads config values."""
+        # Uses ctx.get_config_value() method - no import needed
+        # This works because ctx has ToolkitConfig (not base Config)
+        timeout = ctx.get_config_value("completion.callback_timeout", default=999.0)
+
+        # With the fix, this should be 10.0 (the ToolkitConfig default)
+        # Without the fix, it would fall back to the default value (999.0)
+        return [f"timeout={timeout}"]
+
+    coll = ToolkitCollection()
+
+    @task
+    def config_task(
+        ctx: Context,
+        option: Annotated[str, config_aware_callback],
+    ) -> None:
+        """Task that uses config in completion callback."""
+
+    coll.add_task(config_task)  # type: ignore[arg-type]
+
+    # Get completion choices
+    choices = get_choices_for_argument(coll, "config-task", "option", "")
+
+    # Verify the callback could access the ToolkitConfig default value
+    assert len(choices) == 1, f"Expected 1 choice, got {len(choices)}: {choices}"
+    # Should be the ToolkitConfig default (10.0), not the fallback default (999.0)
+    assert "timeout=10.0" in choices, (
+        f"Expected default timeout value (10.0) from ToolkitConfig, got: {choices}"
+    )