diff --git a/dev/changelog/index.html b/dev/changelog/index.html index 3f7c9d9..5800805 100644 --- a/dev/changelog/index.html +++ b/dev/changelog/index.html @@ -7,4 +7,4 @@ .gdesc-inner { font-size: 0.75rem; } body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color);} body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color);} - body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}
Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added:

  • Add cache management command

Fixed:

  • Bootstrapping is now safe across multiple processes (a shared resource message is displayed if another process is already bootstrapping)
  • The pip management command is now resilient to cache removal
  • Management commands now properly support the -h/--help flag

0.19.0 - 2024-04-24

Added:

  • Add remove management command
  • Update dependencies

Fixed:

  • Fix UV and the VIRTUAL_ENV environment variable on non-Windows systems

0.18.0 - 2024-04-22

Added:

  • Update PyPy distributions to 7.3.15

Fixed:

  • Fix resolution for legacy 3.7 builds

0.17.0 - 2024-04-21

Added:

  • Support using UV for virtual environment creation and project installation
  • The PATH environment variable is now updated to include the installation's directory of executables
  • Update default distributions to 20240415

Fixed:

  • Dependencies are now locked

0.16.0 - 2024-03-24

Added:

  • Add PYAPP_IS_GUI option to support graphical applications

0.15.1 - 2024-03-03

Fixed:

  • Fix reading metadata with Windows line endings during build time from embedded distributions

0.15.0 - 2024-03-01

Added:

  • Update default distributions to 20240224
  • Update default Python version to 3.12
  • Statically link the C runtime on Windows
  • Add PYAPP_PROJECT_FEATURES option for selecting extras
  • Add new execution mode option PYAPP_EXEC_NOTEBOOK for running Jupyter notebooks

Fixed:

  • Properly resolve correct default distributions on MinGW-w64
  • Fix embedding custom distributions
  • Ignore nonexistent variant options for 3.7 distributions

0.14.0 - 2024-01-21

Added:

  • Update default distributions to 20240107

0.13.0 - 2023-12-31

Added:

  • Allow for forwarding of unknown management commands e.g. if apps have their own self commands

Fixed:

  • Remove patch for powerpc64le now that the transitive dependency ring is fixed

0.12.0 - 2023-10-07

Added:

  • Update default distributions to 20231002, adding support for Python 3.12

0.11.1 - 2023-09-14

Fixed:

  • Fix the Python path for the pypy2.7 distribution

0.11.0 - 2023-09-07

Added:

  • Update default distributions to 20230826
  • Build releases with codegen-units=1

0.10.1 - 2023-06-26

Fixed:

  • Fix regression in the PYAPP_EXEC_SPEC option

0.10.0 - 2023-06-26

Added:

  • Add PYAPP_EXEC_SCRIPT option for executing a project using a script
  • Add support for overriding the installation directory
  • Make the PYAPP_DISTRIBUTION_PATH option implicitly enable PYAPP_DISTRIBUTION_EMBED

Fixed:

  • Properly handle cases where options contain line feed characters

0.9.0 - 2023-06-21

Changed:

  • Custom distributions should now define the relative path to the site-packages directory

Added:

  • Add support for PyPy distributions
  • Add the PYAPP_UPGRADE_VIRTUALENV option to create virtual environments with virtualenv rather than the stdlib's venv
  • Add support for custom distributions with bzip2 compression

Fixed:

  • Properly handle cases where temporary files are on different filesystems
  • Fix regression in the metadata management command on Windows
  • Improve error messages when running binaries that were misconfigured

0.8.0 - 2023-06-09

Added:

  • Add the ability to externally manage pip with the PYAPP_PIP_EXTERNAL and PYAPP_PIP_VERSION options
  • Allow for project installation with a dependency file using the PYAPP_PROJECT_DEPENDENCY_FILE option
  • Add management command to directly invoke pip with the installed Python
  • Add management command to output the path to the installed Python

Fixed:

  • Fix builds for PowerPC64

0.7.0 - 2023-05-24

Changed:

  • Installations use virtual environments by default; the previous behavior can be enabled with the PYAPP_FULL_ISOLATION option

Added:

  • Update default CPython distributions
  • Add -r/--restore flag to the update command
  • Allow for disabling of management commands
  • Add ability to expose optional commands
  • Add optional command to directly invoke the installed Python
  • Run Python in isolated mode
  • Execute projects with execvp on non-Windows systems
  • When the management command is enabled its name is available at runtime via an environment variable
  • Add different installation wait message for when there is a guarantee of no side effects (e.g. pip's --only-binary :all:)

0.6.0 - 2023-05-16

Added:

  • Add PYAPP_PROJECT_PATH option to embed the project for installation at runtime
  • Add PYAPP_DISTRIBUTION_PATH option to embed the distribution from a local path rather than fetching the source

Fixed:

  • Properly handle distributions packed as ZIP files

0.5.0 - 2023-05-11

Added:

  • Strip symbols from release builds

Fixed:

  • Properly pass through all required environment variable options to cross compilation images
  • Properly allow configuration of the template used for the metadata command

0.4.0 - 2023-05-11

Changed:

  • Rename PYAPP_STARSHIP_PROMPT option to PYAPP_METADATA_TEMPLATE

Added:

  • Add PYAPP_PIP_EXTRA_ARGS option to provide extra pip install arguments
  • Add PYAPP_PIP_ALLOW_CONFIG option to allow runtime configuration of pip
  • Add configuration for correct cross compilation

0.3.1 - 2023-05-10

Fixed:

  • Fix default distribution detection for Linux on architectures other than x86_64

0.3.0 - 2023-05-10

Changed:

  • Rename PYAPP_DISTRIBUTION_COMPRESSION option to PYAPP_DISTRIBUTION_FORMAT

Added:

  • Add --pre flag to the self update command to allow pre-release and development versions
  • Add environment variable for detection
  • Add PYAPP_SELF_COMMAND option to control the name of the management command
  • Add PYAPP_SKIP_INSTALL option to skip project installation
  • Remove dependence on OpenSSL

Fixed:

  • Properly display error messages from pip install commands
  • Fix project version reading for the metadata command on non-Windows systems

0.2.0 - 2023-05-07

This is the initial public release.

\ No newline at end of file + body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color);}
Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added:

  • Add cache management command
  • Update dependencies

Fixed:

  • Bootstrapping is now safe across multiple processes (a shared resource message is displayed if another process is already bootstrapping)
  • The pip management command is now resilient to cache removal
  • Management commands now properly support the -h/--help flag

0.19.0 - 2024-04-24

Added:

  • Add remove management command
  • Update dependencies

Fixed:

  • Fix UV and the VIRTUAL_ENV environment variable on non-Windows systems

0.18.0 - 2024-04-22

Added:

  • Update PyPy distributions to 7.3.15

Fixed:

  • Fix resolution for legacy 3.7 builds

0.17.0 - 2024-04-21

Added:

  • Support using UV for virtual environment creation and project installation
  • The PATH environment variable is now updated to include the installation's directory of executables
  • Update default distributions to 20240415

Fixed:

  • Dependencies are now locked

0.16.0 - 2024-03-24

Added:

  • Add PYAPP_IS_GUI option to support graphical applications

0.15.1 - 2024-03-03

Fixed:

  • Fix reading metadata with Windows line endings during build time from embedded distributions

0.15.0 - 2024-03-01

Added:

  • Update default distributions to 20240224
  • Update default Python version to 3.12
  • Statically link the C runtime on Windows
  • Add PYAPP_PROJECT_FEATURES option for selecting extras
  • Add new execution mode option PYAPP_EXEC_NOTEBOOK for running Jupyter notebooks

Fixed:

  • Properly resolve correct default distributions on MinGW-w64
  • Fix embedding custom distributions
  • Ignore nonexistent variant options for 3.7 distributions

0.14.0 - 2024-01-21

Added:

  • Update default distributions to 20240107

