Merge branch 'main' into download-stub

.github/workflows/ci.yml

@@ -5,6 +5,11 @@ on:
     branches:
       - main
   workflow_call:
+    inputs:
+      attest-package:
+        description: "Create GitHub provenance attestation for the package."
+        default: "false"
+        type: string
     outputs:
       artifact-name:
         description: "Name of the uploaded artifact; use for artifact retrieval."
@@ -32,10 +37,24 @@ jobs:
     uses: beeware/.github/.github/workflows/towncrier-run.yml@main
 
   package:
-    name: Python package
+    name: Package Briefcase
+    permissions:
+      id-token: write
+      contents: read
+      attestations: write
     uses: beeware/.github/.github/workflows/python-package-create.yml@main
     with:
-      tox-factors: -with-automation
+      attest: ${{ inputs.attest-package }}
+
+  package-automation:
+    name: Package Automation
+    permissions:
+      id-token: write
+      contents: read
+      attestations: write
+    uses: beeware/.github/.github/workflows/python-package-create.yml@main
+    with:
+      build-subdirectory: "automation"
 
   unit-tests:
     name: Unit tests
@@ -82,12 +101,11 @@ jobs:
         name: ${{ needs.package.outputs.artifact-name }}
         path: dist
 
-    - name: Install dev Dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install --upgrade setuptools build wheel
-        # Utility script installs tox as defined in pyproject.toml
-        python -m install_requirement tox --extra dev
+    - name: Install Tox
+      uses: beeware/.github/.github/actions/install-requirement@main
+      with:
+        requirements: tox
+        extra: dev
 
     - name: Test
       id: test
@@ -129,12 +147,11 @@ jobs:
         # https://github.com/nedbat/coveragepy/issues/1572#issuecomment-1522546425
         python-version: "3.8"
 
-    - name: Install dev Dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install --upgrade setuptools build wheel
-        # Utility script installs tox as defined in pyproject.toml
-        python -m install_requirement tox --extra dev
+    - name: Install Tox
+      uses: beeware/.github/.github/actions/install-requirement@main
+      with:
+        requirements: tox
+        extra: dev
 
     - name: Retrieve Coverage Data
       uses: actions/[email protected]
@@ -162,7 +179,7 @@ jobs:
 
   verify-projects:
     name: Verify project
-    needs: unit-tests
+    needs: [ package, package-automation, unit-tests ]
     uses: beeware/.github/.github/workflows/app-create-verify.yml@main
     with:
       runner-os: ${{ matrix.runner-os }}
@@ -175,7 +192,7 @@ jobs:
 
   verify-apps:
     name: Build app
-    needs: unit-tests
+    needs: [ package, package-automation, unit-tests ]
     uses: beeware/.github/.github/workflows/app-build-verify.yml@main
     with:
       # This *must* be the version of Python that is the system Python on the

.github/workflows/release.yml

@@ -9,6 +9,8 @@ jobs:
   ci:
     name: CI
     uses: ./.github/workflows/ci.yml
+    with:
+      attest-package: "true"
 
   docs:
     name: Verify Docs Build
@@ -29,7 +31,7 @@ jobs:
     steps:
       - name: Set build variables
         run: |
-          echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_ENV
+          echo "VERSION=${GITHUB_REF_NAME#v}" | tee -a $GITHUB_ENV
 
       - name: Set up Python
         uses: actions/[email protected]

changes/1807.doc.rst

@@ -0,0 +1 @@
+Documentation on Briefcase's plug-in interfaces was added.

changes/1807.feature.rst

@@ -0,0 +1 @@
+The new project wizard now includes links to known third-party GUI bootstraps.

changes/1843.misc.rst

@@ -0,0 +1 @@
+``hynek/build-and-inspect-python-package`` is now used to create the Python package.

changes/1847.misc.rst

@@ -0,0 +1 @@
+The ``install_requirement.py`` script was removed.

changes/1850.misc.rst

@@ -0,0 +1 @@
+A UUID cookiecutter extension was added to support Windows MSI templating.

changes/1851.misc.rst

@@ -0,0 +1 @@
+The warning for specifying the license in pyproject.toml was updated to include additional information.

changes/1853.misc.rst

