falyx 0.1.40__py3-none-any.whl → 0.1.41__py3-none-any.whl

falyx/__main__.py

@@ -8,13 +8,12 @@ Licensed under the MIT License. See LICENSE file for details.
 import asyncio
 import os
 import sys
-from argparse import Namespace
 from pathlib import Path
 from typing import Any
 
 from falyx.config import loader
 from falyx.falyx import Falyx
-from falyx.parsers import FalyxParsers, get_arg_parsers
+from falyx.parsers import CommandArgumentParser
 
 
 def find_falyx_config() -> Path | None:
@@ -39,45 +38,40 @@ def bootstrap() -> Path | None:
     return config_path
 
 
-def get_falyx_parsers() -> FalyxParsers:
-    falyx_parsers: FalyxParsers = get_arg_parsers()
-    init_parser = falyx_parsers.subparsers.add_parser(
-        "init", help="Create a new Falyx CLI project"
+def init_config(parser: CommandArgumentParser) -> None:
+    parser.add_argument(
+        "name",
+        type=str,
+        help="Name of the new Falyx project",
+        default=".",
+        nargs="?",
     )
-    init_parser.add_argument("name", nargs="?", default=".", help="Project directory")
-    falyx_parsers.subparsers.add_parser(
-        "init-global", help="Set up ~/.config/falyx with example tasks"
-    )
-    return falyx_parsers
-
-
-def run(args: Namespace) -> Any:
-    if args.command == "init":
-        from falyx.init import init_project
-
-        init_project(args.name)
-        return
 
-    if args.command == "init-global":
-        from falyx.init import init_global
-
-        init_global()
-        return
 
+def main() -> Any:
     bootstrap_path = bootstrap()
     if not bootstrap_path:
-        print("No Falyx config file found. Exiting.")
-        return None
+        from falyx.init import init_global, init_project
+
+        flx: Falyx = Falyx()
+        flx.add_command(
+            "I",
+            "Initialize a new Falyx project",
+            init_project,
+            aliases=["init"],
+            argument_config=init_config,
+        )
+        flx.add_command(
+            "G",
+            "Initialize Falyx global configuration",
+            init_global,
+            aliases=["init-global"],
+        )
+    else:
+        flx = loader(bootstrap_path)
 
-    flx: Falyx = loader(bootstrap_path)
     return asyncio.run(flx.run())
 
 
-def main():
-    parsers = get_falyx_parsers()
-    args = parsers.parse_args()
-    run(args)
-
-
 if __name__ == "__main__":
     main()

falyx/command.py

@@ -307,6 +307,14 @@ class Command(BaseModel):
 
         return FormattedText(prompt)
 
+    @property
+    def usage(self) -> str:
+        """Generate a help string for the command arguments."""
+        if not self.arg_parser:
+            return "No arguments defined."
+
+        return self.arg_parser.get_usage(plain_text=True)
+
     def log_summary(self) -> None:
         if self._context:
             self._context.log_summary()

falyx/config.py

@@ -18,6 +18,7 @@ from falyx.action.base import BaseAction
 from falyx.command import Command
 from falyx.falyx import Falyx
 from falyx.logger import logger
+from falyx.parsers import CommandArgumentParser
 from falyx.retry import RetryPolicy
 from falyx.themes import OneColors
 
@@ -101,6 +102,7 @@ class RawCommand(BaseModel):
     retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
     hidden: bool = False
     help_text: str = ""
+    help_epilogue: str = ""
 
     @field_validator("retry_policy")
     @classmethod
@@ -116,6 +118,14 @@ def convert_commands(raw_commands: list[dict[str, Any]]) -> list[Command]:
     commands = []
     for entry in raw_commands:
         raw_command = RawCommand(**entry)
+        parser = CommandArgumentParser(
+            command_key=raw_command.key,
+            command_description=raw_command.description,
+            command_style=raw_command.style,
+            help_text=raw_command.help_text,
+            help_epilogue=raw_command.help_epilogue,
+            aliases=raw_command.aliases,
+        )
         commands.append(
             Command.model_validate(
                 {
@@ -123,9 +133,11 @@ def convert_commands(raw_commands: list[dict[str, Any]]) -> list[Command]:
                     "action": wrap_if_needed(
                         import_action(raw_command.action), name=raw_command.description
                     ),
+                    "arg_parser": parser,
                 }
             )
         )
+
     return commands
 
 

falyx/falyx.py

@@ -59,7 +59,7 @@ 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.parsers import CommandArgumentParser, get_arg_parsers
+from falyx.parsers import CommandArgumentParser, FalyxParsers, get_arg_parsers
 from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
 from falyx.signals import BackSignal, CancelSignal, HelpSignal, QuitSignal
@@ -152,6 +152,11 @@ class Falyx:
         self,
         title: str | Markdown = "Menu",
         *,
+        program: str | None = "falyx",
+        usage: str | None = None,
+        description: str | None = "Falyx CLI - Run structured async command workflows.",
+        epilog: str | None = None,
+        version: str = __version__,
         prompt: str | AnyFormattedText = "> ",
         columns: int = 3,
         bottom_bar: BottomBar | str | Callable[[], Any] | None = None,
@@ -170,6 +175,11 @@ class Falyx:
     ) -> None:
         """Initializes the Falyx object."""
         self.title: str | Markdown = title
