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 ¶
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 ¶
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
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 the project.
This command runs the project's main.py file as the __main__ module.
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() -> Iterable[ModuleType]
collect_data_modules() -> Iterable[ModuleType]
Return the project's resource package for data collection.
Return the config files required before generating the script.
script() -> str
Return the command that builds the executable.
Source code in src/pyrig_executables/rig/configs/executables/build.py
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.
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
|
|
bool
|
otherwise. |
Source code in src/pyrig_executables/rig/configs/executables/icon.py
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() -> ModuleType
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
|
|
Source code in src/pyrig_executables/rig/configs/executables/main.py
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
|
|
bool
|
present in the target file. |
Source code in src/pyrig_executables/rig/configs/executables/main.py
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.
Reusable workflow for building standalone executables.
Bases: WorkflowConfigFile
Build and upload an executable for each supported operating system.
Return the workflow-artifact name for a runner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
os
|
str
|
Matrix OS label, or |
required |
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
Build and upload executables on their target platforms.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
Return read-only repository permissions for checkout.
Run the generated executable build script.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
Upload this platform's executable artifact.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
Return setup, executable build, and artifact-upload steps.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/executable.py
Release integration for the reusable executable workflow.
Bases: ReleaseWorkflowConfigFile
Call the executable workflow and attach its artifacts to the release.
Call the reusable executable build workflow.
job_publish_needs() -> tuple[MethodType, ...]
Return the jobs required before publishing.
Return builders for the executable and base release jobs.
Build a step that merges executable artifacts into dist/.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
Insert executable downloads immediately before release creation.
Source code in src/pyrig_executables/rig/configs/version_control/remote/workflows/release.py
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(
*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 |
()
|
name
|
str
|
Output name for the executable (without an OS-specific
extension; |
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 ( |
required |
collect_all_modules
|
Iterable[ModuleType]
|
Modules to bundle in full (data,
submodules, and binaries), one |
()
|
collect_data_modules
|
Iterable[ModuleType]
|
Modules whose data files only are
bundled, one |
()
|
Returns:
| Type | Description |
|---|---|
Args
|
Args for the |
Source code in src/pyrig_executables/rig/tools/executables/builder.py
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, ...]
|
|
Source code in src/pyrig_executables/rig/tools/executables/builder.py
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
Return the build artifact paths to exclude from version control.
Returns:
| Type | Description |
|---|---|
str
|
The |
...
|
the generated |
Source code in src/pyrig_executables/rig/tools/executables/builder.py
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.
Bases: RemoteVersionController
Overrides the base class to include executable artifacts in releases.
Build release arguments with the executable artifacts included.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*args
|
str
|
Additional arguments forwarded to |
()
|
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 |