@@ -0,0 +1 @@
+Updated coverage[toml] from 7.5.2 to 7.5.3.

docs/reference/commands/new.rst

@@ -49,3 +49,31 @@ The expected keys are specified by the cookiecutter template being used to
 create the new project. Therefore, the set of possible keys is not listed here
 but should be expected to remain consistent for any specific version of
 Briefcase; with version changes, though, the keys may change.
+
+Third-party Bootstraps
+======================
+
+When you run new project wizard, you are asked to select a GUI toolkit. Briefcase
+includes bootstraps for `Toga <https://toga.readthedocs.io>`__ (BeeWare's cross-platform
+GUI framework), `PySide6 <https://wiki.qt.io/Qt_for_Python>`__ (Python bindings for the
+Qt GUI toolkit) and `Pygame <https://www.pygame.org/news>`__ (a common Python game
+development toolkit), as well as an "empty" bootstrap that doesn't include any GUI code.
+However, Briefcase provides a :ref:`plug-in interface <bootstrap-interface>` that allows
+GUI toolkits to provide a their own bootstrap implementation.
+
+The following third-party bootstraps are known to exist:
+
+=================================== ============== ===================================================
+Bootstrap                           Package name   Description
+=================================== ============== ===================================================
+`PursuedPyBear <https://ppb.dev>`__ ``ppb``        "Unbearably fun game development". A game toolkit
+                                                   with a focus on being education friendly and
+                                                   exposing an idiomatic Python interface.
+----------------------------------- -------------- ---------------------------------------------------
+`Pygame-ce <https://pyga.me>`__     ``pygame-ce``  A fork of pygame, the classic library for making
+                                                   games in Python.
+=================================== ============== ===================================================
+
+To add a third-party bootstrap, ``pip install`` the named package into the virtual
+environment that contains Briefcase, then run ``briefcase new``. The new bootstrap
+option should be added to the list of GUI toolkits.

docs/reference/configuration.rst

@@ -241,8 +241,11 @@ on an app with a formal name of "My App" would remove:
 ~~~~~~~~~~~~~~~
 
 A Boolean describing if the app is a console app, or a GUI app. Defaults to ``False``
-(producing a GUI app). This setting has no effect on platforms that do not support
-a console mode (e.g., web or mobile platforms).
+(producing a GUI app). This setting has no effect on platforms that do not support a
+console mode (e.g., web or mobile platforms). On platforms that do support console apps,
+the resulting app will write output directly to ``stdout``/``stderr`` (rather than
+writing to a system log), creating a terminal window to display this output (if the
+platform allows).
 
 ``exit_regex``
 ~~~~~~~~~~~~~~

docs/reference/index.rst

@@ -14,3 +14,4 @@ This is the technical reference for public APIs provided by Briefcase.
    configuration
    commands/index
    platforms/index
+   plugins

docs/reference/platforms/macOS/app.rst

@@ -24,15 +24,14 @@ By default, apps will be both signed and notarized when they are packaged.
 Packaging format
 ================
 
-Briefcase supports three packaging formats for a macOS ``.app`` bundle:
+Briefcase supports three packaging formats for a macOS app:
 
-1. A DMG that contains the ``.app`` bundle (using ``briefcase package macOS -p dmg``);
-   or
+1. A DMG that contains the ``.app`` bundle (using ``briefcase package macOS -p dmg``).
 2. A zipped ``.app`` folder (using ``briefcase package macOS -p zip``).
 3. A ``.pkg`` installer (using ``briefcase package macOS -p pkg``).
 
-The ``.pkg`` format is the *required* format for console apps. ``.dmg`` format is the
-default format GUI apps.
+``.pkg`` is the *required* format for console apps. ``.dmg`` is the
+default format for GUI apps.
 
 Icon format
 ===========

docs/reference/platforms/macOS/xcode.rst

@@ -24,12 +24,12 @@ Packaging format
 Briefcase supports three packaging formats for a macOS Xcode project:
 
 1. A DMG that contains the ``.app`` bundle (using ``briefcase package macOS Xcode -p
-   dmg``); or
+   dmg``).
 2. A zipped ``.app`` folder (using ``briefcase package macOS Xcode -p zip``).
 3. A ``.pkg`` installer (using ``briefcase package macOS Xcode -p pkg``).
 
