Skip to content

API

Pyrig plugin that builds and publishes standalone project executables.

Installing this package as a dependency extends a pyrig-built project with everything needed to package its entry point as a distributable binary, publish one for every supported operating system alongside each release, and run that entry point locally the same way the packaged binary does.

main

Project entry point.

Provides the main function and __main__ guard used as the project's executable entry point. Replace main with the project's real startup logic.

main

main() -> None

Run the project.

Source code in src/pyrig_executables/main.py
def main() -> None:
    """Run the project."""

rig

Mirrored namespace through which this plugin extends pyrig's scaffolding.

Mirrors the pyrig.rig package layout so pyrig's cross-package plugin discovery finds this plugin's contributions automatically.

cli

CLI commands this plugin contributes to a project.

commands

Backend implementations for this plugin's CLI commands.

Each module implements exactly one command as a plain callable, decoupled from the CLI registration layer. This separation lets the registration layer import commands lazily, loading each module only when its command is invoked.

run

CLI command implementation for running the project's entry-point module.

run_main
run_main() -> None

Execute the project's main.py as the __main__ module.

Runs the file by path rather than importing it, so its if __name__ == "__main__" guard fires and calls main, mirroring how the built executable runs the same file.

Source code in src/pyrig_executables/rig/cli/commands/run.py
def run_main() -> None:
    """Execute the project's `main.py` as the `__main__` module.

    Runs the file by path rather than importing it, so its
    `if __name__ == "__main__"` guard fires and calls `main`, mirroring how the
    built executable runs the same file.
    """
    run_path(MainConfigFile.I.path().as_posix(), run_name="__main__")

subcommands

Project-specific CLI commands.

Functions defined directly in this module are discovered and registered as top-level CLI commands. Module-level typer.Typer instances are registered as command groups, with each group named after the kebab-case form of its variable name.

run
run() -> None

Run the project.

This command runs the project's main.py file as the __main__ module.

Source code in src/pyrig_executables/rig/cli/subcommands.py
def run() -> None:
    """Run the project.

    This command runs the project's `main.py` file as the `__main__` module.
    """
    from pyrig_executables.rig.cli.commands.run import run_main  # noqa: PLC0415

    run_main()

configs

Declarative definitions of the configuration files this plugin contributes.

This package is this plugin's discovery scope for pyrig's config-file management: every file this plugin manages is defined here and validated during pyrig sync.

executables

Executable-related config files contributed by this plugin.

build

Shell script that builds the project's standalone executable.

BuildExecutableConfigFile

Bases: ShellConfigFile

Generate the project-root script used to build the executable.

collect_all_modules
collect_all_modules() -> Iterable[ModuleType]

Return modules to bundle with their data, submodules, and binaries.

Source code in src/pyrig_executables/rig/configs/executables/build.py
def collect_all_modules(self) -> Iterable[ModuleType]:
    """Return modules to bundle with their data, submodules, and binaries."""
    return ()
collect_data_modules
collect_data_modules() -> Iterable[ModuleType]

Return the project's resource package for data collection.

Source code in src/pyrig_executables/rig/configs/executables/build.py
def collect_data_modules(self) -> Iterable[ModuleType]:
    """Return the project's resource package for data collection."""
    return (replace_root_module(resources, PackageManager.I.package_name()),)
dependencies
dependencies() -> Iterable[type[ConfigFile[Any]]]

Return the config files required before generating the script.

Source code in src/pyrig_executables/rig/configs/executables/build.py
@override
def dependencies(self) -> Iterable[type[ConfigFile[Any]]]:
    """Return the config files required before generating the script."""
    return (*super().dependencies(), ResourcesInitConfigFile)
parent_path
parent_path() -> Path

Return the project root.

Source code in src/pyrig_executables/rig/configs/executables/build.py
@override
def parent_path(self) -> Path:
    """Return the project root."""
    return Path()
script
script() -> str

Return the command that builds the executable.

