machineconfig 6.23__py3-none-any.whl → 8.12__py3-none-any.whl

machineconfig/scripts/python/fire_jobs.py

@@ -7,193 +7,193 @@ fire
 
 """
 
-from machineconfig.utils.ve import get_ve_activate_line, get_ve_path_and_ipython_profile
-from machineconfig.utils.options import choose_from_options
-from machineconfig.utils.path_helper import match_file_name, sanitize_path
-from machineconfig.utils.path_extended import PathExtended
-from machineconfig.utils.accessories import get_repo_root, randstr
-from machineconfig.scripts.python.helpers_fire_command.fire_jobs_args_helper import FireJobArgs, extract_kwargs, parse_fire_args_from_context
-
-import platform
 from typing import Optional, Annotated
-from pathlib import Path
 import typer
 
 
-def route(args: FireJobArgs, fire_args: str = "") -> None:
-    path_obj = sanitize_path(args.path)
-    if not path_obj.exists():
-        suffixes = {".py", ".sh", ".ps1"}
-        choice_file = match_file_name(sub_string=args.path, search_root=PathExtended.cwd(), suffixes=suffixes)
-    elif path_obj.is_dir():
-        from machineconfig.scripts.python.helpers_fire.helpers4 import search_for_files_of_interest
-        print(f"🔍 Searching recursively for Python, PowerShell and Shell scripts in directory `{path_obj}`")
-        files = search_for_files_of_interest(path_obj)
-        print(f"🔍 Got #{len(files)} results.")
-        choice_file = choose_from_options(multi=False, options=files, fzf=True, msg="Choose one option")
-        choice_file = PathExtended(choice_file)
-    else:
-        choice_file = path_obj
-
-
-    repo_root = get_repo_root(Path(choice_file))
+def route(args: "FireJobArgs", fire_args: str = "") -> None:
+    from pathlib import Path
+    from machineconfig.utils.path_helper import get_choice_file
+    from machineconfig.utils.accessories import get_repo_root, randstr
+    choice_file = get_choice_file(args.path, suffixes=None)
+    repo_root = get_repo_root(choice_file)
     print(f"💾 Selected file: {choice_file}.\nRepo root: {repo_root}")
-    ve_root_from_file, ipy_profile = get_ve_path_and_ipython_profile(choice_file)
-    if ipy_profile is None:
-        ipy_profile = "default"
-
+    if args.marimo:
+        print(f"🧽 Preparing to launch Marimo notebook for `{choice_file}`...")
+        tmp_dir = Path.home().joinpath(f"tmp_results/tmp_scripts/marimo/{choice_file.stem}_{randstr()}")
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        script = f"""
+cd {tmp_dir}
+uv run --python 3.14 --with marimo marimo convert {choice_file} -o marimo_nb.py
+uv run --project {repo_root} --with marimo marimo edit --host 0.0.0.0 marimo_nb.py
+"""
+        from machineconfig.utils.code import exit_then_run_shell_script
+        print(f"🚀 Launching Marimo notebook for `{choice_file}`...")
+        exit_then_run_shell_script(script)
+        return
 
     # =========================  preparing kwargs_dict
     if choice_file.suffix == ".py":
+        from machineconfig.scripts.python.helpers_fire_command.fire_jobs_args_helper import extract_kwargs
         kwargs_dict = extract_kwargs(args)  # This now returns empty dict, but kept for compatibility
-        ve_root = args.ve or ve_root_from_file
-        if ve_root is None:
-            raise ValueError(f"Could not determine virtual environment for file {choice_file}. Please ensure it is within a recognized project structure or specify the `--ve` option.")
-        activate_ve_line = get_ve_activate_line(ve_root=ve_root)
     else:
-        activate_ve_line = ""
         kwargs_dict = {}
 
-
     # =========================  choosing function to run
     choice_function: Optional[str] = None  # Initialize to avoid unbound variable
     if args.choose_function:
         from machineconfig.scripts.python.helpers_fire_command.fire_jobs_route_helper import choose_function_or_lines
+
         choice_function, choice_file, kwargs_dict = choose_function_or_lines(choice_file, kwargs_dict)
     else:
         choice_function = args.function
 
     if choice_file.suffix == ".py":
-        from machineconfig.scripts.python.helpers_fire_command.fire_jobs_route_helper import get_command_streamlit
-        if args.streamlit:  exe = get_command_streamlit(choice_file, args.environment, repo_root)
-        elif args.interactive is False: exe = "python"
-        elif args.jupyter: exe = "jupyter-lab"
-        else: exe = f"ipython -i --no-banner --profile {ipy_profile} "
-    elif choice_file.suffix == ".ps1" or choice_file.suffix == ".sh": exe = "."
-    elif choice_file.suffix == "": exe = ""
-    else: raise NotImplementedError(f"File type {choice_file.suffix} not supported, in the sense that I don't know how to fire it.")
-
-    if args.module or (args.debug and args.choose_function):  # because debugging tools do not support choosing functions and don't interplay with fire module. So the only way to have debugging and choose function options is to import the file as a module into a new script and run the function of interest there and debug the new script.
-        assert choice_file.suffix == ".py", f"File must be a python file to be imported as a module. Got {choice_file}"
-        from machineconfig.scripts.python.helpers_fire.helpers4 import get_import_module_code
-        import_line = get_import_module_code(str(choice_file))
+        module_line = "-m" if args.module else ""
+        with_project = f"--project {repo_root} " if repo_root is not None else ""
+        interactive_line = "-i" if args.interactive else ""
+        if args.interactive:
+            from machineconfig.utils.ve import get_ve_path_and_ipython_profile
+            _ve_root_from_file, ipy_profile = get_ve_path_and_ipython_profile(init_path=choice_file)
+            if ipy_profile is None:
+                ipy_profile = "default"
+            ipython_line = f"--no-banner --profile {ipy_profile} "
+        else:
+            ipython_line = ""
+
+        if args.streamlit:
+            from machineconfig.scripts.python.helpers_fire_command.fire_jobs_route_helper import get_command_streamlit
+            interpreter_line = get_command_streamlit(choice_file=choice_file, environment=args.environment, repo_root=repo_root)
+        elif args.jupyter:
+            interpreter_line = "jupyter-lab"
+        else:
+            interpreter_line = "python" if not args.interactive else "ipython"
+
+        exe_line = f"uv run {with_project} {interpreter_line} {interactive_line} {module_line} {ipython_line}"
+
+
+    elif choice_file.suffix == ".ps1" or choice_file.suffix == ".sh":
+        exe_line = "."
+    elif choice_file.suffix == "":
+        exe_line = ""
+    else:
+        raise NotImplementedError(f"File type {choice_file.suffix} not supported, in the sense that I don't know how to fire it.")
+
+    if args.module and choice_file.suffix == ".py":
         if repo_root is not None:
-            repo_root_add = f"""sys.path.append(r'{repo_root}')"""
+            choice_file_adjusted = ".".join(Path(choice_file).relative_to(repo_root).parts).replace(".py", "")
         else:
-            repo_root_add = ""
-        txt: str = f"""
-try:
-    {import_line}
-except (ImportError, ModuleNotFoundError) as ex:
-    print(fr"❌ Failed to import `{choice_file}` as a module: {{ex}} ")
-    print(fr"⚠️ Attempting import with ad-hoc `$PATH` manipulation. DO NOT pickle any objects in this session as correct deserialization cannot be guaranteed.")
-    import sys
-    sys.path.append(r'{PathExtended(choice_file).parent}')
-    {repo_root_add}
-    from {PathExtended(choice_file).stem} import *
-    print(fr"✅ Successfully imported `{choice_file}`")
-"""
-        if choice_function is not None:
-            txt = (
-                txt
-                + f"""
-res = {choice_function}({("**" + str(kwargs_dict)) if kwargs_dict else ""})
-"""
-            )
+            choice_file_adjusted = ".".join(Path(choice_file).relative_to(Path.cwd()).parts).replace(".py", "")
+    else:
+        choice_file_adjusted = str(choice_file)
 
-        txt = (
-            f"""
-try:
-    from rich.panel import Panel
-    from rich.console import Console
-    from rich.syntax import Syntax
-    console = Console()
-    console.print(Panel(Syntax(code=r'''{txt}''', lexer='python'), title='Import Script'), style="bold red")
-except ImportError as _ex:
-    print(r'''{txt}''')
-"""
-            + txt
+    if args.script or (args.debug and args.choose_function):
+        # because debugging tools do not support choosing functions and don't interplay with fire module. So the only way to have debugging and choose function options is to import the file as a module into a new script and run the function of interest there and debug the new script.
+        assert choice_file.suffix == ".py", f"File must be a python file to be imported as a module. Got {choice_file}"
+        from machineconfig.scripts.python.helpers_fire_command.file_wrangler import get_import_module_code, wrap_import_in_try_except
+        from machineconfig.utils.meta import lambda_to_python_script
+        from machineconfig.utils.code import print_code
+
+        import_code = get_import_module_code(str(choice_file))
+        import_code_robust = lambda_to_python_script(
+            lambda: wrap_import_in_try_except(
+                import_line=import_code, pyfile=str(choice_file), repo_root=str(repo_root) if repo_root is not None else None
+            ),
+            in_global=True,
+            import_module=False,
         )
-        choice_file = PathExtended.tmp().joinpath(f"tmp_scripts/python/{PathExtended(choice_file).parent.name}_{PathExtended(choice_file).stem}_{randstr()}.py")
+        # print(f"🧩 Preparing import code for module import:\n{import_code}")
+        code_printing = lambda_to_python_script(
+            lambda: print_code(code=import_code_robust, lexer="python", desc="import as module code"),
+            in_global=True, import_module=False
+        )
+        print(f"🧩 Preparing import code for module import:\n{import_code}")
+        if choice_function is not None:
+            calling = f"""res = {choice_function}({("**" + str(kwargs_dict)) if kwargs_dict else ""})"""
+        else:
+            calling = """# No function selected to call. You can add your code here."""
+        choice_file = Path.home().joinpath(f"tmp_results/tmp_scripts/python/{Path(choice_file).parent.name}_{Path(choice_file).stem}_{randstr()}.py")
         choice_file.parent.mkdir(parents=True, exist_ok=True)