0.13.0 - 2023-12-31

Added:

  • Allow for forwarding of unknown management commands e.g. if apps have their own self commands

Fixed:

  • Remove patch for powerpc64le now that the transitive dependency ring is fixed

0.12.0 - 2023-10-07

Added:

  • Update default distributions to 20231002, adding support for Python 3.12

0.11.1 - 2023-09-14

Fixed:

  • Fix the Python path for the pypy2.7 distribution

0.11.0 - 2023-09-07

Added:

  • Update default distributions to 20230826
  • Build releases with codegen-units=1

0.10.1 - 2023-06-26

Fixed:

  • Fix regression in the PYAPP_EXEC_SPEC option

0.10.0 - 2023-06-26

Added:

  • Add PYAPP_EXEC_SCRIPT option for executing a project using a script
  • Add support for overriding the installation directory
  • Make the PYAPP_DISTRIBUTION_PATH option implicitly enable PYAPP_DISTRIBUTION_EMBED

Fixed:

  • Properly handle cases where options contain line feed characters

0.9.0 - 2023-06-21

Changed:

  • Custom distributions should now define the relative path to the site-packages directory

Added:

  • Add support for PyPy distributions
  • Add the PYAPP_UPGRADE_VIRTUALENV option to create virtual environments with virtualenv rather than the stdlib's venv
  • Add support for custom distributions with bzip2 compression

Fixed:

  • Properly handle cases where temporary files are on different filesystems
  • Fix regression in the metadata management command on Windows
  • Improve error messages when running binaries that were misconfigured

0.8.0 - 2023-06-09

Added:

  • Add the ability to externally manage pip with the PYAPP_PIP_EXTERNAL and PYAPP_PIP_VERSION options
  • Allow for project installation with a dependency file using the PYAPP_PROJECT_DEPENDENCY_FILE option
  • Add management command to directly invoke pip with the installed Python
  • Add management command to output the path to the installed Python

Fixed:

  • Fix builds for PowerPC64

0.7.0 - 2023-05-24

Changed:

  • Installations use virtual environments by default; the previous behavior can be enabled with the PYAPP_FULL_ISOLATION option

Added:

  • Update default CPython distributions
  • Add -r/--restore flag to the update command
  • Allow for disabling of management commands
  • Add ability to expose optional commands
  • Add optional command to directly invoke the installed Python
  • Run Python in isolated mode
  • Execute projects with execvp on non-Windows systems
  • When the management command is enabled its name is available at runtime via an environment variable
  • Add different installation wait message for when there is a guarantee of no side effects (e.g. pip's --only-binary :all:)

0.6.0 - 2023-05-16

Added:

  • Add PYAPP_PROJECT_PATH option to embed the project for installation at runtime
  • Add PYAPP_DISTRIBUTION_PATH option to embed the distribution from a local path rather than fetching the source

Fixed:

  • Properly handle distributions packed as ZIP files

0.5.0 - 2023-05-11

Added:

  • Strip symbols from release builds

Fixed:

  • Properly pass through all required environment variable options to cross compilation images
  • Properly allow configuration of the template used for the metadata command

0.4.0 - 2023-05-11

Changed:

  • Rename PYAPP_STARSHIP_PROMPT option to PYAPP_METADATA_TEMPLATE

Added:

  • Add PYAPP_PIP_EXTRA_ARGS option to provide extra pip install arguments
  • Add PYAPP_PIP_ALLOW_CONFIG option to allow runtime configuration of pip
  • Add configuration for correct cross compilation

0.3.1 - 2023-05-10

Fixed:

  • Fix default distribution detection for Linux on architectures other than x86_64

0.3.0 - 2023-05-10

Changed:

  • Rename PYAPP_DISTRIBUTION_COMPRESSION option to PYAPP_DISTRIBUTION_FORMAT

Added:

  • Add --pre flag to the self update command to allow pre-release and development versions
  • Add environment variable for detection
  • Add PYAPP_SELF_COMMAND option to control the name of the management command
  • Add PYAPP_SKIP_INSTALL option to skip project installation
  • Remove dependence on OpenSSL

Fixed:

  • Properly display error messages from pip install commands
  • Fix project version reading for the metadata command on non-Windows systems

0.2.0 - 2023-05-07

This is the initial public release.

\ No newline at end of file diff --git a/dev/search/search_index.json b/dev/search/search_index.json index ee6ed31..6075840 100644 --- a/dev/search/search_index.json +++ b/dev/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"PyApp","text":"CI/CD Docs Project Meta

PyApp is a wrapper for Python applications that bootstrap themselves at runtime.

See the how-to for a detailed example walkthrough.

"},{"location":"#features","title":"Features","text":""},{"location":"#license","title":"License","text":"

PyApp is distributed under the terms of any of the following licenses:

"},{"location":"#navigation","title":"Navigation","text":"

Documentation for specific versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released.

Desktop readers can use special keyboard shortcuts:

Keys Action Navigate to the \"previous\" page Navigate to the \"next\" page Display the search modal"},{"location":"build/","title":"Building","text":"

Before building your application, you must configure your project at the very least.

After you have done that, your application can be built using a local copy of this repository or via installation with Cargo.

Tip

For a more streamlined workflow, consider using the built-in app build target of Hatch.

"},{"location":"build/#local-repository","title":"Local repository","text":"

The recommended method of downloading the repository is via the source asset archives attached to each release.

The latest release can always be downloaded at the following URLs:

Specific releases may be downloaded at the following URLs, replacing X.Y.Z with the desired version:

After unpacking the repository, enter the directory and run:

cargo build --release\n

The executable will be located at target/release/pyapp.exe if on Windows or target/release/pyapp otherwise. If a particular target has been set (or when cross compiling since one will always be set), then the release directory will be nested one level deeper under target/<TARGET>.

"},{"location":"build/#installation","title":"Installation","text":"

Select the directory in which to build the executable with the --root option and run:

cargo install pyapp --force --root <DIR>\n

The executable will be located at <DIR>/bin/pyapp.exe if on Windows or <DIR>/bin/pyapp otherwise.

Specific versions may be chosen with the --version flag.

Note: If you want to cross compile, this method of building is currently unsupported.

"},{"location":"build/#cross-compilation","title":"Cross compilation","text":"

Configuration for cross is validated by CI to ensure all known environment variable options are passed through to the containers.

When embedding the project or the distribution using a local path, you must use the local repository way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.

"},{"location":"changelog/","title":"Changelog","text":"

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

"},{"location":"changelog/#unreleased","title":"Unreleased","text":"

Added:

Fixed:

"},{"location":"changelog/#0190-2024-04-24","title":"0.19.0 - 2024-04-24","text":"

Added:

Fixed:

"},{"location":"changelog/#0180-2024-04-22","title":"0.18.0 - 2024-04-22","text":"

Added:

Fixed:

"},{"location":"changelog/#0170-2024-04-21","title":"0.17.0 - 2024-04-21","text":"

Added:

Fixed:

"},{"location":"changelog/#0160-2024-03-24","title":"0.16.0 - 2024-03-24","text":"

Added:

"},{"location":"changelog/#0151-2024-03-03","title":"0.15.1 - 2024-03-03","text":"

Fixed:

"},{"location":"changelog/#0150-2024-03-01","title":"0.15.0 - 2024-03-01","text":"

Added:

Fixed:

"},{"location":"changelog/#0140-2024-01-21","title":"0.14.0 - 2024-01-21","text":"

Added:

"},{"location":"changelog/#0130-2023-12-31","title":"0.13.0 - 2023-12-31","text":"

Added:

Fixed:

"},{"location":"changelog/#0120-2023-10-07","title":"0.12.0 - 2023-10-07","text":"

Added:

"},{"location":"changelog/#0111-2023-09-14","title":"0.11.1 - 2023-09-14","text":"

Fixed:

"},{"location":"changelog/#0110-2023-09-07","title":"0.11.0 - 2023-09-07","text":"

Added:

"},{"location":"changelog/#0101-2023-06-26","title":"0.10.1 - 2023-06-26","text":"

Fixed:

"},{"location":"changelog/#0100-2023-06-26","title":"0.10.0 - 2023-06-26","text":"

Added:

Fixed:

"},{"location":"changelog/#090-2023-06-21","title":"0.9.0 - 2023-06-21","text":"

Changed:

Added:

Fixed:

"},{"location":"changelog/#080-2023-06-09","title":"0.8.0 - 2023-06-09","text":"

Added:

Fixed:

"},{"location":"changelog/#070-2023-05-24","title":"0.7.0 - 2023-05-24","text":"

Changed:

Added:

"},{"location":"changelog/#060-2023-05-16","title":"0.6.0 - 2023-05-16","text":"

Added:

Fixed:

"},{"location":"changelog/#050-2023-05-11","title":"0.5.0 - 2023-05-11","text":"

Added:

Fixed:

"},{"location":"changelog/#040-2023-05-11","title":"0.4.0 - 2023-05-11","text":"

Changed:

Added:

"},{"location":"changelog/#031-2023-05-10","title":"0.3.1 - 2023-05-10","text":"

Fixed:

"},{"location":"changelog/#030-2023-05-10","title":"0.3.0 - 2023-05-10","text":"

Changed:

Added:

Fixed:

"},{"location":"changelog/#020-2023-05-07","title":"0.2.0 - 2023-05-07","text":"

This is the initial public release.

"},{"location":"examples/","title":"Examples","text":"

The following examples do not illustrate every possible combination of options but rather some common use cases.

"},{"location":"examples/#single-project-basic","title":"Single project basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z"},{"location":"examples/#single-project-embedded","title":"Single project embedded","text":"Option Value PYAPP_PROJECT_PATH ./proj-X.Y.Z.dev0-py3-none-any.whl"},{"location":"examples/#dependency-file-basic","title":"Dependency file basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt

Note

The default execution will be python -m proj at runtime.

"},{"location":"examples/#dependency-file-with-script","title":"Dependency file with script","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt PYAPP_EXEC_SCRIPT ./script.py"},{"location":"examples/#execution-with-object-reference","title":"Execution with object reference","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_EXEC_SPEC proj.cli:main"},{"location":"examples/#specific-known-distribution","title":"Specific known distribution","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PYTHON_VERSION 3.10"},{"location":"examples/#custom-remote-distribution-basic","title":"Custom remote distribution basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_SOURCE https://foo.bar.baz/archive.tar.gz"},{"location":"examples/#custom-remote-distribution-embedded","title":"Custom remote distribution embedded","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_SOURCE https://foo.bar.baz/archive.tar.gz PYAPP_DISTRIBUTION_EMBED true"},{"location":"examples/#custom-embedded-local-distribution","title":"Custom embedded local distribution","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_PATH ./archive.tar.gz"},{"location":"examples/#offline-installation","title":"Offline installation","text":"Option Value PYAPP_PROJECT_PATH ./proj-X.Y.Z-py3-none-any.whl PYAPP_DISTRIBUTION_PATH ./archive.tar.gz PYAPP_PIP_EXTRA_ARGS --no-deps"},{"location":"examples/#reproducible-installation-with-custom-package-index","title":"Reproducible installation with custom package index","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt PYAPP_PIP_EXTRA_ARGS --only-binary :all: --index-url URL"},{"location":"how-to/","title":"How-to","text":"

What follows is a short example showing the end-to-end experience from building an application to running the application as a user.

"},{"location":"how-to/#install-rust","title":"Install Rust","text":"

Follow the instructions to install Rust and make sure the package manager Cargo is on your PATH.

"},{"location":"how-to/#get-pyapp","title":"Get PyApp","text":"

In order to build applications with PyApp, you must first download the source code. Here we will download the latest release.

Linux/macOSWindows
  1. curl https://github.com/ofek/pyapp/releases/latest/download/source.tar.gz -Lo pyapp-source.tar.gz
  2. tar -xzf pyapp-source.tar.gz
  3. mv pyapp-v* pyapp-latest
  4. cd pyapp-latest
  1. Invoke-WebRequest https://github.com/ofek/pyapp/releases/latest/download/source.zip -OutFile pyapp-source.zip
  2. 7z x pyapp-source.zip
  3. mv pyapp-v* pyapp-latest
  4. cd pyapp-latest
"},{"location":"how-to/#configuration","title":"Configuration","text":"

You must configure the binaries PyApp produces with environment variables. There are many ways to configure applications but here we will define a single package to install from PyPI at a specific version:

Option Value PYAPP_PROJECT_NAME cowsay PYAPP_PROJECT_VERSION 6.0"},{"location":"how-to/#building","title":"Building","text":"

Run:

cargo build --release\n

The executable will be located at target/release/pyapp.exe if on Windows or target/release/pyapp otherwise.

"},{"location":"how-to/#distribution","title":"Distribution","text":"

Be sure to rename the binary to the name of the application (and make it executable on non-Windows systems):

Linux/macOSWindows 
mv target/release/pyapp cowsay && chmod +x cowsay\n
mv target\\release\\pyapp.exe cowsay\n
"},{"location":"how-to/#runtime","title":"Runtime","text":"

After you have distributed the binary to the user, they can execute it directly:

$ ./cowsay -t 'Hello, World!'\n  _____________\n| Hello, World! |\n  =============\n             \\\n              \\\n                ^__^\n                (oo)\\_______\n                (__)\\       )\\/\\\n                    ||----w |\n                    ||     ||\n
"},{"location":"runtime/","title":"Runtime behavior","text":""},{"location":"runtime/#initialization","title":"Initialization","text":"

