maxson-build-utils 0.1.1__tar.gz

maxson_build_utils-0.1.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: maxson-build-utils
+Version: 0.1.1
+Summary: Common tools for deploying packages to EXE, MSIX, DMG, DEB, PYZ, flatpak, and more. Templated approach to mkdocs.
+Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
+Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/maxson-build-utils
+Project-URL: Repository, https://github.com/city-of-memphis-wastewater/maxson-build-utils
+Project-URL: Issues, https://github.com/city-of-memphis-wastewater/maxson-build-utils/issues
+Project-URL: Changelog, https://raw.githubusercontent.com/city-of-memphis-wastewater/maxson-build-utils/main/docs/CHANGELOG.md
+Keywords: build-tools,build
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyhabitat>=1.3.9
+Requires-Dist: typer>=0.27.0
+Requires-Dist: typer-helptree>=0.2.12
+
+# maxson-build-utils
+
+Centralized org tooling for PyInstaller, DMG, AppImage, DEB, PYZ, etc.

maxson_build_utils-0.1.1/README.md

@@ -0,0 +1,3 @@
+# maxson-build-utils
+
+Centralized org tooling for PyInstaller, DMG, AppImage, DEB, PYZ, etc.

maxson_build_utils-0.1.1/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "maxson-build-utils"
+dynamic = ["version"]
+description = "Common tools for deploying packages to EXE, MSIX, DMG, DEB, PYZ, flatpak, and more. Templated approach to mkdocs."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pyhabitat>=1.3.9",
+    "typer>=0.27.0",
+    "typer-helptree>=0.2.12",
+]
+license = "MIT"
+authors = [
+    { name = "George Clayton Bennett", email = "george.bennett@memphistn.gov" }
+]
+maintainers = [
+    { name = "George Clayton Bennett", email = "george.bennett@memphistn.gov" }
+]
+
+classifiers=[
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers", # library and documentation
+    #"Intended Audience :: Other Audience", # Government/engineering docs
+    #"Topic :: Scientific/Engineering :: Information Analysis",
+    #"Environment :: Console",
+    #"Environment :: MacOS X",
+    #"Environment :: Win32 (MS Windows)",
+    "Typing :: Typed",
+    "Development Status :: 3 - Alpha",
+    #"Development Status :: 4 - Beta",
+    #"Development Status :: 5 - Production/Stable",
+]
+
+keywords = [
+    "build-tools",
+    "build",
+]
+
+[project.scripts]
+maxson-build-utils = "maxson_build_utils.__main__:main"
+
+#[project.optional-dependencies]
+
+# add with `uv sync --group dev`, plus other extras, like `--extra pdfium`
+[dependency-groups]
+dev = [
+    "build>=1.3.0",
+    "pyinstaller>=6.17.0 ; platform_system == 'Linux' and platform_machine != 'aarch64'", # to avoid on termux
+    "shiv>=1.0.8",
+    "ruff>=0.7.0 ; platform_system == 'Linux' and platform_machine != 'aarch64'", # to avoid on termux
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/city-of-memphis-wastewater/maxson-build-utils"
+Repository = "https://github.com/city-of-memphis-wastewater/maxson-build-utils"
+Issues = "https://github.com/city-of-memphis-wastewater/maxson-build-utils/issues"
+Changelog = "https://raw.githubusercontent.com/city-of-memphis-wastewater/maxson-build-utils/main/docs/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.uv.sources]
+maxson-build-utils = { path = "src/maxson_build_utils" }
+#pyhabitat = { path = "../pyhabitat/dist/pyhabitat-1.2.3-py3-none-any.whl" }
+
+[tool.setuptools.dynamic]
+version = {file = "src/maxson_build_utils/VERSION"}

maxson_build_utils-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maxson_build_utils-0.1.1/src/maxson_build_utils/VERSION

@@ -0,0 +1,2 @@
+0.1.1
+

maxson_build_utils-0.1.1/src/maxson_build_utils/__init__.py

@@ -0,0 +1,5 @@
+# maxson_build_utils/src/maxson_build_utils/__init__.py
+from maxson_build_utils.build_executable import run_build_executable
+from maxson_build_utils.build_pyz import run_build_pyz
+
+__all__ = ["run_build_executable", "run_build_pyz"]

maxson_build_utils-0.1.1/src/maxson_build_utils/__main__.py

@@ -0,0 +1,6 @@
+# src/maxson_build_utils/__main__.py
+from __future__ import annotations
+from maxson_build_utils.cli import main
+
+if __name__ == "__main__":
+    main()

maxson_build_utils-0.1.1/src/maxson_build_utils/_version.py

@@ -0,0 +1,22 @@
+# src/maxson_build_utils/_version.py
+from pathlib import Path
+from .context import APP_NAME
+def get_version() -> str:
+    try:
+        version_file = Path(__file__).parent / "VERSION"
+        if version_file.exists():
+            return version_file.read_text(encoding="utf-8").strip()
+    except Exception:
+        pass
+
+    # Try metadata (Installed)
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+        return version(APP_NAME)
+    except (ImportError, PackageNotFoundError):
+        pass
+
+
+    return "0.0.0-unknown"
+
+__version__ = get_version()

maxson_build_utils-0.1.1/src/maxson_build_utils/build_executable.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+# maxson_build_utils/builder.py
+
+"""
+maxson_build_utils/builder.py
+Modular build execution orchestrator for PyInstaller, AppImage, and DMG workflows.
+"""
+
+from __future__ import annotations
+
+import argparse
+from enum import Enum
+import logging
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+import pyhabitat
+
+from .helpers import form_dynamic_name, PyinsMode, IconFileType
+
+logger = logging.getLogger(__name__)
+
+
+DIST_DIR = Path("dist")
+DIST_DIR_ONEFILE = DIST_DIR / PyinsMode.ONEFILE.value
+DIST_DIR_ONEDIR = DIST_DIR / PyinsMode.ONEDIR.value
+STANDARD_MACOS_APP_DIST_DIR = DIST_DIR
+BUILD_DIR = Path("build/pyinstaller_work")
+RC_TEMPLATE = Path("build_assets") / "version.rc.template"
+RC_FILE = Path("build_assets") / "version.rc"
+PROJECT_ROOT = Path.cwd()
+HOOKS_DIR_ABS = PROJECT_ROOT / "pyinstaller_hooks"
+
+
+def resolve_icon_filetype(icon_src: Path) -> IconFileType | None:
+    """Resolves and validates the extension of a given icon path."""
+    suffix = icon_src.suffix.lower().removeprefix(".")
+    try:
+        return IconFileType(suffix)
+    except ValueError:
+        return None
+
+
+def form_dynamic_name(src_folder_name: str, version: str, mode: PyinsMode) -> str:
+    """Forms a standard dynamic build descriptor string."""
+    return f"{src_folder_name}-{version}-{mode.value}"
+
+
+def get_cli_main_file(src_folder_name: str) -> Path:
+    """Locates the entry point module inside the package source folder."""
+    return PROJECT_ROOT / "src" / src_folder_name / "__main__.py"
+
+
+def generate_rc_file(package_version: str) -> None:
+    """Generates the .rc file using the provided version string on Windows."""
+    if not pyhabitat.on_windows():
+        return
+
+    if not RC_TEMPLATE.exists():
+        logger.warning("RC template not found at %s. Skipping version info.", RC_TEMPLATE)
+        return
+
+    logger.info("Generated resource file %s for version %s", RC_FILE, package_version)
+    RC_FILE.write_text("// Placeholder content for versioning", encoding="utf-8")
+
+
+def setup_dirs() -> None:
+    """Ensures intermediate and output distribution directories exist."""
+    BUILD_DIR.mkdir(parents=True, exist_ok=True)
+    DIST_DIR.mkdir(parents=True, exist_ok=True)
+    DIST_DIR_ONEFILE.mkdir(parents=True, exist_ok=True)
+    DIST_DIR_ONEDIR.mkdir(parents=True, exist_ok=True)
+
+
+def determine_file_extension(is_windowed_build: bool) -> str:
+    """Determines binary output extension based on target system and window flag."""
+    if pyhabitat.on_windows():
+        return ".exe"
+    elif pyhabitat.on_macos() and is_windowed_build:
+        return ".app"
+    return ""
+
+
+def clean_artifacts(exe_name: str, mode: PyinsMode, file_extension: str) -> None:
+    """Cleans previous build outputs and temporary work directories."""
+    target = (
+        DIST_DIR_ONEDIR / exe_name
+        if mode == PyinsMode.ONEDIR
+        else DIST_DIR_ONEFILE / f"{exe_name}{file_extension}"
+    )
+
+    if target.exists():
+        logger.info("Removing old build artifact: %s", target.resolve())
+        if target.is_dir():
+            shutil.rmtree(target)
+        else:
+            target.unlink()
+
+    if BUILD_DIR.exists():
+        logger.info("Removing build work folder: %s", BUILD_DIR.resolve())
+        shutil.rmtree(BUILD_DIR)
+
+    if pyhabitat.on_windows() and RC_FILE.exists():
+        RC_FILE.unlink()
+
+
+def determine_app_path_and_dist_path(
+    dynamic_exe_name: str, mode: PyinsMode, is_windowed_build: bool
+) -> tuple[str, Path, Path, str]:
+    """Calculates distribution targets and final artifact file paths."""
+    ext = determine_file_extension(is_windowed_build)
+    app_filename = f"{dynamic_exe_name}{ext}"
+
+    if mode == PyinsMode.ONEFILE:
+        dist_path = DIST_DIR_ONEFILE
+        app_path = DIST_DIR_ONEFILE / app_filename
+    else:
+        if pyhabitat.on_macos():
+            dist_path = STANDARD_MACOS_APP_DIST_DIR
+            app_path = STANDARD_MACOS_APP_DIST_DIR / app_filename
+        else:
+            dist_path = DIST_DIR_ONEDIR
+            app_path = DIST_DIR_ONEDIR / dynamic_exe_name / app_filename
+
+    dist_path.mkdir(parents=True, exist_ok=True)
+    logger.info("Executable target path: %s", app_path.resolve())
+    return app_filename, dist_path, app_path, ext
+
+
+def build_linux_appimage(
+    app_dir_path: Path,
+    dynamic_exe_name: str,
+    app_name_pretty: str,
+    icon_src: Path,
+) -> Path:
+    """Packages a PyInstaller ONEDIR bundle into a standalone Linux AppImage."""
+    logger.info("Executing build_linux_appimage()")
+    logger.info("Source AppDir components from: %s", app_dir_path)
+
+    if shutil.which("appimagetool") is None:
+        raise RuntimeError(
+            "appimagetool is not installed. Please download it or install via your package manager."
+        )
+
+    upload_dir = DIST_DIR / "upload"
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    appimage_output_path = upload_dir / f"{dynamic_exe_name}-x86_64.AppImage"
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        staged_appdir = tmp_dir / f"{dynamic_exe_name}.AppDir"
+        staged_appdir.mkdir(parents=True, exist_ok=True)
+
+        usr_bin = staged_appdir / "usr" / "bin"
+        usr_bin.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(app_dir_path, usr_bin / dynamic_exe_name)
+
+        apprun_path = staged_appdir / "AppRun"
+        apprun_content = f"""#!/bin/sh
+HERE="$(dirname "$(readlink -f "${{0}}")")"
+EXEC="${{HERE}}/usr/bin/{dynamic_exe_name}/{dynamic_exe_name}"
+exec "${{EXEC}}" "$@"
+"""
+        apprun_path.write_text(apprun_content, encoding="utf-8")
+        apprun_path.chmod(0o755)
+
+        desktop_path = staged_appdir / f"{dynamic_exe_name}.desktop"
+        desktop_content = f"""[Desktop Entry]
+Type=Application
+Name={app_name_pretty}
+Exec=AppRun
+Icon={dynamic_exe_name}
+Categories=Utility;
+Terminal=true
+"""
+        desktop_path.write_text(desktop_content, encoding="utf-8")
+
+        icon_filetype = resolve_icon_filetype(icon_src)
+        if icon_filetype is None:
+            raise ValueError(
+                f"Unsupported icon type: '{icon_src.suffix}'. "
+                f"Supported types: {[x.value for x in IconFileType]}"
+            )
+
+        icon_dst = staged_appdir / f"{dynamic_exe_name}.{icon_filetype.value}"
+
+        logger.info("Staging Linux AppImage icon: %s -> %s", icon_src.name, icon_dst.name)
+        if icon_src.exists():
+            shutil.copy2(icon_src, icon_dst)
+        else:
+            raise FileNotFoundError(
+                f"Critical asset missing! Could not locate icon at: {icon_src.resolve()}"
+            )
+
+        logger.info("Compiling AppImage to %s...", appimage_output_path)
+        subprocess.run(
+            [
+                "appimagetool",
+                str(staged_appdir.resolve()),
+                str(appimage_output_path.resolve()),
+            ],
+            check=True,
+            env=os.environ.copy(),
+        )
+
+    return appimage_output_path
+
+
+def post_process_linux_build(
+    app_path: Path,
+    dynamic_exe_name: str,
+    app_name_pretty: str,
+    icon_src: Path,
+    mode: PyinsMode,
+) -> Path | None:
+    """Handles downstream staging tasks on Linux platforms (skips Termux)."""
+    is_linux = getattr(pyhabitat, "on_linux", lambda: sys.platform.startswith("linux"))()
+    is_termux = getattr(pyhabitat, "on_termux", lambda: False)()
+
+    if is_linux and not is_termux and mode == PyinsMode.ONEDIR:
+        bundle_dir = app_path.parent
+        return build_linux_appimage(
+            app_dir_path=bundle_dir,
+            dynamic_exe_name=dynamic_exe_name,
+            app_name_pretty=app_name_pretty,
+            icon_src=icon_src,
+        )
+
+    return None
+
+
+def construct_pyinstaller_command(
+    dynamic_exe_name: str,
+    dist_path: Path,
+    mode: PyinsMode,
+    main_script_path: Path,
+    is_windowed_build: bool,
+    src_folder_name: str,
+    icon_ico_path: Path | None = None,
+    icon_icns_path: Path | None = None,
+    collect_data_pkgs: list[str] | set[str] | None = None,
+    collect_binary_pkgs: list[str] | set[str] | None = None,
+) -> list[str]:
+    """Constructs the PyInstaller CLI argument array."""
+    base_command = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        "--noconfirm",
+        "--clean",
+        f"--name={dynamic_exe_name}",
+        f'--paths={PROJECT_ROOT / "src"}',
+        f"--distpath={dist_path}",
+        f'--workpath={BUILD_DIR / "work"}',
+        f"--specpath={BUILD_DIR}",
+    ]
+
+    # Explicit data directory check
+    data_dir = PROJECT_ROOT / "src" / src_folder_name / "data"
+    if data_dir.exists():
+        base_command.append(f"--add-data={data_dir}{os.path.pathsep}{src_folder_name}/data")
+
+    # Safely attach hooks directory only if present in target project
+    if HOOKS_DIR_ABS.exists() and HOOKS_DIR_ABS.is_dir():
+        base_command.append(f"--additional-hooks-dir={HOOKS_DIR_ABS}")
+
+    # Process dynamic package collection flags
+    for pkg in collect_data_pkgs or []:
+        base_command.append(f"--collect-data={pkg}")
+
+    for pkg in collect_binary_pkgs or []:
+        base_command.append(f"--collect-binaries={pkg}")
+
+    base_command.append(f"--{mode.value}")
+
+    if is_windowed_build:
+        base_command.append("--windowed")
+    else:
+        logger.info("Building without --windowed flag (favoring CLI usage).")
+
+    if pyhabitat.on_windows():
+        if RC_FILE.exists():
+            base_command.append(f"--version-file={RC_FILE.resolve()}")
+        if icon_ico_path and icon_ico_path.exists():
+            base_command.append(f"--icon={icon_ico_path.resolve()}")
+
+    if pyhabitat.on_macos() and icon_icns_path and icon_icns_path.exists():
+        base_command.append(f"--icon={icon_icns_path.resolve()}")
+
+    base_command.append(str(main_script_path.resolve()))
+    return base_command
+
+
+def run_pyinstaller(
+    dynamic_exe_name: str,
+    main_script_path: Path,
+    src_folder_name: str,
+    mode: PyinsMode = PyinsMode.ONEDIR,
+    is_windowed_build: bool = True,
+    icon_ico_path: Path | None = None,
+    icon_icns_path: Path | None = None,
+    collect_data_pkgs: list[str] | set[str] | None = None,
+    collect_binary_pkgs: list[str] | set[str] | None = None,
+) -> tuple[Path, str]:
+    """Executes the PyInstaller command within a subshell."""
+    logger.info("--- %s Executable Builder ---", src_folder_name)
+    app_filename, dist_path, app_path, ext = determine_app_path_and_dist_path(
+        dynamic_exe_name, mode, is_windowed_build
+    )
+
+    clean_artifacts(exe_name=dynamic_exe_name, mode=mode, file_extension=ext)
+    setup_dirs()
+
+    full_command = construct_pyinstaller_command(
+        dynamic_exe_name=dynamic_exe_name,
+        dist_path=dist_path,
+        mode=mode,
+        main_script_path=main_script_path,
+        is_windowed_build=is_windowed_build,
+        src_folder_name=src_folder_name,
+        icon_ico_path=icon_ico_path,
+        icon_icns_path=icon_icns_path,
+        collect_data_pkgs=collect_data_pkgs,
+        collect_binary_pkgs=collect_binary_pkgs,
+    )
+
+    logger.info("Executing command: %s", " ".join(full_command))
+    try:
+        subprocess.run(full_command, check=True, env=os.environ.copy())
+    except subprocess.CalledProcessError as e:
+        logger.error("PyInstaller failed with exit code %d", e.returncode)
+        raise SystemExit(e.returncode) from e
+
+    if pyhabitat.on_macos() and mode == PyinsMode.ONEDIR:
+        duplicate_cli_dir = DIST_DIR / dynamic_exe_name
+        if duplicate_cli_dir.exists() and duplicate_cli_dir.is_dir():
+            shutil.rmtree(duplicate_cli_dir)
+
+    return app_path.resolve(), app_filename
+
+
+def run_build_executable(
+    src_folder_name: str,
+    version: str,
+    app_name_pretty: str,
+    icon_png_path: Path | None = None,
+    icon_ico_path: Path | None = None,
+    icon_icns_path: Path | None = None,
+    collect_data_pkgs: list[str] | set[str] | None = None,
+    collect_binary_pkgs: list[str] | set[str] | None = None,
+    args_list: list[str] | None = None,
+) -> None:
+    """Primary entry point for downstream project packaging scripts."""
+    parser = argparse.ArgumentParser(description=f"Build runner for {app_name_pretty}")
+    parser.add_argument(
+        "--mode",
+        type=PyinsMode,
+        choices=list(PyinsMode),
+        default=PyinsMode.ONEDIR,
+        help="PyInstaller build mode.",
+    )
+    args = parser.parse_args(args_list)
+    mode = args.mode
+
+    is_windowed_build = (
+        (pyhabitat.on_windows() or pyhabitat.on_macos())
+        and (mode == PyinsMode.ONEDIR)
+        and pyhabitat.tkinter_is_available()
+    )
+
+    try:
+        if version == "0.0.0" or not version:
+            logger.error("FATAL: Invalid package version provided.")
+            sys.exit(1)
+
+        generate_rc_file(version)
+        executable_descriptor = form_dynamic_name(src_folder_name, version, mode)
+        cli_main_file = get_cli_main_file(src_folder_name)
+
+        app_path, app_filename = run_pyinstaller(
+            dynamic_exe_name=executable_descriptor,
+            main_script_path=cli_main_file,
+            src_folder_name=src_folder_name,
+            mode=mode,
+            is_windowed_build=is_windowed_build,
+            icon_ico_path=icon_ico_path,
+            icon_icns_path=icon_icns_path,
+            collect_data_pkgs=collect_data_pkgs,
+            collect_binary_pkgs=collect_binary_pkgs,
+        )
+
+        if icon_png_path and icon_png_path.exists():
+            appimage_path = post_process_linux_build(
+                app_path=app_path,
+                dynamic_exe_name=executable_descriptor,
+                app_name_pretty=app_name_pretty,
+                icon_src=icon_png_path,
+                mode=mode,
+            )
+            if appimage_path:
+                logger.info("AppImage successfully generated at: %s", appimage_path)
+
+    except SystemExit as e:
+        sys.exit(e.code)
+    except Exception as e:
+        logger.error("An unhandled error occurred during build: %s", e, exc_info=True)
+        sys.exit(1)

