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

machineconfig/scripts/python/fire_jobs.py

@@ -7,39 +7,20 @@ fire
 
 """
 
-from machineconfig.utils.ve import 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_command.file_wrangler 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}")
     if args.marimo:
         print(f"🧽 Preparing to launch Marimo notebook for `{choice_file}`...")
-        tmp_dir = PathExtended.tmp().joinpath(f"tmp_scripts/marimo/{choice_file.stem}_{randstr()}")
+        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}
@@ -53,7 +34,7 @@ uv run --project {repo_root} --with marimo marimo edit --host 0.0.0.0 marimo_nb.
 
     # =========================  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
     else:
         kwargs_dict = {}
@@ -62,70 +43,108 @@ uv run --project {repo_root} --with marimo marimo edit --host 0.0.0.0 marimo_nb.
     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
+        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:
-            exe = get_command_streamlit(choice_file=choice_file, environment=args.environment, repo_root=repo_root)
-            exe = f"uv run {with_project} {exe} "
-        elif args.jupyter: exe = f"uv run {with_project} jupyter-lab"
+            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:
+            choice_file_adjusted = ".".join(Path(choice_file).relative_to(repo_root).parts).replace(".py", "")
         else:
-            if args.interactive:
-                _ve_root_from_file, ipy_profile = get_ve_path_and_ipython_profile(choice_file)
-                if ipy_profile is None:
-                    ipy_profile = "default"
-                exe = f"uv run {with_project} ipython -i --no-banner --profile {ipy_profile} "
-            else:
-                exe = f"uv run {with_project} python "
-    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.
+            choice_file_adjusted = ".".join(Path(choice_file).relative_to(Path.cwd()).parts).replace(".py", "")
+    else:
+        choice_file_adjusted = str(choice_file)
+
+    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)
-        code_printing = lambda_to_python_script(lambda: print_code(code=import_code_robust, lexer="python", desc="import code"), in_global=True, import_module=False)
-        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."""
+        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,
+        )
+        # 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(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} "
+        command = f"{exe_line} {choice_file_adjusted} "
     elif choice_function is not None and choice_file.suffix == ".py":
-        command = f"{exe} -m fire {choice_file} {choice_function} {fire_args}"
+        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: pass
+    if not args.cmd:
+        pass
     else:
         new_line = "\n"
         command = rf"""start cmd -Argument "/k {command.replace(new_line, " & ")} " """  # this works from powershell
@@ -134,23 +153,27 @@ uv run --project {repo_root} --with marimo marimo edit --host 0.0.0.0 marimo_nb.
         if choice_function is not None:
             command += f"--function {choice_function} "
 
-    if args.optimized: command = command.replace("python ", "python -OO ")
+    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
@@ -158,16 +181,17 @@ uv run --project {repo_root} --with marimo marimo edit --host 0.0.0.0 marimo_nb.
         command = f"\ngit -C {choice_file.parent} pull\n" + command
     if args.PathExport:
         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 exit_then_run_shell_script
     exit_then_run_shell_script(script=command, strict=False)
 