Source code in src/pyrig_executables/rig/configs/executables/build.py
@override
def script(self) -> str:
    """Return the command that builds the executable."""
    command = PackageManager.I.run_args(
        *ExecutableBuilder.I.build_args(
            name=f'{PackageManager.I.project_name()}-"${{OSTYPE}}"',
            entry_point=MainConfigFile.I.path(),
            icon=IconConfigFile.I.path(),
            collect_all_modules=self.collect_all_modules(),
            collect_data_modules=self.collect_data_modules(),
        ),
    )
    return command.multiline() + "\n"
stem
stem() -> str

Return the script filename without its extension.

Source code in src/pyrig_executables/rig/configs/executables/build.py
@override
def stem(self) -> str:
    """Return the script filename without its extension."""
    return "build-executable"
icon

Config that scaffolds the executable's icon as rig/resources/icon.png.

IconConfigFile

Bases: DictConfigFile

Config file that scaffolds the icon.png used as the executable's icon.

The executable build script uses this file as the built executable's icon. The scaffolded file is a default -- replace it with your own; it is created only when missing, so a project's own icon is preserved.

Note

If the file exists but is not a valid PNG, validation raises RuntimeError rather than automatically restoring the default icon.

extension
extension() -> str

Return "png" as the icon's file extension.

Source code in src/pyrig_executables/rig/configs/executables/icon.py
@override
def extension(self) -> str:
    """Return `"png"` as the icon's file extension."""
    return "png"
is_correct
is_correct() -> bool

Return whether the icon file starts with the PNG signature.

Only the 8-byte PNG magic number is checked; the rest of the file's bytes are not otherwise validated.

Returns:

Type Description
bool

True if the icon file starts with the PNG signature; False

bool

otherwise.

Source code in src/pyrig_executables/rig/configs/executables/icon.py
@override
def is_correct(self) -> bool:
    """Return whether the icon file starts with the PNG signature.

    Only the 8-byte PNG magic number is checked; the rest of the file's
    bytes are not otherwise validated.

    Returns:
        `True` if the icon file starts with the PNG signature; `False`
        otherwise.
    """
    with self.path().open("rb") as f:
        return f.read(8) == b"\x89PNG\r\n\x1a\n"
parent_path
parent_path() -> Path

Return the directory the icon lives in.

Returns:

Type Description
Path

The project's rig/resources package directory, shared with the

Path

config file that scaffolds that package's __init__.py.

Source code in src/pyrig_executables/rig/configs/executables/icon.py
@override
def parent_path(self) -> Path:
    """Return the directory the icon lives in.

    Returns:
        The project's `rig/resources` package directory, shared with the
        config file that scaffolds that package's `__init__.py`.
    """
    return ResourcesInitConfigFile.I.parent_path()
stem
stem() -> str

Return "icon" as the icon's filename stem.

Source code in src/pyrig_executables/rig/configs/executables/icon.py
@override
def stem(self) -> str:
    """Return `"icon"` as the icon's filename stem."""
    return "icon"
main

Configuration for the project's main entry-point module.

Scaffolds a main.py containing a callable main function in every project that installs this plugin. The module provides the entry point that the executable builder bundles into a standalone binary, so this config guarantees that a suitable build target always exists.

MainConfigFile

Bases: CopyModuleConfigFile

Scaffolding for the project's main.py entry-point module.

Copies this plugin's own entry-point module into the target project as main.py. Once the file exists, a project's own implementation stands rather than being overwritten, as long as it still satisfies the entry-point contract that is_correct checks for.

copy_module
copy_module() -> ModuleType

Return the pyrig_executables.main module used as main.py scaffolding.

Source code in src/pyrig_executables/rig/configs/executables/main.py
@override
def copy_module(self) -> ModuleType:
    """Return the `pyrig_executables.main` module used as `main.py` scaffolding."""
    return main_module
has_callable_main
has_callable_main() -> bool

Return whether the target file contains the text def main.

Source code in src/pyrig_executables/rig/configs/executables/main.py
def has_callable_main(self) -> bool:
    """Return whether the target file contains the text `def main`."""
    return "def main" in self.read_content()