+        self.program: str | None = program
+        self.usage: str | None = usage
+        self.description: str | None = description
+        self.epilog: str | None = epilog
+        self.version: str = version
         self.prompt: str | AnyFormattedText = prompt
         self.columns: int = columns
         self.commands: dict[str, Command] = CaseInsensitiveDict()
@@ -1015,12 +1025,35 @@ class Falyx:
             if self.exit_message:
                 self.print_message(self.exit_message)
 
-    async def run(self) -> None:
+    async def run(
+        self,
+        falyx_parsers: FalyxParsers | None = None,
+        callback: Callable[..., Any] | None = None,
+    ) -> None:
         """Run Falyx CLI with structured subcommands."""
-        if not self.cli_args:
-            self.cli_args = get_arg_parsers().root.parse_args()
+        if self.cli_args:
+            raise FalyxError(
+                "Run is incompatible with CLI arguments. Use 'run_key' instead."
+            )
+        if falyx_parsers:
+            if not isinstance(falyx_parsers, FalyxParsers):
+                raise FalyxError("falyx_parsers must be an instance of FalyxParsers.")
+        else:
+            falyx_parsers = get_arg_parsers(
+                self.program,
+                self.usage,
+                self.description,
+                self.epilog,
+                commands=self.commands,
+            )
+        self.cli_args = falyx_parsers.parse_args()
         self.options.from_namespace(self.cli_args, "cli_args")
 
+        if callback:
+            if not callable(callback):
+                raise FalyxError("Callback must be a callable function.")
+            callback(self.cli_args)
+
         if not self.options.get("never_prompt"):
             self.options.set("never_prompt", self._never_prompt)
 
@@ -1075,11 +1108,24 @@ class Falyx:
                 args, kwargs = await command.parse_args(self.cli_args.command_args)
             except HelpSignal:
                 sys.exit(0)
+            except CommandArgumentError as error:
+                self.console.print(f"[{OneColors.DARK_RED}]❌ ['{command.key}'] {error}")
+                command.show_help()
+                sys.exit(1)
             try:
                 await self.run_key(self.cli_args.name, args=args, kwargs=kwargs)
             except FalyxError as error:
                 self.console.print(f"[{OneColors.DARK_RED}]❌ Error: {error}[/]")
                 sys.exit(1)
+            except QuitSignal:
+                logger.info("[QuitSignal]. <- Exiting run.")
+                sys.exit(0)
+            except BackSignal:
+                logger.info("[BackSignal]. <- Exiting run.")
+                sys.exit(0)
+            except CancelSignal:
+                logger.info("[CancelSignal]. <- Exiting run.")
+                sys.exit(0)
 
             if self.cli_args.summary:
                 er.summary()

falyx/init.py

@@ -101,7 +101,7 @@ commands:
 console = Console(color_system="auto")
 
 
-def init_project(name: str = ".") -> None:
+def init_project(name: str) -> None:
     target = Path(name).resolve()
     target.mkdir(parents=True, exist_ok=True)
 

falyx/parsers/argparse.py

@@ -168,6 +168,7 @@ class CommandArgumentParser:
         self._arguments: list[Argument] = []
         self._positional: dict[str, Argument] = {}
         self._keyword: dict[str, Argument] = {}