-The ``.pkg`` format is the *required* format for console apps. ``.dmg`` format is the
-default format GUI apps.
+``.pkg`` is the *required* format for console apps. ``.dmg`` is the
+default format for GUI apps.
 
 Icon format
 ===========

docs/reference/plugins.rst

@@ -0,0 +1,70 @@
+========
+Plug-ins
+========
+
+Briefcase ships with support for a range of platforms, output formats and GUI toolkits.
+Internally, these features are implemented using a plug-in interface; as a result, it is
+possible for third-party projects to add their own features to Briefcase by implementing
+plug-ins that satisfy those interfaces.
+
+Each plug-in is defined using an `entry point
+<https://packaging.python.org/en/latest/specifications/entry-points/>`__ definition in
+``pyproject.toml``.
+
+.. _bootstrap-interface:
+
+``briefcase.bootstraps``
+========================
+
+The Briefcase :doc:`new project wizard </reference/commands/new>` asks users to select a
+GUI toolkit. The option selected at this step alters the content of the code generated
+by the wizard, generating framework-specific requirements, system packages, and stub
+code for a new application using that GUI framework. These additions are configured
+using a ``briefcase.bootstrap`` plug-in.
+
+To add a custom ``briefcase.bootstrap`` plug-in, add a
+``[project.entry-points."briefcase.platforms"]`` section to your ``pyproject.toml``
+file; each name/value pair under that section will be interpreted as a bootstrap. The
+name of each bootstrap setting is the label that will be surfaced to the user in the
+wizard. The value is a string identifying a class that implements the
+``briefcase.bootstraps.base.BaseGuiBootstrap`` abstract base class.
+
+For example, the Toga bootstrap is implemented using the following configuration::
+
+    [project.entry-points."briefcase.bootstraps"]
+    Toga = "briefcase.bootstraps.toga:TogaGuiBootstrap"
+
+``briefcase.platforms`` and ``briefcase.formats.*``
+===================================================
+
+Each command implemented by Briefcase is specialized by a platform and output format.
+This implementation is defined using a pair of plug-ins - a ``briefcase.platforms``
+definition describing a platform, and a ``briefcase.format.<platform>`` definition that
+defines the output formats for that platform.
+
+The ``briefcase.platforms`` entry point defines the existence of a platform. Each name
+in this section is name of a platform that can be used when invoking Briefcase commands.
+The value is a fully-qualified Python module name that must defines a single constant
+``DEFAULT_OUTPUT_FORMAT``.
+
+Each platform name is then incorporated into the name of a separate ``format`` entry
+point. Each entry in the ``format`` section for a platform is the name of an output
+format that can be used when invoking Briefcase commands. The value is a fully-qualified
+Python module name that defines 7 symbols:
+
+* ``create`` - a subclass of ``briefcase.commands.create.CreateCommand``
+* ``update`` - a subclass of ``briefcase.commands.create.UpdateCommand``
+* ``open`` - a subclass of ``briefcase.commands.create.OpenCommand``
+* ``build`` - a subclass of ``briefcase.commands.create.BuildCommand``
+* ``run`` - a subclass of ``briefcase.commands.create.RunCommand``
+* ``package`` - a subclass of ``briefcase.commands.create.PackageCommand``
+* ``publish`` - a subclass of ``briefcase.commands.create.PublishCommand``
+
+For example, the definition for the macOS Xcode output format is controlled by the
+following::
+
+    [project.entry-points."briefcase.platforms"]
+    macOS = "briefcase.platforms.macOS"
+
+    [project.entry-points."briefcase.formats.macOS"]
+    xcode = "briefcase.platforms.macOS.xcode"

docs/spelling_wordlist

@@ -11,6 +11,7 @@ backported
 BeeWare
 Bugfix
 Bugfixes
+ce
 checkmarks
 codebase
 Cookiecutter
@@ -66,6 +67,7 @@ proxied
 Proxied
 proxying
 px
+pygame
 Pygame
 Pyodide
 PyScript
@@ -87,6 +89,7 @@ submodule
 subprocesses
 tl
 toml
+toolkits
 towncrier
 tox
 TTY