-        choice_file.write_text(txt, encoding="utf-8")
+        choice_file.write_text(import_code_robust + "\n" + code_printing + "\n" + calling, encoding="utf-8")
 
-    # =========================  determining basic command structure: putting together exe & choice_file & choice_function & pdb
     if args.debug:
+        import platform
         if platform.system() == "Windows":
-            command = f"{exe} -m ipdb {choice_file} "  # pudb is not available on windows machines, use poor man's debugger instead.
+            command = f"{exe_line} -m ipdb {choice_file_adjusted} "  # pudb is not available on windows machines, use poor man's debugger instead.
         elif platform.system() in ["Linux", "Darwin"]:
-            command = f"{exe} -m pudb {choice_file} "  # TODO: functions not supported yet in debug mode.
+            command = f"{exe_line} -m pudb {choice_file_adjusted} "  # TODO: functions not supported yet in debug mode.
         else:
             raise NotImplementedError(f"Platform {platform.system()} not supported.")
     elif args.module:
         # both selected function and kwargs are mentioned in the made up script, therefore no need for fire module.
-        command = f"{exe} {choice_file} "
-    elif choice_function is not None:
-        command = f"{exe} -m fire {choice_file} {choice_function} {fire_args}"
+        command = f"{exe_line} {choice_file_adjusted} "
+    elif choice_function is not None and choice_file.suffix == ".py":
+        command = f"{exe_line} -m fire {choice_file_adjusted} {choice_function} {fire_args}"
     elif args.streamlit:
         # for .streamlit config to work, it needs to be in the current directory.
         if args.holdDirectory:
-            command = f"{exe} {choice_file}"
+            command = f"{exe_line} {choice_file}"
         else:
-            command = f"cd {choice_file.parent}\n{exe} {choice_file.name}\ncd {PathExtended.cwd()}"
-
+            command = f"cd {choice_file.parent}\n{exe_line} {choice_file.name}\ncd {Path.cwd()}"
     elif args.cmd:
-        command = rf""" cd /d {choice_file.parent} & {exe} {choice_file.name} """
+        command = rf""" cd /d {choice_file.parent} & {exe_line} {choice_file.name} """
     else:
-        if choice_file.suffix == "": command = f"{exe} {choice_file} {fire_args}"
-        else: command = f"{exe} {choice_file} "
+        if choice_file.suffix == "":
+            command = f"{exe_line} {choice_file} {fire_args}"
+        else:
+            command = f"{exe_line} {choice_file} "
 
-    if not args.cmd: command = f"{activate_ve_line}\n{command}"
+    if not args.cmd:
+        pass
     else:
         new_line = "\n"
-        command = rf"""start cmd -Argument "/k {activate_ve_line.replace(".ps1", ".bat").replace(". ", "")} & {command.replace(new_line, " & ")} " """  # this works from powershell
+        command = rf"""start cmd -Argument "/k {command.replace(new_line, " & ")} " """  # this works from powershell
     if args.submit_to_cloud:
-        command = f"""
-{activate_ve_line}
-python -m machineconfig.cluster.templates.cli_click --file {choice_file} """
+        command = f"""uv run python -m machineconfig.cluster.templates.cli_click --file {choice_file} """
         if choice_function is not None:
             command += f"--function {choice_function} "
 
     if args.optimized:
         command = command.replace("python ", "python -OO ")
+
     from rich.panel import Panel
     from rich.console import Console
     from rich.syntax import Syntax
+
     console = Console()
     if args.zellij_tab is not None:
-        comman_path__ = PathExtended.tmpfile(suffix=".sh")
+        comman_path__ = Path.home().joinpath(f"tmp_results/tmp_scripts/zellij_commands/{choice_file.stem}_{randstr()}.sh")
         comman_path__.parent.mkdir(parents=True, exist_ok=True)
         comman_path__.write_text(command, encoding="utf-8")
         console.print(Panel(Syntax(command, lexer="shell"), title=f"🔥 fire command @ {comman_path__}: "), style="bold red")
         import subprocess
+
         existing_tab_names = subprocess.run(["zellij", "action", "query-tab-names"], capture_output=True, text=True, check=True).stdout.splitlines()
         if args.zellij_tab in existing_tab_names:
             print(f"⚠️ Tab name `{args.zellij_tab}` already exists. Please choose a different name.")
             args.zellij_tab += f"_{randstr(3)}"
         from machineconfig.cluster.sessions_managers.zellij_local import run_command_in_zellij_tab
+
         command = run_command_in_zellij_tab(command=str(comman_path__), tab_name=args.zellij_tab, cwd=None)
     if args.watch:
         command = "watchexec --restart --exts py,sh,ps1 " + command
     if args.git_pull:
         command = f"\ngit -C {choice_file.parent} pull\n" + command
     if args.PathExport:
-        if platform.system() in ["Linux", "Darwin"]:
-            export_line = f"""export PYTHONPATH="{repo_root}""" + """:${PYTHONPATH}" """
-        elif platform.system() == "Windows":
-            export_line = f"""$env:PYTHONPATH="{repo_root}""" + """:$env:PYTHONPATH" """
-        else:
-            raise NotImplementedError(f"Platform {platform.system()} not supported.")
+        from machineconfig.scripts.python.helpers_fire_command.file_wrangler import add_to_path
+
+        export_line = add_to_path(path_variable="PYTHONPATH", directory=str(repo_root))
         command = export_line + "\n" + command
     if args.loop:
+        import platform
         if platform.system() in ["Linux", "Darwin"]:
             command = command + "\nsleep 0.5"
         elif platform.system() == "Windows":
             command = "$ErrorActionPreference = 'SilentlyContinue';\n" + command + "\nStart-Sleep -Seconds 0.5"
         else:
             raise NotImplementedError(f"Platform {platform.system()} not supported.")