has_main_guard
has_main_guard() -> bool

Return whether the target module's file contains the __main__ guard.

Matched via plain substring search, so the guard text must appear exactly as returned by main_guard.

Returns:

Type Description
bool

True if the guard snippet is present in the file.

Source code in src/pyrig_executables/rig/configs/executables/main.py
def has_main_guard(self) -> bool:
    """Return whether the target module's file contains the `__main__` guard.

    Matched via plain substring search, so the guard text must appear
    exactly as returned by `main_guard`.

    Returns:
        `True` if the guard snippet is present in the file.
    """
    return self.main_guard() in self.read_content()
is_correct
is_correct() -> bool

Return whether the project's main.py is valid.

Overrides the inherited content check: main.py is correct once the target file contains the text def main and the canonical __main__ execution guard, regardless of what the function body does. This lets a project's own entry-point implementation stand unmodified.

Returns:

Type Description
bool

True if both the def main text and the __main__ guard are

bool

present in the target file.

Source code in src/pyrig_executables/rig/configs/executables/main.py
@override
def is_correct(self) -> bool:
    """Return whether the project's `main.py` is valid.

    Overrides the inherited content check: `main.py` is correct once the
    target file contains the text `def main` and the canonical `__main__`
    execution guard, regardless of what the function body does. This lets
    a project's own entry-point implementation stand unmodified.

    Returns:
        `True` if both the `def main` text and the `__main__` guard are
        present in the target file.
    """
    return self.has_callable_main() and self.has_main_guard()
main_guard
main_guard() -> str

Return the canonical __main__ execution guard snippet.

Returns:

Type Description
str

The if __name__ == "__main__" block that calls main.

Source code in src/pyrig_executables/rig/configs/executables/main.py
def main_guard(self) -> str:
    """Return the canonical `__main__` execution guard snippet.

    Returns:
        The `if __name__ == "__main__"` block that calls `main`.
    """
    return f"""if __name__ == "__main__":
{main_func.__name__}()"""

version_control

Version control configuration adjusted for standalone executable distribution.

Extends the base version control setup, local or remote, to account for building and publishing standalone executables alongside a release.

remote

Overrides for the project's GitHub-hosted remote repository configuration.

workflows

Overrides for the project's GitHub Actions workflow configuration.

executable

Reusable workflow for building standalone executables.

ExecutableWorkflowConfigFile

Bases: WorkflowConfigFile

Build and upload an executable for each supported operating system.

concurrency_cancel_in_progress
concurrency_cancel_in_progress() -> bool

Return False; release builds must not be cancelled.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
@override
def concurrency_cancel_in_progress(self) -> bool:
    """Return `False`; release builds must not be cancelled."""
    return False
executable_artifact_name
executable_artifact_name(os: str) -> str

Return the workflow-artifact name for a runner.

Parameters:

Name Type Description Default
os str

Matrix OS label, or "*" to match every OS.

required
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def executable_artifact_name(self, os: str) -> str:
    """Return the workflow-artifact name for a runner.

    Args:
        os: Matrix OS label, or `"*"` to match every OS.
    """
    return f"executable-{os}"
job_build
job_build() -> dict[str, Any]

Build and upload executables on their target platforms.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def job_build(self) -> dict[str, Any]:
    """Build and upload executables on their target platforms."""
    return self.job(
        self.job_build,
        strategy=self.strategy_matrix_os(),
        permissions=self.permissions_job_build(),
        runs_on=self.insert_matrix_os(),
        steps=self.steps_build(),
        timeout_minutes=60,
    )
jobs
jobs() -> tuple[Callable[[], dict[str, Any]], ...]

Return the executable build matrix.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
@override
def jobs(self) -> tuple[Callable[[], dict[str, Any]], ...]:
    """Return the executable build matrix."""
    return (self.job_build,)
permissions_job_build
permissions_job_build() -> dict[str, str]

