wexample-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{wexample_cli-0.2.0 → wexample_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -10,9 +10,9 @@ Classifier: Operating System :: OS Independent
 Project-URL: homepage, https://github.com/wexample/python-cli
 Requires-Python: >=3.10
 Requires-Dist: attrs>=23.1.0
-Requires-Dist: wexample-app>=15.1.0
-Requires-Dist: wexample-helpers>=13.0.0
-Requires-Dist: wexample-prompt>=9.0.0
+Requires-Dist: wexample-app>=15.3.0
+Requires-Dist: wexample-helpers>=13.1.0
+Requires-Dist: wexample-prompt>=9.1.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # cli
 
-Version: 0.2.0
+Version: 0.4.0
 
 Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 
@@ -100,9 +100,9 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=15.1.0
-- wexample-helpers: >=13.0.0
-- wexample-prompt: >=9.0.0
+- wexample-app: >=15.3.0
+- wexample-helpers: >=13.1.0
+- wexample-prompt: >=9.1.0
 
 ## Versioning & Compatibility Policy
 

{wexample_cli-0.2.0 → wexample_cli-0.4.0}/README.md

@@ -1,6 +1,6 @@
 # cli
 
-Version: 0.2.0
+Version: 0.4.0
 
 Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 
@@ -80,9 +80,9 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=15.1.0
-- wexample-helpers: >=13.0.0
-- wexample-prompt: >=9.0.0
+- wexample-app: >=15.3.0
+- wexample-helpers: >=13.1.0
+- wexample-prompt: >=9.1.0
 
 ## Versioning & Compatibility Policy
 

{wexample_cli-0.2.0 → wexample_cli-0.4.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -19,9 +19,9 @@ classifiers = [
 ]
 dependencies = [
     "attrs>=23.1.0",
-    "wexample-app>=15.1.0",
-    "wexample-helpers>=13.0.0",
-    "wexample-prompt>=9.0.0",
+    "wexample-app>=15.3.0",
+    "wexample-helpers>=13.1.0",
+    "wexample-prompt>=9.1.0",
 ]
 
 [project.readme]

{wexample_cli-0.2.0 → wexample_cli-0.4.0}/src/wexample_cli/command/extended_command.py

@@ -35,14 +35,8 @@ class ExtendedCommand(Command):
             MIDDLEWARE_OPTION_VALUE_OPTIONAL,
         )
 
-        # Universal --help / -h handling — render the command's options instead
-        # of dispatching. Done before middleware/option validation so it works
-        # even when required options are missing.
-        if isinstance(request.arguments, list) and any(
-            arg in ("--help", "-h") for arg in request.arguments
-        ):
-            return self._render_help(request)
-
+        # Instantiate middlewares first so their contributed options are visible
+        # to --help below and to option validation in _build_function_kwargs.
         middlewares_attributes = self.command_wrapper.middlewares_attributes
         middlewares_registry = self.kernel.get_registry("middlewares")
 
@@ -51,6 +45,14 @@ class ExtendedCommand(Command):
             middleware = middleware_class(**middlewares_attributes[name])
             self.command_wrapper.set_middleware(middleware)
 
+        # Universal --help / -h handling — render the command's options instead
+        # of dispatching. Done before option validation so it works even when
+        # required options are missing.
+        if isinstance(request.arguments, list) and any(
+            arg in ("--help", "-h") for arg in request.arguments
+        ):
+            return self._render_help(request)
+
         function_kwargs = self._build_function_kwargs(request=request)
 
         if len(self.command_wrapper.middlewares) > 0:
@@ -224,6 +226,27 @@ class ExtendedCommand(Command):
             if value is not None:
                 option.value = function_kwargs[option.name] = value
 
+        # `--` passthrough: if the user supplied extra args after `--`, the
+        # parser put them in parsed_args["__extra_args__"]. Forward them as
+        # `extra_args` if the wrapped function declares that parameter;
+        # otherwise raise so misuse fails loudly instead of silently dropping
+        # input.
+        if "__extra_args__" in parsed_args:
+            import inspect
+
+            sig = inspect.signature(self.command_wrapper.function)
+            if "extra_args" in sig.parameters:
+                function_kwargs["extra_args"] = parsed_args["__extra_args__"]
+            else:
+                from wexample_app.exception.command_unexpected_argument_exception import (
+                    CommandUnexpectedArgumentException,
+                )
+
+                raise CommandUnexpectedArgumentException(
+                    argument="--",
+                    allowed_arguments=self.command_wrapper.get_options_names(),
+                )
+
         return function_kwargs
 
     async def _execute_passes_parallel(

wexample_cli-0.4.0/src/wexample_cli/helpers/extra_args.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import shlex
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_cli.context.execution_context import ExecutionContext
+
+
+def resolve_shell_command(
+    *,
+    context: ExecutionContext,
+    command: str | None,
+    extra_args: list[str] | None,
+) -> str | None:
+    """Pick the shell command string from `--command "..."` or `-- args...`.
+
+    Pattern intended for commands that wrap an underlying shell call (SSH,
+    docker exec, sub-shell, ...). Returns the resolved command string ready
+    to be passed to the remote shell, or None if neither form was provided
+    (caller should then error/exit).
+
+    - `extra_args` (positional, post-`--`) wins over `command` (legacy `-c`),
+      because positional form is the one that round-trips complex quoting.
+    - Args in `extra_args` are joined with `shlex.join`, which single-quotes
+      tokens that need protection — `$VAR` is NOT expanded by the remote
+      shell, which is the safer default. Use the legacy `--command "..."`
+      form if you intentionally want remote expansion.
+    """
+    if extra_args and command:
+        context.io.warning(
+            "Both --command and `-- <args>` were given; using `-- <args>`."
+        )
+    if extra_args:
+        return shlex.join(extra_args)
+    if command:
+        return command
+    return None

wexample_cli-0.4.0/src/wexample_cli/testing/kernel.py

@@ -0,0 +1,65 @@
+"""Test helpers for kernels built on wexample-app + wexample-cli.
+
+Used by downstream packages (trader, wex-core, future kernels) to dispatch a
+command through the **real** @command/@option/middleware pipeline in tests
+instead of calling the decorated function directly — so tests catch
+regressions in the decorator/resolver/runner layer, not just in business logic.
+
+Typical use::
+
+    @pytest.fixture
+    def kernel():
+        from trader.kernel import TraderKernel
+        from wexample_cli.testing.kernel import boot_kernel
+        return boot_kernel(TraderKernel, entrypoint_path="/opt/trader/src/trader/__main__.py")
+
+    def test_missing_required_option_raises(kernel):
+        from wexample_cli.testing.kernel import dispatch_command
+        from wexample_cli.exception.command_option_missing_exception import (
+            CommandOptionMissingException,
+        )
+        with pytest.raises(CommandOptionMissingException):
+            dispatch_command(kernel, "data/ingest", {})
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from wexample_app.common.abstract_kernel import AbstractKernel
+    from wexample_app.response.abstract_response import AbstractResponse
+
+
+def boot_kernel(
+    kernel_class: type[AbstractKernel],
+    entrypoint_path: str,
+    **setup_kwargs: Any,
+) -> AbstractKernel:
+    """Instantiate ``kernel_class`` and run its ``.setup()`` chain.
+
+    Equivalent to the production boot path (``KernelClass(entrypoint_path=...).setup()``)
+    but exposed as a single call so test fixtures stay short.
+    """
+    return kernel_class(entrypoint_path=entrypoint_path, **setup_kwargs).setup()
+
+
+def dispatch_command(
+    kernel: AbstractKernel,
+    name: str,
+    arguments: list[str] | dict | None = None,
+) -> AbstractResponse:
+    """Build a CommandRequest and execute it through the kernel.
+
+    ``arguments`` accepts the same shapes as a real invocation:
+      - ``list[str]``: CLI-style (``["--symbol", "BTCUSDT", ...]``)
+      - ``dict``: pre-parsed kwargs (``{"symbol": "BTCUSDT", ...}``) — used
+        directly without argv parsing, handy in unit tests.
+    """
+    request_class = kernel._get_command_request_class()
+    request = request_class(
+        kernel=kernel,
+        name=name,
+        arguments=arguments if arguments is not None else [],
+    )
+    return kernel.execute_kernel_command(request)