Applications will bootstrap themselves on the first run. All subsequent invocations will only check if the installation directory exists and nothing else, to maximize CLI responsiveness.

Note

The following diagram shows the possible behavior at runtime. The nodes with rounded edges are conditions and those with jagged edges are actions.

Most nodes are clickable and will take you to the relevant documentation.

flowchart TD\n    INSTALLED([Installed]) -- No --> DISTCACHED([Distribution cached])\n    INSTALLED -- Yes --> MNG([Management enabled])\n    DISTCACHED -- No --> DISTEMBEDDED([Distribution embedded])\n    DISTCACHED -- Yes --> FULLISOLATION([Full isolation])\n    DISTEMBEDDED -- No --> DISTSOURCE[[Cache from source]]\n    DISTEMBEDDED -- Yes --> DISTEXTRACT[[Cache from embedded data]]\n    DISTSOURCE --> FULLISOLATION\n    DISTEXTRACT --> FULLISOLATION\n    FULLISOLATION -- No --> UVENABLED([UV enabled])\n    UVENABLED -- No --> VENV[[Create virtual environment]]\n    UVENABLED -- Yes --> UVCACHED([UV cached])\n    UVCACHED -- No --> DOWNLOADUV[[Download UV]]\n    UVCACHED -- Yes --> VENV\n    DOWNLOADUV --> VENV\n    FULLISOLATION -- Yes --> UNPACK[[Unpack distribution directly]]\n    UNPACK --> UVENABLEDUNPACK([UV enabled])\n    UVENABLEDUNPACK -- No --> EXTERNALPIP[[External pip]]\n    UVENABLEDUNPACK -- Yes --> UVCACHEDUNPACK([UV cached])\n    UVCACHEDUNPACK -- No --> DOWNLOADUVUNPACK[[Download UV]]\n    EXTERNALPIP([External pip]) -- No --> PROJEMBEDDED([Project embedded])\n    EXTERNALPIP -- Yes --> PIPCACHED([pip cached])\n    PIPCACHED -- No --> DOWNLOADPIP[[Download pip]]\n    PIPCACHED -- Yes --> PROJEMBEDDED([Project embedded])\n    DOWNLOADPIP --> PROJEMBEDDED\n    PROJEMBEDDED -- No --> DEPFILE([Dependency file])\n    PROJEMBEDDED -- Yes --> PROJEMBED[[Install from embedded data]]\n    DEPFILE -- No --> SINGLEPROJECT[[Install single project]]\n    DEPFILE -- Yes --> DEPFILEINSTALL[[Install from dependency file]]\n    UVCACHEDUNPACK -- Yes --> PROJEMBEDDED\n    DOWNLOADUVUNPACK --> PROJEMBEDDED\n    VENV --> EXTERNALPIP\n    SINGLEPROJECT --> MNG\n    DEPFILEINSTALL --> MNG\n    PROJEMBED --> MNG\n    MNG -- No --> EXECUTE[[Execute project]]\n    MNG -- Yes --> MNGCMD([Command invoked])\n    MNGCMD -- No --> EXECUTE\n    MNGCMD -- Yes --> MANAGE[[Run management command]]\n    click DISTEMBEDDED href \"../config/distribution/#embedding\"\n    click FULLISOLATION href \"../config/distribution/#full-isolation\"\n    click UVENABLED href \"../config/installation/#uv\"\n    click UVENABLEDUNPACK href \"../config/installation/#uv\"\n    click EXTERNALPIP href \"../config/installation/#externally-managed\"\n    click PROJEMBEDDED href \"../config/project/#embedding\"\n    click DEPFILE href \"../config/project/#dependency-file\"\n    click SINGLEPROJECT href \"../config/project/#identifier\"\n    click DEPFILEINSTALL href \"../config/project/#dependency-file\"\n    click PROJEMBED href \"../config/project/#embedding\"\n    click MNG href \"../config/cli/#management-command\"\n    click MNGCMD href \"../config/cli/#management-command\"\n    click MANAGE href \"#commands\"\n    click EXECUTE href \"../config/project/#execution-mode\"
"},{"location":"runtime/#execution","title":"Execution","text":"

