falyx 0.1.42__py3-none-any.whl → 0.1.43__py3-none-any.whl

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/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
@@ -1029,6 +1029,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 +1048,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")

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/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(

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.42"
+__version__ = "0.1.43"

{falyx-0.1.42.dist-info → falyx-0.1.43.dist-info}/METADATA

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

{falyx-0.1.42.dist-info → falyx-0.1.43.dist-info}/RECORD

@@ -1,6 +1,6 @@
 falyx/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/__init__.py,sha256=Gh88lQ5pbD7xbGWrBgslE2kSTZKY9TkvKSa53rZ3l8U,305
-falyx/__main__.py,sha256=8abZbfytyFcSccyEZzlX3E2Krto1tVr1pRI_ep9KcUs,1911
+falyx/__main__.py,sha256=yrNF4m7kwKX9dFn-Q_ci1N6BJCC_ltw2p0HcUDqEuas,3423
 falyx/action/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/action/__init__.py,sha256=4E3Rb0GgGcmggrPJh0YFiwbVgN_PQjIzL06-Z3qMReo,1247
 falyx/action/action.py,sha256=w6xDbsB1SlMPSvpo2Dh0e11lRGP6a4E3K6AdfjlEqGY,5759
@@ -29,7 +29,7 @@ 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=kMQWAd_uL8M5hkzRy7k1KgNe5wBzkWCyHvqwFjykvdI,47340
+falyx/falyx.py,sha256=X4f0O5wgUID0HjlwuH0I88HBLGhlQ1chNeOt1TlDJqw,47559
 falyx/hook_manager.py,sha256=TFuHQnAncS_rk6vuw-VSx8bnAppLuHfrZCrzLwqcO9o,2979
 falyx/hooks.py,sha256=xMfQROib0BNsaQF4AXJpmCiGePoE1f1xpcdibgnVZWM,2913
 falyx/init.py,sha256=VZ3rYMxo7g01EraYATdl_pRN4ZqrsVueo2ZFx54gojo,3326
@@ -37,9 +37,9 @@ 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/__init__.py,sha256=ZfPmbtEUechDvgl99-lWhTXmFnXS_FMXJ_xb8KGEJLo,448
 falyx/parsers/argparse.py,sha256=WB8InZJ_WOaqi6J80IfnxInRyJ7aBCP0sv0zalo8al0,36924
-falyx/parsers/parsers.py,sha256=RQdfK_347TeTMYWZ_7WqZxGaslC-fRZeuir4kdHjvFM,6527
+falyx/parsers/parsers.py,sha256=iCFOcNXuYLzmOzv63CPi8mWh7udi-Ok1ZJB80ASe12M,8673
 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=a0ON039K5sX117g1thh7kP35cYMBjBhhhU9A-PERuT0,23
-falyx-0.1.42.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
-falyx-0.1.42.dist-info/METADATA,sha256=8L4CG1zpDFOwepLhP9oji_1UGmTkM24p6_QcHRQDY8c,5517
-falyx-0.1.42.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-falyx-0.1.42.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
-falyx-0.1.42.dist-info/RECORD,,
+falyx/version.py,sha256=PwEipAcIgfEks4UpVgOERoR8Az-FCfCGocVnb0rkncM,23
+falyx-0.1.43.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.43.dist-info/METADATA,sha256=qHVTRg3y4xhC6cxIDvkkZ5YuJsm98DEhOOi485g-HUE,5517
+falyx-0.1.43.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+falyx-0.1.43.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.43.dist-info/RECORD,,