Metadata-Version: 2.1
Name: pup
Version: 1.0.0a5
Summary: Pluggable Micro Packager
Home-page: https://github.com/mu-editor/pup/
Author: Tiago Montes
Author-email: tiago.montes@gmail.com
Maintainer: Tiago Montes
Maintainer-email: tiago.montes@gmail.com
License: MIT
Keywords: packaging,gui,applications
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Software Distribution
Description-Content-Type: text/x-rst
Requires-Dist: click (==7.1.2)
Requires-Dist: httpx (==0.16.1)
Requires-Dist: wheel (==0.36.1)
Requires-Dist: pkginfo (==1.6.1)
Requires-Dist: cookiecutter (==1.7.2)
Requires-Dist: zstandard (==0.14.1)
Requires-Dist: dmgbuild (==1.4.2)
Requires-Dist: importlib-metadata (==3.1.1) ; python_version < "3.8"
Requires-Dist: importlib-resources (==3.3.0) ; python_version < "3.9"
Provides-Extra: dev
Requires-Dist: coverage ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: towncrier ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: towncrier ; extra == 'docs'
Provides-Extra: release
Requires-Dist: twine ; extra == 'release'
Provides-Extra: tests
Requires-Dist: coverage ; extra == 'tests'

``pup`` | 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 <https://codewith.mu/>`_
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 <https://codewith.mu/>`_
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 <https://codewith.mu/>`_
and `puppy <https://github.com/tmontes/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 <https://pypi.org/pypi/pup>`_.
Install it with:

.. code-block:: console

	$ pip install pup



Generic Usage
-------------

To package an application, run:

.. code-block:: console

        $ 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 <https://python-build-standalone.readthedocs.io/>`_
  project.
  Subsequent runs will use a locally cached version of that.

* On Windows,
  again in the first run,
  ``pup`` will download the `WiX toolset <https://wixtoolset.org>`_,
  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:

.. code-block:: console

        > 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
  <https://glyph.twistedmatrix.com/2018/01/shipping-pygame-mac-app.html>`_,
  for guidance.
* Must create an Application Specific Password --
  see `this article <https://support.apple.com/en-us/HT204397>`_,
  for guidance.

Run:

.. code-block:: console

        $ 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:

.. code-block:: console

        $ 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 <https://pup.readthedocs.io/>`_:
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/.


.. marker-end-welcome-dont-remove


Thanks
------

.. marker-start-thanks-dont-remove

- Nicholas Tollervey for the amazing `Mu Editor <https://codewith.mu/>`_.

- 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 <https://beeware.org>`_ project
  and, in particular, for `briefcase <https://pypi.org/project/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 <https://python-build-standalone.readthedocs.io/>`_
  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
  <https://glyph.twistedmatrix.com/2018/01/shipping-pygame-mac-app.html>`_
  article,
  and for his generous hands-on involvement in the first-steps of ``pup``'s take
  on the subject `in this issue <https://github.com/mu-editor/pup/issues/43>`_.

.. marker-end-thanks-dont-remove



About
-----

.. marker-start-about-dont-remove

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

.. marker-end-about-dont-remove