maxson_build_utils-0.1.1/src/maxson_build_utils/build_pyz.py

@@ -0,0 +1,160 @@
+# maxson_build_utils/src/maxson_build_utils/build_pyz.py
+from __future__ import annotations
+
+import os
+import shutil
+import site
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import pyhabitat
+
+from .helpers import form_dynamic_name
+
+
+def run_command(cmd: list[str], check: bool = True, env: dict[str, str] | None = None) -> subprocess.CompletedProcess[str]:
+    """Run command with logging and error reporting."""
+    print(f"\n$ {' '.join(cmd)}")
+    final_env = env if env is not None else os.environ.copy()
+
+    result = subprocess.run(cmd, text=True, check=False, capture_output=True, env=final_env)
+
+    if result.stdout:
+        print(result.stdout.strip())
+
+    if result.returncode != 0:
+        if result.stderr:
+            print(f"--- COMMAND FAILED (Exit {result.returncode}) ---", file=sys.stderr)
+            print(result.stderr.strip(), file=sys.stderr)
+
+        if check:
+            raise subprocess.CalledProcessError(
+                result.returncode, cmd, output=result.stdout, stderr=result.stderr
+            )
+    return result
+
+
+def find_latest_wheel(dist_dir: Path, src_folder_name: str, version: str) -> Path:
+    """Finds the most recently built wheel file for the given package and version."""
+    wheels = sorted(
+        dist_dir.glob(f"{src_folder_name}-{version}*.whl"),
+        key=lambda f: f.stat().st_mtime,
+        reverse=True,
+    )
+    if not wheels:
+        raise FileNotFoundError(f"No wheel found for {src_folder_name} version {version} in {dist_dir}.")
+    return wheels[0]
+
+
+def ensure_dependencies_and_shiv() -> None:
+    """Ensures environment dependencies and 'shiv' are installed and accessible."""
+    if os.environ.get("CI") == "true":
+        print("\nSkipping dependency check/install inside CI environment.")
+        return
+
+    print("Syncing dev group dependencies via uv...")
+    run_command(["uv", "sync", "--group", "dev"])
+
+    try:
+        run_command(["uv", "run", "shiv", "--version"], check=True)
+    except subprocess.CalledProcessError:
+        print("Installing 'shiv'...")
+        run_command(["uv", "add", "shiv"])
+
+
+def create_windows_bat_launcher(pyz_filename: str, output_dir: Path) -> None:
+    """Creates a Windows BAT file launcher for GUI execution when running on Windows."""
+    if os.name != "nt":
+        return
+
+    bat_filename = pyz_filename.replace(".pyz", "-gui.bat")
+    bat_path = output_dir / bat_filename
+
+    bat_content = f"""@echo off
+rem Launch {pyz_filename} with the 'gui' command using system Python.
+python "%~dp0{pyz_filename}" gui
+"""
+    try:
+        bat_path.write_text(bat_content, encoding="utf-8")
+        print(f"Created Windows BAT launcher: {bat_path.name}")
+    except Exception as e:
+        print(f"WARNING: Failed to create BAT launcher: {e}", file=sys.stderr)
+
+
+def run_build_pyz(
+    src_folder_name: str,
+    version: str,
+    entry_point: str,
+    dist_dir: Path = Path("dist") / "zipapp",
+    test_gui: bool = True,
+) -> Path:
+    """Builds a portable Python ZipApp (PYZ) using shiv and verifies the output artifact."""
+    if version == "0.0.0":
+        raise ValueError("Cannot proceed without a valid version string.")
+
+    dist_dir.mkdir(parents=True, exist_ok=True)
+
+    # Configure isolated temporary root for Shiv internal caching
+    build_temp = Path(tempfile.gettempdir()) / "shiv_build"
+    if build_temp.exists():
+        shutil.rmtree(build_temp, ignore_errors=True)
+    build_temp.mkdir(parents=True, exist_ok=True)
+    os.environ["SHIV_ROOT"] = str(build_temp)
+
+    # 1. Sync dependencies
+    ensure_dependencies_and_shiv()
+
+    # 2. Build Wheel into target zipapp directory
+    print("\nBuilding project wheel via uv build...")
+    custom_env = os.environ.copy()
+    if pyhabitat.on_termux():
+        termux_tmp = Path.home() / ".tmp"
+        termux_tmp.mkdir(exist_ok=True)
+        custom_env["TMPDIR"] = str(termux_tmp)
+
+    run_command(["uv", "build", "--wheel", "--out-dir", str(dist_dir)], env=custom_env)
+
+    # 3. Locate wheel and construct Shiv command
+    wheel_path = find_latest_wheel(dist_dir, src_folder_name, version)
+    dynamic_name = form_dynamic_name(src_folder_name, version, mode=None)
+    pyz_filename = f"{dynamic_name}-shiv.pyz"
+    interpreter = "python" if os.name == "nt" else "/usr/bin/env python3"
+    output_path = dist_dir / pyz_filename
+
+    if output_path.exists():
+        output_path.unlink()
+
+    cmd = [
+        "uv", "run", "shiv",
+        "-o", str(output_path),
+        "-p", interpreter,
+        "-e", entry_point,
+        "--compressed",
+        "--no-cache",
+        str(wheel_path),
+    ]
+
+    print(f"\nBuilding PYZ using shiv from Wheel: {pyz_filename}")
+    run_command(cmd, env=custom_env)
+    output_path.chmod(0o755)
+
+    # Cleanup staging wheel
+    try:
+        wheel_path.unlink()
+        print(f"Removed staging wheel: {wheel_path.name}")
+    except Exception as e:
+        print(f"Note: Could not delete temporary wheel: {e}")
+
+    create_windows_bat_launcher(pyz_filename, dist_dir)
+
+    # 4. Post-build verification
+    print("\nTesting generated Shiv artifact...")
+    run_command([sys.executable, str(output_path), "--help"], check=True)
+
+    if test_gui and pyhabitat.tkinter_is_available():
+        print(f"Testing GUI mode for {output_path.name}...")
+        run_command([sys.executable, str(output_path), "gui", "--auto-close", "1000"], check=True)
+
+    print(f"\nBuild complete! Portable PYZ: {output_path.resolve()}")
+    return output_path

