falyx 0.1.42__tar.gz → 0.1.44__tar.gz

{falyx-0.1.42 → falyx-0.1.44}/PKG-INFO

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

{falyx-0.1.42 → falyx-0.1.44}/falyx/__main__.py

@@ -8,12 +8,13 @@ Licensed under the MIT License. See LICENSE file for details.
 import asyncio
 import os
 import sys
+from argparse import ArgumentParser, Namespace, _SubParsersAction
 from pathlib import Path
 from typing import Any
 
 from falyx.config import loader
 from falyx.falyx import Falyx
-from falyx.parsers import CommandArgumentParser
+from falyx.parsers import CommandArgumentParser, get_root_parser, get_subparsers
 
 
 def find_falyx_config() -> Path | None:
@@ -48,6 +49,42 @@ def init_config(parser: CommandArgumentParser) -> None:
     )
 
 
+def init_callback(args: Namespace) -> None:
+    """Callback for the init command."""
+    if args.command == "init":
+        from falyx.init import init_project
+
+        init_project(args.name)
+    elif args.command == "init_global":
+        from falyx.init import init_global
+
+        init_global()
+
+
+def get_parsers() -> tuple[ArgumentParser, _SubParsersAction]:
+    root_parser: ArgumentParser = get_root_parser()
+    subparsers = get_subparsers(root_parser)
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize a new Falyx project",
+        description="Create a new Falyx project with mock configuration files.",
+        epilog="If no name is provided, the current directory will be used.",
+    )
+    init_parser.add_argument(
+        "name",
+        type=str,
+        help="Name of the new Falyx project",
+        default=".",
+        nargs="?",
+    )
+    subparsers.add_parser(
+        "init-global",
+        help="Initialize Falyx global configuration",
+        description="Create a global Falyx configuration at ~/.config/falyx/.",
+    )
+    return root_parser, subparsers
+
+
 def main() -> Any:
     bootstrap_path = bootstrap()
     if not bootstrap_path:
@@ -60,17 +97,23 @@ def main() -> Any:
             init_project,
             aliases=["init"],
             argument_config=init_config,
+            help_epilogue="If no name is provided, the current directory will be used.",
         )
         flx.add_command(
             "G",
             "Initialize Falyx global configuration",
             init_global,
             aliases=["init-global"],
+            help_text="Create a global Falyx configuration at ~/.config/falyx/.",
         )
     else:
         flx = loader(bootstrap_path)
 
-    return asyncio.run(flx.run())
+    root_parser, subparsers = get_parsers()
+
+    return asyncio.run(
+        flx.run(root_parser=root_parser, subparsers=subparsers, callback=init_callback)
+    )
 
 
 if __name__ == "__main__":

{falyx-0.1.42 → falyx-0.1.44}/falyx/command.py

@@ -135,6 +135,7 @@ class Command(BaseModel):
     custom_help: Callable[[], str | None] | None = None
     auto_args: bool = True
     arg_metadata: dict[str, str | dict[str, Any]] = Field(default_factory=dict)
+    simple_help_signature: bool = False
 
     _context: ExecutionContext | None = PrivateAttr(default=None)
 
@@ -317,6 +318,22 @@ class Command(BaseModel):
         options_text = self.arg_parser.get_options_text(plain_text=True)
         return f"  {command_keys_text:<20}  {options_text} "
 
+    @property
+    def help_signature(self) -> str:
+        """Generate a help signature for the command."""
+        if self.arg_parser and not self.simple_help_signature:
+            signature = [self.arg_parser.get_usage()]
+            signature.append(f"  {self.help_text or self.description}")
+            if self.tags:
+                signature.append(f"  [dim]Tags: {', '.join(self.tags)}[/dim]")
+            return "\n".join(signature).strip()
+
+        command_keys = " | ".join(
+            [f"[{self.style}]{self.key}[/{self.style}]"]
+            + [f"[{self.style}]{alias}[/{self.style}]" for alias in self.aliases]
+        )
+        return f"{command_keys}  {self.description}"
+
     def log_summary(self) -> None:
         if self._context:
             self._context.log_summary()

{falyx-0.1.42 → falyx-0.1.44}/falyx/falyx.py

@@ -25,7 +25,7 @@ import asyncio
 import logging
 import shlex
 import sys
-from argparse import Namespace
+from argparse import ArgumentParser, Namespace, _SubParsersAction
 from difflib import get_close_matches
 from enum import Enum
 from functools import cached_property