Projects are executed using execvp on non-Windows systems, replacing the process.

To provide consistent behavior on each user's machine:

"},{"location":"runtime/#detection","title":"Detection","text":"

A single environment variable called PYAPP is injected with the value of 1 (by default) when running applications and may be used to detect this mode of installation versus others.

"},{"location":"runtime/#commands","title":"Commands","text":"

Built applications have a single top-level command group named self (by default) and all other invocations will be forwarded to your actual execution logic.

"},{"location":"runtime/#default","title":"Default","text":"

These commands are always exposed.

"},{"location":"runtime/#remove","title":"Remove","text":"
<EXE> self remove\n

This will wipe the installation.

"},{"location":"runtime/#restore","title":"Restore","text":"
<EXE> self restore\n

This will wipe the installation and then reinstall.

"},{"location":"runtime/#update","title":"Update","text":"
<EXE> self update\n

This will update the project to the latest available version in the currently used distribution.

"},{"location":"runtime/#optional","title":"Optional","text":"

These commands are hidden by default and each can be individually exposed by setting its corresponding PYAPP_EXPOSE_<COMMAND> option (e.g. PYAPP_EXPOSE_METADATA) to true or 1.

"},{"location":"runtime/#cache","title":"Cache","text":"
<EXE> self cache [dist|pip|uv]\n

This is the command group for managing the cache. Each subcommand has a -r/--remove flag to remove the cached asset. Not passing that flag will display the location instead.

"},{"location":"runtime/#metadata","title":"Metadata","text":"
<EXE> self metadata\n

This displays customized output based on a template.

"},{"location":"runtime/#pip","title":"pip","text":"
<EXE> self pip\n

This directly invokes pip with the installed Python.

"},{"location":"runtime/#python","title":"Python","text":"
<EXE> self python\n

This directly invokes the installed Python.

"},{"location":"runtime/#python-path","title":"Python path","text":"
<EXE> self python-path\n

This outputs the path to the installed Python.

"},{"location":"users/","title":"Users","text":"

The following is not intended to be a complete enumeration. Be sure to view the development version of this page for an up-to-date listing.

"},{"location":"users/#projects","title":"Projects","text":"

AppleCrate | Datadog QA | FreeMoCap | Hatch | instawow | Litestar | Preservation Workbench | tidal-wave

"},{"location":"config/cli/","title":"Command line configuration","text":""},{"location":"config/cli/#installation-indicator","title":"Installation indicator","text":"

The environment variable that is used for detection may be set to the path of the executable at runtime if you set the PYAPP_PASS_LOCATION option to true or 1. This is useful if your application wishes to in some way manage itself.

"},{"location":"config/cli/#management-command","title":"Management command","text":"

You may set the PYAPP_SELF_COMMAND option to override the default name (self) of the management command group. Setting this to none effectively disables the use of management commands.

When enabled, the value will be available at runtime as the PYAPP_COMMAND_NAME environment variable.

"},{"location":"config/cli/#metadata-template","title":"Metadata template","text":"

You may set a custom template used to output metadata with the PYAPP_METADATA_TEMPLATE option which supports the following placeholders:

Placeholder Description {project} The normalized project name {version} The currently installed version of the project

The default template is {project} v{version} if this option is unset.

This is useful for setting custom commands for the Starship prompt. The following example configuration assumes that the built executable has been renamed to foo:

format = \"\"\"\n...\n${custom.foo}\\\n...\n$line_break\\\n...\n$character\"\"\"\n\n# <clipped>\n\n[custom.foo]\ncommand = \"foo self metadata\"\nwhen = true\n## Windows\n# shell = [\"cmd\", \"/C\"]\n## Other\n# shell = [\"sh\", \"--norc\"]\n
"},{"location":"config/distribution/","title":"Python distribution configuration","text":""},{"location":"config/distribution/#known","title":"Known","text":"

Setting the PYAPP_PYTHON_VERSION option will determine the distribution used at runtime based on the environment at build time. If unset then the default will be the latest stable minor version of CPython.

"},{"location":"config/distribution/#cpython","title":"CPython","text":"ID 3.7 3.8 3.9 3.10 3.11 3.12

The source for pre-built distributions is the python-build-standalone project.

Some distributions have variants that may be configured with the PYAPP_DISTRIBUTION_VARIANT option:

Platform Options Linux "},{"location":"config/distribution/#pypy","title":"PyPy","text":"ID pypy2.7 pypy3.9 pypy3.10

The source of distributions is the PyPy project.

"},{"location":"config/distribution/#custom","title":"Custom","text":"

You may explicitly set the PYAPP_DISTRIBUTION_SOURCE option which overrides the known distribution settings. The source must be a URL that points to an archived version of the desired Python distribution.

Setting this manually may require you to define extra metadata about the distribution that is required for correct runtime behavior.

"},{"location":"config/distribution/#format","title":"Format","text":"

The following formats are supported for the PYAPP_DISTRIBUTION_FORMAT option, with the default chosen based on the ending of the source URL:

Format Extensions Description tar|bzip2 A tar file with bzip2 compression tar|gzip A tar file with gzip compression tar|zstd A tar file with Zstandard compression zip A ZIP file with DEFLATE compression"},{"location":"config/distribution/#python-location","title":"Python location","text":"

You may set the relative path to the Python executable after unpacking the archive with the PYAPP_DISTRIBUTION_PYTHON_PATH option. The default is python.exe on Windows and bin/python3 on all other platforms.

"},{"location":"config/distribution/#site-packages-location","title":"Site packages location","text":"

You may set the relative path to the site-packages directory after unpacking the archive with the PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH option. The default is Lib\\site-packages on Windows and lib/python<ID>/site-packages on all other platforms where <ID> is the defined distribution ID.

"},{"location":"config/distribution/#pip-availability","title":"pip availability","text":"

You may indicate whether pip is already installed by setting the PYAPP_DISTRIBUTION_PIP_AVAILABLE option to true or 1. This elides the check for installation when upgraded virtual environments are enabled.

"},{"location":"config/distribution/#embedding","title":"Embedding","text":"