Return read-only repository permissions for checkout.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def permissions_job_build(self) -> dict[str, str]:
    """Return read-only repository permissions for checkout."""
    return self.permission_contents()
stem
stem() -> str

Return the workflow file stem, executable.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
@override
def stem(self) -> str:
    """Return the workflow file stem, `executable`."""
    return "executable"
step_build_executable
step_build_executable() -> dict[str, Any]

Run the generated executable build script.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def step_build_executable(self) -> dict[str, Any]:
    """Run the generated executable build script."""
    return self.step(
        self.step_build_executable,
        run=str(
            Args(
                ShellFormatter.I.dialect(),
                BuildExecutableConfigFile.I.path().as_posix(),
            ),
        ),
    )
step_upload_executable
step_upload_executable() -> dict[str, Any]

Upload this platform's executable artifact.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def step_upload_executable(self) -> dict[str, Any]:
    """Upload this platform's executable artifact."""
    return self.step_upload_artifact(
        self.step_upload_executable,
        name=self.executable_artifact_name(self.insert_matrix_os()),
        path=PackageManager.I.dist_dir(),
    )
steps_build
steps_build() -> list[dict[str, Any]]

Return setup, executable build, and artifact-upload steps.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
def steps_build(self) -> list[dict[str, Any]]:
    """Return setup, executable build, and artifact-upload steps."""
    return [
        *self.steps_core_installed_setup(),
        self.step_build_executable(),
        self.step_upload_executable(),
    ]
workflow_triggers
workflow_triggers() -> dict[str, Any]

Return a reusable-workflow trigger.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
@override
def workflow_triggers(self) -> dict[str, Any]:
    """Return a reusable-workflow trigger."""
    return self.on_workflow_call()
release

Release integration for the reusable executable workflow.

ReleaseWorkflowConfigFile

Bases: ReleaseWorkflowConfigFile

Call the executable workflow and attach its artifacts to the release.

job_executable
job_executable() -> dict[str, Any]

Call the reusable executable build workflow.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
def job_executable(self) -> dict[str, Any]:
    """Call the reusable executable build workflow."""
    return self.job_workflow_call(
        self.job_executable,
        workflow=ExecutableWorkflowConfigFile,
    )
job_publish_needs
job_publish_needs() -> tuple[MethodType, ...]

Return the jobs required before publishing.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
@override
def job_publish_needs(self) -> tuple[MethodType, ...]:
    """Return the jobs required before publishing."""
    return (*super().job_publish_needs(), self.job_executable)
jobs
jobs() -> tuple[Callable[[], dict[str, Any]], ...]

Return builders for the executable and base release jobs.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
@override
def jobs(self) -> tuple[Callable[[], dict[str, Any]], ...]:
    """Return builders for the executable and base release jobs."""
    return (
        self.job_executable,
        *super().jobs(),
    )
step_download_executables
step_download_executables() -> dict[str, Any]

Build a step that merges executable artifacts into dist/.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
def step_download_executables(self) -> dict[str, Any]:
    """Build a step that merges executable artifacts into `dist/`."""
    return self.step_download_artifact(
        self.step_download_executables,
        pattern=ExecutableWorkflowConfigFile.I.executable_artifact_name("*"),
        path=PackageManager.I.dist_dir(),
        merge_multiple=True,
    )
steps_publish
steps_publish() -> list[dict[str, Any]]

Insert executable downloads immediately before release creation.

Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
@override
def steps_publish(self) -> list[dict[str, Any]]:
    """Insert executable downloads immediately before release creation."""
    steps = super().steps_publish()
    create_release_id = self.step_id_from_method(self.step_create_release)
    create_release_index = next(
        index for index, step in enumerate(steps) if step["id"] == create_release_id
    )
    steps.insert(create_release_index, self.step_download_executables())
    return steps

resources

Bundled static resource files read when scaffolding executable projects.

Holds verbatim resource files that config file subclasses copy into a project that builds a standalone executable.

tools

Wrappers for the external CLI tools this plugin contributes to a project.

executables

