machineconfig 6.82__py3-none-any.whl → 8.51__py3-none-any.whl

machineconfig/scripts/python/{helpers_repos/count_lines.py → helpers/helpers_repos/repo_analyzer_2.py}

@@ -1,190 +1,23 @@
-
-from typing import TYPE_CHECKING, Annotated
 from git import Repo
-from collections import defaultdict
+from machineconfig.scripts.python.helpers.helpers_repos.repo_analyzer_1 import count_python_lines, get_default_branch
 from datetime import datetime
-
+import polars as pl
 from pathlib import Path
-from rich.progress import track
-import typer
-
-
-if TYPE_CHECKING:
-    from typing import Any, Dict, List, Optional, Union
-    import polars as pl
-
-
-app = typer.Typer()
-
-
-def count_lines_in_commit(commit: "Any") -> int:
-    _total_lines = 0
-    for _file in commit.stats.files:
-        if str(_file).endswith(".py"):
-            _blob = commit.tree / _file
-            _total_lines += len(_blob.data_stream.read().decode("utf-8").splitlines())
-    return _total_lines
-
-
-def count_historical_loc(repo_path: str) -> int:
-    repo = Repo(repo_path)
-    file_line_counts: "Dict[str, int]" = defaultdict(int)
-    total_commits: int = sum(1 for _ in repo.iter_commits())
-    print(f"Total commits to process: {total_commits}")
-    for i, commit in enumerate(repo.iter_commits(), 1):
-        if i % 100 == 0 or i == total_commits:
-            print(f"Processing commit {i}/{total_commits} ({i / total_commits:.1%})")
-        try:
-            # Handle initial commits that have no parents
-            if not commit.parents:
-                # For initial commit, count all lines in Python files
-                for file in commit.stats.files:
-                    if str(file).endswith(".py"):
-                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
-            else:
-                # For commits with parents, use stats
-                for file in commit.stats.files:
-                    if str(file).endswith(".py"):
-                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
-        except Exception:
-            # If stats fail (e.g., corrupted parent), skip this commit
-            print(f"Warning: Could not get stats for commit {commit.hexsha[:8]}, skipping")
-            continue
-
-    print(f"\nProcessed files: {len(file_line_counts)}")
-    return sum(file_line_counts.values())
-
-def count_python_lines(commit: "Any") -> int:
-    """Count total lines in Python files for a specific commit"""
-    total_lines = 0
-    try:
-        for blob in commit.tree.traverse():
-            if blob.path.endswith(".py"):
-                try:
-                    content = blob.data_stream.read().decode("utf-8")
-                    total_lines += len(content.splitlines())
-                except Exception as _e:
-                    continue
-    except Exception as _e:
-        return 0
-    return total_lines
-def get_default_branch(repo: Repo) -> str:
-    """Get the default branch name of the repository"""
-    try:
-        _ = repo.refs["main"]
-        return "main"  # First try 'main'
-    except IndexError:
-        try:
-            _ = repo.refs["master"]
-            return "master"  # Then try 'master'
-        except IndexError:
-            return repo.head.reference.name  # If neither exists, get the branch the HEAD is pointing to
-
-
-@app.command()
-def count_historical(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Count total historical lines of Python code in the repository."""
-    print(f"Analyzing repository: {repo_path}")
-    total_loc: int = count_historical_loc(repo_path)
-    print(f"\nTotal historical lines of Python code: {total_loc}")
-
-
-@app.command()
-def analyze_over_time(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Analyze a git repository to track Python code size over time with visualization."""
-    repo: Repo = Repo(repo_path)
-    branch_name: str = get_default_branch(repo)
-    print(f"🔍 Using branch: {branch_name}")
-    commit_data: "List[Dict[str, Any]]" = []
-    print("⏳ Analyzing commits...")
-    try:
-        commits = list(repo.iter_commits(branch_name))
-        from datetime import timezone
-
-        for commit in track(commits, description="Processing commits..."):
-            commit_data.append({"hash": commit.hexsha, "dtmExit": datetime.fromtimestamp(commit.committed_date, tz=timezone.utc), "lines": count_python_lines(commit)})
-    except Exception as e:
-        print(f"❌ Error analyzing commits: {str(e)}")
-        return
-
-    import polars as pl
-    import plotly.graph_objects as go
-
-    df = pl.DataFrame(commit_data)
-    df = df.sort("dtmExit")
-    # Create interactive plotly figure with dark theme and all bells and whistles
-    fig = go.Figure()
-    # Add line chart with gradient fill and sparkle effect
-    fig.add_trace(go.Scatter(x=df["dtmExit"], y=df["lines"], mode="lines", line={"width": 3, "color": "#00b4ff"}, fill="tozeroy", fillcolor="rgba(0, 180, 255, 0.2)", name="Lines of Code", hovertemplate="<b>Date:</b> %{x}<br><b>Lines:</b> %{y:,}<extra></extra>"))
-    # Add markers for significant points (min, max, last)
-    min_idx = df["lines"].arg_min()
-    max_idx = df["lines"].arg_max()
-    min_point = df.slice(min_idx, 1).to_dicts()[0] if min_idx is not None else {}
-    max_point = df.slice(max_idx, 1).to_dicts()[0] if max_idx is not None else {}
-    last_point = df.slice(-1, 1).to_dicts()[0]
-
-    # Add markers for significant points
-    fig.add_trace(
-        go.Scatter(
-            x=[min_point["dtmExit"], max_point["dtmExit"], last_point["dtmExit"]],
-            y=[min_point["lines"], max_point["lines"], last_point["lines"]],
-            mode="markers",
-            marker={"size": [10, 14, 12], "color": ["#ff4f4f", "#4fff4f", "#4f4fff"], "line": {"width": 2, "color": "white"}, "symbol": ["circle", "star", "diamond"]},
-            name="Key Points",
-            hovertemplate="<b>%{text}</b><br>Date: %{x}<br>Lines: %{y:,}<extra></extra>",
-            text=[f"🔽 Min: {min_point['lines']:,} lines", f"🔼 Max: {max_point['lines']:,} lines", f"📊 Current: {last_point['lines']:,} lines"],
-        )
-    )
+from typing import cast, TypedDict
 
-    # Add annotation only for current point
-    # annotations = [
-    #     {"x": last_point['date'], "y": last_point['lines'], "text": f"📊 Current: {last_point['lines']:,} lines", "showarrow": True, "arrowhead": 2, "arrowsize": 1,
-    #         "arrowwidth": 2, "arrowcolor": "#ffffff", "font": {"size": 14, "color": "#ffffff"}, "bgcolor": "#00b4ff", "bordercolor": "#ffffff",
-    #         "borderwidth": 1, "borderpad": 4, "ax": 40, "ay": -40}
-    # ]
 
-    # Update layout with dark theme and customizations
-    fig.update_layout(
-        title={"text": "✨ Python Code Base Size Over Time ✨", "y": 0.95, "x": 0.5, "xanchor": "center", "yanchor": "top", "font": {"size": 24, "color": "white"}},
-        xaxis_title="Date 📅",
-        yaxis_title="Lines of Code 📝",
-        hovermode="closest",
-        template="plotly_dark",
-        plot_bgcolor="rgba(25, 25, 35, 1)",
-        paper_bgcolor="rgba(15, 15, 25, 1)",
-        font={"family": "Arial, sans-serif", "size": 14, "color": "white"},  # annotations=annotations,
-        autosize=True,
-        height=700,
-        margin={"l": 80, "r": 80, "t": 100, "b": 80},
-        xaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickfont": {"size": 12}},
-        yaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickformat": ",", "tickfont": {"size": 12}},
-    )
-
-    # Add range slider for date selection
-    fig.update_xaxes(rangeslider_visible=True, rangeslider_thickness=0.05)
-
-    # Save as interactive HTML and static image
-    plot_dir = Path.home().joinpath("tmp_results", "tmp_images", Path(repo_path).name)
-    plot_dir.mkdir(parents=True, exist_ok=True)
+class FileDataRow(TypedDict):
+    filename: str
+    lines: int
 
-    html_path = plot_dir.joinpath("code_size_evolution.html")
-    png_path = plot_dir.joinpath("code_size_evolution.png")
 
-    fig.write_html(html_path, include_plotlyjs="cdn")
-    fig.write_image(png_path, width=1200, height=700, scale=2)
-
-    print(f"🖼️ Interactive plot saved as {html_path}")
-    print(f"🖼️ Static image saved as {png_path}")
-    # Print statistics
-    print("\n📊 Repository Statistics:")
-    print(f"📚 Total commits analyzed: {len(df)}")
-    print(f"🔙 Initial line count: {df['lines'][-1]:,}")
-    print(f"🔜 Final line count: {df['lines'][0]:,}")
-    print(f"📈 Net change: {df['lines'][0] - df['lines'][-1]:,} lines")
+class CommitDataRow(TypedDict):
+    hash: str
+    dtmExit: datetime
+    lines: int
 
 
-def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exception]":
-    import polars as pl
+def print_python_files_by_size_impl(repo_path: str) -> pl.DataFrame | Exception:
     import plotly.graph_objects as go
     import plotly.express as px
 
