From 4b83c03ce964af7fb204144db9adaa524c113a82 Mon Sep 17 00:00:00 2001
From: Ned Deily <nad@python.org>
Date: Sun, 29 Sep 2024 17:39:46 -0600
Subject: gh-124720: Update "Using Python on a Mac" document (#124721)
Update "Using Python on a Mac" section of the "Python Setup and Usage"
document and include information on installing free-threading support.
---
Doc/using/mac.rst | 471 ++++++++++++++++-----
Doc/using/mac_installer_01_introduction.png | Bin 0 -> 190852 bytes
Doc/using/mac_installer_02_readme.png | Bin 0 -> 204902 bytes
Doc/using/mac_installer_03_license.png | Bin 0 -> 120419 bytes
Doc/using/mac_installer_04_installation_type.png | Bin 0 -> 125352 bytes
Doc/using/mac_installer_05_custom_install.png | Bin 0 -> 169369 bytes
Doc/using/mac_installer_06_summary.png | Bin 0 -> 157956 bytes
Doc/using/mac_installer_07_applications.png | Bin 0 -> 148826 bytes
.../mac_installer_08_install_certificates.png | Bin 0 -> 174152 bytes
...c_installer_09_custom_install_free_threaded.png | Bin 0 -> 192812 bytes
.../2024-09-27-16-47-48.gh-issue-124720.nVSTVb.rst | 2 +
11 files changed, 363 insertions(+), 110 deletions(-)
create mode 100644 Doc/using/mac_installer_01_introduction.png
create mode 100644 Doc/using/mac_installer_02_readme.png
create mode 100644 Doc/using/mac_installer_03_license.png
create mode 100644 Doc/using/mac_installer_04_installation_type.png
create mode 100644 Doc/using/mac_installer_05_custom_install.png
create mode 100644 Doc/using/mac_installer_06_summary.png
create mode 100644 Doc/using/mac_installer_07_applications.png
create mode 100644 Doc/using/mac_installer_08_install_certificates.png
create mode 100644 Doc/using/mac_installer_09_custom_install_free_threaded.png
create mode 100644 Misc/NEWS.d/next/Documentation/2024-09-27-16-47-48.gh-issue-124720.nVSTVb.rst
diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst
index 2dfac07..4b6c884 100644
--- a/Doc/using/mac.rst
+++ b/Doc/using/mac.rst
@@ -2,140 +2,223 @@
.. _using-on-mac:
*********************
-Using Python on a Mac
+Using Python on macOS
*********************
-:Author: Bob Savage <bobsavage@mac.com>
+.. sectionauthor:: Bob Savage <bobsavage@mac.com>
+.. sectionauthor:: Ned Deily <nad@python.org>
+This document aims to give an overview of macOS-specific behavior you should
+know about to get started with Python on Mac computers.
+Python on a Mac running macOS is very similar to Python on other Unix-derived platforms,
+but there are some differences in installation and some features.
-Python on a Mac running macOS is in principle very similar to Python on
-any other Unix platform, but there are a number of additional features such as
-the integrated development environment (IDE) and the Package Manager that are
-worth pointing out.
+There are various ways to obtain and install Python for macOS.
+Pre-built versions of the most recent versions of Python are available
+from a number of distributors. Much of this document describes use of
+the Pythons provided by the CPython release team for download from
+the `python.org website <https://www.python.org/downloads/>`_. See
+:ref:`alternative_bundles` for some other options.
+.. |usemac_x_dot_y| replace:: 3.13
+.. |usemac_python_x_dot_y_literal| replace:: ``python3.13``
+.. |usemac_python_x_dot_y_t_literal| replace:: ``python3.13t``
+.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python3.13t-config``
+.. |usemac_applications_folder_name| replace:: ``Python 3.13``
+.. |usemac_applications_folder_version| replace:: ``/Applications/Python 3.13/``
.. _getting-osx:
.. _getting-and-installing-macpython:
-Getting and Installing Python
-=============================
+Using Python for macOS from ``python.org``
+==========================================
-macOS used to come with Python 2.7 pre-installed between versions
-10.8 and `12.3 <https://developer.apple.com/documentation/macos-release-notes/macos-12_3-release-notes#Python>`_.
-You are invited to install the most recent version of Python 3 from the `Python
-website <https://www.python.org/downloads/macos/>`__.
-A current "universal2 binary" build of Python, which runs natively on the Mac's
-new Apple Silicon and legacy Intel processors, is available there.
+Installation steps
+------------------
-What you get after installing is a number of things:
+For `current Python versions <https://www.python.org/downloads/>`_
+(other than those in ``security`` status), the release team produces a
+**Python for macOS** installer package for each new release.
+A list of available installers
+is available `here <https://www.python.org/downloads/macos/>`_.
+We recommend using the most recent supported Python version where possible.
+Current installers provide a
+`universal2 binary <https://en.wikipedia.org/wiki/Universal_binary>`_ build
+of Python which runs natively on all Macs (Apple Silicon and Intel) that are
+supported by a wide range of macOS versions,
+currently typically from at least **macOS 10.13 High Sierra** on.
-* A |python_version_literal| folder in your :file:`Applications` folder. In here
- you find IDLE, the development environment that is a standard part of official
+The downloaded file is a standard macOS installer package file (``.pkg``).
+File integrity information (checksum, size, sigstore signature, etc) for each file is included
+on the release download page. Installer packages and their contents are signed and notarized
+with ``Python Software Foundation`` Apple Developer ID certificates
+to meet `macOS Gatekeeper requirements <https://support.apple.com/en-us/102445>`_.
+
+For a default installation, double-click on the downloaded installer package file.
+This should launch the standard macOS Installer app and display the first of several
+installer windows steps.
+
+.. image:: mac_installer_01_introduction.png
+
+Clicking on the **Continue** button brings up the **Read Me** for this installer.
+Besides other important information, the **Read Me** documents which Python version is
+going to be installed and on what versions of macOS it is supported. You may need
+to scroll through to read the whole file. By default, this **Read Me** will also be
+installed in |usemac_applications_folder_version| and available to read anytime.
+
+.. image:: mac_installer_02_readme.png
+
+Clicking on **Continue** proceeds to display the license for Python and for
+other included software. You will then need to **Agree** to the license terms
+before proceeding to the next step. This license file will also be installed
+and available to be read later.
+
+.. image:: mac_installer_03_license.png
+
+After the license terms are accepted, the next step is the **Installation Type**
+display. For most uses, the standard set of installation operations is appropriate.
+
+.. image:: mac_installer_04_installation_type.png
+
+By pressing the **Customize** button, you can choose to omit or select certain package
+components of the installer. Click on each package name to see a description of
+what it installs.
+To also install support for the optional experimental free-threaded feature,
+see :ref:`install-freethreaded-macos`.
+
+.. image:: mac_installer_05_custom_install.png
+
+In either case, clicking **Install** will begin the install process by asking
+permission to install new software. A macOS user name with ``Administrator`` privilege
+is needed as the installed Python will be available to all users of the Mac.
+
+When the installation is complete, the **Summary** window will appear.
+
+.. image:: mac_installer_06_summary.png
+
+Double-click on the :command:`Install Certificates.command`
+icon or file in the |usemac_applications_folder_version| window to complete the
+installation.
+
+.. image:: mac_installer_07_applications.png
+
+This will open a temporary :program:`Terminal` shell window that
+will use the new Python to download and install SSL root certificates
+for its use.
+
+.. image:: mac_installer_08_install_certificates.png
+
+If ``Successfully installed certifi`` and ``update complete`` appears
+in the terminal window, the installation is complete.
+Close this terminal window and the installer window.
+
+A default install will include:
+
+* A |usemac_applications_folder_name| folder in your :file:`Applications` folder. In here
+ you find :program:`IDLE`, the development environment that is a standard part of official
Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
- scripts from the Finder.
+ scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
Python executable and libraries. The installer adds this location to your shell
- path. To uninstall Python, you can remove these three things. A
- symlink to the Python executable is placed in :file:`/usr/local/bin/`.
+ path. To uninstall Python, you can remove these three things.
+ Symlinks to the Python executable are placed in :file:`/usr/local/bin/`.
.. note::
- On macOS 10.8-12.3, the Apple-provided build of Python is installed in
- :file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
- respectively. You should never modify or delete these, as they are
- Apple-controlled and are used by Apple- or third-party software. Remember that
- if you choose to install a newer Python version from python.org, you will have
- two different but functional Python installations on your computer, so it will
- be important that your paths and usages are consistent with what you want to do.
-
-IDLE includes a Help menu that allows you to access Python documentation. If you
-are completely new to Python you should start reading the tutorial introduction
-in that document.
-
-If you are familiar with Python on other Unix platforms you should read the
-section on running Python scripts from the Unix shell.
-
+ Recent versions of macOS include a :command:`python3` command in :file:`/usr/bin/python3`
+ that links to a usually older and incomplete version of Python provided by and for use by
+ the Apple development tools, :program:`Xcode` or the :program:`Command Line Tools for Xcode`.
+ You should never modify or attempt to delete this installation, as it is
+ Apple-controlled and is used by Apple-provided or third-party software. If
+ you choose to install a newer Python version from ``python.org``, you will have
+ two different but functional Python installations on your computer that
+ can co-exist. The default installer options should ensure that its :command:`python3`
+ will be used instead of the system :command:`python3`.
How to run a Python script
--------------------------
-Your best way to get started with Python on macOS is through the IDLE
-integrated development environment; see section :ref:`ide` and use the Help menu
-when the IDE is running.
+There are two ways to invoke the Python interpreter.
+If you are familiar with using a Unix shell in a terminal
+window, you can invoke |usemac_python_x_dot_y_literal| or ``python3`` optionally
+followed by one or more command line options (described in :ref:`using-on-general`).
+The Python tutorial also has a useful section on
+:ref:`using Python interactively from a shell <tut-interac>`.
+
+You can also invoke the interpreter through an integrated
+development environment.
+:ref:`idle` is a basic editor and interpreter environment
+which is included with the standard distribution of Python.
+:program:`IDLE` includes a Help menu that allows you to access Python documentation. If you
+are completely new to Python, you can read the tutorial introduction
+in that document.
-If you want to run Python scripts from the Terminal window command line or from
-the Finder you first need an editor to create your script. macOS comes with a
-number of standard Unix command line editors, :program:`vim`
-:program:`nano` among them. If you want a more Mac-like editor,
-:program:`BBEdit` from Bare Bones Software (see
-https://www.barebones.com/products/bbedit/index.html) are good choices, as is
-:program:`TextMate` (see https://macromates.com). Other editors include
-:program:`MacVim` (https://macvim.org) and :program:`Aquamacs`
-(https://aquamacs.org).
+There are many other editors and IDEs available, see :ref:`editors`
+for more information.
-To run your script from the Terminal window you must make sure that
-:file:`/usr/local/bin` is in your shell search path.
+To run a Python script file from the terminal window, you can
+invoke the interpreter with the name of the script file:
-To run your script from the Finder you have two options:
+ |usemac_python_x_dot_y_literal| ``myscript.py``
+
+To run your script from the Finder, you can either:
* Drag it to :program:`Python Launcher`.
* Select :program:`Python Launcher` as the default application to open your
- script (or any ``.py`` script) through the finder Info window and double-click it.
+ script (or any ``.py`` script) through the Finder Info window and double-click it.
:program:`Python Launcher` has various preferences to control how your script is
launched. Option-dragging allows you to change these for one invocation, or use
- its Preferences menu to change things globally.
-
-
-.. _osx-gui-scripts:
-
-Running scripts with a GUI
---------------------------
-
-With older versions of Python, there is one macOS quirk that you need to be
-aware of: programs that talk to the Aqua window manager (in other words,
-anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
-instead of :program:`python` to start such scripts.
+ its ``Preferences`` menu to change things globally.
-With Python 3.9, you can use either :program:`python` or :program:`pythonw`.
+Be aware that running the script directly from the macOS Finder might
+produce different results than when running from a terminal window as
+the script will not be run in the usual shell environment including
+any setting of environment variables in shell profiles.
+And, as with any other script or program,
+be certain of what you are about to run.
+.. _alternative_bundles:
-Configuration
--------------
+Alternative Distributions
+=========================
-Python on macOS honors all standard Unix environment variables such as
-:envvar:`PYTHONPATH`, but setting these variables for programs started from the
-Finder is non-standard as the Finder does not read your :file:`.profile` or
-:file:`.cshrc` at startup. You need to create a file
-:file:`~/.MacOSX/environment.plist`. See Apple's
-`Technical Q&A QA1067 <https://developer.apple.com/library/archive/qa/qa1067/_index.html>`__
-for details.
+Besides the standard ``python.org`` for macOS installer, there are third-party
+distributions for macOS that may include additional functionality.
+Some popular distributions and their key features:
-For more information on installation Python packages, see section
-:ref:`mac-package-manager`.
+`ActivePython <https://www.activestate.com/products/python/>`_
+ Installer with multi-platform compatibility, documentation
+`Anaconda <https://www.anaconda.com/download/>`_
+ Popular scientific modules (such as numpy, scipy, and pandas) and the
+ ``conda`` package manager.
-.. _ide:
+`Homebrew <https://brew.sh>`_
+ Package manager for macOS including multiple versions of Python and many
+ third-party Python-based packages (including numpy, scipy, and pandas).
-The IDE
-=======
-
-Python ships with the standard IDLE development environment. A good
-introduction to using IDLE can be found at
-https://www.hashcollision.org/hkn/python/idle_intro/index.html.
+`MacPorts <https://www.macports.org>`_
+ Another package manager for macOS including multiple versions of Python and many
+ third-party Python-based packages. May include pre-built versions of Python and
+ many packages for older versions of macOS.
+Note that distributions might not include the latest versions of Python or
+other libraries, and are not maintained or supported by the core Python team.
.. _mac-package-manager:
Installing Additional Python Packages
=====================================
-This section has moved to the `Python Packaging User Guide`_.
+Refer to the `Python Packaging User Guide`_ for more information.
.. _Python Packaging User Guide: https://packaging.python.org/en/latest/tutorials/installing-packages/
+.. _osx-gui-scripts:
+
.. _gui-programming-on-the-mac:
GUI Programming
@@ -143,36 +226,209 @@ GUI Programming
There are several options for building GUI applications on the Mac with Python.
-*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
-the foundation of most modern Mac development. Information on PyObjC is
-available from :pypi:`pyobjc`.
-
The standard Python GUI toolkit is :mod:`tkinter`, based on the cross-platform
-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.
+Tk toolkit (https://www.tcl.tk). A macOS-native version of Tk is included with
+the installer.
+
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework.
+Information on PyObjC is available from :pypi:`pyobjc`.
-A number of alternative macOS GUI toolkits are available:
+A number of alternative macOS GUI toolkits are available including:
-* `PySide <https://www.qt.io/qt-for-python>`__: Official Python bindings to the
- `Qt GUI toolkit <https://www.qt.io>`__.
+* `PySide <https://www.qt.io/qt-for-python>`_: Official Python bindings to the
+ `Qt GUI toolkit <https://wiki.qt.io/Qt_for_Python>`_.
-* `PyQt <https://riverbankcomputing.com/software/pyqt/intro>`__: Alternative
+* `PyQt <https://riverbankcomputing.com/software/pyqt/>`_: Alternative
Python bindings to Qt.
-* `Kivy <https://kivy.org>`__: A cross-platform GUI toolkit that supports
+* `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.
+* `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
+* `wxPython <https://wxpython.org>`_: A cross-platform toolkit that
supports desktop operating systems.
+
+Advanced Topics
+===============
+
+.. _install-freethreaded-macos:
+
+Installing Free-threaded Binaries
+---------------------------------
+
+.. versionadded:: 3.13 (Experimental)
+
+.. note::
+
+ Everything described in this section is considered experimental,
+ and should be expected to change in future releases.
+
+The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
+installer package can optionally install an additional build of
+Python |usemac_x_dot_y| that supports :pep:`703`, the experimental free-threading feature
+(running with the :term:`global interpreter lock` disabled).
+Check the release page on ``python.org`` for possible updated information.
+
+Because this feature is still considered experimental, the support for it
+is not installed by default. It is packaged as a separate install option,
+available by clicking the **Customize** button on the **Installation Type**
+step of the installer as described above.
+
+.. image:: mac_installer_09_custom_install_free_threaded.png
+
+If the box next to the **Free-threaded Python** package name is checked,
+a separate :file:`PythonT.framework` will also be installed
+alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`.
+This configuration allows a free-threaded Python |usemac_x_dot_y| build to co-exist
+on your system with a traditional (GIL only) Python |usemac_x_dot_y| build with
+minimal risk while installing or testing. This installation layout is itself
+experimental and is subject to change in future releases.
+
+Known cautions and limitations:
+
+- The **UNIX command-line tools** package, which is selected by default,
+ will install links in :file:`/usr/local/bin` for |usemac_python_x_dot_y_t_literal|,
+ the free-threaded interpreter, and |usemac_python_x_dot_y_t_literal_config|,
+ a configuration utility which may be useful for package builders.
+ Since :file:`/usr/local/bin` is typically included in your shell ``PATH``,
+ in most cases no changes to your ``PATH`` environment variables should
+ be needed to use |usemac_python_x_dot_y_t_literal|.
+
+- For this release, the **Shell profile updater** package and the
+ :file:`Update Shell Profile.command` in |usemac_applications_folder_version|
+ do not support the free-threaded package.
+
+- The free-threaded build and the traditional build have separate search
+ paths and separate :file:`site-packages` directories so, by default,
+ if you need a package available in both builds, it may need to be installed in both.
+ The free-threaded package will install a separate instance of :program:`pip` for use
+ with |usemac_python_x_dot_y_t_literal|.
+
+ - To install a package using :command:`pip` without a :command:`venv`:
+
+ |usemac_python_x_dot_y_t_literal| ``-m pip install <package_name>``
+
+- When working with multiple Python environments, it is usually safest and easiest
+ to :ref:`create and use virtual environments <tut-venv>`.
+ This can avoid possible command name conflicts and confusion about which Python is in use:
+
+ |usemac_python_x_dot_y_t_literal| ``-m venv <venv_name>``
+
+ then :command:`activate`.
+
+- To run a free-threaded version of IDLE:
+
+ |usemac_python_x_dot_y_t_literal| ``-m idlelib``
+
+- The interpreters in both builds respond to the same
+ :ref:`PYTHON environment variables <using-on-envvars>`
+ which may have unexpected results, for example, if you have ``PYTHONPATH``
+ set in a shell profile. If necessary, there are
+ :ref:`command line options <using-on-interface-options>` like ``-E``
+ to ignore these environment variables.
+
+- The free-threaded build links to the third-party shared libraries,
+ such as ``OpenSSL`` and ``Tk``, installed in the traditional framework.
+ This means that both builds also share one set of trust certificates
+ as installed by the :command:`Install Certificates.command` script,
+ thus it only needs to be run once.
+
+- If you cannot depend on the link in ``/usr/local/bin`` pointing to the
+ ``python.org`` free-threaded |usemac_python_x_dot_y_t_literal| (for example, if you want
+ to install your own version there or some other distribution does),
+ you can explicitly set your shell ``PATH`` environment variable to
+ include the ``PythonT`` framework ``bin`` directory:
+
+ .. code-block:: sh
+
+ export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
+
+ The traditional framework installation by default does something similar,
+ except for :file:`Python.framework`. Be aware that having both framework ``bin``
+ directories in ``PATH`` can lead to confusion if there are duplicate names
+ like ``python3.13`` in both; which one is actually used depends on the order
+ they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt``
+ commands can show which path is being used. Using virtual environments
+ can help avoid such ambiguities. Another option might be to create
+ a shell :command:`alias` to the desired interpreter, like:
+
+ .. code-block:: sh
+
+ alias py3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13"
+ alias py3.13t="/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t"
+
+Installing using the command line
+---------------------------------
+
+If you want to use automation to install the ``python.org`` installer package
+(rather than by using the familiar macOS :program:`Installer` GUI app),
+the macOS command line :command:`installer` utility lets you select non-default
+options, too. If you are not familiar with :command:`installer`, it can be
+somewhat cryptic (see :command:`man installer` for more information).
+As an example, the following shell snippet shows one way to do it,
+using the ``3.13.0b2`` release and selecting the free-threaded interpreter
+option:
+
+.. code-block:: sh
+
+ RELEASE="python-3.13.0b2-macos11.pkg"
+
+ # download installer pkg
+ curl -O https://www.python.org/ftp/python/3.13.0/${RELEASE}
+
+ # create installer choicechanges to customize the install:
+ # enable the PythonTFramework-3.13 package
+ # while accepting the other defaults (install all other packages)
+ cat > ./choicechanges.plist <<EOF
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+ <plist version="1.0">
+ <array>
+ <dict>
+ <key>attributeSetting</key>
+ <integer>1</integer>
+ <key>choiceAttribute</key>
+ <string>selected</string>
+ <key>choiceIdentifier</key>
+ <string>org.python.Python.PythonTFramework-3.13</string>
+ </dict>
+ </array>
+ </plist>
+ EOF
+
+ sudo installer -pkg ./${RELEASE} -applyChoiceChangesXML ./choicechanges.plist -target /
+
+
+You can then test that both installer builds are now available with something like:
+
+.. code-block:: console
+
+ $ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
+ $ /usr/local/bin/python3.13t -VV
+ Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
+ $ # and the traditional interpreter
+ $ /usr/local/bin/python3.13 -VV
+ Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
+ $ # test that they are also available without the prefix if /usr/local/bin is on $PATH
+ $ python3.13t -VV
+ Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
+ $ python3.13 -VV
+ Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
+
+.. note::
+
+ Current ``python.org`` installers only install to fixed locations like
+ :file:`/Library/Frameworks/`, :file:`/Applications`, and :file:`/usr/local/bin`.
+ You cannot use the :command:`installer` ``-domain`` option to install to
+ other locations.
+
.. _distributing-python-applications-on-the-mac:
Distributing Python Applications
-================================
+--------------------------------
A range of tools exist for converting your Python code into a standalone
distributable application:
@@ -180,12 +436,12 @@ distributable application:
* :pypi:`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
+* `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
+* `PyInstaller <https://pyinstaller.org/>`_: A cross-platform packaging tool that creates
a single file or folder as a distributable artifact.
App Store Compliance
@@ -213,11 +469,6 @@ required if you are using the macOS App Store as a distribution channel.
Other Resources
===============
-The Pythonmac-SIG mailing list is an excellent support resource for Python users
-and developers on the Mac:
-
-https://www.python.org/community/sigs/current/pythonmac-sig/
-
-Another useful resource is the MacPython wiki:
-
-https://wiki.python.org/moin/MacPython
+The `python.org Help page <https://www.python.org/about/help/>`_ has links to many useful resources.
+The `Pythonmac-SIG mailing list <https://www.python.org/community/sigs/current/pythonmac-sig/>`_
+is another support resource specifically for Python users and developers on the Mac.
diff --git a/Doc/using/mac_installer_01_introduction.png b/Doc/using/mac_installer_01_introduction.png
new file mode 100644
index 0000000..1999f3a
Binary files /dev/null and b/Doc/using/mac_installer_01_introduction.png differ
diff --git a/Doc/using/mac_installer_02_readme.png b/Doc/using/mac_installer_02_readme.png
new file mode 100644
index 0000000..a36efaf
Binary files /dev/null and b/Doc/using/mac_installer_02_readme.png differ
diff --git a/Doc/using/mac_installer_03_license.png b/Doc/using/mac_installer_03_license.png
new file mode 100644
index 0000000..598c22a
Binary files /dev/null and b/Doc/using/mac_installer_03_license.png differ
diff --git a/Doc/using/mac_installer_04_installation_type.png b/Doc/using/mac_installer_04_installation_type.png
new file mode 100644
index 0000000..9498fd0
Binary files /dev/null and b/Doc/using/mac_installer_04_installation_type.png differ
diff --git a/Doc/using/mac_installer_05_custom_install.png b/Doc/using/mac_installer_05_custom_install.png
new file mode 100644
index 0000000..3a201d2
Binary files /dev/null and b/Doc/using/mac_installer_05_custom_install.png differ
diff --git a/Doc/using/mac_installer_06_summary.png b/Doc/using/mac_installer_06_summary.png
new file mode 100644
index 0000000..1af6eee
Binary files /dev/null and b/Doc/using/mac_installer_06_summary.png differ
diff --git a/Doc/using/mac_installer_07_applications.png b/Doc/using/mac_installer_07_applications.png
new file mode 100644
index 0000000..940219c
Binary files /dev/null and b/Doc/using/mac_installer_07_applications.png differ
diff --git a/Doc/using/mac_installer_08_install_certificates.png b/Doc/using/mac_installer_08_install_certificates.png
new file mode 100644
index 0000000..c125eeb
Binary files /dev/null and b/Doc/using/mac_installer_08_install_certificates.png differ
diff --git a/Doc/using/mac_installer_09_custom_install_free_threaded.png b/Doc/using/mac_installer_09_custom_install_free_threaded.png
new file mode 100644
index 0000000..0f69c55
Binary files /dev/null and b/Doc/using/mac_installer_09_custom_install_free_threaded.png differ
diff --git a/Misc/NEWS.d/next/Documentation/2024-09-27-16-47-48.gh-issue-124720.nVSTVb.rst b/Misc/NEWS.d/next/Documentation/2024-09-27-16-47-48.gh-issue-124720.nVSTVb.rst
new file mode 100644
index 0000000..6bef1e4
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2024-09-27-16-47-48.gh-issue-124720.nVSTVb.rst
@@ -0,0 +1,2 @@
+Update "Using Python on a Mac" section of the "Python Setup and Usage"
+document and include information on installing free-threading support.
--
cgit v0.12