pup 1.0.0a5

Pluggable Micro Packager

pup is (in the early stages of development and risks becoming) a packaging tool for GUI programs written in Python.

Fundamentally, its raison d’être is producing macOS and Windows native packages for distributing the Mu Editor to Python beginners around the world. As a by-product of that, it will very likely become effective at packaging generic Python written GUI programs. If that ever becomes the case, then great. Otherwise, that’s fine too.

The purpose, again, is to package Mu Editor for macOS and Windows distribution.

Capabilities

The current version of pup, while still very limited and somewhat exploratory, can package, at least, the Mu Editor and puppy into distributable:

• Native Windows application MSI installer files.

  Minimally featured, user-installable, with no GUI. They do add an entry to the Windows Start menu, however, even though no custom icon is used yet. As a byproduct of the process, a relocatable directory holding the aplication is produced too, paving the way for producing “portable” Windows applications.

• Native macOS DMG application distribution files.

  The hold the relocatable .app application bundle, properly signed and notarized as required for distribution. The DMG files are also minimally featured, and do not include custom icons yet.

It might work with any Python GUI application that:

• Runs on Python 3.7 or 3.8.

• Is pip-installable (no need to be on PyPI, though).

• Is launchable from the CLI with python -m <launch-module>.

Installation

pup is distributed via PyPI. Install it with:

$ pip install pup

Generic Usage

To package an application, run:

$ pup package <pip-installable-source>

• Assumes that the application is launchable with python -m <name>, where <name> is extracted from the wheel metadata of a wheel created from <pip-installable-source>. If the name of the launch module does not match that, the --launch-module <launch-module-name> CLI option should be provided.

• In the first run, pup will download a distributable Python Runtime from the Python Build Standalone project. Subsequent runs will use a locally cached version of that.

• On Windows, again in the first run, pup will download the WiX toolset, used to create MSI files. Subsequent runs will use a locally cached version of that, too.

• pup logs its progress to STDERR, with fewer per-event details when it’s a TTY. The logging level defaults to INFO and can be changed with either the --log-level CLI option, or by setting the PUP_LOG_LEVEL environment variable.

• Intermediate artifacts are created under ./build/pup/.

• The final artifacts are delivered to ./dist/.

Packaging the Mu Editor on Windows

Run:

> pup package --launch-module=mu <path-to-local-mu-git-repo-root>

• The resulting MSI file will be ./dist/<name> <version>.msi.

• A byproduct of that is the ./build/pup/<name> <version>/ relocatable directory, containing a GUI-clickable script that launches Mu. Creating a ZIP file from it for distribution results in a minimally working “portable” Windows application.

• In either case, distribution will have limitations given that no code/package signing is implemented yet.

Packaging the Mu Editor on macOS

Requirements:

• Must be running macOS 10.14.6 (Mojave) or later.

• Must have XCode 10.3 or later installed – the Command Line Tools are not enough.

• Must have an Apple Developer Certificate – see this article’s step 4, for guidance.

• Must create an Application Specific Password – see this article, for guidance.

Run:

$ export PUP_SIGNING_IDENTITY=<signer>
$ export PUP_NOTARIZE_USER=<user>
$ export PUP_NOTARIZE_PASSWORD=<asp>

Where:

• <signer> is the 10-digit identifier on your Apple Developer Certificate’s cname.

• <user> is the email address associated to you Apple Developer Account.

• <asp> is the Application Specific Password.

Then run:

$ pup package --launch-module=mu <path-to-local-mu-git-repo-root>

Note:

• One of the last packaging stages is notarization.

• It will take a while – no less than 3 minutes, IME, sometimes 10-15 minutes.

• The logged messages should help understand that the “thing” is not “hung”.

• Just be patient, I guess! :)

Once completed:

• The resulting DMG file will be ./dist/<name> <version>.dmg.

• A byproduct of that is the ./build/pup/<name>.app/ relocatable application bundle. Archiving it into a ZIP file, for distribution, should be perfectly fine.

More

To learn more about pup refer to the online documentation: at this early stage, it is mostly a collection of thoughts and ideas around behaviour, requirements, and internal design. Development moves forward on GitHub at https://github.com/mu-editor/pup/.

Thanks

• Nicholas Tollervey for the amazing Mu Editor.

• The Mu contributors I’ve been having the privilege of working more directly with, Carlos Pereira Atencio, Martin Dybdal, and Tim Golden, as well as the others whom I haven’t met yet but whose contributions I highly respect.

• To Russell Keith-Magee for the inspiring BeeWare project and, in particular, for briefcase that being used as the packaging tool for Mu on macOS as of this writing, serves as a great inspiration to pup.

• To Gregory Szorc for the incredible Python Standalone Builds project, on top of which we plan to package redistributable Python GUI applications.

• To Donald Stufft for letting us pick up the pup name in PyPI.

• To Glyph Lefkowitz for the very useful, high quality Tips And Tricks for Shipping a PyGame App on the Mac article, and for his generous hands-on involvement in the first-steps of pup’s take on the subject in this issue.

About

pup is in the process of being created by Tiago Montes, with the wonderful support of the Mu development team.