Tool wrappers for building standalone executables.

builder

Tool wrapper for bundling the project into standalone release executables.

ExecutableBuilder

Bases: Tool

Wrapper for pyinstaller, the tool that builds standalone executables.

Exposes a project-info badge showing the cumulative download count across all GitHub release assets, linking to the releases page where the built executables are published.

build_args
build_args(
    *args: str,
    name: str,
    entry_point: Path,
    icon: Path,
    collect_all_modules: Iterable[ModuleType] = (),
    collect_data_modules: Iterable[ModuleType] = ()
) -> Args

Build the pyinstaller command that bundles a single-file executable.

Bundles each module with its own --collect-all or --collect-data flag rather than pointing --add-data at a path. This preserves the package layout so resources stay locatable at runtime through importlib.resources in both development and the frozen executable, and sidesteps the platform-specific separator --add-data requires. --collect-all also pulls in a module's submodules and any binaries it ships, so it suits modules that are not known to be pure data (e.g. an extension point where callers may pass anything); --collect-data is narrower and suits known pure-data packages, avoiding unrelated submodules/binaries. The build runs in console mode by default; pass --windowed through *args for a GUI application that should run without a console window (this instead produces a .app bundle directory on macOS).

Parameters:

Name Type Description Default
*args str

Additional arguments forwarded to pyinstaller, inserted after the resource flags and before entry_point.

()
name str

Output name for the executable (without an OS-specific extension; pyinstaller appends .exe on Windows).

required
entry_point Path

Path to the entry-point script to bundle.

required
icon Path

Path to the icon image. A non-native format (e.g. PNG) is converted to the per-OS format (.ico / .icns) at build time via Pillow; ignored on Linux.

required
collect_all_modules Iterable[ModuleType]

Modules to bundle in full (data, submodules, and binaries), one --collect-all flag per module.

()
collect_data_modules Iterable[ModuleType]

Modules whose data files only are bundled, one --collect-data flag per module.

()

Returns:

Type Description
Args

Args for the pyinstaller command.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
def build_args(
    self,
    *args: str,
    name: str,
    entry_point: Path,
    icon: Path,
    collect_all_modules: Iterable[ModuleType] = (),
    collect_data_modules: Iterable[ModuleType] = (),
) -> Args:
    """Build the `pyinstaller` command that bundles a single-file executable.

    Bundles each module with its own `--collect-all` or `--collect-data`
    flag rather than pointing `--add-data` at a path. This preserves the
    package layout so resources stay locatable at runtime through
    `importlib.resources` in both development and the frozen
    executable, and sidesteps the platform-specific separator
    `--add-data` requires. `--collect-all` also pulls in a module's
    submodules and any binaries it ships, so it suits modules that are
    not known to be pure data (e.g. an extension point where callers may
    pass anything); `--collect-data` is narrower and suits known
    pure-data packages, avoiding unrelated submodules/binaries. The
    build runs in console mode by default; pass `--windowed` through
    `*args` for a GUI application that should run without a console
    window (this instead produces a `.app` bundle directory on macOS).

    Args:
        *args: Additional arguments forwarded to `pyinstaller`, inserted
            after the resource flags and before `entry_point`.
        name: Output name for the executable (without an OS-specific
            extension; `pyinstaller` appends `.exe` on Windows).
        entry_point: Path to the entry-point script to bundle.
        icon: Path to the icon image. A non-native format (e.g. PNG) is
            converted to the per-OS format (`.ico` / `.icns`) at build
            time via Pillow; ignored on Linux.
        collect_all_modules: Modules to bundle in full (data,
            submodules, and binaries), one `--collect-all` flag per
            module.
        collect_data_modules: Modules whose data files only are
            bundled, one `--collect-data` flag per module.

    Returns:
        Args for the `pyinstaller` command.
    """
    collect_all = (
        f"--collect-all={module.__name__}" for module in collect_all_modules
    )
    collect_data = (
        f"--collect-data={module.__name__}" for module in collect_data_modules
    )
    return self.args(
        "--onefile",
        f"--name={name}",
        f"--icon={icon.as_posix()}",
        *collect_all,
        *collect_data,
        *args,
        entry_point.as_posix(),
    )