You may set the PYAPP_DISTRIBUTION_EMBED option to true or 1 to embed the distribution in the executable at build time to avoid fetching it at runtime.

You can set the PYAPP_DISTRIBUTION_PATH option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the default distributions in that there should be a Python interpreter ready for use.

"},{"location":"config/distribution/#full-isolation","title":"Full isolation","text":"

You may set the PYAPP_FULL_ISOLATION option to true or 1 to provide each installation with a full copy of the distribution rather than a virtual environment.

"},{"location":"config/installation/","title":"Installation configuration","text":"

These options have no effect when the project installation is disabled.

"},{"location":"config/installation/#uv","title":"UV","text":"

You may set the PYAPP_UV_ENABLED option to true or 1 to use UV for virtual environment creation and project installation.

"},{"location":"config/installation/#uv-version","title":"Version","text":"

You may use a specific X.Y.Z version by setting the PYAPP_UV_VERSION option.

By default, a version of UV that has already been downloaded by a PyApp application is used. If UV has not yet been downloaded then the latest version is used.

"},{"location":"config/installation/#only-bootstrap","title":"Only bootstrap","text":"

You may set the PYAPP_UV_ONLY_BOOTSTRAP option to true or 1 to only use UV for virtual environment creation and continue using pip for project installation.

"},{"location":"config/installation/#pip","title":"pip","text":"

These options have no effect when UV is enabled.

"},{"location":"config/installation/#externally-managed","title":"Externally managed","text":"

You may set the PYAPP_PIP_EXTERNAL option to true or 1 to use the standalone versions of pip rather than whatever the distribution provides.

By default, the latest version is used. You may use a specific X.Y.Z version by setting the PYAPP_PIP_VERSION option.

Tip

This provides a significant installation speed up when full isolation is not enabled.

"},{"location":"config/installation/#allowing-configuration","title":"Allowing configuration","text":"

You may set the PYAPP_PIP_ALLOW_CONFIG option to true or 1 to allow the use of environment variables and other configuration at runtime.

"},{"location":"config/installation/#virtual-environments","title":"Virtual environments","text":"

When full isolation is not enabled, you may set the PYAPP_UPGRADE_VIRTUALENV option to true or 1 to create virtual environments with virtualenv rather than the standard library's venv module.

"},{"location":"config/installation/#extra-installer-arguments","title":"Extra installer arguments","text":"

You may set the PYAPP_PIP_EXTRA_ARGS option to provide extra arguments to the pip install (or UV equivalent) command at runtime when installing or updating the project e.g. --only-binary :all: --extra-index-url URL.

"},{"location":"config/installation/#location","title":"Location","text":"

The default location of your application's installation differs based on the operating system and can be overridden at runtime with the PYAPP_INSTALL_DIR_<PROJECT_NAME> environment variable where <PROJECT_NAME> is the uppercased version of the project name.

"},{"location":"config/installation/#skipping-installation","title":"Skipping installation","text":"

You may set the PYAPP_SKIP_INSTALL option to true or 1 to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with distribution embedding.

"},{"location":"config/project/","title":"Project configuration","text":""},{"location":"config/project/#sources","title":"Sources","text":"

There are 3 ways to configure runtime installation, none of which will occur when disabled.

The project identifier must be known in all cases.

"},{"location":"config/project/#identifier","title":"Identifier","text":"

The desired project name and version are configured with the PYAPP_PROJECT_NAME and PYAPP_PROJECT_VERSION options, respectively. The project name must adhere to PEP 508 and will be normalized during builds according to PEP 503.

When using only this method, the package will be installed from a package index like PyPI.

"},{"location":"config/project/#dependency-file","title":"Dependency file","text":"

You may install your project using a dependency file with the PYAPP_PROJECT_DEPENDENCY_FILE option which should be a local path to the file. In this mode, the project identifier has nothing to do with installation and is just used as metadata.

The following formats are supported:

Extensions Description .txt.in This is the requirements file format"},{"location":"config/project/#embedding","title":"Embedding","text":"

You may embed the project with the PYAPP_PROJECT_PATH option which should be a path to a wheel ending in .whl or a source distribution ending in .tar.gz.

Note

The project identifier is automatically derived from the metadata files inside.

"},{"location":"config/project/#features","title":"Features (extras)","text":"

You may set the PYAPP_PROJECT_FEATURES option to select optional dependency groups that would usually be passed to installers within square brackets after the package name e.g. pkg[foo,bar]. In that example, you would set PYAPP_PROJECT_FEATURES to foo,bar.

This also works when embedding the project.

"},{"location":"config/project/#execution-mode","title":"Execution mode","text":"

The following options are mutually exclusive:

Option Description PYAPP_EXEC_MODULE This is the name of the module to execute via python -m <MODULE> PYAPP_EXEC_SPEC This is an object reference to execute e.g. pkg.foo:cli PYAPP_EXEC_CODE This is arbitrary code to run via python -c <CODE> (the spec option uses this internally) PYAPP_EXEC_SCRIPT This is a path to a script to embed in the binary and run PYAPP_EXEC_NOTEBOOK This is a path to a Jupyter notebook (.ipynb file) to embed in the binary and run

If none are set then the PYAPP_EXEC_MODULE option will default to the value of PYAPP_PROJECT_NAME with hyphens replaced by underscores.

"},{"location":"config/project/#gui","title":"GUI","text":"

If you are packaging a graphical user interface (GUI), you can set PYAPP_IS_GUI to true or 1.

On Windows, this will use pythonw.exe instead of python.exe to execute the application, which avoids a console window from appearing. Running a GUI application with pythonw.exe means that all stdout and stderr output from your GUI will be discarded.

Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning.

Even when PYAPP_IS_GUI is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages.

Note

On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior can be changed in the user settings to close after the last process terminates successfully.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"PyApp","text":"CI/CD Docs Project Meta

PyApp is a wrapper for Python applications that bootstrap themselves at runtime.

See the how-to for a detailed example walkthrough.

"},{"location":"#features","title":"Features","text":""},{"location":"#license","title":"License","text":"

PyApp is distributed under the terms of any of the following licenses:

"},{"location":"#navigation","title":"Navigation","text":"

Documentation for specific versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released.

Desktop readers can use special keyboard shortcuts:

Keys Action Navigate to the \"previous\" page Navigate to the \"next\" page Display the search modal"},{"location":"build/","title":"Building","text":"

Before building your application, you must configure your project at the very least.

After you have done that, your application can be built using a local copy of this repository or via installation with Cargo.

Tip

For a more streamlined workflow, consider using the built-in app build target of Hatch.

"},{"location":"build/#local-repository","title":"Local repository","text":"

The recommended method of downloading the repository is via the source asset archives attached to each release.

The latest release can always be downloaded at the following URLs:

Specific releases may be downloaded at the following URLs, replacing X.Y.Z with the desired version:

After unpacking the repository, enter the directory and run:

cargo build --release\n

The executable will be located at target/release/pyapp.exe if on Windows or target/release/pyapp otherwise. If a particular target has been set (or when cross compiling since one will always be set), then the release directory will be nested one level deeper under target/<TARGET>.

"},{"location":"build/#installation","title":"Installation","text":"

Select the directory in which to build the executable with the --root option and run:

cargo install pyapp --force --root <DIR>\n

The executable will be located at <DIR>/bin/pyapp.exe if on Windows or <DIR>/bin/pyapp otherwise.

Specific versions may be chosen with the --version flag.

Note: If you want to cross compile, this method of building is currently unsupported.

"},{"location":"build/#cross-compilation","title":"Cross compilation","text":"

Configuration for cross is validated by CI to ensure all known environment variable options are passed through to the containers.

When embedding the project or the distribution using a local path, you must use the local repository way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.

"},{"location":"changelog/","title":"Changelog","text":"

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

"},{"location":"changelog/#unreleased","title":"Unreleased","text":"

Added:

Fixed:

"},{"location":"changelog/#0190-2024-04-24","title":"0.19.0 - 2024-04-24","text":"

Added:

Fixed:

"},{"location":"changelog/#0180-2024-04-22","title":"0.18.0 - 2024-04-22","text":"

Added:

Fixed:

"},{"location":"changelog/#0170-2024-04-21","title":"0.17.0 - 2024-04-21","text":"

Added:

Fixed:

"},{"location":"changelog/#0160-2024-03-24","title":"0.16.0 - 2024-03-24","text":"

Added:

"},{"location":"changelog/#0151-2024-03-03","title":"0.15.1 - 2024-03-03","text":"

Fixed:

"},{"location":"changelog/#0150-2024-03-01","title":"0.15.0 - 2024-03-01","text":"

Added:

Fixed:

"},{"location":"changelog/#0140-2024-01-21","title":"0.14.0 - 2024-01-21","text":"

Added:

"},{"location":"changelog/#0130-2023-12-31","title":"0.13.0 - 2023-12-31","text":"

Added:

Fixed:

"},{"location":"changelog/#0120-2023-10-07","title":"0.12.0 - 2023-10-07","text":"

Added:

"},{"location":"changelog/#0111-2023-09-14","title":"0.11.1 - 2023-09-14","text":"

Fixed:

"},{"location":"changelog/#0110-2023-09-07","title":"0.11.0 - 2023-09-07","text":"

Added:

"},{"location":"changelog/#0101-2023-06-26","title":"0.10.1 - 2023-06-26","text":"

Fixed:

"},{"location":"changelog/#0100-2023-06-26","title":"0.10.0 - 2023-06-26","text":"

Added:

Fixed:

"},{"location":"changelog/#090-2023-06-21","title":"0.9.0 - 2023-06-21","text":"

Changed:

Added:

Fixed:

"},{"location":"changelog/#080-2023-06-09","title":"0.8.0 - 2023-06-09","text":"

Added:

Fixed:

"},{"location":"changelog/#070-2023-05-24","title":"0.7.0 - 2023-05-24","text":"

Changed:

Added:

"},{"location":"changelog/#060-2023-05-16","title":"0.6.0 - 2023-05-16","text":"

Added:

Fixed:

"},{"location":"changelog/#050-2023-05-11","title":"0.5.0 - 2023-05-11","text":"

Added:

Fixed:

"},{"location":"changelog/#040-2023-05-11","title":"0.4.0 - 2023-05-11","text":"

Changed:

Added:

"},{"location":"changelog/#031-2023-05-10","title":"0.3.1 - 2023-05-10","text":"

Fixed:

"},{"location":"changelog/#030-2023-05-10","title":"0.3.0 - 2023-05-10","text":"

Changed:

Added:

Fixed:

"},{"location":"changelog/#020-2023-05-07","title":"0.2.0 - 2023-05-07","text":"

This is the initial public release.

"},{"location":"examples/","title":"Examples","text":"

The following examples do not illustrate every possible combination of options but rather some common use cases.

"},{"location":"examples/#single-project-basic","title":"Single project basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z"},{"location":"examples/#single-project-embedded","title":"Single project embedded","text":"Option Value PYAPP_PROJECT_PATH ./proj-X.Y.Z.dev0-py3-none-any.whl"},{"location":"examples/#dependency-file-basic","title":"Dependency file basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt

Note

The default execution will be python -m proj at runtime.

"},{"location":"examples/#dependency-file-with-script","title":"Dependency file with script","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt PYAPP_EXEC_SCRIPT ./script.py"},{"location":"examples/#execution-with-object-reference","title":"Execution with object reference","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_EXEC_SPEC proj.cli:main"},{"location":"examples/#specific-known-distribution","title":"Specific known distribution","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PYTHON_VERSION 3.10"},{"location":"examples/#custom-remote-distribution-basic","title":"Custom remote distribution basic","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_SOURCE https://foo.bar.baz/archive.tar.gz"},{"location":"examples/#custom-remote-distribution-embedded","title":"Custom remote distribution embedded","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_SOURCE https://foo.bar.baz/archive.tar.gz PYAPP_DISTRIBUTION_EMBED true"},{"location":"examples/#custom-embedded-local-distribution","title":"Custom embedded local distribution","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_DISTRIBUTION_PATH ./archive.tar.gz"},{"location":"examples/#offline-installation","title":"Offline installation","text":"Option Value PYAPP_PROJECT_PATH ./proj-X.Y.Z-py3-none-any.whl PYAPP_DISTRIBUTION_PATH ./archive.tar.gz PYAPP_PIP_EXTRA_ARGS --no-deps"},{"location":"examples/#reproducible-installation-with-custom-package-index","title":"Reproducible installation with custom package index","text":"Option Value PYAPP_PROJECT_NAME proj PYAPP_PROJECT_VERSION X.Y.Z PYAPP_PROJECT_DEPENDENCY_FILE ./requirements.txt PYAPP_PIP_EXTRA_ARGS --only-binary :all: --index-url URL"},{"location":"how-to/","title":"How-to","text":"

What follows is a short example showing the end-to-end experience from building an application to running the application as a user.

"},{"location":"how-to/#install-rust","title":"Install Rust","text":"

Follow the instructions to install Rust and make sure the package manager Cargo is on your PATH.

"},{"location":"how-to/#get-pyapp","title":"Get PyApp","text":"

In order to build applications with PyApp, you must first download the source code. Here we will download the latest release.

Linux/macOSWindows
  1. curl https://github.com/ofek/pyapp/releases/latest/download/source.tar.gz -Lo pyapp-source.tar.gz
  2. tar -xzf pyapp-source.tar.gz
  3. mv pyapp-v* pyapp-latest
  4. cd pyapp-latest
  1. Invoke-WebRequest https://github.com/ofek/pyapp/releases/latest/download/source.zip -OutFile pyapp-source.zip
  2. 7z x pyapp-source.zip
  3. mv pyapp-v* pyapp-latest
  4. cd pyapp-latest
"},{"location":"how-to/#configuration","title":"Configuration","text":"

You must configure the binaries PyApp produces with environment variables. There are many ways to configure applications but here we will define a single package to install from PyPI at a specific version:

Option Value PYAPP_PROJECT_NAME cowsay PYAPP_PROJECT_VERSION 6.0"},{"location":"how-to/#building","title":"Building","text":"

Run:

cargo build --release\n

The executable will be located at target/release/pyapp.exe if on Windows or target/release/pyapp otherwise.

"},{"location":"how-to/#distribution","title":"Distribution","text":"

Be sure to rename the binary to the name of the application (and make it executable on non-Windows systems):

Linux/macOSWindows 
mv target/release/pyapp cowsay && chmod +x cowsay\n
mv target\\release\\pyapp.exe cowsay\n
"},{"location":"how-to/#runtime","title":"Runtime","text":"

After you have distributed the binary to the user, they can execute it directly:

$ ./cowsay -t 'Hello, World!'\n  _____________\n| Hello, World! |\n  =============\n             \\\n              \\\n                ^__^\n                (oo)\\_______\n                (__)\\       )\\/\\\n                    ||----w |\n                    ||     ||\n
"},{"location":"runtime/","title":"Runtime behavior","text":""},{"location":"runtime/#initialization","title":"Initialization","text":"

Applications will bootstrap themselves on the first run. All subsequent invocations will only check if the installation directory exists and nothing else, to maximize CLI responsiveness.

Note

The following diagram shows the possible behavior at runtime. The nodes with rounded edges are conditions and those with jagged edges are actions.

Most nodes are clickable and will take you to the relevant documentation.