+        self._keyword_list: list[Argument] = []
         self._flag_map: dict[str, Argument] = {}
         self._dest_set: set[str] = set()
         self._add_help()
@@ -488,6 +489,8 @@ class CommandArgumentParser:
         self._arguments.append(argument)
         if positional:
             self._positional[dest] = argument
+        else:
+            self._keyword_list.append(argument)
 
     def get_argument(self, dest: str) -> Argument | None:
         return next((a for a in self._arguments if a.dest == dest), None)
@@ -832,11 +835,11 @@ class CommandArgumentParser:
                 kwargs_dict[arg.dest] = parsed[arg.dest]
         return tuple(args_list), kwargs_dict
 
-    def render_help(self) -> None:
+    def get_options_text(self, plain_text=False) -> str:
         # Options
         # Add all keyword arguments to the options list
         options_list = []
-        for arg in self._keyword.values():
+        for arg in self._keyword_list:
             choice_text = arg.get_choice_text()
             if choice_text:
                 options_list.extend([f"[{arg.flags[0]} {choice_text}]"])
@@ -848,19 +851,39 @@ class CommandArgumentParser:
             choice_text = arg.get_choice_text()
             if isinstance(arg.nargs, int):
                 choice_text = " ".join([choice_text] * arg.nargs)
-            options_list.append(escape(choice_text))
-
-        options_text = " ".join(options_list)
-        command_keys = " | ".join(
-            [f"[{self.command_style}]{self.command_key}[/{self.command_style}]"]
-            + [
-                f"[{self.command_style}]{alias}[/{self.command_style}]"
-                for alias in self.aliases
-            ]
-        )
+            if plain_text:
+                options_list.append(choice_text)
+            else:
+                options_list.append(escape(choice_text))
+
+        return " ".join(options_list)
 
-        usage = f"usage: {command_keys} {options_text}"
-        self.console.print(f"[bold]{usage}[/bold]\n")
+    def get_command_keys_text(self, plain_text=False) -> str:
+        if plain_text:
+            command_keys = " | ".join(
+                [f"{self.command_key}"] + [f"{alias}" for alias in self.aliases]
+            )
+        else:
+            command_keys = " | ".join(
+                [f"[{self.command_style}]{self.command_key}[/{self.command_style}]"]
+                + [
+                    f"[{self.command_style}]{alias}[/{self.command_style}]"
+                    for alias in self.aliases
+                ]
+            )
+        return command_keys
+
+    def get_usage(self, plain_text=False) -> str:
+        """Get the usage text for the command."""
+        command_keys = self.get_command_keys_text(plain_text)
+        options_text = self.get_options_text(plain_text)
+        if options_text:
+            return f"{command_keys} {options_text}"
+        return command_keys
+
+    def render_help(self) -> None:
+        usage = self.get_usage()
+        self.console.print(f"[bold]usage: {usage}[/bold]\n")
 
         # Description
         if self.help_text:
@@ -877,7 +900,7 @@ class CommandArgumentParser:
                     arg_line.append(help_text)
                     self.console.print(arg_line)
             self.console.print("[bold]options:[/bold]")
-            for arg in self._keyword.values():
+            for arg in self._keyword_list:
                 flags = ", ".join(arg.flags)
                 flags_choice = f"{flags} {arg.get_choice_text()}"
                 arg_line = Text(f"  {flags_choice:<30} ")

falyx/parsers/parsers.py

@@ -2,10 +2,18 @@
 """parsers.py
 This module contains the argument parsers used for the Falyx CLI.
 """
-from argparse import REMAINDER, ArgumentParser, Namespace, _SubParsersAction
+from argparse import (
+    REMAINDER,
+    ArgumentParser,
+    Namespace,
+    RawDescriptionHelpFormatter,
+    _SubParsersAction,
+)
 from dataclasses import asdict, dataclass
 from typing import Any, Sequence
 
+from falyx.command import Command
+
 
 @dataclass
 class FalyxParsers:
@@ -47,6 +55,7 @@ def get_arg_parsers(
     add_help: bool = True,
     allow_abbrev: bool = True,
     exit_on_error: bool = True,
+    commands: dict[str, Command] | None = None,
 ) -> FalyxParsers:
     """Returns the argument parser for the CLI."""
     parser = ArgumentParser(
@@ -79,8 +88,25 @@ def get_arg_parsers(
     parser.add_argument("--version", action="store_true", help="Show Falyx version")
     subparsers = parser.add_subparsers(dest="command")
 
-    run_parser = subparsers.add_parser("run", help="Run a specific command")
-    run_parser.add_argument("name", help="Key, alias, or description of the command")
+    run_description = "Run a command by its key or alias."
+    run_epilog = ["commands:"]
+    if isinstance(commands, dict):
+        for command in commands.values():
+            run_epilog.append(command.usage)
+            command_description = command.description or command.help_text
+            run_epilog.append(f"  {command_description}")
+            run_epilog.append("  ")
+    run_epilog.append(
+        "Tip: Use 'falyx run ?[COMMAND]' to preview commands by their key or alias."
+    )
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run a specific command",
+        description=run_description,
+        epilog="\n".join(run_epilog),
+        formatter_class=RawDescriptionHelpFormatter,
+    )
+    run_parser.add_argument("name", help="Run a command by its key or alias")
     run_parser.add_argument(
         "--summary",
         action="store_true",

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.40"
+__version__ = "0.1.41"

{falyx-0.1.40.dist-info → falyx-0.1.41.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: falyx
-Version: 0.1.40
+Version: 0.1.41
 Summary: Reliable and introspectable async CLI action framework.
 License: MIT
 Author: Roland Thomas Jr

{falyx-0.1.40.dist-info → falyx-0.1.41.dist-info}/RECORD

@@ -1,6 +1,6 @@
 falyx/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/__init__.py,sha256=Gh88lQ5pbD7xbGWrBgslE2kSTZKY9TkvKSa53rZ3l8U,305
-falyx/__main__.py,sha256=g_LwJieofK3DJzCYtpkAMEeOXhzSLQenb7pRVUqcf-Y,2152
+falyx/__main__.py,sha256=8abZbfytyFcSccyEZzlX3E2Krto1tVr1pRI_ep9KcUs,1911
 falyx/action/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/action/__init__.py,sha256=4E3Rb0GgGcmggrPJh0YFiwbVgN_PQjIzL06-Z3qMReo,1247
 falyx/action/action.py,sha256=w6xDbsB1SlMPSvpo2Dh0e11lRGP6a4E3K6AdfjlEqGY,5759
@@ -23,23 +23,23 @@ falyx/action/signal_action.py,sha256=5UMqvzy7fBnLANGwYUWoe1VRhrr7e-yOVeLdOnCBiJo
 falyx/action/types.py,sha256=NfZz1ufZuvCgp-he2JIItbnjX7LjOUadjtKbjpRlSIY,1399
 falyx/action/user_input_action.py,sha256=7kL5G7L0j2LuLvHu-CMwOaHyEisagE7O_2G2EhqWRr8,3483
 falyx/bottom_bar.py,sha256=iWxgOKWgn5YmREeZBuGA50FzqzEfz1-Vnqm0V_fhldc,7383
-falyx/command.py,sha256=QCuhbsTu93PPggGhhPTmL0iiR3AoY7XhFiO7FnRaYP0,14623
-falyx/config.py,sha256=wfxKnhCyfwxHP0pLbYf-i8Tt1lBJlSeB-5DgI8JbnKM,9626
+falyx/command.py,sha256=M-XZDKKMhjHYF5mcn0Pdc_mXmvLlEmKk2l84sGS66jc,14864
+falyx/config.py,sha256=BBDRv5uj0teydBm25eTIvEl9hKQqGGGX-Z6H9EHOHHw,10077
 falyx/context.py,sha256=NfBpxzFzn-dYP6I3wrtGFucqm__UZo4SSBLmM8yYayE,10330
 falyx/debug.py,sha256=IRpYtdH8yeXJEsfP5rASALmBQb2U_EwrTudF2GIDdZY,1545
 falyx/exceptions.py,sha256=kK9k1v7LVNjJSwYztRa9Krhr3ZOI-6Htq2ZjlYICPKg,922
 falyx/execution_registry.py,sha256=rctsz0mrIHPToLZqylblVjDdKWdq1x_JBc8GwMP5sJ8,4710
-falyx/falyx.py,sha256=DhZ5J_CiAODz3-96P9BCLlcJuE9E_lOlnbKVy0FbnrI,44887
+falyx/falyx.py,sha256=v4G-OUzzU5N6HD2LDmlA9IDXb3uFe_HNCUUFwxi1qn4,46717
 falyx/hook_manager.py,sha256=TFuHQnAncS_rk6vuw-VSx8bnAppLuHfrZCrzLwqcO9o,2979
 falyx/hooks.py,sha256=xMfQROib0BNsaQF4AXJpmCiGePoE1f1xpcdibgnVZWM,2913
-falyx/init.py,sha256=rspe0ye3teTCHWPM8RwPCv6pVub49r8BQxcl_Uwxa6o,3332
+falyx/init.py,sha256=VZ3rYMxo7g01EraYATdl_pRN4ZqrsVueo2ZFx54gojo,3326
 falyx/logger.py,sha256=1Mfb_vJFJ1tQwziuyU2p-cSMi2Js8N2byniFEnI6vOQ,132
 falyx/menu.py,sha256=E580qZsx08bnWcqRVjJuD2Fy8Zh_1zIexp5f0lC7L2c,3745
 falyx/options_manager.py,sha256=dFAnQw543tQ6Xupvh1PwBrhiSWlSACHw8K-sHP_lUh4,2842
 falyx/parsers/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/parsers/__init__.py,sha256=l0QMf89uJHhTpOqQfiV3tx7aAHvELqDFWAyjCbwEgBQ,370
-falyx/parsers/argparse.py,sha256=P4iH0N5_vqzbw7dS9mU1HJ2TPhZMF6BN7t0RxRadXbM,36076
-falyx/parsers/parsers.py,sha256=yGyAwNIJQz12LU_WF87aW4xbBmJtyEY7RnLRFqXAsio,5763
+falyx/parsers/argparse.py,sha256=WB8InZJ_WOaqi6J80IfnxInRyJ7aBCP0sv0zalo8al0,36924
+falyx/parsers/parsers.py,sha256=EUArQTJkrpgrCa6qCc1zZXTX4GOZXnSvsQhEvzgDyQ8,6538
 falyx/parsers/signature.py,sha256=i4iOiJxv70sxQYivKKXC_YOsShRUYfcI8Cjq8yVZvMo,2262
 falyx/parsers/utils.py,sha256=Z4qLu8NVIprcHK2RDXoISpcDKBUii3n05G9mlgiPDgw,889
 falyx/prompt_utils.py,sha256=qgk0bXs7mwzflqzWyFhEOTpKQ_ZtMIqGhKeg-ocwNnE,1542
@@ -53,9 +53,9 @@ falyx/themes/__init__.py,sha256=1CZhEUCin9cUk8IGYBUFkVvdHRNNJBEFXccHwpUKZCA,284
 falyx/themes/colors.py,sha256=4aaeAHJetmeNInI0Zytg4E3YqKfPFelpf04vtjSvsS8,19776
 falyx/utils.py,sha256=U45xnZFUdoFC4xiji_9S1jHS5V7MvxSDtufP8EgB0SM,6732
 falyx/validators.py,sha256=t5iyzVpY8tdC4rfhr4isEfWpD5gNTzjeX_Hbi_Uq6sA,1328
-falyx/version.py,sha256=bRKE9C91TYGzTq0wxI4905SCxXVaXJVP1EuahhGjfCQ,23
-falyx-0.1.40.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
-falyx-0.1.40.dist-info/METADATA,sha256=q0xBvg_XhNasYPJW6YdVuospCVYn1mTBsPQeqOYXKlk,5517
-falyx-0.1.40.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-falyx-0.1.40.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
-falyx-0.1.40.dist-info/RECORD,,
+falyx/version.py,sha256=y9uk7vaddYq7x48m1qAG2qgbHu814vUzjs_fjnrQ3Es,23
+falyx-0.1.41.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.41.dist-info/METADATA,sha256=CajQhPtTIGTUkRJw7mYcyGh-7JUie9IPER3RS31zsDw,5517
+falyx-0.1.41.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+falyx-0.1.41.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.41.dist-info/RECORD,,