@@ -193,7 +26,7 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         if not os.path.exists(repo_path):
             return ValueError(f"Repository path does not exist: {repo_path}")
         # Initialize data storage
-        file_data: "List[Dict[str, Union[str, int]]]" = []
+        file_data: list[FileDataRow] = []
 
         # Walk through the repository
         for root, _, files in os.walk(repo_path):
@@ -227,13 +60,26 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         df = df.sort("lines", descending=True)
         df = df.filter(pl.col("lines") > 0)  # Filter out empty files
 
+        from rich.console import Console
+        from rich.table import Table
+
         # Add total count
         total_lines = int(df["lines"].sum())
         file_count: int = len(df)
-
+        console = Console()
         # Print the DataFrame
-        print("\n📊 Python Files Line Count (sorted max to min):")
-        print(df)
+        console.print("\n📊 Python Files Line Count (sorted max to min):")
+
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("#", justify="right")
+        table.add_column("File", overflow="fold")
+        table.add_column("Lines", justify="right")
+
+        for idx, row in enumerate(df.iter_rows(named=True), 1):
+            typed_row = cast(FileDataRow, row)
+            table.add_row(str(idx), typed_row["filename"], f"{typed_row['lines']:,}")
+
+        console.print(table)
         print(f"\n📁 Total Python files: {file_count}")
         print(f"📝 Total lines of Python code: {total_lines:,}")
 