@@ -185,23 +209,24 @@ def fire(
     jupyter: Annotated[bool, typer.Option("--jupyter", "-j", help="Open in a jupyter notebook")] = 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,
     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(
@@ -218,6 +243,7 @@ def fire(
         submit_to_cloud=submit_to_cloud,
         remote=remote,
         module=module,
+        script=script,
         streamlit=streamlit,
         environment=environment,
         holdDirectory=holdDirectory,
@@ -235,12 +261,14 @@ def fire(
     except Exception as e:
         # For other exceptions, print clean error message and exit
         import sys
+
         print(f"❌ Error: {e}", file=sys.stderr)
         sys.exit(1)
 
 
 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
@@ -252,4 +280,4 @@ def main():
 
 
 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.helpers_cloud.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_rel2home=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

machineconfig/scripts/python/helpers/qr_code.py

@@ -0,0 +1,166 @@
+
+
+from typing import Literal
+
+
+def generate_qrcode_grid(
+    strings: list[str],
+    output_path: str,
+    per_row: int = 3,
+    qr_size: int = 200,
+    label_height: int = 30,
+    padding: int = 20,
+    label_max_chars: int = 25,
+    format: Literal["svg", "png"] = "svg",
+) -> str:
+    from pathlib import Path
+    if not strings:
+        raise ValueError("strings list cannot be empty")
+
+    output_path_obj = Path(output_path)
+    output_path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+    if format == "svg":
+        return _generate_svg(strings, output_path, per_row, qr_size, label_height, padding, label_max_chars)
+    elif format == "png":
+        return _generate_png(strings, output_path, per_row, qr_size, label_height, padding, label_max_chars)
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+
+
+def _generate_svg(
+    strings: list[str],
+    output_path: str,
+    per_row: int,
+    qr_size: int,
+    label_height: int,
+    padding: int,
+    label_max_chars: int,
+) -> str:
+    num_items = len(strings)
+    num_rows = (num_items + per_row - 1) // per_row
+
+    cell_width = qr_size
+    cell_height = qr_size + label_height
+    total_width = per_row * cell_width + (per_row + 1) * padding
+    total_height = num_rows * cell_height + (num_rows + 1) * padding
+
+    from xml.etree import ElementTree as ET
+
+    import qrcode
+    svg_root = ET.Element(
+        "svg",
+        xmlns="http://www.w3.org/2000/svg",
+        width=str(total_width),
+        height=str(total_height),
+        viewBox=f"0 0 {total_width} {total_height}",
+    )
+
+    _bg_rect = ET.SubElement(svg_root, "rect", width=str(total_width), height=str(total_height), fill="white")
+
+    for idx, text in enumerate(strings):
+        row = idx // per_row
+        col = idx % per_row
+
+        x_offset = padding + col * (cell_width + padding)
+        y_offset = padding + row * (cell_height + padding)
+
+        qr = qrcode.QRCode(version=1, error_correction=qrcode.ERROR_CORRECT_L, box_size=10, border=2, image_factory=qrcode.image.svg.SvgPathImage)  # type: ignore
+        qr.add_data(text)
+        qr.make(fit=True)
+
+        qr_img = qr.make_image()
+        qr_svg_string = qr_img.to_string(encoding="unicode")
+
+        qr_tree = ET.fromstring(qr_svg_string)
+
+        group = ET.SubElement(svg_root, "g", transform=f"translate({x_offset}, {y_offset})")
+
+        qr_group = ET.SubElement(group, "g")
+        for child in qr_tree:
+            qr_group.append(child)
+
+        label_text = text[:label_max_chars] if len(text) > label_max_chars else text
+        text_y = qr_size + label_height // 2
+
+        text_elem = ET.SubElement(
+            group,
+            "text",
+            x=str(qr_size // 2),
+            y=str(text_y),
+            fill="black",
+            attrib={
+                "font-family": "monospace",
+                "font-size": "12",
+                "text-anchor": "middle",
+                "dominant-baseline": "middle",
+            },
+        )
+        text_elem.text = label_text
+
+    tree = ET.ElementTree(svg_root)
+    ET.indent(tree, space="  ")
+    tree.write(output_path, encoding="unicode", xml_declaration=True)
+
+    return output_path
+
+
+def _generate_png(
+    strings: list[str],
+    output_path: str,
+    per_row: int,
+    qr_size: int,
+    label_height: int,
+    padding: int,
+    label_max_chars: int,
+) -> str:
+    num_items = len(strings)
+    num_rows = (num_items + per_row - 1) // per_row
+
+    cell_width = qr_size
+    cell_height = qr_size + label_height
+    total_width = per_row * cell_width + (per_row + 1) * padding
+    total_height = num_rows * cell_height + (num_rows + 1) * padding
+
+    import qrcode
+    import qrcode.image.pil
+    from PIL import Image, ImageDraw, ImageFont
+    img = Image.new("RGB", (total_width, total_height), color="white")
+    draw = ImageDraw.Draw(img)
+
+    try:
+        font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", 12)
+    except OSError:
+        try:
+            font = ImageFont.truetype("arial.ttf", 12)
+        except OSError:
+            font = ImageFont.load_default()
+
+    for idx, text in enumerate(strings):
+        row = idx // per_row
+        col = idx % per_row
+
+        x_offset = padding + col * (cell_width + padding)
+        y_offset = padding + row * (cell_height + padding)
+
+        qr = qrcode.QRCode(version=1, error_correction=qrcode.ERROR_CORRECT_L, box_size=10, border=2, image_factory=qrcode.image.pil.PilImage)
+        qr.add_data(text)
+        qr.make(fit=True)
+
+        qr_img = qr.make_image(fill_color="black", back_color="white")
+        qr_img_resized = qr_img.resize((qr_size, qr_size), Image.Resampling.LANCZOS)
+
+        img.paste(qr_img_resized, (x_offset, y_offset))
+
+        label_text = text[:label_max_chars] if len(text) > label_max_chars else text
+
+        bbox = draw.textbbox((0, 0), label_text, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_x = x_offset + (qr_size - text_width) // 2
+        text_y = y_offset + qr_size + label_height // 2 - 6
+
+        draw.text((text_x, text_y), label_text, fill="black", font=font)
+
+    img.save(output_path, format="PNG")
+
+    return output_path