wexample-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{wexample_cli-0.3.0 → wexample_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-cli
-Version: 0.3.0
+Version: 0.5.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,7 +10,7 @@ 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.2.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
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # cli
 
-Version: 0.3.0
+Version: 0.5.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,7 +100,7 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=15.2.0
+- wexample-app: >=15.3.0
 - wexample-helpers: >=13.1.0
 - wexample-prompt: >=9.1.0
 

{wexample_cli-0.3.0 → wexample_cli-0.5.0}/README.md

@@ -1,6 +1,6 @@
 # cli
 
-Version: 0.3.0
+Version: 0.5.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,7 +80,7 @@ Visit the [Wexample Suite documentation](https://docs.wexample.com) for the comp
 ## Dependencies
 
 - attrs: >=23.1.0
-- wexample-app: >=15.2.0
+- wexample-app: >=15.3.0
 - wexample-helpers: >=13.1.0
 - wexample-prompt: >=9.1.0
 

{wexample_cli-0.3.0 → wexample_cli-0.5.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-cli"
-version = "0.3.0"
+version = "0.5.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,7 +19,7 @@ classifiers = [
 ]
 dependencies = [
     "attrs>=23.1.0",
-    "wexample-app>=15.2.0",
+    "wexample-app>=15.3.0",
     "wexample-helpers>=13.1.0",
     "wexample-prompt>=9.1.0",
 ]

{wexample_cli-0.3.0 → wexample_cli-0.5.0}/src/wexample_cli/command/extended_command.py

@@ -25,16 +25,14 @@ class ExtendedCommand(Command):
         # Now override function based on command_wrapper
         self.function = self.command_wrapper.function
 
-    def execute_request(self, request: CommandRequest) -> Any:
-        from wexample_app.helpers.response import response_normalize
-        from wexample_app.response.failure_response import FailureResponse
-        from wexample_app.response.multiple_response import MultipleResponse
+    @staticmethod
+    def _wrap_dispatch(wrapper_fn: Any, inner: Any, request: CommandRequest) -> Any:
+        def wrapped(function_kwargs: dict[str, Any]) -> Any:
+            return wrapper_fn(inner, function_kwargs, request)
 
-        from wexample_cli.const.middleware import (
-            MIDDLEWARE_OPTION_VALUE_ALLWAYS,
-            MIDDLEWARE_OPTION_VALUE_OPTIONAL,
-        )
+        return wrapped
 
+    def execute_request(self, request: CommandRequest) -> Any:
         # 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
@@ -55,6 +53,111 @@ class ExtendedCommand(Command):
 
         function_kwargs = self._build_function_kwargs(request=request)
 
+        # Compose pipeline wrappers around the dispatch. Each wrapper has
+        # signature (next_dispatch, function_kwargs, request) -> response and
+        # decides whether to call next_dispatch (passthrough), call it multiple
+        # times (refresh loop), modify kwargs, etc. Generic mechanism — knows
+        # nothing about specific wrappers like @screenable.
+        dispatch = self._make_dispatch(request=request)
+        for wrapper_fn in reversed(self.command_wrapper.pipeline_wrappers):
+            dispatch = self._wrap_dispatch(wrapper_fn, dispatch, request)
+
+        return dispatch(function_kwargs)
+
+    def _build_function_kwargs(self, request: CommandRequest) -> dict[str, Any]:
+        from wexample_cli.exception.command_option_missing_exception import (
+            CommandOptionMissingException,
+        )
+
+        # Allow middleware to add extra options.
+        for middleware in self.command_wrapper.middlewares:
+            middleware.append_options(
+                request=request,
+                command_wrapper=self.command_wrapper,
+            )
+
+        """Execute the command with the given request arguments."""
+        # Parse and convert arguments to appropriate types
+        parsed_args = self._parse_arguments(request.arguments)
+
+        """Build the final kwargs dictionary for the function call."""
+        function_kwargs = {}
+
+        # Process all declared options
+        for option in self.command_wrapper.options:
+            value = None
+
+            # If the option is in parsed args, use that value
+            if option.name in parsed_args:
+                value = parsed_args[option.name]
+            # Otherwise, use the default value if available
+            elif option.default is not None:
+                value = option.default
+            # If the option is required but not provided, raise an error
+            elif option.required:
+                raise CommandOptionMissingException(option_name=option.name)
+
+            # Validate the value if validators are defined and value is not None
+            if value is not None and option.validators:
+                # For multiple values, validate each item individually
+                values_to_validate = value if isinstance(value, list) else [value]
+
+                for val in values_to_validate:
+                    for validator in option.validators:
+                        if not validator.validate(val):
+                            from wexample_cli.exception.command_option_validation_exception import (
+                                CommandOptionValidationException,
+                            )
+
+                            raise CommandOptionValidationException(
+                                option_name=option.name,
+                                value=val,
+                                error_message=validator.get_error_message(val),
+                            )
+
+            # Normalize to list if always_list is True
+            if value is not None and option.always_list and not isinstance(value, list):
+                value = [value]
+
+            # Assign the validated value
+            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
+
+    def _execute_dispatch(
+        self, request: CommandRequest, function_kwargs: dict[str, Any]
+    ) -> Any:
+        from wexample_app.helpers.response import response_normalize
+        from wexample_app.response.failure_response import FailureResponse
+        from wexample_app.response.multiple_response import MultipleResponse
+
+        from wexample_cli.const.middleware import (
+            MIDDLEWARE_OPTION_VALUE_ALLWAYS,
+            MIDDLEWARE_OPTION_VALUE_OPTIONAL,
+        )
+
         if len(self.command_wrapper.middlewares) > 0:
             output = MultipleResponse(kernel=self.kernel)
 
@@ -167,67 +270,6 @@ class ExtendedCommand(Command):
             kernel=self.kernel, response=function_to_execute(**context.function_kwargs)
         )
 
-    def _build_function_kwargs(self, request: CommandRequest) -> dict[str, Any]:
-        from wexample_cli.exception.command_option_missing_exception import (
-            CommandOptionMissingException,
-        )
-
-        # Allow middleware to add extra options.
-        for middleware in self.command_wrapper.middlewares:
-            middleware.append_options(
-                request=request,
-                command_wrapper=self.command_wrapper,
-            )
-
-        """Execute the command with the given request arguments."""
-        # Parse and convert arguments to appropriate types
-        parsed_args = self._parse_arguments(request.arguments)
-
-        """Build the final kwargs dictionary for the function call."""
-        function_kwargs = {}
-
-        # Process all declared options
-        for option in self.command_wrapper.options:
-            value = None
-
-            # If the option is in parsed args, use that value
-            if option.name in parsed_args:
-                value = parsed_args[option.name]
-            # Otherwise, use the default value if available
-            elif option.default is not None:
-                value = option.default
-            # If the option is required but not provided, raise an error
-            elif option.required:
-                raise CommandOptionMissingException(option_name=option.name)
-
-            # Validate the value if validators are defined and value is not None
-            if value is not None and option.validators:
-                # For multiple values, validate each item individually
-                values_to_validate = value if isinstance(value, list) else [value]
-
-                for val in values_to_validate:
-                    for validator in option.validators:
-                        if not validator.validate(val):
-                            from wexample_cli.exception.command_option_validation_exception import (
-                                CommandOptionValidationException,
-                            )
-
-                            raise CommandOptionValidationException(
-                                option_name=option.name,
-                                value=val,
-                                error_message=validator.get_error_message(val),
-                            )
-
-            # Normalize to list if always_list is True
-            if value is not None and option.always_list and not isinstance(value, list):
-                value = [value]
-
-            # Assign the validated value
-            if value is not None:
-                option.value = function_kwargs[option.name] = value
-
-        return function_kwargs
-
     async def _execute_passes_parallel(
         self, execution_contexts: list[ExecutionContext]
     ) -> list[Any]:
@@ -290,6 +332,14 @@ class ExtendedCommand(Command):
 
         return responses
 
+    def _make_dispatch(self, request: CommandRequest) -> Any:
+        def dispatch(function_kwargs: dict[str, Any]) -> Any:
+            return self._execute_dispatch(
+                request=request, function_kwargs=function_kwargs
+            )
+
+        return dispatch
+
     def _parse_arguments(self, arguments: list[str] | dict) -> ParsedArgs:
         """Parse raw command line arguments into a dictionary of option name to value.
 

{wexample_cli-0.3.0 → wexample_cli-0.5.0}/src/wexample_cli/common/command_method_wrapper.py

@@ -46,6 +46,15 @@ class CommandMethodWrapper(BaseClass):
         factory=list,
         description="List of command options available for this method",
     )
+    pipeline_wrappers: list[AnyCallable] = public_field(
+        factory=list,
+        description=(
+            "Pipeline wrappers applied around the full dispatch. Each wrapper "
+            "has signature `(next_dispatch, function_kwargs, request) -> response` "
+            "and decides whether/how to invoke `next_dispatch(kwargs)`. "
+            "Registered in outer-to-inner order: the first registered wraps everything."
+        ),
+    )
     sudo: bool = public_field(
         default=False,
         description="If True, re-exec the entire process under sudo if not already root",
@@ -95,6 +104,10 @@ class CommandMethodWrapper(BaseClass):
 
         self.middlewares_attributes[middleware_name] = middleware_kwargs
 
+    def register_pipeline_wrapper(self, wrapper_fn: AnyCallable) -> None:
+        """Register a pipeline wrapper. See `pipeline_wrappers` field doc."""
+        self.pipeline_wrappers.append(wrapper_fn)
+
     def set_middleware(self, middleware: AbstractMiddleware) -> None:
         self.middlewares.append(middleware)
 

wexample_cli-0.5.0/src/wexample_cli/decorator/screenable.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+OPTION_NAME_SCREEN: str = "screen"
+OPTION_NAME_SCREEN_INTERVAL: str = "screen_interval"
+
+
+def screenable(interval: float = 1.0, height: int = 30) -> AnyCallable:
+    """Make a command refreshable via `--screen`.
+
+    Adds two CLI options to the wrapped command:
+      - `--screen` (flag): opt-in to continuous refresh.
+      - `--screen-interval <float>`: override the default interval.
+
+    Registers a pipeline wrapper that handles the refresh loop. The wrapper
+    pops the screen kwargs unconditionally (so they never leak to the user
+    function) and, when enabled, drives a `ScreenPromptResponse` whose callback
+    invokes the rest of the dispatch on every frame.
+    """
+
+    def decorator(command_wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        from wexample_app.command.option import Option
+
+        from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+        if not isinstance(command_wrapper, CommandMethodWrapper):
+            raise TypeError(
+                "@screenable must decorate a CommandMethodWrapper produced by @command. "
+                "Apply @command first."
+            )
+
+        command_wrapper.set_option(
+            Option(
+                name=OPTION_NAME_SCREEN,
+                type=bool,
+                description="Refresh the command continuously like `watch`.",
+                default=False,
+                is_flag=True,
+            )
+        )
+        command_wrapper.set_option(
+            Option(
+                name=OPTION_NAME_SCREEN_INTERVAL,
+                type=float,
+                description="Override the refresh interval in seconds.",
+                default=None,
+                required=False,
+            )
+        )
+
+        command_wrapper.register_pipeline_wrapper(
+            _build_screen_wrapper(default_interval=float(interval), height=int(height))
+        )
+
+        return command_wrapper
+
+    return decorator
+
+
+def _build_screen_wrapper(default_interval: float, height: int) -> AnyCallable:
+    """Build the pipeline wrapper closure for one decorated command."""
+
+    def screen_wrapper(
+        next_dispatch: AnyCallable,
+        function_kwargs: dict[str, Any],
+        request: Any,
+    ) -> Any:
+        # Always strip screen kwargs so they cannot leak to the user function
+        # or to inner pipeline wrappers, whether or not --screen was passed.
+        enabled = bool(function_kwargs.pop(OPTION_NAME_SCREEN, False))
+        interval_override = function_kwargs.pop(OPTION_NAME_SCREEN_INTERVAL, None)
+
+        if not enabled:
+            return next_dispatch(function_kwargs)
+
+        import time
+
+        from wexample_app.response.null_response import NullResponse
+
+        interval = (
+            float(interval_override)
+            if interval_override is not None
+            else default_interval
+        )
+        kernel_io = request.kernel.io
+        # Skip the inter-frame sleep on the very first frame so the user sees
+        # output immediately instead of waiting `interval` seconds before the
+        # first render.
+        is_first_frame = [True]
+
+        def _frame(response) -> None:
+            if not is_first_frame[0]:
+                time.sleep(interval)
+            is_first_frame[0] = False
+
+            response.clear()
+            saved_output = kernel_io.output
+            kernel_io.output = response.io.output
+            try:
+                next_dispatch(function_kwargs)
+            finally:
+                kernel_io.output = saved_output
+
+            response.reload()
+
+        kernel_io.screen(callback=_frame, height=height)
+        return NullResponse(kernel=request.kernel)
+
+    return screen_wrapper

wexample_cli-0.5.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