falyx 0.1.56__py3-none-any.whl → 0.1.57__py3-none-any.whl

falyx/__init__.py

@@ -12,6 +12,7 @@ from .falyx import Falyx
 
 logger = logging.getLogger("falyx")
 
+
 __all__ = [
     "Falyx",
     "ExecutionRegistry",

falyx/action/__init__.py

@@ -10,6 +10,7 @@ from .action_factory import ActionFactory
 from .action_group import ActionGroup
 from .base_action import BaseAction
 from .chained_action import ChainedAction
+from .confirm_action import ConfirmAction
 from .fallback_action import FallbackAction
 from .http_action import HTTPAction
 from .io_action import BaseIOAction
@@ -19,6 +20,7 @@ from .menu_action import MenuAction
 from .process_action import ProcessAction
 from .process_pool_action import ProcessPoolAction
 from .prompt_menu_action import PromptMenuAction
+from .save_file_action import SaveFileAction
 from .select_file_action import SelectFileAction
 from .selection_action import SelectionAction
 from .shell_action import ShellAction
@@ -45,4 +47,6 @@ __all__ = [
     "PromptMenuAction",
     "ProcessPoolAction",
     "LoadFileAction",
+    "SaveFileAction",
+    "ConfirmAction",
 ]

falyx/action/action_group.py

@@ -14,6 +14,7 @@ from falyx.exceptions import EmptyGroupError
 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.parser.utils import same_argument_definitions
 from falyx.themes.colors import OneColors
 
@@ -96,6 +97,11 @@ class ActionGroup(BaseAction, ActionListMixin):
         for action in actions:
             self.add_action(action)
 
+    def set_options_manager(self, options_manager: OptionsManager) -> None:
+        super().set_options_manager(options_manager)
+        for action in self.actions:
+            action.set_options_manager(options_manager)
+
     def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         arg_defs = same_argument_definitions(self.actions)
         if arg_defs:

falyx/action/base_action.py

@@ -36,6 +36,7 @@ from typing import Any, Callable
 from rich.console import Console
 from rich.tree import Tree
 
+from falyx.console import console
 from falyx.context import SharedContext
 from falyx.debug import register_debug_hooks
 from falyx.hook_manager import Hook, HookManager, HookType
@@ -73,7 +74,7 @@ class BaseAction(ABC):
         self.inject_into: str = inject_into
         self._never_prompt: bool = never_prompt
         self._skip_in_chain: bool = False
-        self.console = Console(color_system="truecolor")
+        self.console: Console = console
         self.options_manager: OptionsManager | None = None
 
         if logging_hooks:

falyx/action/chained_action.py

@@ -16,6 +16,7 @@ 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.themes import OneColors
 
 
@@ -92,6 +93,11 @@ class ChainedAction(BaseAction, ActionListMixin):
         for action in actions:
             self.add_action(action)
 
+    def set_options_manager(self, options_manager: OptionsManager) -> None:
+        super().set_options_manager(options_manager)
+        for action in self.actions:
+            action.set_options_manager(options_manager)
+
     def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         if self.actions:
             return self.actions[0].get_infer_target()
@@ -197,7 +203,7 @@ class ChainedAction(BaseAction, ActionListMixin):
 
     def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
         """Register a hook for all actions and sub-actions."""
-        self.hooks.register(hook_type, hook)
+        super().register_hooks_recursively(hook_type, hook)
         for action in self.actions:
             action.register_hooks_recursively(hook_type, hook)
 

falyx/action/confirm_action.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from prompt_toolkit import PromptSession
+from rich.tree import Tree
+
+from falyx.action.base_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.prompt_utils import confirm_async, should_prompt_user
+from falyx.signals import CancelSignal
+from falyx.themes import OneColors
+from falyx.validators import word_validator, words_validator
+
+
+class ConfirmType(Enum):
+    """Enum for different confirmation types."""
+
+    YES_NO = "yes_no"
+    YES_CANCEL = "yes_cancel"
+    YES_NO_CANCEL = "yes_no_cancel"
+    TYPE_WORD = "type_word"
+    OK_CANCEL = "ok_cancel"
+
+    @classmethod
+    def choices(cls) -> list[ConfirmType]:
+        """Return a list of all hook type choices."""
+        return list(cls)
+
+    def __str__(self) -> str:
+        """Return the string representation of the confirm type."""
+        return self.value
+
+
+class ConfirmAction(BaseAction):
+    """
+    Action to confirm an operation with the user.
+
+    There are several ways to confirm an action, such as using a simple
+    yes/no prompt. You can also use a confirmation type that requires the user
+    to type a specific word or phrase to confirm the action, or use an OK/Cancel
+    dialog.
+
+    This action can be used to ensure that the user explicitly agrees to proceed
+    with an operation.
+
+    Attributes:
+        name (str): Name of the action.
+        message (str): The confirmation message to display.
+        confirm_type (ConfirmType | str): The type of confirmation to use.
+            Options include YES_NO, YES_CANCEL, YES_NO_CANCEL, TYPE_WORD, and OK_CANCEL.
+        prompt_session (PromptSession | None): The session to use for input.
+        confirm (bool): Whether to prompt the user for confirmation.
+        word (str): The word to type for TYPE_WORD confirmation.
+        return_last_result (bool): Whether to return the last result of the action.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        message: str = "Continue",
+        confirm_type: ConfirmType | str = ConfirmType.YES_NO,
+        prompt_session: PromptSession | None = None,
+        confirm: bool = True,
+        word: str = "CONFIRM",
+        return_last_result: bool = False,
+        inject_last_result: bool = True,
+        inject_into: str = "last_result",
+    ):
+        """
+        Initialize the ConfirmAction.
+
+        Args:
+            message (str): The confirmation message to display.
+            confirm_type (ConfirmType): The type of confirmation to use.
+                Options include YES_NO, YES_CANCEL, YES_NO_CANCEL, TYPE_WORD, and OK_CANCEL.
+            prompt_session (PromptSession | None): The session to use for input.
+            confirm (bool): Whether to prompt the user for confirmation.
+            word (str): The word to type for TYPE_WORD confirmation.
+            return_last_result (bool): Whether to return the last result of the action.
+        """
+        super().__init__(
+            name=name,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
+        self.message = message
+        self.confirm_type = self._coerce_confirm_type(confirm_type)
+        self.prompt_session = prompt_session or PromptSession()
+        self.confirm = confirm
+        self.word = word
+        self.return_last_result = return_last_result
+
+    def _coerce_confirm_type(self, confirm_type: ConfirmType | str) -> ConfirmType:
+        """Coerce the confirm_type to a ConfirmType enum."""
+        if isinstance(confirm_type, ConfirmType):
+            return confirm_type
+        elif isinstance(confirm_type, str):
+            return ConfirmType(confirm_type)
+        return ConfirmType(confirm_type)
+
+    async def _confirm(self) -> bool:
+        """Confirm the action with the user."""
+        match self.confirm_type:
+            case ConfirmType.YES_NO:
+                return await confirm_async(
+                    self.message,
+                    prefix="❓ ",
+                    suffix=" [Y/n] > ",
+                    session=self.prompt_session,
+                )
+            case ConfirmType.YES_NO_CANCEL:
+                answer = await self.prompt_session.prompt_async(
+                    f"❓ {self.message} ([Y]es, [N]o, or [C]ancel to abort): ",
+                    validator=words_validator(["Y", "N", "C"]),
+                )
+                if answer.upper() == "C":
+                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
+                return answer.upper() == "Y"
+            case ConfirmType.TYPE_WORD:
+                answer = await self.prompt_session.prompt_async(
+                    f"❓ {self.message} (type '{self.word}' to confirm or N/n): ",
+                    validator=word_validator(self.word),
+                )
+                return answer.upper().strip() != "N"
+            case ConfirmType.YES_CANCEL:
+                answer = await confirm_async(
+                    self.message,
+                    prefix="❓ ",
+                    suffix=" [Y/n] > ",
+                    session=self.prompt_session,
+                )
+                if not answer:
+                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
+                return answer
+            case ConfirmType.OK_CANCEL:
+                answer = await self.prompt_session.prompt_async(
+                    f"❓ {self.message} ([O]k to continue, [C]ancel to abort): ",
+                    validator=words_validator(["O", "C"]),
+                )
+                if answer.upper() == "C":
+                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
+                return answer.upper() == "O"
+            case _:
+                raise ValueError(f"Unknown confirm_type: {self.confirm_type}")
+
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
+
+    async def _run(self, *args, **kwargs) -> Any:
+        combined_kwargs = self._maybe_inject_last_result(kwargs)
+        context = ExecutionContext(
+            name=self.name, args=args, kwargs=combined_kwargs, action=self
+        )
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            if (
+                not self.confirm
+                or self.options_manager
+                and not should_prompt_user(
+                    confirm=self.confirm, options=self.options_manager
+                )
+            ):
+                logger.debug(
+                    "Skipping confirmation for action '%s' as 'confirm' is False or options manager indicates no prompt.",
+                    self.name,
+                )
+                if self.return_last_result:
+                    result = combined_kwargs[self.inject_into]
+                else:
+                    result = True
+            else:
+                answer = await self._confirm()
+                if self.return_last_result and answer:
+                    result = combined_kwargs[self.inject_into]
+                else:
+                    result = answer
+            logger.debug("Action '%s' confirmed with result: %s", self.name, result)
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return result
+        except Exception as error:
+            context.exception = error
+            await self.hooks.trigger(HookType.ON_ERROR, context)
+            raise
+        finally:
+            context.stop_timer()
+            await self.hooks.trigger(HookType.AFTER, context)
+            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
+            er.record(context)
+
+    async def preview(self, parent: Tree | None = None) -> None:
+        tree = (
+            Tree(
+                f"[{OneColors.CYAN_b}]ConfirmAction[/]: {self.name}",
+                guide_style=OneColors.BLUE_b,
+            )
+            if not parent
+            else parent.add(f"[{OneColors.CYAN_b}]ConfirmAction[/]: {self.name}")
+        )
+        tree.add(f"[bold]Message:[/] {self.message}")
+        tree.add(f"[bold]Type:[/] {self.confirm_type.value}")
+        tree.add(f"[bold]Prompt Required:[/] {'Yes' if self.confirm else 'No'}")
+        if self.confirm_type == ConfirmType.TYPE_WORD:
+            tree.add(f"[bold]Confirmation Word:[/] {self.word}")
+        if parent is None:
+            self.console.print(tree)
+
+    def __str__(self) -> str:
+        return (
+            f"ConfirmAction(name={self.name}, message={self.message}, "
+            f"confirm_type={self.confirm_type})"
+        )

falyx/action/load_file_action.py

@@ -80,9 +80,14 @@ class LoadFileAction(BaseAction):
     def get_infer_target(self) -> tuple[None, None]:
         return None, None
 
-    def load_file(self) -> Any:
+    async def load_file(self) -> Any:
+        """Load and parse the file based on its type."""
         if self.file_path is None:
             raise ValueError("file_path must be set before loading a file")
+        elif not self.file_path.exists():
+            raise FileNotFoundError(f"File not found: {self.file_path}")
+        elif not self.file_path.is_file():
+            raise ValueError(f"Path is not a regular file: {self.file_path}")
         value: Any = None
         try:
             if self.file_type == FileType.TEXT:
@@ -125,14 +130,7 @@ class LoadFileAction(BaseAction):
             elif self.inject_last_result and self.last_result:
                 self.file_path = self.last_result
 
-            if self.file_path is None:
-                raise ValueError("file_path must be set before loading a file")
-            elif not self.file_path.exists():
-                raise FileNotFoundError(f"File not found: {self.file_path}")
-            elif not self.file_path.is_file():
-                raise ValueError(f"Path is not a regular file: {self.file_path}")
-
-            result = self.load_file()
+            result = await self.load_file()
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
             return result
         except Exception as error:

falyx/action/menu_action.py

@@ -3,7 +3,6 @@
 from typing import Any
 
 from prompt_toolkit import PromptSession
-from rich.console import Console
 from rich.table import Table
 from rich.tree import Tree
 
@@ -33,7 +32,6 @@ class MenuAction(BaseAction):
         default_selection: str = "",
         inject_last_result: bool = False,
         inject_into: str = "last_result",
-        console: Console | None = None,
         prompt_session: PromptSession | None = None,
         never_prompt: bool = False,
         include_reserved: bool = True,
@@ -51,10 +49,6 @@ class MenuAction(BaseAction):
         self.columns = columns
         self.prompt_message = prompt_message
         self.default_selection = default_selection
-        if isinstance(console, Console):
-            self.console = console
-        elif console:
-            raise ValueError("`console` must be an instance of `rich.console.Console`")
         self.prompt_session = prompt_session or PromptSession()
         self.include_reserved = include_reserved
         self.show_table = show_table
@@ -115,7 +109,6 @@ class MenuAction(BaseAction):
                     self.menu_options.keys(),
                     table,
                     default_selection=self.default_selection,
-                    console=self.console,
                     prompt_session=self.prompt_session,
                     prompt_message=self.prompt_message,
                     show_table=self.show_table,

falyx/action/prompt_menu_action.py

@@ -4,7 +4,6 @@ from typing import Any
 
 from prompt_toolkit import PromptSession
 from prompt_toolkit.formatted_text import FormattedText, merge_formatted_text
-from rich.console import Console
 from rich.tree import Tree
 
 from falyx.action.base_action import BaseAction
@@ -29,7 +28,6 @@ class PromptMenuAction(BaseAction):
         default_selection: str = "",
         inject_last_result: bool = False,
         inject_into: str = "last_result",
-        console: Console | None = None,
         prompt_session: PromptSession | None = None,
         never_prompt: bool = False,
         include_reserved: bool = True,
@@ -43,10 +41,6 @@ class PromptMenuAction(BaseAction):
         self.menu_options = menu_options
         self.prompt_message = prompt_message
         self.default_selection = default_selection
-        if isinstance(console, Console):
-            self.console = console
-        elif console:
-            raise ValueError("`console` must be an instance of `rich.console.Console`")
         self.prompt_session = prompt_session or PromptSession()
         self.include_reserved = include_reserved
 

falyx/action/save_file_action.py

@@ -1,22 +1,44 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """save_file_action.py"""
+import csv
+import json
+import xml.etree.ElementTree as ET
+from datetime import datetime
 from pathlib import Path
+from typing import Any, Literal
 
+import toml
+import yaml
 from rich.tree import Tree
 
 from falyx.action.action_types import FileType
 from falyx.action.base_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.themes import OneColors
 
 
 class SaveFileAction(BaseAction):
-    """ """
+    """
+    SaveFileAction saves data to a file in the specified format (e.g., TEXT, JSON, YAML).
+    Supports overwrite control and integrates with chaining workflows via inject_last_result.
+
+    Supported types: TEXT, JSON, YAML, TOML, CSV, TSV, XML
+
+    If the file exists and overwrite is False, the action will raise a FileExistsError.
+    """
 
     def __init__(
         self,
         name: str,
         file_path: str,
-        input_type: str | FileType = "text",
-        output_type: str | FileType = "text",
+        file_type: FileType | str = FileType.TEXT,
+        mode: Literal["w", "a"] = "w",
+        inject_last_result: bool = True,
+        inject_into: str = "data",
+        overwrite: bool = True,
     ):
         """
         SaveFileAction allows saving data to a file.
@@ -24,21 +46,187 @@ class SaveFileAction(BaseAction):
         Args:
             name (str): Name of the action.
             file_path (str | Path): Path to the file where data will be saved.
-            input_type (str | FileType): Type of data being saved (default is "text").
-            output_type (str | FileType): Type of data to save to the file (default is "text").
+            file_type (FileType | str): Format to write to (e.g. TEXT, JSON, YAML).
+            inject_last_result (bool): Whether to inject result from previous action.
+            inject_into (str): Kwarg name to inject the last result as.
+            overwrite (bool): Whether to overwrite the file if it exists.
         """
-        super().__init__(name=name)
-        self.file_path = file_path
+        super().__init__(
+            name=name, inject_last_result=inject_last_result, inject_into=inject_into
+        )
+        self._file_path = self._coerce_file_path(file_path)
+        self._file_type = self._coerce_file_type(file_type)
+        self.overwrite = overwrite
+        self.mode = mode
+
+    @property
+    def file_path(self) -> Path | None:
+        """Get the file path as a Path object."""
+        return self._file_path
+
+    @file_path.setter
+    def file_path(self, value: str | Path):
+        """Set the file path, converting to Path if necessary."""
+        self._file_path = self._coerce_file_path(value)
+
+    def _coerce_file_path(self, file_path: str | Path | None) -> Path | None:
+        """Coerce the file path to a Path object."""
+        if isinstance(file_path, Path):
+            return file_path
+        elif isinstance(file_path, str):
+            return Path(file_path)
+        elif file_path is None:
+            return None
+        else:
+            raise TypeError("file_path must be a string or Path object")
+
+    @property
+    def file_type(self) -> FileType:
+        """Get the file type."""
+        return self._file_type
+
+    @file_type.setter
+    def file_type(self, value: FileType | str):
+        """Set the file type, converting to FileType if necessary."""
+        self._file_type = self._coerce_file_type(value)
+
+    def _coerce_file_type(self, file_type: FileType | str) -> FileType:
+        """Coerce the file type to a FileType enum."""
+        if isinstance(file_type, FileType):
+            return file_type
+        elif isinstance(file_type, str):
+            return FileType(file_type)
+        else:
+            raise TypeError("file_type must be a FileType enum or string")
 
     def get_infer_target(self) -> tuple[None, None]:
         return None, None
 
+    def _dict_to_xml(self, data: dict, root: ET.Element) -> None:
+        """Convert a dictionary to XML format."""
+        for key, value in data.items():
+            if isinstance(value, dict):
+                sub_element = ET.SubElement(root, key)
+                self._dict_to_xml(value, sub_element)
+            elif isinstance(value, list):
+                for item in value:
+                    item_element = ET.SubElement(root, key)
+                    if isinstance(item, dict):
+                        self._dict_to_xml(item, item_element)
+                    else:
+                        item_element.text = str(item)
+            else:
+                element = ET.SubElement(root, key)
+                element.text = str(value)
+
+    async def save_file(self, data: Any) -> None:
+        """Save data to the specified file in the desired format."""
+        if self.file_path is None:
+            raise ValueError("file_path must be set before saving a file")
+        elif self.file_path.exists() and not self.overwrite:
+            raise FileExistsError(f"File already exists: {self.file_path}")
+
+        try:
+            if self.file_type == FileType.TEXT:
+                self.file_path.write_text(data, encoding="UTF-8")
+            elif self.file_type == FileType.JSON:
+                self.file_path.write_text(json.dumps(data, indent=4), encoding="UTF-8")
+            elif self.file_type == FileType.TOML:
+                self.file_path.write_text(toml.dumps(data), encoding="UTF-8")
+            elif self.file_type == FileType.YAML:
+                self.file_path.write_text(yaml.dump(data), encoding="UTF-8")
+            elif self.file_type == FileType.CSV:
+                if not isinstance(data, list) or not all(
+                    isinstance(row, list) for row in data
+                ):
+                    raise ValueError(
+                        f"{self.file_type.name} file type requires a list of lists"
+                    )
+                with open(
+                    self.file_path, mode=self.mode, newline="", encoding="UTF-8"
+                ) as csvfile:
+                    writer = csv.writer(csvfile)
+                    writer.writerows(data)
+            elif self.file_type == FileType.TSV:
+                if not isinstance(data, list) or not all(
+                    isinstance(row, list) for row in data
+                ):
+                    raise ValueError(
+                        f"{self.file_type.name} file type requires a list of lists"
+                    )
+                with open(
+                    self.file_path, mode=self.mode, newline="", encoding="UTF-8"
+                ) as tsvfile:
+                    writer = csv.writer(tsvfile, delimiter="\t")
+                    writer.writerows(data)
+            elif self.file_type == FileType.XML:
+                if not isinstance(data, dict):
+                    raise ValueError("XML file type requires data to be a dictionary")
+                root = ET.Element("root")
+                self._dict_to_xml(data, root)
+                tree = ET.ElementTree(root)
+                tree.write(self.file_path, encoding="UTF-8", xml_declaration=True)
+            else:
+                raise ValueError(f"Unsupported file type: {self.file_type}")
+
+        except Exception as error:
+            logger.error("Failed to save %s: %s", self.file_path.name, error)
+            raise
+
     async def _run(self, *args, **kwargs):
-        raise NotImplementedError(
-            "SaveFileAction is not finished yet... Use primitives instead..."
+        combined_kwargs = self._maybe_inject_last_result(kwargs)
+        data = combined_kwargs.get(self.inject_into)
+
+        context = ExecutionContext(
+            name=self.name, args=args, kwargs=combined_kwargs, action=self
         )
+        context.start_timer()
+
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+
+            await self.save_file(data)
+            logger.debug("File saved successfully: %s", self.file_path)
+
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return str(self.file_path)
+
+        except Exception as error:
+            context.exception = error
+            await self.hooks.trigger(HookType.ON_ERROR, context)
+            raise
+        finally:
+            context.stop_timer()
+            await self.hooks.trigger(HookType.AFTER, context)
+            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
+            er.record(context)
+
+    async def preview(self, parent: Tree | None = None):
+        label = f"[{OneColors.CYAN}]💾 SaveFileAction[/] '{self.name}'"
+        tree = parent.add(label) if parent else Tree(label)
+
+        tree.add(f"[dim]Path:[/] {self.file_path}")
+        tree.add(f"[dim]Type:[/] {self.file_type.name}")
+        tree.add(f"[dim]Overwrite:[/] {self.overwrite}")
+
+        if self.file_path and self.file_path.exists():
+            if self.overwrite:
+                tree.add(f"[{OneColors.LIGHT_YELLOW}]⚠️ File will be overwritten[/]")
+            else:
+                tree.add(
+                    f"[{OneColors.DARK_RED}]❌ File exists and overwrite is disabled[/]"
+                )
+            stat = self.file_path.stat()
+            tree.add(f"[dim]Size:[/] {stat.st_size:,} bytes")
+            tree.add(
+                f"[dim]Modified:[/] {datetime.fromtimestamp(stat.st_mtime):%Y-%m-%d %H:%M:%S}"
+            )
+            tree.add(
+                f"[dim]Created:[/] {datetime.fromtimestamp(stat.st_ctime):%Y-%m-%d %H:%M:%S}"
+            )
 
-    async def preview(self, parent: Tree | None = None): ...
+        if not parent:
+            self.console.print(tree)
 
     def __str__(self) -> str:
-        return f"SaveFileAction(file_path={self.file_path})"
+        return f"SaveFileAction(file_path={self.file_path}, file_type={self.file_type})"