@@ -284,6 +284,7 @@ class Falyx:
             action=Action("Exit", action=_noop),
             aliases=["EXIT", "QUIT"],
             style=OneColors.DARK_RED,
+            simple_help_signature=True,
         )
 
     def _get_history_command(self) -> Command:
@@ -294,60 +295,71 @@ class Falyx:
             aliases=["HISTORY"],
             action=Action(name="View Execution History", action=er.summary),
             style=OneColors.DARK_YELLOW,
+            simple_help_signature=True,
         )
 
-    async def _show_help(self):
-        table = Table(title="[bold cyan]Help Menu[/]", box=box.SIMPLE)
-        table.add_column("Key", style="bold", no_wrap=True)
-        table.add_column("Aliases", style="dim", no_wrap=True)
-        table.add_column("Description", style="dim", overflow="fold")
-        table.add_column("Tags", style="dim", no_wrap=True)
-
-        for command in self.commands.values():
-            help_text = command.help_text or command.description
-            table.add_row(
-                f"[{command.style}]{command.key}[/]",
-                ", ".join(command.aliases) if command.aliases else "",
-                help_text,
-                ", ".join(command.tags) if command.tags else "",
+    async def _show_help(self, tag: str = "") -> None:
+        if tag:
+            table = Table(
+                title=tag.upper(),
+                title_justify="left",
+                show_header=False,
+                box=box.SIMPLE,
+                show_footer=False,
             )
-
-        table.add_row(
-            f"[{self.exit_command.style}]{self.exit_command.key}[/]",
-            ", ".join(self.exit_command.aliases),
-            "Exit this menu or program",
-        )
-
-        if self.history_command:
-            table.add_row(
-                f"[{self.history_command.style}]{self.history_command.key}[/]",
-                ", ".join(self.history_command.aliases),
-                "History of executed actions",
+            tag_lower = tag.lower()
+            commands = [
+                command
+                for command in self.commands.values()
+                if any(tag_lower == tag.lower() for tag in command.tags)
+            ]
+            for command in commands:
+                table.add_row(command.help_signature)
+            self.console.print(table)
+            return
+        else:
+            table = Table(
+                title="Help",
+                title_justify="left",
+                title_style=OneColors.LIGHT_YELLOW_b,
+                show_header=False,
+                show_footer=False,
+                box=box.SIMPLE,
             )
-
+            for command in self.commands.values():
+                table.add_row(command.help_signature)
         if self.help_command:
-            table.add_row(
-                f"[{self.help_command.style}]{self.help_command.key}[/]",
-                ", ".join(self.help_command.aliases),
-                "Show this help menu",
-            )
-
-        self.console.print(table, justify="center")
-        if self.mode == FalyxMode.MENU:
-            self.console.print(
-                f"📦 Tip: '[{OneColors.LIGHT_YELLOW}]?[KEY][/]' to preview a command "
-                "before running it.\n",
-                justify="center",
-            )
+            table.add_row(self.help_command.help_signature)
+        if self.history_command:
+            table.add_row(self.history_command.help_signature)
+        table.add_row(self.exit_command.help_signature)
+        table.add_row(f"Tip: '[{OneColors.LIGHT_YELLOW}]?[KEY][/]' to preview a command ")
+        self.console.print(table)
 
     def _get_help_command(self) -> Command:
         """Returns the help command for the menu."""
+        parser = CommandArgumentParser(
+            command_key="H",
+            command_description="Help",
+            command_style=OneColors.LIGHT_YELLOW,
+            aliases=["?", "HELP", "LIST"],
+        )
+        parser.add_argument(
+            "-t",
+            "--tag",
+            nargs="?",
+            default="",
+            help="Optional tag to filter commands by.",
+        )
         return Command(
             key="H",
-            aliases=["HELP", "?"],
+            aliases=["?", "HELP", "LIST"],
             description="Help",
+            help_text="Show this help menu",
             action=Action("Help", self._show_help),
             style=OneColors.LIGHT_YELLOW,
+            arg_parser=parser,
+            auto_args=False,
         )
 
     def _get_completer(self) -> WordCompleter:
@@ -568,7 +580,9 @@ class Falyx:
         if not isinstance(submenu, Falyx):
             raise NotAFalyxError("submenu must be an instance of Falyx.")
         self._validate_command_key(key)
-        self.add_command(key, description, submenu.menu, style=style)
+        self.add_command(
+            key, description, submenu.menu, style=style, simple_help_signature=True
+        )
         if submenu.exit_command.key == "X":
             submenu.update_exit_command(key="B", description="Back", aliases=["BACK"])
 
@@ -630,6 +644,7 @@ class Falyx:
         custom_help: Callable[[], str | None] | None = None,
         auto_args: bool = True,
         arg_metadata: dict[str, str | dict[str, Any]] | None = None,
+        simple_help_signature: bool = False,
     ) -> Command:
         """Adds an command to the menu, preventing duplicates."""
         self._validate_command_key(key)
@@ -682,6 +697,7 @@ class Falyx:
             custom_help=custom_help,
             auto_args=auto_args,
             arg_metadata=arg_metadata or {},
+            simple_help_signature=simple_help_signature,
         )
 
         if hooks:
@@ -706,16 +722,16 @@ class Falyx:
     def get_bottom_row(self) -> list[str]:
         """Returns the bottom row of the table for displaying additional commands."""
         bottom_row = []
-        if self.history_command:
-            bottom_row.append(
-                f"[{self.history_command.key}] [{self.history_command.style}]"
-                f"{self.history_command.description}"
-            )
         if self.help_command:
             bottom_row.append(
                 f"[{self.help_command.key}] [{self.help_command.style}]"
                 f"{self.help_command.description}"
             )
+        if self.history_command:
+            bottom_row.append(
+                f"[{self.history_command.key}] [{self.history_command.style}]"
+                f"{self.history_command.description}"
+            )
         bottom_row.append(
             f"[{self.exit_command.key}] [{self.exit_command.style}]"
             f"{self.exit_command.description}"
@@ -727,12 +743,14 @@ class Falyx:
         Build the standard table layout. Developers can subclass or call this
         in custom tables.
         """
-        table = Table(title=self.title, show_header=False, box=box.SIMPLE, expand=True)  # type: ignore[arg-type]
+        table = Table(title=self.title, show_header=False, box=box.SIMPLE)  # type: ignore[arg-type]
         visible_commands = [item for item in self.commands.items() if not item[1].hidden]
+        space = self.console.width // self.columns
         for chunk in chunks(visible_commands, self.columns):
             row = []
             for key, command in chunk:
-                row.append(f"[{key}] [{command.style}]{command.description}")
+                cell = f"[{key}] [{command.style}]{command.description}"
+                row.append(f"{cell:<{space}}")
             table.add_row(*row)
         bottom_row = self.get_bottom_row()
         for row in chunks(bottom_row, self.columns):
@@ -1029,6 +1047,8 @@ class Falyx:
     async def run(
         self,
         falyx_parsers: FalyxParsers | None = None,
+        root_parser: ArgumentParser | None = None,
+        subparsers: _SubParsersAction | None = None,
         callback: Callable[..., Any] | None = None,
     ) -> None:
         """Run Falyx CLI with structured subcommands."""
@@ -1046,6 +1066,8 @@ class Falyx:
                 self.description,
                 self.epilog,
                 commands=self.commands,
+                root_parser=root_parser,
+                subparsers=subparsers,
             )
         self.cli_args = falyx_parsers.parse_args()
         self.options.from_namespace(self.cli_args, "cli_args")
@@ -1072,7 +1094,7 @@ class Falyx:
             self.register_all_with_debug_hooks()
 
         if self.cli_args.command == "list":
-            await self._show_help()
+            await self._show_help(tag=self.cli_args.tag)
             sys.exit(0)
 
         if self.cli_args.command == "version" or self.cli_args.version:

{falyx-0.1.42 → falyx-0.1.44}/falyx/parsers/__init__.py

@@ -6,12 +6,14 @@ Licensed under the MIT License. See LICENSE file for details.
 """
 
 from .argparse import Argument, ArgumentAction, CommandArgumentParser
-from .parsers import FalyxParsers, get_arg_parsers
+from .parsers import FalyxParsers, get_arg_parsers, get_root_parser, get_subparsers
 
 __all__ = [
     "Argument",
     "ArgumentAction",
     "CommandArgumentParser",
     "get_arg_parsers",
+    "get_root_parser",
+    "get_subparsers",
     "FalyxParsers",
 ]

{falyx-0.1.42 → falyx-0.1.44}/falyx/parsers/parsers.py

@@ -40,7 +40,7 @@ class FalyxParsers:
         return self.as_dict().get(name)
 
 
-def get_arg_parsers(
+def get_root_parser(
     prog: str | None = "falyx",
     usage: str | None = None,
     description: str | None = "Falyx CLI - Run structured async command workflows.",
@@ -55,9 +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."""
+) -> ArgumentParser:
     parser = ArgumentParser(
         prog=prog,
         usage=usage,
@@ -86,7 +84,70 @@ def get_arg_parsers(
         help="Enable default lifecycle debug logging",
     )
     parser.add_argument("--version", action="store_true", help="Show Falyx version")
-    subparsers = parser.add_subparsers(dest="command")
+    return parser
+
+
+def get_subparsers(
+    parser: ArgumentParser,
+    title: str = "Falyx Commands",
+    description: str | None = "Available commands for the Falyx CLI.",
+) -> _SubParsersAction:
+    """Create and return a subparsers action for the given parser."""
+    if not isinstance(parser, ArgumentParser):
+        raise TypeError("parser must be an instance of ArgumentParser")
+    subparsers = parser.add_subparsers(
+        title=title,
+        description=description,
+        metavar="COMMAND",
+        dest="command",
+    )
+    return subparsers
+
+
+def get_arg_parsers(
+    prog: str | None = "falyx",
+    usage: str | None = None,
+    description: str | None = "Falyx CLI - Run structured async command workflows.",
+    epilog: (
+        str | None
+    ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
+    parents: Sequence[ArgumentParser] | None = None,
+    prefix_chars: str = "-",
+    fromfile_prefix_chars: str | None = None,
+    argument_default: Any = None,
+    conflict_handler: str = "error",
+    add_help: bool = True,
+    allow_abbrev: bool = True,
+    exit_on_error: bool = True,
+    commands: dict[str, Command] | None = None,
+    root_parser: ArgumentParser | None = None,
+    subparsers: _SubParsersAction | None = None,
+) -> FalyxParsers:
+    """Returns the argument parser for the CLI."""
+    if root_parser is None:
+        parser = get_root_parser(
+            prog=prog,
+            usage=usage,
+            description=description,
+            epilog=epilog,
+            parents=parents,
+            prefix_chars=prefix_chars,
+            fromfile_prefix_chars=fromfile_prefix_chars,
+            argument_default=argument_default,
+            conflict_handler=conflict_handler,
+            add_help=add_help,
+            allow_abbrev=allow_abbrev,
+            exit_on_error=exit_on_error,
+        )
+    else:
+        if not isinstance(root_parser, ArgumentParser):
+            raise TypeError("root_parser must be an instance of ArgumentParser")
+        parser = root_parser
+
+    if subparsers is None:
+        subparsers = get_subparsers(parser)
+    if not isinstance(subparsers, _SubParsersAction):
+        raise TypeError("subparsers must be an instance of _SubParsersAction")
 
     run_description = ["Run a command by its key or alias.\n"]
     run_description.append("commands:")
@@ -105,7 +166,9 @@ def get_arg_parsers(
         epilog=run_epilog,
         formatter_class=RawDescriptionHelpFormatter,
     )
-    run_parser.add_argument("name", help="Run a command by its key or alias")
+    run_parser.add_argument(
+        "name", help="Run a command by its key or alias", metavar="COMMAND"
+    )
     run_parser.add_argument(
         "--summary",
         action="store_true",
@@ -143,6 +206,7 @@ def get_arg_parsers(
         "command_args",
         nargs=REMAINDER,
         help="Arguments to pass to the command (if applicable)",
+        metavar="ARGS",
     )
 
     run_all_parser = subparsers.add_parser(
@@ -191,6 +255,10 @@ def get_arg_parsers(
         "list", help="List all available commands with tags"
     )
 
+    list_parser.add_argument(
+        "-t", "--tag", help="Filter commands by tag (case-insensitive)", default=None
+    )
+
     version_parser = subparsers.add_parser("version", help="Show the Falyx version")
 
     return FalyxParsers(

{falyx-0.1.42 → falyx-0.1.44}/falyx/parsers/signature.py

@@ -24,7 +24,6 @@ def infer_args_from_func(
         metadata = (
             {"help": raw_metadata} if isinstance(raw_metadata, str) else raw_metadata
         )
-
         if param.kind not in (
             inspect.Parameter.POSITIONAL_ONLY,
             inspect.Parameter.POSITIONAL_OR_KEYWORD,
@@ -35,6 +34,8 @@ def infer_args_from_func(
         arg_type = (
             param.annotation if param.annotation is not inspect.Parameter.empty else str
         )
+        if isinstance(arg_type, str):
+            arg_type = str
         default = param.default if param.default is not inspect.Parameter.empty else None
         is_required = param.default is inspect.Parameter.empty
         if is_required:

falyx-0.1.44/falyx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.44"

{falyx-0.1.42 → falyx-0.1.44}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.42"
+version = "0.1.44"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"

falyx-0.1.42/falyx/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.42"