maxson_build_utils-0.1.1/src/maxson_build_utils/build_utils.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3 
+# maxson_build_utils/build_utils.py
+
+from __future__ import annotations
+import pyhabitat
+from enum import Enum
+import sys
+import logging
+
+class PyinsMode(str, Enum):
+    """onedir vs onefile"""
+    ONEDIR = "onedir"
+    ONEFILE = "onefile"
+
+# --- Dynamic Naming Placeholder (Simplified version for this context) ---
+def form_dynamic_name(pkg_name: str, version: str, mode: PyinsMode|None = None) -> str:
+    """Creates a standardized binary name descriptor."""
+
+    os_tag = pyhabitat.SystemInfo().get_os_tag()
+    arch = pyhabitat.SystemInfo().get_arch()
+    py_ver = f"py{sys.version_info.major}{sys.version_info.minor}"
+    dynamic_exe_name = f"{pkg_name}-{version}-{py_ver}-{os_tag}-{arch}"
+    if mode == PyinsMode.ONEFILE:
+        dynamic_exe_name += f"-{PyinsMode.ONEFILE.value}"
+    return dynamic_exe_name

maxson_build_utils-0.1.1/src/maxson_build_utils/cli.py

@@ -0,0 +1,29 @@
+import typer
+from pathlib import Path
+from maxson_build_utils.deb import build_debian_package
+from maxson_build_utils.vendor import vendor_wheels
+
+app = typer.Typer(help="Maxson build and packaging tools.")
+
+@app.command(name="prepare-flatpak")
+def prepare_flatpak(
+    dist_dir: Path = Path("dist"),
+    vendor_dir: Path = Path("vendor-wheels")
+):
+    """Build project wheel and vendor offline dependencies for Flatpak."""
+    vendor_wheels(dist_dir=dist_dir, vendor_dir=vendor_dir)
+
+@app.command(name="build-deb")
+def build_deb(
+    app_name: str = typer.Option("cellshift", "--app-name", help="Package application name"),
+    version: str = typer.Option("0.1.0", "--version", help="Version string"),
+    arch: str = typer.Option("amd64", "--arch", help="Target architecture")
+):
+    """Assemble and build a Debian .deb package."""
+    build_debian_package(app_name=app_name, version=version, arch=arch)
+
+def main():
+    app()
+
+if __name__ == "__main__":
+    main()

