falyx 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

falyx/__init__.py

@@ -7,7 +7,7 @@ Licensed under the MIT License. See LICENSE file for details.
 
 import logging
 
-from .action import Action, ActionGroup, ChainedAction, ProcessAction
+from .action.action import Action, ActionGroup, ChainedAction, ProcessAction
 from .command import Command
 from .context import ExecutionContext, SharedContext
 from .execution_registry import ExecutionRegistry

falyx/action/__init__.py

@@ -0,0 +1,41 @@
+"""
+Falyx CLI Framework
+
+Copyright (c) 2025 rtj.dev LLC.
+Licensed under the MIT License. See LICENSE file for details.
+"""
+
+from .action import (
+    Action,
+    ActionGroup,
+    BaseAction,
+    ChainedAction,
+    FallbackAction,
+    LiteralInputAction,
+    ProcessAction,
+)
+from .action_factory import ActionFactoryAction
+from .http_action import HTTPAction
+from .io_action import BaseIOAction, ShellAction
+from .menu_action import MenuAction
+from .select_file_action import SelectFileAction
+from .selection_action import SelectionAction
+from .signal_action import SignalAction
+
+__all__ = [
+    "Action",
+    "ActionGroup",
+    "BaseAction",
+    "ChainedAction",
+    "ProcessAction",
+    "ActionFactoryAction",
+    "HTTPAction",
+    "BaseIOAction",
+    "ShellAction",
+    "SelectionAction",
+    "SelectFileAction",
+    "MenuAction",
+    "SignalAction",
+    "FallbackAction",
+    "LiteralInputAction",
+]

falyx/{action.py → action/action.py}

@@ -4,7 +4,8 @@
 Core action system for Falyx.
 
 This module defines the building blocks for executable actions and workflows,
-providing a structured way to compose, execute, recover, and manage sequences of operations.
+providing a structured way to compose, execute, recover, and manage sequences of
+operations.
 
 All actions are callable and follow a unified signature:
     result = action(*args, **kwargs)
@@ -14,7 +15,8 @@ Core guarantees:
 - Consistent timing and execution context tracking for each run.
 - Unified, predictable result handling and error propagation.
 - Optional last_result injection to enable flexible, data-driven workflows.
-- Built-in support for retries, rollbacks, parallel groups, chaining, and fallback recovery.
+- Built-in support for retries, rollbacks, parallel groups, chaining, and fallback
+  recovery.
 
 Key components:
 - Action: wraps a function or coroutine into a standard executable unit.
@@ -43,10 +45,11 @@ from falyx.debug import register_debug_hooks
 from falyx.exceptions import EmptyChainError
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import Hook, HookManager, HookType
+from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.retry import RetryHandler, RetryPolicy
-from falyx.themes.colors import OneColors
-from falyx.utils import ensure_async, logger
+from falyx.themes import OneColors
+from falyx.utils import ensure_async
 
 
 class BaseAction(ABC):
@@ -55,7 +58,8 @@ class BaseAction(ABC):
     complex actions like `ChainedAction` or `ActionGroup`. They can also
     be run independently or as part of Falyx.
 
-    inject_last_result (bool): Whether to inject the previous action's result into kwargs.
+    inject_last_result (bool): Whether to inject the previous action's result
+                               into kwargs.
     inject_into (str): The name of the kwarg key to inject the result as
                                  (default: 'last_result').
     _requires_injection (bool): Whether the action requires input injection.
@@ -104,7 +108,9 @@ class BaseAction(ABC):
         self.shared_context = shared_context
 
     def get_option(self, option_name: str, default: Any = None) -> Any:
-        """Resolve an option from the OptionsManager if present, otherwise use the fallback."""
+        """
+        Resolve an option from the OptionsManager if present, otherwise use the fallback.
+        """
         if self.options_manager:
             return self.options_manager.get(option_name, default)
         return default
@@ -288,8 +294,10 @@ class Action(BaseAction):
 
     def __str__(self):
         return (
-            f"Action(name={self.name!r}, action={getattr(self._action, '__name__', repr(self._action))}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r}, retry={self.retry_policy.enabled})"
+            f"Action(name={self.name!r}, action="
+            f"{getattr(self._action, '__name__', repr(self._action))}, "
+            f"args={self.args!r}, kwargs={self.kwargs!r}, "
+            f"retry={self.retry_policy.enabled})"
         )
 
 