dev_dependencies
dev_dependencies() -> tuple[str, ...]

Return the dev dependencies required to build executables.

Extends the default with pillow so pyinstaller can convert a non-native icon image (e.g. PNG) into the per-OS icon format (.ico / .icns) at build time.

Returns:

Type Description
tuple[str, ...]

pyinstaller and pillow.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def dev_dependencies(self) -> tuple[str, ...]:
    """Return the dev dependencies required to build executables.

    Extends the default with `pillow` so `pyinstaller` can convert a
    non-native icon image (e.g. PNG) into the per-OS icon format (`.ico`
    / `.icns`) at build time.

    Returns:
        `pyinstaller` and `pillow`.
    """
    return (*super().dev_dependencies(), "pillow")
group
group() -> str

Return Group.PROJECT_INFO.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def group(self) -> str:
    """Return `Group.PROJECT_INFO`."""
    return Group.PROJECT_INFO
image_url
image_url() -> str

Return the shields.io URL for the GitHub release downloads badge.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def image_url(self) -> str:
    """Return the shields.io URL for the GitHub release downloads badge."""
    owner, repo = (
        VersionController.I.repo_owner(),
        PackageManager.I.project_name(),
    )
    return f"https://img.shields.io/github/downloads/{owner}/{repo}/total?logo=github&label=downloads"
link_url
link_url() -> str

Return the GitHub releases page URL where the binaries are published.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def link_url(self) -> str:
    """Return the GitHub releases page URL where the binaries are published."""
    return RemoteVersionController.I.releases_url()
name
name() -> str

Return 'pyinstaller'.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def name(self) -> str:
    """Return `'pyinstaller'`."""
    return "pyinstaller"
version_control_ignore_patterns
version_control_ignore_patterns() -> tuple[str, ...]

Return the build artifact paths to exclude from version control.

Returns:

Type Description
str

The pyinstaller build artifacts: the dist/ output directory,

...

the generated *.spec files, and the build/ working directory.

Source code in src/pyrig_executables/rig/tools/executables/builder.py
@override
def version_control_ignore_patterns(self) -> tuple[str, ...]:
    """Return the build artifact paths to exclude from version control.

    Returns:
        The `pyinstaller` build artifacts: the `dist/` output directory,
        the generated `*.spec` files, and the `build/` working directory.
    """
    return (*super().version_control_ignore_patterns(), "*.spec", "build/")

version_control

Version control tool customizations for standalone executable distribution.

remote

Overrides for the project's remote version control tooling.

controller

Customization of the remote version controller.

RemoteVersionController

Bases: RemoteVersionController

Overrides the base class to include executable artifacts in releases.

create_release_args
create_release_args(
    *args: str, tag: str, files: Iterable[str] = ()
) -> Args

Build release arguments with the executable artifacts included.

Parameters:

Name Type Description Default
*args str

Additional arguments forwarded to gh release create.

()
tag str

The tag to release, also used as the release title.

required
files Iterable[str]

Release asset paths to upload alongside the executable artifacts.

()

Returns:

Type Description
Args

Args for gh release create with every file in dist/ attached.

Source code in src/pyrig_executables/rig/tools/version_control/remote/controller.py
@override
def create_release_args(
    self,
    *args: str,
    tag: str,
    files: Iterable[str] = (),
) -> Args:
    """Build release arguments with the executable artifacts included.

    Args:
        *args: Additional arguments forwarded to `gh release create`.
        tag: The tag to release, also used as the release title.
        files: Release asset paths to upload alongside the executable
            artifacts.

    Returns:
        Args for `gh release create` with every file in `dist/` attached.
    """
    return super().create_release_args(
        *args,
        tag=tag,
        files=(
            f"{PackageManager.I.dist_dir().as_posix()}/*",
            *files,
        ),
    )