maxson_build_utils-0.1.1/src/maxson_build_utils/context.py

@@ -0,0 +1,12 @@
+# src/maxson_build_utils/context.py
+from __future__ import annotations
+from pathlib import Path
+
+APP_NAME = "maxson-build-utils"
+SRC_FOLDER_NAME = "maxson_build_utils"
+APP_NAME_PRETTY = "maxson-build-utils"
+APP_DIR = Path.home() / f".{APP_NAME}"
+APP_DIR.mkdir(parents=True,exist_ok=True)
+
+SERVICE = APP_NAME
+DESCRIPTION_STR = "Centralized build tools for the standard Maxson architecture."

maxson_build_utils-0.1.1/src/maxson_build_utils/deb.py

@@ -0,0 +1,21 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+def build_debian_package(app_name: str, version: str, arch: str) -> Path:
+    """Assembles /opt, DEBIAN/control, launcher scripts, and executes dpkg-deb."""
+    pkg_dir = Path("deb/pkg")
+    pkg_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Render control file
+    control_in = Path("deb/control.in").read_text()
+    control_out = control_in.replace("__VERSION__", version).replace("__ARCH__", arch)
+    (pkg_dir / "DEBIAN").mkdir(exist_ok=True)
+    (pkg_dir / "DEBIAN/control").write_text(control_out)
+    
+    # Run dpkg-deb
+    deb_filename = f"{app_name}_{version}_{arch}.deb"
+    output_path = Path(f"deb/{deb_filename}")
+    subprocess.run(["fakeroot", "dpkg-deb", "--build", str(pkg_dir), str(output_path)], check=True)
+    return output_path