@@ -283,7 +129,7 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         )
 
         # Define pie chart figure before conditionally using it
-        fig2: "Optional[go.Figure]" = None
+        fig2: go.Figure | None = None
 
         # Add pie chart showing distribution
         if len(df) > top_n:
@@ -335,14 +181,133 @@ def _print_python_files_by_size_impl(repo_path: str) -> "Union[pl.DataFrame, Exc
         return Exception(f"❌ Error analyzing repository: {str(e)}")
 
 
-@app.command()
-def print_python_files_by_size(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
-    """Print Python files sorted by size with visualizations."""
-    result = _print_python_files_by_size_impl(repo_path)
-    if isinstance(result, Exception):
-        print(f"Error: {result}")
+def analyze_over_time(repo_path: str):
+    """Analyze a git repository to track Python code size over time with visualization."""
+    repo: Repo = Repo(repo_path)
+    branch_name: str = get_default_branch(repo)
+    print(f"🔍 Using branch: {branch_name}")
+    commit_data: list[CommitDataRow] = []
+    print("⏳ Analyzing commits...")
+    try:
+        commits = list(repo.iter_commits(branch_name))
+        from datetime import timezone
+        from rich.progress import track
+        for commit in track(commits, description="Processing commits..."):
+            lines, _files = count_python_lines(commit)
+            commit_data.append({"hash": commit.hexsha, "dtmExit": datetime.fromtimestamp(commit.committed_date, tz=timezone.utc), "lines": lines})
+    except Exception as e:
+        print(f"❌ Error analyzing commits: {str(e)}")
         return
 
+    import polars as pl
+    import plotly.graph_objects as go
 
-if __name__ == "__main__":
-    app()
+    df = pl.DataFrame(commit_data)
+    df = df.sort("dtmExit")
+    # Create interactive plotly figure with dark theme and all bells and whistles
+    fig = go.Figure()
+    # Add line chart with gradient fill and sparkle effect
+    fig.add_trace(go.Scatter(x=df["dtmExit"], y=df["lines"], mode="lines", line={"width": 3, "color": "#00b4ff"}, fill="tozeroy", fillcolor="rgba(0, 180, 255, 0.2)", name="Lines of Code", hovertemplate="<b>Date:</b> %{x}<br><b>Lines:</b> %{y:,}<extra></extra>"))
+    # Add markers for significant points (min, max, last)
+    min_idx = df["lines"].arg_min()
+    max_idx = df["lines"].arg_max()
+    last_point = cast(CommitDataRow, df.slice(-1, 1).to_dicts()[0])
+    
+    marker_x: list[datetime] = []
+    marker_y: list[int] = []
+    marker_sizes: list[int] = []
+    marker_colors: list[str] = []
+    marker_symbols: list[str] = []
+    marker_texts: list[str] = []
+    
+    if min_idx is not None:
+        min_point = cast(CommitDataRow, df.slice(min_idx, 1).to_dicts()[0])
+        marker_x.append(min_point["dtmExit"])
+        marker_y.append(min_point["lines"])
+        marker_sizes.append(10)
+        marker_colors.append("#ff4f4f")
+        marker_symbols.append("circle")
+        marker_texts.append(f"🔽 Min: {min_point['lines']:,} lines")
+    
+    if max_idx is not None:
+        max_point = cast(CommitDataRow, df.slice(max_idx, 1).to_dicts()[0])
+        marker_x.append(max_point["dtmExit"])
+        marker_y.append(max_point["lines"])
+        marker_sizes.append(14)
+        marker_colors.append("#4fff4f")
+        marker_symbols.append("star")
+        marker_texts.append(f"🔼 Max: {max_point['lines']:,} lines")
+    
+    marker_x.append(last_point["dtmExit"])
+    marker_y.append(last_point["lines"])
+    marker_sizes.append(12)
+    marker_colors.append("#4f4fff")
+    marker_symbols.append("diamond")
+    marker_texts.append(f"📊 Current: {last_point['lines']:,} lines")
+
+    # Add markers for significant points
+    fig.add_trace(
+        go.Scatter(
+            x=marker_x,
+            y=marker_y,
+            mode="markers",
+            marker={"size": marker_sizes, "color": marker_colors, "line": {"width": 2, "color": "white"}, "symbol": marker_symbols},
+            name="Key Points",
+            hovertemplate="<b>%{text}</b><br>Date: %{x}<br>Lines: %{y:,}<extra></extra>",
+            text=marker_texts,
+        )
+    )
+
+    # Add annotation only for current point
+    # annotations = [
+    #     {"x": last_point['date'], "y": last_point['lines'], "text": f"📊 Current: {last_point['lines']:,} lines", "showarrow": True, "arrowhead": 2, "arrowsize": 1,
+    #         "arrowwidth": 2, "arrowcolor": "#ffffff", "font": {"size": 14, "color": "#ffffff"}, "bgcolor": "#00b4ff", "bordercolor": "#ffffff",
+    #         "borderwidth": 1, "borderpad": 4, "ax": 40, "ay": -40}
+    # ]
+
+    # Update layout with dark theme and customizations
+    fig.update_layout(
+        title={"text": "✨ Python Code Base Size Over Time ✨", "y": 0.95, "x": 0.5, "xanchor": "center", "yanchor": "top", "font": {"size": 24, "color": "white"}},
+        xaxis_title="Date 📅",
+        yaxis_title="Lines of Code 📝",
+        hovermode="closest",
+        template="plotly_dark",
+        plot_bgcolor="rgba(25, 25, 35, 1)",
+        paper_bgcolor="rgba(15, 15, 25, 1)",
+        font={"family": "Arial, sans-serif", "size": 14, "color": "white"},  # annotations=annotations,
+        autosize=True,
+        height=700,
+        margin={"l": 80, "r": 80, "t": 100, "b": 80},
+        xaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickfont": {"size": 12}},
+        yaxis={"showgrid": True, "gridcolor": "rgba(80, 80, 100, 0.2)", "showline": True, "linecolor": "rgba(200, 200, 255, 0.2)", "tickformat": ",", "tickfont": {"size": 12}},
+    )
+
+    # Add range slider for date selection
+    fig.update_xaxes(rangeslider_visible=True, rangeslider_thickness=0.05)
+
+    # Save as interactive HTML and static image
+    plot_dir = Path.home().joinpath("tmp_results", "tmp_images", Path(repo_path).name)
+    plot_dir.mkdir(parents=True, exist_ok=True)
+
+    html_path = plot_dir.joinpath("code_size_evolution.html")
+    png_path = plot_dir.joinpath("code_size_evolution.png")
+
+    try:
+        fig.write_html(html_path, include_plotlyjs="cdn")
+    except Exception as e:
+        print(f"❌ Error saving HTML plot: {str(e)}")
+    try:
+        fig.write_image(png_path, width=1200, height=700, scale=2)
+    except Exception as e:
+        print(f"❌ Error saving PNG plot: {str(e)}")
+
+    print(f"🖼️ Interactive plot saved as {html_path}")
+    print(f"🖼️ Static image saved as {png_path}")
+    # Print statistics
+    print("\n📊 Repository Statistics:")
+    print(f"📚 Total commits analyzed: {len(df)}")
+    initial_lines = int(df['lines'][-1])
+    final_lines = int(df['lines'][0])
+    print(f"🔙 Initial line count: {initial_lines:,}")
+    print(f"🔜 Final line count: {final_lines:,}")
+    print(f"📈 Net change: {final_lines - initial_lines:,} lines")

machineconfig/scripts/python/{helpers_repos → helpers/helpers_repos}/update.py

@@ -246,12 +246,6 @@ def update_repository(repo: git.Repo, auto_uv_sync: bool, allow_password_prompt:
                 result["permissions_updated"] = True
                 print(f"✅ Set permissions for {linux_jobs_path}")
 
-            lf_exe_path = repo_path / "src" / "machineconfig" / "settings" / "lf" / "linux" / "exe"
-            if lf_exe_path.exists():
-                set_permissions_recursive(lf_exe_path)
-                result["permissions_updated"] = True
-                print(f"✅ Set permissions for {lf_exe_path}")
-
         # Run uv sync if dependencies changed and auto_sync is enabled
         if result["dependencies_changed"] and auto_uv_sync:
             result["uv_sync_ran"] = True

machineconfig/scripts/python/helpers/helpers_search/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/helpers_search/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