flowchart TD\n    INSTALLED([Installed]) -- No --> DISTCACHED([Distribution cached])\n    INSTALLED -- Yes --> MNG([Management enabled])\n    DISTCACHED -- No --> DISTEMBEDDED([Distribution embedded])\n    DISTCACHED -- Yes --> FULLISOLATION([Full isolation])\n    DISTEMBEDDED -- No --> DISTSOURCE[[Cache from source]]\n    DISTEMBEDDED -- Yes --> DISTEXTRACT[[Cache from embedded data]]\n    DISTSOURCE --> FULLISOLATION\n    DISTEXTRACT --> FULLISOLATION\n    FULLISOLATION -- No --> UVENABLED([UV enabled])\n    UVENABLED -- No --> VENV[[Create virtual environment]]\n    UVENABLED -- Yes --> UVCACHED([UV cached])\n    UVCACHED -- No --> DOWNLOADUV[[Download UV]]\n    UVCACHED -- Yes --> VENV\n    DOWNLOADUV --> VENV\n    FULLISOLATION -- Yes --> UNPACK[[Unpack distribution directly]]\n    UNPACK --> UVENABLEDUNPACK([UV enabled])\n    UVENABLEDUNPACK -- No --> EXTERNALPIP[[External pip]]\n    UVENABLEDUNPACK -- Yes --> UVCACHEDUNPACK([UV cached])\n    UVCACHEDUNPACK -- No --> DOWNLOADUVUNPACK[[Download UV]]\n    EXTERNALPIP([External pip]) -- No --> PROJEMBEDDED([Project embedded])\n    EXTERNALPIP -- Yes --> PIPCACHED([pip cached])\n    PIPCACHED -- No --> DOWNLOADPIP[[Download pip]]\n    PIPCACHED -- Yes --> PROJEMBEDDED([Project embedded])\n    DOWNLOADPIP --> PROJEMBEDDED\n    PROJEMBEDDED -- No --> DEPFILE([Dependency file])\n    PROJEMBEDDED -- Yes --> PROJEMBED[[Install from embedded data]]\n    DEPFILE -- No --> SINGLEPROJECT[[Install single project]]\n    DEPFILE -- Yes --> DEPFILEINSTALL[[Install from dependency file]]\n    UVCACHEDUNPACK -- Yes --> PROJEMBEDDED\n    DOWNLOADUVUNPACK --> PROJEMBEDDED\n    VENV --> EXTERNALPIP\n    SINGLEPROJECT --> MNG\n    DEPFILEINSTALL --> MNG\n    PROJEMBED --> MNG\n    MNG -- No --> EXECUTE[[Execute project]]\n    MNG -- Yes --> MNGCMD([Command invoked])\n    MNGCMD -- No --> EXECUTE\n    MNGCMD -- Yes --> MANAGE[[Run management command]]\n    click DISTEMBEDDED href \"../config/distribution/#embedding\"\n    click FULLISOLATION href \"../config/distribution/#full-isolation\"\n    click UVENABLED href \"../config/installation/#uv\"\n    click UVENABLEDUNPACK href \"../config/installation/#uv\"\n    click EXTERNALPIP href \"../config/installation/#externally-managed\"\n    click PROJEMBEDDED href \"../config/project/#embedding\"\n    click DEPFILE href \"../config/project/#dependency-file\"\n    click SINGLEPROJECT href \"../config/project/#identifier\"\n    click DEPFILEINSTALL href \"../config/project/#dependency-file\"\n    click PROJEMBED href \"../config/project/#embedding\"\n    click MNG href \"../config/cli/#management-command\"\n    click MNGCMD href \"../config/cli/#management-command\"\n    click MANAGE href \"#commands\"\n    click EXECUTE href \"../config/project/#execution-mode\"
"},{"location":"runtime/#execution","title":"Execution","text":"

Projects are executed using execvp on non-Windows systems, replacing the process.

To provide consistent behavior on each user's machine:

"},{"location":"runtime/#detection","title":"Detection","text":"

A single environment variable called PYAPP is injected with the value of 1 (by default) when running applications and may be used to detect this mode of installation versus others.

"},{"location":"runtime/#commands","title":"Commands","text":"

Built applications have a single top-level command group named self (by default) and all other invocations will be forwarded to your actual execution logic.

"},{"location":"runtime/#default","title":"Default","text":"

These commands are always exposed.

"},{"location":"runtime/#remove","title":"Remove","text":"
<EXE> self remove\n

This will wipe the installation.

"},{"location":"runtime/#restore","title":"Restore","text":"
<EXE> self restore\n

This will wipe the installation and then reinstall.

"},{"location":"runtime/#update","title":"Update","text":"
<EXE> self update\n

This will update the project to the latest available version in the currently used distribution.

"},{"location":"runtime/#optional","title":"Optional","text":"

These commands are hidden by default and each can be individually exposed by setting its corresponding PYAPP_EXPOSE_<COMMAND> option (e.g. PYAPP_EXPOSE_METADATA) to true or 1.

"},{"location":"runtime/#cache","title":"Cache","text":"
<EXE> self cache [dist|pip|uv]\n

This is the command group for managing the cache. Each subcommand has a -r/--remove flag to remove the cached asset. Not passing that flag will display the location instead.

"},{"location":"runtime/#metadata","title":"Metadata","text":"
<EXE> self metadata\n

This displays customized output based on a template.

"},{"location":"runtime/#pip","title":"pip","text":"
<EXE> self pip\n

This directly invokes pip with the installed Python.

"},{"location":"runtime/#python","title":"Python","text":"
<EXE> self python\n

This directly invokes the installed Python.

"},{"location":"runtime/#python-path","title":"Python path","text":"
<EXE> self python-path\n

This outputs the path to the installed Python.

"},{"location":"users/","title":"Users","text":"

The following is not intended to be a complete enumeration. Be sure to view the development version of this page for an up-to-date listing.

"},{"location":"users/#projects","title":"Projects","text":"

AppleCrate | Datadog QA | FreeMoCap | Hatch | instawow | Litestar | Preservation Workbench | tidal-wave

"},{"location":"config/cli/","title":"Command line configuration","text":""},{"location":"config/cli/#installation-indicator","title":"Installation indicator","text":"

The environment variable that is used for detection may be set to the path of the executable at runtime if you set the PYAPP_PASS_LOCATION option to true or 1. This is useful if your application wishes to in some way manage itself.

"},{"location":"config/cli/#management-command","title":"Management command","text":"

You may set the PYAPP_SELF_COMMAND option to override the default name (self) of the management command group. Setting this to none effectively disables the use of management commands.

When enabled, the value will be available at runtime as the PYAPP_COMMAND_NAME environment variable.

"},{"location":"config/cli/#metadata-template","title":"Metadata template","text":"

You may set a custom template used to output metadata with the PYAPP_METADATA_TEMPLATE option which supports the following placeholders:

Placeholder Description {project} The normalized project name {version} The currently installed version of the project

The default template is {project} v{version} if this option is unset.

This is useful for setting custom commands for the Starship prompt. The following example configuration assumes that the built executable has been renamed to foo:

format = \"\"\"\n...\n${custom.foo}\\\n...\n$line_break\\\n...\n$character\"\"\"\n\n# <clipped>\n\n[custom.foo]\ncommand = \"foo self metadata\"\nwhen = true\n## Windows\n# shell = [\"cmd\", \"/C\"]\n## Other\n# shell = [\"sh\", \"--norc\"]\n
"},{"location":"config/distribution/","title":"Python distribution configuration","text":""},{"location":"config/distribution/#known","title":"Known","text":"

Setting the PYAPP_PYTHON_VERSION option will determine the distribution used at runtime based on the environment at build time. If unset then the default will be the latest stable minor version of CPython.

"},{"location":"config/distribution/#cpython","title":"CPython","text":"ID 3.7 3.8 3.9 3.10 3.11 3.12

The source for pre-built distributions is the python-build-standalone project.

Some distributions have variants that may be configured with the PYAPP_DISTRIBUTION_VARIANT option:

Platform Options Linux "},{"location":"config/distribution/#pypy","title":"PyPy","text":"ID pypy2.7 pypy3.9 pypy3.10