-    from machineconfig.utils.code import run_shell_script
-    run_shell_script(command)
+    from machineconfig.utils.code import exit_then_run_shell_script
+    exit_then_run_shell_script(script=command, strict=False)
 
 
 def fire(
@@ -204,24 +204,29 @@ def fire(
     cmd: Annotated[bool, typer.Option("--cmd", "-B", help="Create a cmd fire command to launch the job asynchronously")] = False,
     interactive: Annotated[bool, typer.Option("--interactive", "-i", help="Whether to run the job interactively using IPython")] = False,
     debug: Annotated[bool, typer.Option("--debug", "-d", help="Enable debug mode")] = False,
-    choose_function: Annotated[bool, typer.Option("--choose_function", "-c", help="Choose function interactively")] = False,
+    choose_function: Annotated[bool, typer.Option("--choose-function", "-c", help="Choose function interactively")] = False,
     loop: Annotated[bool, typer.Option("--loop", "-l", help="Infinite recursion (runs again after completion/interruption)")] = False,
     jupyter: Annotated[bool, typer.Option("--jupyter", "-j", help="Open in a jupyter notebook")] = False,
-    submit_to_cloud: Annotated[bool, typer.Option("--submit_to_cloud", "-C", help="Submit to cloud compute")] = False,
-    remote: Annotated[bool, typer.Option("--remote", "-r", help="Launch on a remote machine")] = False,
+    marimo: Annotated[bool, typer.Option("--marimo", "-M", help="Open in a marimo notebook")] = False,
     module: Annotated[bool, typer.Option("--module", "-m", help="Launch the main file")] = False,
+    script: Annotated[bool, typer.Option("--script", "-s", help="Launch as a script without fire")] = False,
+    optimized: Annotated[bool, typer.Option("--optimized", "-O", help="Run the optimized version of the function")] = False,
+    zellij_tab: Annotated[Optional[str], typer.Option("--zellij-tab", "-z", help="Open in a new zellij tab")] = None,
+    submit_to_cloud: Annotated[bool, typer.Option("--submit-to-cloud", "-C", help="Submit to cloud compute")] = False,
+    remote: Annotated[bool, typer.Option("--remote", "-r", help="Launch on a remote machine")] = False,
     streamlit: Annotated[bool, typer.Option("--streamlit", "-S", help="Run as streamlit app")] = False,
     environment: Annotated[str, typer.Option("--environment", "-E", help="Choose ip, localhost, hostname or arbitrary url")] = "",
-    holdDirectory: Annotated[bool, typer.Option("--holdDirectory", "-D", help="Hold current directory and avoid cd'ing to the script directory")] = False,
+    holdDirectory: Annotated[
+        bool, typer.Option("--holdDirectory", "-D", help="Hold current directory and avoid cd'ing to the script directory")
+    ] = False,
     PathExport: Annotated[bool, typer.Option("--PathExport", "-P", help="Augment the PYTHONPATH with repo root")] = False,
-    git_pull: Annotated[bool, typer.Option("--git_pull", "-g", help="Start by pulling the git repo")] = False,
-    optimized: Annotated[bool, typer.Option("--optimized", "-O", help="Run the optimized version of the function")] = False,
-    zellij_tab: Annotated[Optional[str], typer.Option("--zellij_tab", "-z", help="Open in a new zellij tab")] = None,
+    git_pull: Annotated[bool, typer.Option("--git-pull", "-g", help="Start by pulling the git repo")] = False,
     watch: Annotated[bool, typer.Option("--watch", "-w", help="Watch the file for changes")] = False,
 ) -> None:
     """Main function to process fire jobs arguments."""
 
     # Get Fire arguments from context
+    from machineconfig.scripts.python.helpers_fire_command.fire_jobs_args_helper import FireJobArgs, parse_fire_args_from_context
     fire_args = parse_fire_args_from_context(ctx)
 
     args = FireJobArgs(
@@ -234,9 +239,11 @@ def fire(
         choose_function=choose_function,
         loop=loop,
         jupyter=jupyter,
+        marimo=marimo,
         submit_to_cloud=submit_to_cloud,
         remote=remote,
         module=module,
+        script=script,
         streamlit=streamlit,
         environment=environment,
         holdDirectory=holdDirectory,
@@ -261,14 +268,16 @@ def fire(
 
 def get_app():
     from typer import Typer
+
     app = Typer(add_completion=False)
     app.command(context_settings={"allow_extra_args": True, "allow_interspersed_args": False})(fire)
     return app
 
+
 def main():
     app = get_app()
     app()
 
 
 if __name__ == "__main__":
-    pass
+    from machineconfig.scripts.python.helpers_fire_command.fire_jobs_args_helper import FireJobArgs

machineconfig/scripts/python/ftpx.py

@@ -6,17 +6,7 @@ Currently, the only way to work around this is to predifine the host in ~/.ssh/c
 """
 
 import typer
-from typing_extensions import Annotated
-from rich.console import Console
-from rich.panel import Panel
-
-from machineconfig.utils.ssh import SSH
-from machineconfig.utils.path_extended import PathExtended
-from machineconfig.scripts.python.cloud_helpers.helpers2 import ES
-from machineconfig.utils.accessories import pprint
-
-
-console = Console()
+from typing import Annotated
 
 
 def ftpx(
@@ -25,7 +15,42 @@ def ftpx(
     recursive: Annotated[bool, typer.Option("--recursive", "-r", help="Send recursively.")] = False,
     zipFirst: Annotated[bool, typer.Option("--zipFirst", "-z", help="Zip before sending.")] = False,
     cloud: Annotated[bool, typer.Option("--cloud", "-c", help="Transfer through the cloud.")] = False,
+    overwrite_existing: Annotated[bool, typer.Option("--overwrite-existing", "-o", help="Overwrite existing files on remote when sending from local to remote.")] = False,
 ) -> None:
+    """File transfer utility though SSH."""
+    from pathlib import Path
+    if target == "wsl" or source == "wsl":
+        from machineconfig.utils.ssh_utils.wsl import copy_when_inside_windows
+        if target == "wsl":
+            target_obj = Path(source).expanduser().absolute().relative_to(Path.home())
+            source_obj = target_obj
+        else:
+            source_obj = Path(target).expanduser().absolute().relative_to(Path.home())
+            target_obj = source_obj
+        copy_when_inside_windows(source_obj, target_obj, overwrite_existing)
+        return
+    elif source == "win" or target == "win":
+        if source == "win":
+            source_obj = Path(target).expanduser().absolute().relative_to(Path.home())
+            target_obj = source_obj
+        else:
+            target_obj = Path(source).expanduser().absolute().relative_to(Path.home())
+            source_obj = target_obj
+        from machineconfig.utils.ssh_utils.wsl import copy_when_inside_wsl
+        copy_when_inside_wsl(source_obj, target_obj, overwrite_existing)
+        return
+
+    from rich.console import Console
+    from rich.panel import Panel
+
+    from machineconfig.utils.ssh import SSH
+    from machineconfig.utils.path_extended import PathExtended
+    from machineconfig.scripts.python.helpers_cloud.helpers2 import ES
+    from machineconfig.utils.accessories import pprint
+
+
+    console = Console()
+
     console.print(
         Panel(
             "\n".join(
@@ -133,7 +158,7 @@ def ftpx(
                 border_style="cyan",
             )
         )
-        ssh.run_shell(command=f"cloud_copy {resolved_source} :^", verbose_output=True, description="Uploading from remote to the cloud.", strict_stderr=False, strict_return_code=False)
+        ssh.run_shell_cmd_on_remote(command=f"cloud_copy {resolved_source} :^", verbose_output=True, description="Uploading from remote to the cloud.", strict_stderr=False, strict_return_code=False)
         console.print(
             Panel.fit(
                 "⬇️  Cloud transfer mode — downloading from cloud to local...",
@@ -141,12 +166,14 @@ def ftpx(
                 border_style="cyan",
             )
         )
-        ssh.run_locally(command=f"cloud_copy :^ {resolved_target}")
+        ssh.run_shell_cmd_on_local(command=f"cloud_copy :^ {resolved_target}")
         received_file = PathExtended(resolved_target)  # type: ignore
     else:
         if source_is_remote:
-            assert resolved_source is not None, """
-❌ Path Error: Source must be a remote path (machine:path)"""
+            if resolved_source is None:
+                typer.echo("""❌ Path Error: Source must be a remote path (machine:path)""")
+                typer.Exit(code=1)
+                return                
             target_display = resolved_target or "<auto>"
             console.print(
                 Panel(
@@ -183,7 +210,7 @@ def ftpx(
                     padding=(1, 2),
                 )
             )
-            received_file = ssh.copy_from_here(source_path=resolved_source, target_path=resolved_target, compress_with_zip=zipFirst, recursive=recursive, overwrite_existing=False)
+            received_file = ssh.copy_from_here(source_path=resolved_source, target_rel2home=resolved_target, compress_with_zip=zipFirst, recursive=recursive, overwrite_existing=overwrite_existing)
 
     if source_is_remote and isinstance(received_file, PathExtended):
         console.print(
@@ -213,7 +240,7 @@ def ftpx(
 def main() -> None:
     """Entry point function that uses typer to parse arguments and call main."""
     app = typer.Typer()
-    app.command(no_args_is_help=True, help="File transfer utility though SSH.")(ftpx)
+    app.command(no_args_is_help=True, help=ftpx.__doc__, short_help="File transfer utility though SSH.")(ftpx)
     app()
 
 

machineconfig/scripts/python/helpers/ast_search.py

@@ -0,0 +1,74 @@
+
+import ast
+import os
+from typing import TypedDict
+
+
+class SymbolInfo(TypedDict):
+    """Represents a symbol (module, class, or function) in the repository."""
+    type: str
+    name: str
+    path: str
+    # line: int | None
+    # column: int | None
+    docstring: str
+
+
+def _get_docstring(node: ast.AsyncFunctionDef | ast.FunctionDef | ast.ClassDef | ast.Module) -> str:
+    """Extract docstring from an AST node."""
+    return ast.get_docstring(node) or ""
+
+
+def _extract_symbols(tree: ast.AST, module_path: str, source: str) -> list[SymbolInfo]:
+    """Extract symbols from an AST tree."""
+    symbols: list[SymbolInfo] = []
+    
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            symbol: SymbolInfo = {
+                "type": "function",
+                "name": node.name,
+                "path": f"{module_path}.{node.name}",
+                "docstring": _get_docstring(node),
+            }
+            symbols.append(symbol)
+        elif isinstance(node, ast.ClassDef):
+            symbol: SymbolInfo = {
+                "type": "class",
+                "name": node.name,
+                "path": f"{module_path}.{node.name}",
+                "docstring": _get_docstring(node),
+            }
+            symbols.append(symbol)
+    
+    return symbols
+
+
+def get_repo_symbols(repo_path: str) -> list[SymbolInfo]:
+    skip_dirs = {'.venv', 'venv', '__pycache__', '.mypy_cache', '.pytest_cache', '.git'}
+    results: list[SymbolInfo] = []
+    counter: int = 0
+    for root, dirs, files in os.walk(repo_path):
+        dirs[:] = [d for d in dirs if d not in skip_dirs and not d.startswith('.')]
+        for file in files:
+            if not file.endswith(".py"):
+                continue
+            file_path = os.path.join(root, file)
+            module_path = (
+                os.path.relpath(file_path, repo_path)
+                .replace(os.sep, ".")
+                .removesuffix(".py")
+            )
+            try:
+                if counter % 100 == 0: print(f"🔍 Parsing {counter}: {file_path}...")
+                with open(file_path, encoding="utf-8") as f:
+                    source = f.read()
+                tree = ast.parse(source, filename=file_path)
+                symbols = _extract_symbols(tree, module_path, source)
+                results.extend(symbols)
+            except Exception as e:
+                print(f"⚠️ Error parsing {file_path}: {e}")
+                continue
+            counter += 1
+
+    return results