@@ -309,7 +317,7 @@ class LiteralInputAction(Action):
     def __init__(self, value: Any):
         self._value = value
 
-        async def literal(*args, **kwargs):
+        async def literal(*_, **__):
             return value
 
         super().__init__("Input", literal)
@@ -333,14 +341,16 @@ class LiteralInputAction(Action):
 
 class FallbackAction(Action):
     """
-    FallbackAction provides a default value if the previous action failed or returned None.
+    FallbackAction provides a default value if the previous action failed or
+    returned None.
 
     It injects the last result and checks:
     - If last_result is not None, it passes it through unchanged.
     - If last_result is None (e.g., due to failure), it replaces it with a fallback value.
 
     Used in ChainedAction pipelines to gracefully recover from errors or missing data.
-    When activated, it consumes the preceding error and allows the chain to continue normally.
+    When activated, it consumes the preceding error and allows the chain to continue
+    normally.
 
     Args:
         fallback (Any): The fallback value to use if last_result is None.
@@ -413,16 +423,19 @@ class ChainedAction(BaseAction, ActionListMixin):
     - Rolls back all previously executed actions if a failure occurs.
     - Handles literal values with LiteralInputAction.
 
-    Best used for defining robust, ordered workflows where each step can depend on previous results.
+    Best used for defining robust, ordered workflows where each step can depend on
+    previous results.
 
     Args:
         name (str): Name of the chain.
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
+        inject_last_result (bool, optional): Whether to inject last results into kwargs
+                                             by default.
         inject_into (str, optional): Key name for injection.
         auto_inject (bool, optional): Auto-enable injection for subsequent actions.
-        return_list (bool, optional): Whether to return a list of all results. False returns the last result.
+        return_list (bool, optional): Whether to return a list of all results. False
+                                      returns the last result.
     """
 
     def __init__(
@@ -468,7 +481,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         if not self.actions:
             raise EmptyChainError(f"[{self.name}] No actions to execute.")
 
-        shared_context = SharedContext(name=self.name)
+        shared_context = SharedContext(name=self.name, action=self)
         if self.shared_context:
             shared_context.add_result(self.shared_context.last_result())
         updated_kwargs = self._maybe_inject_last_result(kwargs)
@@ -503,7 +516,8 @@ class ChainedAction(BaseAction, ActionListMixin):
                         self.actions[index + 1], FallbackAction
                     ):
                         logger.warning(
-                            "[%s] ⚠️ Fallback triggered: %s, recovering with fallback '%s'.",
+                            "[%s] ⚠️ Fallback triggered: %s, recovering with fallback "
+                            "'%s'.",
                             self.name,
                             error,
                             self.actions[index + 1].name,
@@ -579,7 +593,8 @@ class ChainedAction(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ChainedAction(name={self.name!r}, actions={[a.name for a in self.actions]!r}, "
+            f"ChainedAction(name={self.name!r}, "
+            f"actions={[a.name for a in self.actions]!r}, "
             f"auto_inject={self.auto_inject}, return_list={self.return_list})"
         )
 
@@ -613,7 +628,8 @@ class ActionGroup(BaseAction, ActionListMixin):
         name (str): Name of the chain.
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
+        inject_last_result (bool, optional): Whether to inject last results into kwargs
+                                             by default.
         inject_into (str, optional): Key name for injection.
     """
 
@@ -643,7 +659,8 @@ class ActionGroup(BaseAction, ActionListMixin):
             return Action(name=action.__name__, action=action)
         else:
             raise TypeError(
-                f"ActionGroup only accepts BaseAction or callable, got {type(action).__name__}"
+                "ActionGroup only accepts BaseAction or callable, got "
+                f"{type(action).__name__}"
             )
 
     def add_action(self, action: BaseAction | Any) -> None:
@@ -653,7 +670,7 @@ class ActionGroup(BaseAction, ActionListMixin):
             action.register_teardown(self.hooks)
 
     async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
-        shared_context = SharedContext(name=self.name, is_parallel=True)
+        shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
         if self.shared_context:
             shared_context.set_shared_result(self.shared_context.last_result())
         updated_kwargs = self._maybe_inject_last_result(kwargs)
@@ -721,8 +738,8 @@ class ActionGroup(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ActionGroup(name={self.name!r}, actions={[a.name for a in self.actions]!r}, "
-            f"inject_last_result={self.inject_last_result})"
+            f"ActionGroup(name={self.name!r}, actions={[a.name for a in self.actions]!r},"
+            f" inject_last_result={self.inject_last_result})"
         )
 
 
@@ -831,6 +848,7 @@ class ProcessAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"ProcessAction(name={self.name!r}, action={getattr(self.action, '__name__', repr(self.action))}, "
+            f"ProcessAction(name={self.name!r}, "
+            f"action={getattr(self.action, '__name__', repr(self.action))}, "
             f"args={self.args!r}, kwargs={self.kwargs!r})"
         )

falyx/{action_factory.py → action/action_factory.py}

@@ -1,14 +1,16 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""action_factory.py"""
 from typing import Any
 
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
+from falyx.logger import logger
 from falyx.protocols import ActionFactoryProtocol
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 
 
 class ActionFactoryAction(BaseAction):
@@ -33,7 +35,7 @@ class ActionFactoryAction(BaseAction):
         inject_last_result: bool = False,
         inject_into: str = "last_result",
         preview_args: tuple[Any, ...] = (),
-        preview_kwargs: dict[str, Any] = {},
+        preview_kwargs: dict[str, Any] | None = None,
     ):
         super().__init__(
             name=name,
@@ -42,7 +44,7 @@ class ActionFactoryAction(BaseAction):
         )
         self.factory = factory
         self.preview_args = preview_args
-        self.preview_kwargs = preview_kwargs
+        self.preview_kwargs = preview_kwargs or {}
 
     async def _run(self, *args, **kwargs) -> Any:
         updated_kwargs = self._maybe_inject_last_result(kwargs)
@@ -58,10 +60,20 @@ class ActionFactoryAction(BaseAction):
             generated_action = self.factory(*args, **updated_kwargs)
             if not isinstance(generated_action, BaseAction):
                 raise TypeError(
-                    f"[{self.name}] Factory must return a BaseAction, got {type(generated_action).__name__}"
+                    f"[{self.name}] Factory must return a BaseAction, got "
+                    f"{type(generated_action).__name__}"
                 )
             if self.shared_context:
                 generated_action.set_shared_context(self.shared_context)
+                if hasattr(generated_action, "register_teardown") and callable(
+                    generated_action.register_teardown
+                ):
+                    generated_action.register_teardown(self.shared_context.action.hooks)
+                    logger.debug(
+                        "[%s] Registered teardown for %s",
+                        self.name,
+                        generated_action.name,
+                    )
             if self.options_manager:
                 generated_action.set_options_manager(self.options_manager)
             context.result = await generated_action(*args, **kwargs)

falyx/{http_action.py → action/http_action.py}

@@ -13,11 +13,11 @@ from typing import Any
 import aiohttp
 from rich.tree import Tree
 
-from falyx.action import Action
+from falyx.action.action import Action
 from falyx.context import ExecutionContext, SharedContext
 from falyx.hook_manager import HookManager, HookType
-from falyx.themes.colors import OneColors
-from falyx.utils import logger
+from falyx.logger import logger
+from falyx.themes import OneColors
 
 
 async def close_shared_http_session(context: ExecutionContext) -> None:
@@ -35,9 +35,9 @@ class HTTPAction(Action):
     """
     An Action for executing HTTP requests using aiohttp with shared session reuse.
 
-    This action integrates seamlessly into Falyx pipelines, with automatic session management,
-    result injection, and lifecycle hook support. It is ideal for CLI-driven API workflows
-    where you need to call remote services and process their responses.
+    This action integrates seamlessly into Falyx pipelines, with automatic session
+    management, result injection, and lifecycle hook support. It is ideal for CLI-driven
+    API workflows where you need to call remote services and process their responses.
 
     Features:
     - Uses aiohttp for asynchronous HTTP requests
@@ -97,7 +97,7 @@ class HTTPAction(Action):
             retry_policy=retry_policy,
         )
 
-    async def _request(self, *args, **kwargs) -> dict[str, Any]:
+    async def _request(self, *_, **__) -> dict[str, Any]:
         if self.shared_context:
             context: SharedContext = self.shared_context
             session = context.get("http_session")
@@ -153,6 +153,7 @@ class HTTPAction(Action):
     def __str__(self):
         return (
             f"HTTPAction(name={self.name!r}, method={self.method!r}, url={self.url!r}, "
-            f"headers={self.headers!r}, params={self.params!r}, json={self.json!r}, data={self.data!r}, "
-            f"retry={self.retry_policy.enabled}, inject_last_result={self.inject_last_result})"
+            f"headers={self.headers!r}, params={self.params!r}, json={self.json!r}, "
+            f"data={self.data!r}, retry={self.retry_policy.enabled}, "
+            f"inject_last_result={self.inject_last_result})"
         )

falyx/{io_action.py → action/io_action.py}

@@ -23,13 +23,13 @@ from typing import Any
 
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.exceptions import FalyxError
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
-from falyx.themes.colors import OneColors
-from falyx.utils import logger
+from falyx.logger import logger
+from falyx.themes import OneColors
 
 
 class BaseIOAction(BaseAction):
@@ -78,7 +78,7 @@ class BaseIOAction(BaseAction):
     def from_input(self, raw: str | bytes) -> Any:
         raise NotImplementedError
 
-    def to_output(self, data: Any) -> str | bytes:
+    def to_output(self, result: Any) -> str | bytes:
         raise NotImplementedError
 
     async def _resolve_input(self, kwargs: dict[str, Any]) -> str | bytes:
@@ -113,7 +113,7 @@ class BaseIOAction(BaseAction):
         try:
             if self.mode == "stream":
                 line_gen = await self._read_stdin_stream()
-                async for line in self._stream_lines(line_gen, args, kwargs):
+                async for _ in self._stream_lines(line_gen, args, kwargs):
                     pass
                 result = getattr(self, "_last_result", None)
             else:
@@ -185,8 +185,9 @@ class ShellAction(BaseIOAction):
     Designed for quick integration with shell tools like `grep`, `ping`, `jq`, etc.
 
     ⚠️ Security Warning:
-    By default, ShellAction uses `shell=True`, which can be dangerous with unsanitized input.
-    To mitigate this, set `safe_mode=True` to use `shell=False` with `shlex.split()`.
+    By default, ShellAction uses `shell=True`, which can be dangerous with
+    unsanitized input. To mitigate this, set `safe_mode=True` to use `shell=False`
+    with `shlex.split()`.
 
     Features:
     - Automatically handles input parsing (str/bytes)
@@ -198,9 +199,11 @@ class ShellAction(BaseIOAction):
 
     Args:
         name (str): Name of the action.
-        command_template (str): Shell command to execute. Must include `{}` to include input.
-                                If no placeholder is present, the input is not included.
-        safe_mode (bool): If True, runs with `shell=False` using shlex parsing (default: False).
+        command_template (str): Shell command to execute. Must include `{}` to include
+                                input. If no placeholder is present, the input is not
+                                included.
+        safe_mode (bool): If True, runs with `shell=False` using shlex parsing
+                          (default: False).
     """
 
     def __init__(
@@ -222,9 +225,11 @@ class ShellAction(BaseIOAction):
         command = self.command_template.format(parsed_input)
         if self.safe_mode:
             args = shlex.split(command)
-            result = subprocess.run(args, capture_output=True, text=True)
+            result = subprocess.run(args, capture_output=True, text=True, check=True)
         else:
-            result = subprocess.run(command, shell=True, text=True, capture_output=True)
+            result = subprocess.run(
+                command, shell=True, text=True, capture_output=True, check=True
+            )
         if result.returncode != 0:
             raise RuntimeError(result.stderr.strip())
         return result.stdout.strip()
@@ -246,6 +251,6 @@ class ShellAction(BaseIOAction):
 
     def __str__(self):
         return (
-            f"ShellAction(name={self.name!r}, command_template={self.command_template!r}, "
-            f"safe_mode={self.safe_mode})"
+            f"ShellAction(name={self.name!r}, command_template={self.command_template!r},"
+            f" safe_mode={self.safe_mode})"
         )

falyx/{menu_action.py → action/menu_action.py}

@@ -1,6 +1,5 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """menu_action.py"""
-from dataclasses import dataclass
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -8,91 +7,21 @@ from rich.console import Console
 from rich.table import Table
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
+from falyx.logger import logger
+from falyx.menu import MenuOptionMap
 from falyx.selection import prompt_for_selection, render_table_base
-from falyx.signal_action import SignalAction
 from falyx.signals import BackSignal, QuitSignal
-from falyx.themes.colors import OneColors
-from falyx.utils import CaseInsensitiveDict, chunks, logger
-
-
-@dataclass
-class MenuOption:
-    description: str
-    action: BaseAction
-    style: str = OneColors.WHITE
-
-    def __post_init__(self):
-        if not isinstance(self.description, str):
-            raise TypeError("MenuOption description must be a string.")
-        if not isinstance(self.action, BaseAction):
-            raise TypeError("MenuOption action must be a BaseAction instance.")
-
-    def render(self, key: str) -> str:
-        """Render the menu option for display."""
-        return f"[{OneColors.WHITE}][{key}][/] [{self.style}]{self.description}[/]"
-
-
-class MenuOptionMap(CaseInsensitiveDict):
-    """
-    Manages menu options including validation, reserved key protection,
-    and special signal entries like Quit and Back.
-    """
-
-    RESERVED_KEYS = {"Q", "B"}
-
-    def __init__(
-        self,
-        options: dict[str, MenuOption] | None = None,
-        allow_reserved: bool = False,
-    ):
-        super().__init__()
-        self.allow_reserved = allow_reserved
-        if options:
-            self.update(options)
-        self._inject_reserved_defaults()
-
-    def _inject_reserved_defaults(self):
-        self._add_reserved(
-            "Q",
-            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
-        )
-        self._add_reserved(
-            "B",
-            MenuOption("Back", SignalAction("Back", BackSignal()), OneColors.DARK_YELLOW),
-        )
-
-    def _add_reserved(self, key: str, option: MenuOption) -> None:
-        """Add a reserved key, bypassing validation."""
-        norm_key = key.upper()
-        super().__setitem__(norm_key, option)
-
-    def __setitem__(self, key: str, option: MenuOption) -> None:
-        if not isinstance(option, MenuOption):
-            raise TypeError(f"Value for key '{key}' must be a MenuOption.")
-        norm_key = key.upper()
-        if norm_key in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(
-                f"Key '{key}' is reserved and cannot be used in MenuOptionMap."
-            )
-        super().__setitem__(norm_key, option)
-
-    def __delitem__(self, key: str) -> None:
-        if key.upper() in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(f"Cannot delete reserved option '{key}'.")
-        super().__delitem__(key)
-
-    def items(self, include_reserved: bool = True):
-        for k, v in super().items():
-            if not include_reserved and k in self.RESERVED_KEYS:
-                continue
-            yield k, v
+from falyx.themes import OneColors
+from falyx.utils import chunks
 
 
 class MenuAction(BaseAction):
+    """MenuAction class for creating single use menu actions."""
+
     def __init__(
         self,
         name: str,
@@ -162,7 +91,8 @@ class MenuAction(BaseAction):
 
         if self.never_prompt and not effective_default:
             raise ValueError(
-                f"[{self.name}] 'never_prompt' is True but no valid default_selection was provided."
+                f"[{self.name}] 'never_prompt' is True but no valid default_selection"
+                " was provided."
             )
 
         context.start_timer()

falyx/{select_file_action.py → action/select_file_action.py}

@@ -1,10 +1,10 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""select_file_action.py"""
 from __future__ import annotations
 
 import csv
 import json
 import xml.etree.ElementTree as ET
-from enum import Enum
 from pathlib import Path
 from typing import Any
 
@@ -14,49 +14,18 @@ from prompt_toolkit import PromptSession
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
+from falyx.action.types import FileReturnType
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
+from falyx.logger import logger
 from falyx.selection import (
     SelectionOption,
     prompt_for_selection,
     render_selection_dict_table,
 )
-from falyx.themes.colors import OneColors
-from falyx.utils import logger
-
-
-class FileReturnType(Enum):
-    TEXT = "text"
-    PATH = "path"
-    JSON = "json"
-    TOML = "toml"
-    YAML = "yaml"
-    CSV = "csv"
-    TSV = "tsv"
-    XML = "xml"
-
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "yml": "yaml",
-            "txt": "text",
-            "file": "path",
-            "filepath": "path",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> FileReturnType:
-        if isinstance(value, str):
-            normalized = value.lower()
-            alias = cls._get_alias(normalized)
-            for member in cls:
-                if member.value == alias:
-                    return member
-        valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid FileReturnType: '{value}'. Must be one of: {valid}")
+from falyx.themes import OneColors
 
 
 class SelectFileAction(BaseAction):