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

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

@@ -6,10 +6,11 @@ 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.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_index,
@@ -17,11 +18,19 @@ from falyx.selection import (
     render_selection_dict_table,
     render_selection_indexed_table,
 )
-from falyx.themes.colors import OneColors
-from falyx.utils import CaseInsensitiveDict, logger
+from falyx.themes import OneColors
+from falyx.utils import CaseInsensitiveDict
 
 
 class SelectionAction(BaseAction):
+    """
+    A selection action that prompts the user to select an option from a list or
+    dictionary. The selected option is then returned as the result of the action.
+
+    If return_key is True, the key of the selected option is returned instead of
+    the value.
+    """
+
     def __init__(
         self,
         name: str,
@@ -45,7 +54,8 @@ class SelectionAction(BaseAction):
             inject_into=inject_into,
             never_prompt=never_prompt,
         )
-        self.selections: list[str] | CaseInsensitiveDict = selections
+        # Setter normalizes to correct type, mypy can't infer that
+        self.selections: list[str] | CaseInsensitiveDict = selections  # type: ignore[assignment]
         self.return_key = return_key
         self.title = title
         self.columns = columns
@@ -71,7 +81,8 @@ class SelectionAction(BaseAction):
             self._selections = cid
         else:
             raise TypeError(
-                f"'selections' must be a list[str] or dict[str, SelectionOption], got {type(value).__name__}"
+                "'selections' must be a list[str] or dict[str, SelectionOption], "
+                f"got {type(value).__name__}"
             )
 
     async def _run(self, *args, **kwargs) -> Any:
@@ -108,7 +119,8 @@ class SelectionAction(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()
@@ -152,7 +164,8 @@ class SelectionAction(BaseAction):
                 result = key if self.return_key else self.selections[key].value
             else:
                 raise TypeError(
-                    f"'selections' must be a list[str] or dict[str, tuple[str, Any]], got {type(self.selections).__name__}"
+                    "'selections' must be a list[str] or dict[str, tuple[str, Any]], "
+                    f"got {type(self.selections).__name__}"
                 )
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -205,5 +218,6 @@ class SelectionAction(BaseAction):
         return (
             f"SelectionAction(name={self.name!r}, type={selection_type}, "
             f"default_selection={self.default_selection!r}, "
-            f"return_key={self.return_key}, prompt={'off' if self.never_prompt else 'on'})"
+            f"return_key={self.return_key}, "
+            f"prompt={'off' if self.never_prompt else 'on'})"
         )

falyx/action/signal_action.py

@@ -0,0 +1,43 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""signal_action.py"""
+from rich.tree import Tree
+
+from falyx.action.action import Action
+from falyx.signals import FlowSignal
+from falyx.themes import OneColors
+
+
+class SignalAction(Action):
+    """
+    An action that raises a control flow signal when executed.
+
+    Useful for exiting a menu, going back, or halting execution gracefully.
+    """
+
+    def __init__(self, name: str, signal: Exception):
+        self.signal = signal
+        super().__init__(name, action=self.raise_signal)
+
+    async def raise_signal(self, *args, **kwargs):
+        raise self.signal
+
+    @property
+    def signal(self):
+        return self._signal
+
+    @signal.setter
+    def signal(self, value: FlowSignal):
+        if not isinstance(value, FlowSignal):
+            raise TypeError(
+                f"Signal must be an FlowSignal instance, got {type(value).__name__}"
+            )
+        self._signal = value
+
+    def __str__(self):
+        return f"SignalAction(name={self.name}, signal={self._signal.__class__.__name__})"
+
+    async def preview(self, parent: Tree | None = None):
+        label = f"[{OneColors.LIGHT_RED}]⚡ SignalAction[/] '{self.signal.__class__.__name__}'"
+        tree = parent.add(label) if parent else Tree(label)
+        if not parent:
+            self.console.print(tree)

falyx/action/types.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class FileReturnType(Enum):
+    """Enum for file return types."""
+
+    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}")

falyx/bottom_bar.py

@@ -8,7 +8,7 @@ from prompt_toolkit.key_binding import KeyBindings
 from rich.console import Console
 
 from falyx.options_manager import OptionsManager
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import CaseInsensitiveDict, chunks
 
 
@@ -146,7 +146,7 @@ class BottomBar:
         for k in (key.upper(), key.lower()):
 
             @self.key_bindings.add(k)
-            def _(event):
+            def _(_):
                 toggle_state()
 
     def add_toggle_from_option(
@@ -204,6 +204,6 @@ class BottomBar:
         """Render the bottom bar."""
         lines = []
         for chunk in chunks(self._named_items.values(), self.columns):
-            lines.extend([fn for fn in chunk])
+            lines.extend(list(chunk))
             lines.append(lambda: HTML("\n"))
         return merge_formatted_text([fn() for fn in lines[:-1]])

falyx/command.py

@@ -26,19 +26,20 @@ from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action import Action, ActionGroup, BaseAction, ChainedAction
+from falyx.action.action import Action, ActionGroup, BaseAction, ChainedAction
+from falyx.action.io_action import BaseIOAction
 from falyx.context import ExecutionContext
 from falyx.debug import register_debug_hooks
 from falyx.exceptions import FalyxError
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
-from falyx.io_action import BaseIOAction
+from falyx.logger import logger
 from falyx.options_manager import OptionsManager
-from falyx.prompt_utils import should_prompt_user
+from falyx.prompt_utils import confirm_async, should_prompt_user
 from falyx.retry import RetryPolicy
 from falyx.retry_utils import enable_retries_recursively
-from falyx.themes.colors import OneColors
-from falyx.utils import _noop, confirm_async, ensure_async, logger
+from falyx.themes import OneColors
+from falyx.utils import _noop, ensure_async
 
 console = Console(color_system="auto")
 
@@ -134,7 +135,7 @@ class Command(BaseModel):
             return ensure_async(action)
         raise TypeError("Action must be a callable or an instance of BaseAction")
 
-    def model_post_init(self, __context: Any) -> None:
+    def model_post_init(self, _: Any) -> None:
         """Post-initialization to set up the action and hooks."""
         if self.retry and isinstance(self.action, Action):
             self.action.enable_retry()
@@ -142,14 +143,16 @@ class Command(BaseModel):
             self.action.set_retry_policy(self.retry_policy)
         elif self.retry:
             logger.warning(
-                f"[Command:{self.key}] Retry requested, but action is not an Action instance."
+                "[Command:%s] Retry requested, but action is not an Action instance.",
+                self.key,
             )
         if self.retry_all and isinstance(self.action, BaseAction):
             self.retry_policy.enabled = True
             enable_retries_recursively(self.action, self.retry_policy)
         elif self.retry_all:
             logger.warning(
-                f"[Command:{self.key}] Retry all requested, but action is not a BaseAction instance."
+                "[Command:%s] Retry all requested, but action is not a BaseAction.",
+                self.key,
             )
 
         if self.logging_hooks and isinstance(self.action, BaseAction):
@@ -201,7 +204,7 @@ class Command(BaseModel):
             if self.preview_before_confirm:
                 await self.preview()
             if not await confirm_async(self.confirmation_prompt):
-                logger.info(f"[Command:{self.key}] ❌ Cancelled by user.")
+                logger.info("[Command:%s] ❌ Cancelled by user.", self.key)
                 raise FalyxError(f"[Command:{self.key}] Cancelled by confirmation.")
 
         context.start_timer()
@@ -288,7 +291,7 @@ class Command(BaseModel):
             if self.help_text:
                 console.print(f"[dim]💡 {self.help_text}[/dim]")
             console.print(
-                f"[{OneColors.DARK_RED}]⚠️ Action is not callable or lacks a preview method.[/]"
+                f"[{OneColors.DARK_RED}]⚠️ No preview available for this action.[/]"
             )
 
     def __str__(self) -> str:

falyx/config.py

@@ -13,12 +13,12 @@ import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
 from rich.console import Console
 
-from falyx.action import Action, BaseAction
+from falyx.action.action import Action, BaseAction
 from falyx.command import Command
 from falyx.falyx import Falyx
+from falyx.logger import logger
 from falyx.retry import RetryPolicy
-from falyx.themes.colors import OneColors
-from falyx.utils import logger
+from falyx.themes import OneColors
 
 console = Console(color_system="auto")
 
@@ -47,7 +47,8 @@ def import_action(dotted_path: str) -> Any:
         logger.error("Failed to import module '%s': %s", module_path, error)
         console.print(
             f"[{OneColors.DARK_RED}]❌ Could not import '{dotted_path}': {error}[/]\n"
-            f"[{OneColors.COMMENT_GREY}]Ensure the module is installed and discoverable via PYTHONPATH."
+            f"[{OneColors.COMMENT_GREY}]Ensure the module is installed and discoverable "
+            "via PYTHONPATH."
         )
         sys.exit(1)
     try:
@@ -57,13 +58,16 @@ def import_action(dotted_path: str) -> Any:
             "Module '%s' does not have attribute '%s': %s", module_path, attr, error
         )
         console.print(
-            f"[{OneColors.DARK_RED}]❌ Module '{module_path}' has no attribute '{attr}': {error}[/]"
+            f"[{OneColors.DARK_RED}]❌ Module '{module_path}' has no attribute "
+            f"'{attr}': {error}[/]"
         )
         sys.exit(1)
     return action
 
 
 class RawCommand(BaseModel):
+    """Raw command model for Falyx CLI configuration."""
+
     key: str
     description: str
     action: str
@@ -72,7 +76,7 @@ class RawCommand(BaseModel):
     kwargs: dict[str, Any] = {}
     aliases: list[str] = []
     tags: list[str] = []
-    style: str = "white"
+    style: str = OneColors.WHITE
 
     confirm: bool = False
     confirm_message: str = "Are you sure?"
@@ -81,7 +85,7 @@ class RawCommand(BaseModel):
     spinner: bool = False
     spinner_message: str = "Processing..."
     spinner_type: str = "dots"
-    spinner_style: str = "cyan"
+    spinner_style: str = OneColors.CYAN
     spinner_kwargs: dict[str, Any] = {}
 
     before_hooks: list[Callable] = []
@@ -126,6 +130,8 @@ def convert_commands(raw_commands: list[dict[str, Any]]) -> list[Command]:
 
 
 class FalyxConfig(BaseModel):
+    """Falyx CLI configuration model."""
+
     title: str = "Falyx CLI"
     prompt: str | list[tuple[str, str]] | list[list[str]] = [
         (OneColors.BLUE_b, "FALYX > ")
@@ -148,7 +154,7 @@ class FalyxConfig(BaseModel):
     def to_falyx(self) -> Falyx:
         flx = Falyx(
             title=self.title,
-            prompt=self.prompt,
+            prompt=self.prompt,  # type: ignore[arg-type]
             columns=self.columns,
             welcome_message=self.welcome_message,
             exit_message=self.exit_message,
@@ -159,7 +165,9 @@ class FalyxConfig(BaseModel):
 
 def loader(file_path: Path | str) -> Falyx:
     """
-    Load command definitions from a YAML or TOML file.
+    Load Falyx CLI configuration from a YAML or TOML file.
+
+    The file should contain a dictionary with a list of commands.
 
     Each command should be defined as a dictionary with at least:
     - key: a unique single-character key

falyx/context.py

@@ -29,10 +29,10 @@ class ExecutionContext(BaseModel):
     """
     Represents the runtime metadata and state for a single action execution.
 
-    The `ExecutionContext` tracks arguments, results, exceptions, timing, and additional
-    metadata for each invocation of a Falyx `BaseAction`. It provides integration with the
-    Falyx hook system and execution registry, enabling lifecycle management, diagnostics,
-    and structured logging.
+    The `ExecutionContext` tracks arguments, results, exceptions, timing, and
+    additional metadata for each invocation of a Falyx `BaseAction`. It provides
+    integration with the Falyx hook system and execution registry, enabling lifecycle
+    management, diagnostics, and structured logging.
 
     Attributes:
         name (str): The name of the action being executed.
@@ -47,7 +47,8 @@ class ExecutionContext(BaseModel):
         end_wall (datetime | None): Wall-clock timestamp when execution ended.
         extra (dict): Metadata for custom introspection or special use by Actions.
         console (Console): Rich console instance for logging or UI output.
-        shared_context (SharedContext | None): Optional shared context when running in a chain or group.
+        shared_context (SharedContext | None): Optional shared context when running in
+                                               a chain or group.
 
     Properties:
         duration (float | None): The execution duration in seconds.
@@ -95,7 +96,11 @@ class ExecutionContext(BaseModel):
         self.end_wall = datetime.now()
 
     def get_shared_context(self) -> SharedContext:
-        return self.shared_context or SharedContext(name="default")
+        if not self.shared_context:
+            raise ValueError(
+                "SharedContext is not set. This context is not part of a chain or group."
+            )
+        return self.shared_context
 
     @property
     def duration(self) -> float | None:
@@ -190,8 +195,10 @@ class SharedContext(BaseModel):
         errors (list[tuple[int, Exception]]): Indexed list of errors from failed actions.
         current_index (int): Index of the currently executing action (used in chains).
         is_parallel (bool): Whether the context is used in parallel mode (ActionGroup).
-        shared_result (Any | None): Optional shared value available to all actions in parallel mode.
-        share (dict[str, Any]): Custom shared key-value store for user-defined communication
+        shared_result (Any | None): Optional shared value available to all actions in
+                                    parallel mode.
+        share (dict[str, Any]): Custom shared key-value store for user-defined
+                                communication
             between actions (e.g., flags, intermediate data, settings).
 
     Note:
@@ -208,6 +215,7 @@ class SharedContext(BaseModel):
     """
 
     name: str
+    action: Any
     results: list[Any] = Field(default_factory=list)
     errors: list[tuple[int, Exception]] = Field(default_factory=list)
     current_index: int = -1

falyx/debug.py

@@ -1,7 +1,8 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""debug.py"""
 from falyx.context import ExecutionContext
 from falyx.hook_manager import HookManager, HookType
-from falyx.utils import logger
+from falyx.logger import logger
 
 
 def log_before(context: ExecutionContext):

falyx/exceptions.py

@@ -1,4 +1,7 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""exceptions.py"""
+
+
 class FalyxError(Exception):
     """Custom exception for the Menu class."""
 

falyx/execution_registry.py

@@ -1,5 +1,32 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""execution_registry.py"""
+"""
+execution_registry.py
+
+This module provides the `ExecutionRegistry`, a global class for tracking and
+introspecting the execution history of Falyx actions.
+
+The registry captures `ExecutionContext` instances from all executed actions, making it
+easy to debug, audit, and visualize workflow behavior over time. It supports retrieval,
+filtering, clearing, and formatted summary display.
+
+Core Features:
+- Stores all action execution contexts globally (with access by name).
+- Provides live execution summaries in a rich table format.
+- Enables creation of a built-in Falyx Action to print history on demand.
+- Integrates with Falyx's introspectable and hook-driven execution model.
+
+Intended for:
+- Debugging and diagnostics
+- Post-run inspection of CLI workflows
+- Interactive tools built with Falyx
+
+Example:
+    from falyx.execution_registry import ExecutionRegistry as er
+    er.record(context)
+    er.summary()
+"""
+from __future__ import annotations
+
 from collections import defaultdict
 from datetime import datetime
 from typing import Dict, List
@@ -9,11 +36,40 @@ from rich.console import Console
 from rich.table import Table
 
 from falyx.context import ExecutionContext
-from falyx.themes.colors import OneColors
-from falyx.utils import logger
+from falyx.logger import logger
+from falyx.themes import OneColors
 
 
 class ExecutionRegistry:
+    """
+    Global registry for recording and inspecting Falyx action executions.
+
+    This class captures every `ExecutionContext` generated by a Falyx `Action`,
+    `ChainedAction`, or `ActionGroup`, maintaining both full history and
+    name-indexed access for filtered analysis.
+
+    Methods:
+        - record(context): Stores an ExecutionContext, logging a summary line.
+        - get_all(): Returns the list of all recorded executions.
+        - get_by_name(name): Returns all executions with the given action name.
+        - get_latest(): Returns the most recent execution.
+        - clear(): Wipes the registry for a fresh run.
+        - summary(): Renders a formatted Rich table of all execution results.
+
+    Use Cases:
+        - Debugging chained or factory-generated workflows
+        - Viewing results and exceptions from multiple runs
+        - Embedding a diagnostic command into your CLI for user support
+
+    Note:
+        This registry is in-memory and not persistent. It's reset each time the process
+        restarts or `clear()` is called.
+
+    Example:
+        ExecutionRegistry.record(context)
+        ExecutionRegistry.summary()
+    """
+
     _store_by_name: Dict[str, List[ExecutionContext]] = defaultdict(list)
     _store_all: List[ExecutionContext] = []
     _console = Console(color_system="auto")
@@ -78,13 +134,3 @@ class ExecutionRegistry:
             table.add_row(ctx.name, start, end, duration, status, result)
 
         cls._console.print(table)
-
-    @classmethod
-    def get_history_action(cls) -> "Action":
-        """Return an Action that prints the execution summary."""
-        from falyx.action import Action
-
-        async def show_history():
-            cls.summary()
-
-        return Action(name="View Execution History", action=show_history)