maxson_build_utils-0.1.1/src/maxson_build_utils/helpers.py

@@ -0,0 +1,23 @@
+# maxson_build_utils/src/maxson_build_utils/helpers.py
+from __future__ import annotations
+from enum import Enum
+
+from typing import Any
+
+
+def form_dynamic_name(src_folder_name: str, version: str, mode: Any = None) -> str:
+    """Forms a dynamic output artifact base name."""
+    if mode is None:
+        return f"{src_folder_name}-{version}"
+
+    mode_str = mode.value if hasattr(mode, "value") else str(mode)
+    return f"{src_folder_name}-{version}-{mode_str}"
+
+class PyinsMode(str, Enum):
+    ONEDIR = "onedir"
+    ONEFILE = "onefile"
+
+class IconFileType(str, Enum):
+    PNG = "png"
+    ICO = "ico"
+    SVG = "svg"

maxson_build_utils-0.1.1/src/maxson_build_utils/linux_app_image.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# maxson_build_utils/build_utils.py
+
+"""Build utilities for packaging PyInstaller outputs across target platforms."""
+
+from __future__ import annotations
+
+from enum import Enum
+import logging
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+import pyhabitat
+
+logger = logging.getLogger(__name__)
+
+
+class PyinsMode(str, Enum):
+    ONEDIR = "onedir"
+    ONEFILE = "onefile"
+
+
+class IconFileType(str, Enum):
+    PNG = "png"
+    ICO = "ico"
+    SVG = "svg"
+
+
+def resolve_icon_filetype(icon_src: Path) -> IconFileType | None:
+    """Resolves and validates the extension of a given icon path."""
+    suffix = icon_src.suffix.lower().removeprefix(".")
+    try:
+        return IconFileType(suffix)
+    except ValueError:
+        return None
+
+
+def build_linux_appimage(
+    app_dir_path: Path,
+    dynamic_exe_name: str,
+    app_name_pretty: str,
+    icon_src: Path,
+) -> Path:
+    """Packages a PyInstaller ONEDIR bundle into a standalone Linux AppImage."""
+    logger.info("Executing build_linux_appimage()")
+    logger.info("Source AppDir components from: %s", app_dir_path)
+
+    if shutil.which("appimagetool") is None:
+        raise RuntimeError(
+            "appimagetool is not installed. Please download it or install via your package manager."
+        )
+
+    upload_dir = Path("dist/upload")
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    appimage_output_path = upload_dir / f"{dynamic_exe_name}-x86_64.AppImage"
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        staged_appdir = tmp_dir / f"{dynamic_exe_name}.AppDir"
+        staged_appdir.mkdir(parents=True, exist_ok=True)
+
+        # 1. Populate the usr/bin directory with the PyInstaller bundle
+        usr_bin = staged_appdir / "usr" / "bin"
+        usr_bin.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(app_dir_path, usr_bin / dynamic_exe_name)
+
+        # 2. Create the AppRun entrypoint script
+        apprun_path = staged_appdir / "AppRun"
+        apprun_content = f"""#!/bin/sh
+HERE="$(dirname "$(readlink -f "${{0}}")")"
+EXEC="${{HERE}}/usr/bin/{dynamic_exe_name}/{dynamic_exe_name}"
+exec "${{EXEC}}" "$@"
+"""
+        apprun_path.write_text(apprun_content, encoding="utf-8")
+        apprun_path.chmod(0o755)
+
+        # 3. Create the .desktop file
+        desktop_path = staged_appdir / f"{dynamic_exe_name}.desktop"
+        desktop_content = f"""[Desktop Entry]
+Type=Application
+Name={app_name_pretty}
+Exec=AppRun
+Icon={dynamic_exe_name}
+Categories=Utility;
+Terminal=true
+"""
+        desktop_path.write_text(desktop_content, encoding="utf-8")
+
+        # 4. Copy and stage the icon asset
+        icon_filetype = resolve_icon_filetype(icon_src)
+        if icon_filetype is None:
+            raise ValueError(
+                f"Unsupported icon type: '{icon_src.suffix}'. "
+                f"Supported types: {[x.value for x in IconFileType]}"
+            )
+
+        icon_dst = staged_appdir / f"{dynamic_exe_name}.{icon_filetype.value}"
+
+        logger.info("Staging Linux AppImage icon: %s -> %s", icon_src.name, icon_dst.name)
+        if icon_src.exists():
+            shutil.copy2(icon_src, icon_dst)
+        else:
+            raise FileNotFoundError(
+                f"Critical asset missing! Could not locate icon at: {icon_src.resolve()}"
+            )
+
+        # 5. Run appimagetool
+        logger.info("Compiling AppImage to %s...", appimage_output_path)
+        subprocess.run(
+            [
+                "appimagetool",
+                str(staged_appdir.resolve()),
+                str(appimage_output_path.resolve()),
+            ],
+            check=True,
+            env=os.environ.copy(),
+        )
+
+    return appimage_output_path
+
+
+def post_process_linux_build(
+    app_path: Path,
+    dynamic_exe_name: str,
+    app_name_pretty: str,
+    icon_src: Path,
+    mode: PyinsMode,
+) -> Path | None:
+    """Handles downstream staging tasks on Linux platforms (skips Termux)."""
+    is_linux = getattr(pyhabitat, "on_linux", lambda: sys.platform.startswith("linux"))()
+    is_termux = getattr(pyhabitat, "on_termux", lambda: False)()
+
+    if is_linux and not is_termux and mode == PyinsMode.ONEDIR:
+        bundle_dir = app_path.parent
+        return build_linux_appimage(
+            app_dir_path=bundle_dir,
+            dynamic_exe_name=dynamic_exe_name,
+            app_name_pretty=app_name_pretty,
+            icon_src=icon_src,
+        )
+
+    return None