The source of distributions is the PyPy project.

"},{"location":"config/distribution/#custom","title":"Custom","text":"

You may explicitly set the PYAPP_DISTRIBUTION_SOURCE option which overrides the known distribution settings. The source must be a URL that points to an archived version of the desired Python distribution.

Setting this manually may require you to define extra metadata about the distribution that is required for correct runtime behavior.

"},{"location":"config/distribution/#format","title":"Format","text":"

The following formats are supported for the PYAPP_DISTRIBUTION_FORMAT option, with the default chosen based on the ending of the source URL:

Format Extensions Description tar|bzip2 A tar file with bzip2 compression tar|gzip A tar file with gzip compression tar|zstd A tar file with Zstandard compression zip A ZIP file with DEFLATE compression"},{"location":"config/distribution/#python-location","title":"Python location","text":"

You may set the relative path to the Python executable after unpacking the archive with the PYAPP_DISTRIBUTION_PYTHON_PATH option. The default is python.exe on Windows and bin/python3 on all other platforms.

"},{"location":"config/distribution/#site-packages-location","title":"Site packages location","text":"

You may set the relative path to the site-packages directory after unpacking the archive with the PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH option. The default is Lib\\site-packages on Windows and lib/python<ID>/site-packages on all other platforms where <ID> is the defined distribution ID.

"},{"location":"config/distribution/#pip-availability","title":"pip availability","text":"

You may indicate whether pip is already installed by setting the PYAPP_DISTRIBUTION_PIP_AVAILABLE option to true or 1. This elides the check for installation when upgraded virtual environments are enabled.

"},{"location":"config/distribution/#embedding","title":"Embedding","text":"

You may set the PYAPP_DISTRIBUTION_EMBED option to true or 1 to embed the distribution in the executable at build time to avoid fetching it at runtime.

You can set the PYAPP_DISTRIBUTION_PATH option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the default distributions in that there should be a Python interpreter ready for use.

"},{"location":"config/distribution/#full-isolation","title":"Full isolation","text":"

You may set the PYAPP_FULL_ISOLATION option to true or 1 to provide each installation with a full copy of the distribution rather than a virtual environment.

"},{"location":"config/installation/","title":"Installation configuration","text":"

These options have no effect when the project installation is disabled.

"},{"location":"config/installation/#uv","title":"UV","text":"

You may set the PYAPP_UV_ENABLED option to true or 1 to use UV for virtual environment creation and project installation.

"},{"location":"config/installation/#uv-version","title":"Version","text":"

You may use a specific X.Y.Z version by setting the PYAPP_UV_VERSION option.

By default, a version of UV that has already been downloaded by a PyApp application is used. If UV has not yet been downloaded then the latest version is used.

"},{"location":"config/installation/#only-bootstrap","title":"Only bootstrap","text":"

You may set the PYAPP_UV_ONLY_BOOTSTRAP option to true or 1 to only use UV for virtual environment creation and continue using pip for project installation.

"},{"location":"config/installation/#pip","title":"pip","text":"

These options have no effect when UV is enabled.

"},{"location":"config/installation/#externally-managed","title":"Externally managed","text":"

You may set the PYAPP_PIP_EXTERNAL option to true or 1 to use the standalone versions of pip rather than whatever the distribution provides.

By default, the latest version is used. You may use a specific X.Y.Z version by setting the PYAPP_PIP_VERSION option.

Tip

This provides a significant installation speed up when full isolation is not enabled.

"},{"location":"config/installation/#allowing-configuration","title":"Allowing configuration","text":"

You may set the PYAPP_PIP_ALLOW_CONFIG option to true or 1 to allow the use of environment variables and other configuration at runtime.

"},{"location":"config/installation/#virtual-environments","title":"Virtual environments","text":"

When full isolation is not enabled, you may set the PYAPP_UPGRADE_VIRTUALENV option to true or 1 to create virtual environments with virtualenv rather than the standard library's venv module.

"},{"location":"config/installation/#extra-installer-arguments","title":"Extra installer arguments","text":"

You may set the PYAPP_PIP_EXTRA_ARGS option to provide extra arguments to the pip install (or UV equivalent) command at runtime when installing or updating the project e.g. --only-binary :all: --extra-index-url URL.

"},{"location":"config/installation/#location","title":"Location","text":"

The default location of your application's installation differs based on the operating system and can be overridden at runtime with the PYAPP_INSTALL_DIR_<PROJECT_NAME> environment variable where <PROJECT_NAME> is the uppercased version of the project name.

"},{"location":"config/installation/#skipping-installation","title":"Skipping installation","text":"

You may set the PYAPP_SKIP_INSTALL option to true or 1 to skip installing the project in the distribution. This allows for entirely predefined distributions and thus no network calls at runtime if used in conjunction with distribution embedding.

"},{"location":"config/project/","title":"Project configuration","text":""},{"location":"config/project/#sources","title":"Sources","text":"

There are 3 ways to configure runtime installation, none of which will occur when disabled.

The project identifier must be known in all cases.

"},{"location":"config/project/#identifier","title":"Identifier","text":"

The desired project name and version are configured with the PYAPP_PROJECT_NAME and PYAPP_PROJECT_VERSION options, respectively. The project name must adhere to PEP 508 and will be normalized during builds according to PEP 503.

When using only this method, the package will be installed from a package index like PyPI.

"},{"location":"config/project/#dependency-file","title":"Dependency file","text":"

You may install your project using a dependency file with the PYAPP_PROJECT_DEPENDENCY_FILE option which should be a local path to the file. In this mode, the project identifier has nothing to do with installation and is just used as metadata.

The following formats are supported:

Extensions Description .txt.in This is the requirements file format"},{"location":"config/project/#embedding","title":"Embedding","text":"

You may embed the project with the PYAPP_PROJECT_PATH option which should be a path to a wheel ending in .whl or a source distribution ending in .tar.gz.

Note

The project identifier is automatically derived from the metadata files inside.

"},{"location":"config/project/#features","title":"Features (extras)","text":"

You may set the PYAPP_PROJECT_FEATURES option to select optional dependency groups that would usually be passed to installers within square brackets after the package name e.g. pkg[foo,bar]. In that example, you would set PYAPP_PROJECT_FEATURES to foo,bar.

This also works when embedding the project.

"},{"location":"config/project/#execution-mode","title":"Execution mode","text":"

The following options are mutually exclusive:

Option Description PYAPP_EXEC_MODULE This is the name of the module to execute via python -m <MODULE> PYAPP_EXEC_SPEC This is an object reference to execute e.g. pkg.foo:cli PYAPP_EXEC_CODE This is arbitrary code to run via python -c <CODE> (the spec option uses this internally) PYAPP_EXEC_SCRIPT This is a path to a script to embed in the binary and run PYAPP_EXEC_NOTEBOOK This is a path to a Jupyter notebook (.ipynb file) to embed in the binary and run

If none are set then the PYAPP_EXEC_MODULE option will default to the value of PYAPP_PROJECT_NAME with hyphens replaced by underscores.

"},{"location":"config/project/#gui","title":"GUI","text":"

If you are packaging a graphical user interface (GUI), you can set PYAPP_IS_GUI to true or 1.

On Windows, this will use pythonw.exe instead of python.exe to execute the application, which avoids a console window from appearing. Running a GUI application with pythonw.exe means that all stdout and stderr output from your GUI will be discarded.

Otherwise, the application will execute as usual. PyApp will run your GUI by spawning a new process, such that the console window that runs the application terminates after successful spawning.

Even when PYAPP_IS_GUI is enabled you can still run the application from the command line. Furthermore, PyApp-specific logic (e.g. installation and setup) will still display a console window with status messages.

Note

On macOS, the console by default does not automatically close when processes have terminated (however it can be closed manually without interferring with the GUI). The default console behavior can be changed in the user settings to close after the last process terminates successfully.

"}]} \ No newline at end of file