Repository: python/cpython
Pull request: gh-117058: Update GUI and packaging recommendations for macOS.
Updates the list of GUI and app packaging recommendations for macOS, adding Toga, Briefcase, Kivy and PyInstaller.

Full disclosure - I'm the maintainer of Toga and Briefcase. I have no affiliation to the other projects added.

Fixes #117058.


<!-- gh-issue-number: gh-117058 -->
* Issue: gh-117058
<!-- /gh-issue-number -->


<!-- readthedocs-preview cpython-previews start -->
----
📚 Documentation preview 📚: https://cpython-previews--117059.org.readthedocs.build/en/117059/using/mac.html

<!-- readthedocs-preview cpython-previews end -->

Problem statement:
macOS GUI and packaging suggestions are out of date
# Documentation

The current macOS usage guide doesn't mention several prominent GUI toolkits (Kivy, Toga), or app packaging tools (PyInstaller, Briefcacse). The guide should be updated to include links to these projects.

<!-- gh-linked-prs -->
### Linked PRs
* gh-117059
* gh-117081
* gh-117082
<!-- /gh-linked-prs -->

Hints from issue discussion:

Commit message: Update GUI and packaging recommendations for macOS.

Patch to review:
diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst
index e99993238895f9..8f3372b8e017f5 100644
--- a/Doc/using/mac.rst
+++ b/Doc/using/mac.rst
@@ -152,26 +152,41 @@ Tk toolkit (https://www.tcl.tk). An Aqua-native version of Tk is bundled with
 macOS by Apple, and the latest version can be downloaded and installed from
 https://www.activestate.com; it can also be built from source.
 
-*wxPython* is another popular cross-platform GUI toolkit that runs natively on
-macOS. Packages and documentation are available from https://www.wxpython.org.
+A number of alternative macOS GUI toolkits are available:
 
-*PyQt* is another popular cross-platform GUI toolkit that runs natively on
-macOS. More information can be found at
-https://riverbankcomputing.com/software/pyqt/intro.
+* `PySide <https://www.qt.io/qt-for-python>`__: Official Python bindings to the
+  `Qt GUI toolkit <https://qt.io>`__.
 
-*PySide* is another cross-platform Qt-based toolkit. More information at
-https://www.qt.io/qt-for-python.
+* `PyQt <https://riverbankcomputing.com/software/pyqt/intro>`__: Alternative
+  Python bindings to Qt.
 
+* `Kivy <https://kivy.org>`__: A cross-platform GUI toolkit that supports
+  desktop and mobile platforms.
+
+* `Toga <https://toga.readthedocs.io>`__: Part of the `BeeWare Project
+  <https://beeware.org>`__; supports desktop, mobile, web and console apps.
+
+* `wxPython <https://www.wxpython.org>`__: A cross-platform toolkit that
+  supports desktop operating systems.
 
 .. _distributing-python-applications-on-the-mac:
 
 Distributing Python Applications
 ================================
 
-The standard tool for deploying standalone Python applications on the Mac is
-:program:`py2app`. More information on installing and using :program:`py2app`
-can be found at https://pypi.org/project/py2app/.
+A range of tools exist for converting your Python code into a standalone
+distributable application:
+
+* `py2app <https://pypi.org/project/py2app/>`__: Supports creating macOS ``.app``
+  bundles from a Python project.
 
+* `Briefcase <https://briefcase.readthedocs.io>`__: Part of the `BeeWare Project
+  <https://beeware.org>`__; a cross-platform packaging tool that supports
+  creation of ``.app`` bundles on macOS, as well as managing signing and
+  notarization.
+
+* `PyInstaller <https://pyinstaller.org/>`__: A cross-platform packaging tool that creates
+  a single file or folder as a distributable artifact.
 
 Other Resources
 ===============
@@ -184,4 +199,3 @@ https://www.python.org/community/sigs/current/pythonmac-sig/
 Another useful resource is the MacPython wiki:
 
 https://wiki.python.org/moin/MacPython
-
diff --git a/Misc/NEWS.d/next/Documentation/2024-03-20-12-58-00.gh-issue-117058.t-1AzS.rst b/Misc/NEWS.d/next/Documentation/2024-03-20-12-58-00.gh-issue-117058.t-1AzS.rst
new file mode 100644
index 00000000000000..416ed94ac0f2cd
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2024-03-20-12-58-00.gh-issue-117058.t-1AzS.rst
@@ -0,0 +1,2 @@
+The macOS usage guide was updated to include some newer GUI and packaging
+tools.


Code review comments:
path: Misc/NEWS.d/next/Documentation/2024-03-20-12-58-00.gh-issue-117058.t-1AzS.rst
text: @user1:
Let's remove this NEWS file, we usually don't include them for docs changes ([ref](https://devguide.python.org/core-developers/committing/#updating-news-and-what-s-new-in-python)).


@author:
No problems - removed.

Out of interest, is there a way to flag to Bevedere that there's no NEWS file requirement, or do we just live with the CI failure for that test?

@author:
... and now I see the reference to the skip-news label in Bevedere's message. I've added the label; feels like this would be a good addition to the dev guide (and/or the repo PR template?).

@user1:
It's in the devguide here: https://devguide.python.org/triage/labels/#labels-specific-to-prs

It could be useful PR template, but we need to strike a balance between informative and tl;dr. Feel free to propose something if you'd like 👍