maxson_build_utils-0.1.1/src/maxson_build_utils/macos_dmg.py

@@ -0,0 +1,107 @@
+# src/maxson_build_utils/macos_dmg.py
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import pyhabitat
+
+from maxson_build_utils.build_utils import PyinsMode
+
+STANDARD_MACOS_APP_DIST_DIR = Path("dist")
+DIST_DIR_ONEDIR = Path("dist") / PyinsMode.ONEDIR.value
+
+
+def purge_raw_unix_structure_from_macos_build(dynamic_exe_name: str, mode: PyinsMode) -> None:
+    """Removes duplicate CLI directories created by PyInstaller next to .app bundles."""
+    if pyhabitat.on_macos() and mode == PyinsMode.ONEDIR:
+        duplicate_cli_dir = Path("dist") / dynamic_exe_name
+        if duplicate_cli_dir.exists() and duplicate_cli_dir.is_dir():
+            print(f"Cleaning up duplicate raw Unix folder: {duplicate_cli_dir.resolve()}")
+            shutil.rmtree(duplicate_cli_dir)
+
+
+def move_macos_app(macos_app_filename: str, app_path: Path) -> Path:
+    """Relocates standard PyInstaller .app bundle into dist/onedir/."""
+    src = STANDARD_MACOS_APP_DIST_DIR / macos_app_filename
+    dst = DIST_DIR_ONEDIR / macos_app_filename
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    if src.exists():
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.move(str(src), str(dst))
+        return dst
+    return app_path
+
+
+def build_macos_dmg(
+    app: Path,
+    app_pretty_name: str,
+    version: str,
+    output_dir: Path = Path("dist/upload"),
+) -> Path:
+    """Packages a macOS .app bundle into a .dmg using create-dmg."""
+    print("build_macos_dmg()")
+    print(f"{app=}")
+
+    if app.suffix != ".app":
+        raise ValueError(f"Expected a .app bundle, got {app}")
+
+    if shutil.which("create-dmg") is None:
+        raise RuntimeError("create-dmg is not installed. Install with: brew install create-dmg")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    dmg_path = output_dir / f"{app.stem}.dmg"
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        staged = tmp_path / app.name
+        shutil.copytree(app, staged)
+
+        cmd = [
+            "create-dmg",
+            "--volname",
+            f"{app_pretty_name} {version}",
+            "--window-size",
+            "500",
+            "300",
+            "--icon-size",
+            "100",
+            "--icon",
+            staged.name,
+            "150",
+            "180",
+            "--app-drop-link",
+            "450",
+            "180",
+            str(dmg_path.resolve()),
+            str(tmp_path),
+        ]
+
+        print(f"Executing create-dmg command: {' '.join(cmd)}")
+        subprocess.run(cmd, check=True)
+
+    return dmg_path
+
+
+def post_process_macos_build(
+    app_filename: str,
+    app_path: Path,
+    mode: PyinsMode,
+    app_pretty_name: str,
+    version: str,
+) -> tuple[Path, Path | None]:
+    """Coordinates post-build cleanup, app relocation, and DMG generation for macOS."""
+    if pyhabitat.on_macos() and mode == PyinsMode.ONEDIR:
+        app_path = move_macos_app(app_filename, app_path)
+        dmg_path = build_macos_dmg(
+            app=app_path,
+            app_pretty_name=app_pretty_name,
+            version=version,
+        )
+        return app_path, dmg_path
+    return app_path, None

