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

@@ -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
+There are various ways to obtain and install Python for macOS.
-any other Unix platform, but there are a number of additional features such as
+Pre-built versions of the most recent versions of Python are available
-the integrated development environment (IDE) and the Package Manager that are
+from a number of distributors. Much of this document describes use of
-worth pointing out.
+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
+Installation steps
-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.
 
-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
+The downloaded file is a standard macOS installer package file (``.pkg``).
-  you find IDLE, the development environment that is a standard part of official
+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
+  path. To uninstall Python, you can remove these three things.
-  symlink to the Python executable is placed in :file:`/usr/local/bin/`.
+  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
+   Recent versions of macOS include a :command:`python3` command in :file:`/usr/bin/python3`
-   :file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
+   that links to a usually older and incomplete version of Python provided by and for use by
-   respectively. You should never modify or delete these, as they are
+   the Apple development tools, :program:`Xcode` or the :program:`Command Line Tools for Xcode`.
-   Apple-controlled and are used by Apple- or third-party software.  Remember that
+   You should never modify or attempt to delete this installation, as it is
-   if you choose to install a newer Python version from python.org, you will have
+   Apple-controlled and is used by Apple-provided or third-party software.  If
-   two different but functional Python installations on your computer, so it will
+   you choose to install a newer Python version from ``python.org``, you will have
-   be important that your paths and usages are consistent with what you want to do.
+   two different but functional Python installations on your computer that
-
+   can co-exist. The default installer options should ensure that its :command:`python3`
-IDLE includes a Help menu that allows you to access Python documentation. If you
+   will be used instead of the system :command:`python3`.
-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.
-
 
 How to run a Python script
 --------------------------
 
-Your best way to get started with Python on macOS is through the IDLE
+There are two ways to invoke the Python interpreter.
-integrated development environment; see section :ref:`ide` and use the Help menu
+If you are familiar with using a Unix shell in a terminal
-when the IDE is running.
+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>`.
 
-If you want to run Python scripts from the Terminal window command line or from
+You can also invoke the interpreter through an integrated
-the Finder you first need an editor to create your script. macOS comes with a
+development environment.
-number of standard Unix command line editors, :program:`vim`
+:ref:`idle` is a basic editor and interpreter environment
-:program:`nano` among them. If you want a more Mac-like editor,
+which is included with the standard distribution of Python.
-:program:`BBEdit` from Bare Bones Software (see
+:program:`IDLE` includes a Help menu that allows you to access Python documentation. If you
-https://www.barebones.com/products/bbedit/index.html) are good choices, as is
+are completely new to Python, you can read the tutorial introduction
-:program:`TextMate` (see https://macromates.com). Other editors include
+in that document.
-:program:`MacVim` (https://macvim.org) and :program:`Aquamacs`
-(https://aquamacs.org).
 
-To run your script from the Terminal window you must make sure that
+There are many other editors and IDEs available, see :ref:`editors`
-:file:`/usr/local/bin` is in your shell search path.
+for more information.
 
-To run your script from the Finder you have two options:
+To run a Python script file from the terminal window, you can
+invoke the interpreter with the name of the script file:
+
+    |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.
+  its ``Preferences`` menu to change things globally.
 
+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.
 
-.. _osx-gui-scripts:
+.. _alternative_bundles:
 
-Running scripts with a GUI
+Alternative Distributions
---------------------------
+=========================
 
-With older versions of Python, there is one macOS quirk that you need to be
+Besides the standard ``python.org`` for macOS installer, there are third-party
-aware of: programs that talk to the Aqua window manager (in other words,
+distributions for macOS that may include additional functionality.
-anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
+Some popular distributions and their key features:
-instead of :program:`python` to start such scripts.
 
-With Python 3.9, you can use either :program:`python` or :program:`pythonw`.
+`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.
 
-Configuration
+`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).
 
-Python on macOS honors all standard Unix environment variables such as
+`MacPorts <https://www.macports.org>`_
-:envvar:`PYTHONPATH`, but setting these variables for programs started from the
+    Another package manager for macOS including multiple versions of Python and many
-Finder is non-standard as the Finder does not read your :file:`.profile` or
+    third-party Python-based packages. May include pre-built versions of Python and
-:file:`.cshrc` at startup. You need to create a file
+    many packages for older versions of macOS.
-:file:`~/.MacOSX/environment.plist`. See Apple's
-`Technical Q&A QA1067 <https://developer.apple.com/library/archive/qa/qa1067/_index.html>`__
-for details.
-
-For more information on installation Python packages, see section
-:ref:`mac-package-manager`.
-
-
-.. _ide:
-
-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.
 
+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
+Tk toolkit (https://www.tcl.tk). A macOS-native version of Tk is included with
-macOS by Apple, and the latest version can be downloaded and installed from
+the installer.
-https://www.activestate.com; it can also be built from source.
 
-A number of alternative macOS GUI toolkits are available:
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework.
+Information on PyObjC is available from :pypi:`pyobjc`.
 
-* `PySide <https://www.qt.io/qt-for-python>`__: Official Python bindings to the
+A number of alternative macOS GUI toolkits are available including:
-  `Qt GUI toolkit <https://www.qt.io>`__.
 
-* `PyQt <https://riverbankcomputing.com/software/pyqt/intro>`__: Alternative
+* `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/>`_: 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
+* `Toga <https://toga.readthedocs.io>`_: Part of the `BeeWare Project
-  <https://beeware.org>`__; supports desktop, mobile, web and console apps.
+  <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
+* `Briefcase <https://briefcase.readthedocs.io>`_: Part of the `BeeWare Project
-  <https://beeware.org>`__; a cross-platform packaging tool that supports
+  <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
+The `python.org Help page <https://www.python.org/about/help/>`_ has links to many useful resources.
-and developers on the Mac:
+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.
-https://www.python.org/community/sigs/current/pythonmac-sig/
-
-Another useful resource is the MacPython wiki:
-
-https://wiki.python.org/moin/MacPython

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.