maxson_build_utils-0.1.1/src/maxson_build_utils/vendor.py

@@ -0,0 +1,40 @@
+# src/maxson_build_utils/vendor.py
+import subprocess
+from pathlib import Path
+
+def vendor_wheels(dist_dir: Path = Path("dist"), vendor_dir: Path = Path("vendor-wheels")) -> None:
+    """Builds project wheel and downloads all runtime dependencies offline for Flatpak."""
+    vendor_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Build the project wheel first
+    subprocess.run(["uv", "build", "--wheel", "--out-dir", str(dist_dir)], check=True)
+
+    # 2. Export ONLY third-party runtime dependencies (exclude dev deps and the local project itself)
+    req_file = Path("requirements.txt")
+    subprocess.run([
+        "uv", "export",
+        "--format", "requirements-txt",
+        "--no-editable",
+        "--no-dev",
+        "--no-emit-project",
+        "-o", str(req_file)
+    ], check=True)
+
+    # 3. Download third-party runtime wheels
+    subprocess.run([
+        "uv", "run", "pip", "download",
+        "-r", str(req_file),
+        "-d", str(vendor_dir)
+    ], check=True)
+
+    # 4. Stage the built primary wheel into vendor-wheels without checking PyPI dependencies
+    wheels = list(dist_dir.glob("*.whl"))
+    if not wheels:
+        raise FileNotFoundError(f"No built wheels found in {dist_dir}")
+        
+    subprocess.run([
+        "uv", "run", "pip", "download",
+        str(wheels[0]),
+        "--no-deps",
+        "-d", str(vendor_dir)
+    ], check=True)

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: maxson-build-utils
+Version: 0.1.1
+Summary: Common tools for deploying packages to EXE, MSIX, DMG, DEB, PYZ, flatpak, and more. Templated approach to mkdocs.
+Author-email: George Clayton Bennett <george.bennett@memphistn.gov>
+Maintainer-email: George Clayton Bennett <george.bennett@memphistn.gov>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/city-of-memphis-wastewater/maxson-build-utils
+Project-URL: Repository, https://github.com/city-of-memphis-wastewater/maxson-build-utils
+Project-URL: Issues, https://github.com/city-of-memphis-wastewater/maxson-build-utils/issues
+Project-URL: Changelog, https://raw.githubusercontent.com/city-of-memphis-wastewater/maxson-build-utils/main/docs/CHANGELOG.md
+Keywords: build-tools,build
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyhabitat>=1.3.9
+Requires-Dist: typer>=0.27.0
+Requires-Dist: typer-helptree>=0.2.12
+
+# maxson-build-utils
+
+Centralized org tooling for PyInstaller, DMG, AppImage, DEB, PYZ, etc.

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+src/maxson_build_utils/VERSION
+src/maxson_build_utils/__init__.py
+src/maxson_build_utils/__main__.py
+src/maxson_build_utils/_version.py
+src/maxson_build_utils/build_executable.py
+src/maxson_build_utils/build_pyz.py
+src/maxson_build_utils/build_utils.py
+src/maxson_build_utils/cli.py
+src/maxson_build_utils/context.py
+src/maxson_build_utils/deb.py
+src/maxson_build_utils/helpers.py
+src/maxson_build_utils/linux_app_image.py
+src/maxson_build_utils/macos_dmg.py
+src/maxson_build_utils/vendor.py
+src/maxson_build_utils.egg-info/PKG-INFO
+src/maxson_build_utils.egg-info/SOURCES.txt
+src/maxson_build_utils.egg-info/dependency_links.txt
+src/maxson_build_utils.egg-info/entry_points.txt
+src/maxson_build_utils.egg-info/requires.txt
+src/maxson_build_utils.egg-info/top_level.txt

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+maxson-build-utils = maxson_build_utils.__main__:main

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pyhabitat>=1.3.9
+typer>=0.27.0
+typer-helptree>=0.2.12

maxson_build_utils-0.1.1/src/maxson_build_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+maxson_build_utils