mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-07 19:35:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Use replacements to update versions in "Using Python on macOS" (#130400)

Browse source
This commit is contained in:
Hugo van Kemenade 2025-06-17 01:07:25 +03:00 • committed by GitHub
parent d8994b0a77
commit 21bac3aecd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 51 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/conf.py
View file

@ -79,6 +79,10 @@ version, release = import_module('patchlevel').get_version_info()
rst_epilog = f""" rst_epilog = f"""
.. |python_version_literal| replace:: ``Python {version}`` .. |python_version_literal| replace:: ``Python {version}``
.. |python_x_dot_y_literal| replace:: ``python{version}`` .. |python_x_dot_y_literal| replace:: ``python{version}``
.. |python_x_dot_y_t_literal| replace:: ``python{version}t``
.. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config``
.. |x_dot_y_b2_literal| replace:: ``{version}.0b2``
.. |applications_python_version_literal| replace:: ``/Applications/Python {version}/``
.. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}`` .. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``
.. Apparently this how you hack together a formatted link: .. Apparently this how you hack together a formatted link:

93
Doc/using/mac.rst
View file

@ -20,13 +20,6 @@ the Pythons provided by the CPython release team for download from
the `python.org website <https://www.python.org/downloads/>`_. See the `python.org website <https://www.python.org/downloads/>`_. See
:ref:`alternative_bundles` for some other options. :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-osx:
.. _getting-and-installing-macpython: .. _getting-and-installing-macpython:
@ -64,7 +57,7 @@ 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 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 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 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. installed in |applications_python_version_literal| and available to read anytime.
.. image:: mac_installer_02_readme.png .. image:: mac_installer_02_readme.png
@ -97,7 +90,7 @@ When the installation is complete, the **Summary** window will appear.
.. image:: mac_installer_06_summary.png .. image:: mac_installer_06_summary.png
Double-click on the :command:`Install Certificates.command` Double-click on the :command:`Install Certificates.command`
icon or file in the |usemac_applications_folder_version| window to complete the icon or file in the |applications_python_version_literal| window to complete the
installation. installation.
.. image:: mac_installer_07_applications.png .. image:: mac_installer_07_applications.png
@ -114,7 +107,7 @@ Close this terminal window and the installer window.
A default install will include: A default install will include:
* A |usemac_applications_folder_name| folder in your :file:`Applications` folder. In here * A |python_version_literal| folder in your :file:`Applications` folder. In here
you find :program:`IDLE`, the development environment that is a standard part of official 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 Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_. scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
@ -141,7 +134,7 @@ How to run a Python script
There are two ways to invoke the Python interpreter. There are two ways to invoke the Python interpreter.
If you are familiar with using a Unix shell in a terminal 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 window, you can invoke |python_x_dot_y_literal| or ``python3`` optionally
followed by one or more command line options (described in :ref:`using-on-general`). followed by one or more command line options (described in :ref:`using-on-general`).
The Python tutorial also has a useful section on The Python tutorial also has a useful section on
:ref:`using Python interactively from a shell <tut-interac>`. :ref:`using Python interactively from a shell <tut-interac>`.
@ -160,7 +153,7 @@ for more information.
To run a Python script file from the terminal window, you can To run a Python script file from the terminal window, you can
invoke the interpreter with the name of the script file: invoke the interpreter with the name of the script file:
|usemac_python_x_dot_y_literal| ``myscript.py`` |python_x_dot_y_literal| ``myscript.py``
To run your script from the Finder, you can either: To run your script from the Finder, you can either:
@ -268,7 +261,7 @@ Installing Free-threaded Binaries
The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>` The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
installer package can optionally install an additional build of installer package can optionally install an additional build of
Python |usemac_x_dot_y| that supports :pep:`703`, the experimental free-threading feature Python |version| that supports :pep:`703`, the experimental free-threading feature
(running with the :term:`global interpreter lock` disabled). (running with the :term:`global interpreter lock` disabled).
Check the release page on ``python.org`` for possible updated information. Check the release page on ``python.org`` for possible updated information.
@ -282,46 +275,54 @@ step of the installer as described above.
If the box next to the **Free-threaded Python** package name is checked, If the box next to the **Free-threaded Python** package name is checked,
a separate :file:`PythonT.framework` will also be installed a separate :file:`PythonT.framework` will also be installed
alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`. 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 This configuration allows a free-threaded Python |version| build to co-exist
on your system with a traditional (GIL only) Python |usemac_x_dot_y| build with on your system with a traditional (GIL only) Python |version| build with
minimal risk while installing or testing. This installation layout is itself minimal risk while installing or testing. This installation layout is itself
experimental and is subject to change in future releases. experimental and is subject to change in future releases.
Known cautions and limitations: Known cautions and limitations:
- The **UNIX command-line tools** package, which is selected by default, - 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|, will install links in :file:`/usr/local/bin` for |python_x_dot_y_t_literal|,
the free-threaded interpreter, and |usemac_python_x_dot_y_t_literal_config|, the free-threaded interpreter, and |python_x_dot_y_t_literal_config|,
a configuration utility which may be useful for package builders. a configuration utility which may be useful for package builders.
Since :file:`/usr/local/bin` is typically included in your shell ``PATH``, Since :file:`/usr/local/bin` is typically included in your shell ``PATH``,
in most cases no changes to your ``PATH`` environment variables should in most cases no changes to your ``PATH`` environment variables should
be needed to use |usemac_python_x_dot_y_t_literal|. be needed to use |python_x_dot_y_t_literal|.
- For this release, the **Shell profile updater** package and the - For this release, the **Shell profile updater** package and the
:file:`Update Shell Profile.command` in |usemac_applications_folder_version| :file:`Update Shell Profile.command` in |applications_python_version_literal|
do not support the free-threaded package. do not support the free-threaded package.
- The free-threaded build and the traditional build have separate search - The free-threaded build and the traditional build have separate search
paths and separate :file:`site-packages` directories so, by default, 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. 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 The free-threaded package will install a separate instance of :program:`pip` for use
with |usemac_python_x_dot_y_t_literal|. with |python_x_dot_y_t_literal|.
- To install a package using :command:`pip` without a :command:`venv`: - To install a package using :command:`pip` without a :command:`venv`:
|usemac_python_x_dot_y_t_literal| ``-m pip install <package_name>`` .. parsed-literal::
python\ |version|\ t -m pip install <package_name>
- When working with multiple Python environments, it is usually safest and easiest - When working with multiple Python environments, it is usually safest and easiest
to :ref:`create and use virtual environments <tut-venv>`. to :ref:`create and use virtual environments <tut-venv>`.
This can avoid possible command name conflicts and confusion about which Python is in use: 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>`` .. parsed-literal::
python\ |version|\ t -m venv <venv_name>
then :command:`activate`. then :command:`activate`.
- To run a free-threaded version of IDLE: - To run a free-threaded version of IDLE:
|usemac_python_x_dot_y_t_literal| ``-m idlelib`` .. parsed-literal::
python\ |version|\ t -m idlelib
- The interpreters in both builds respond to the same - The interpreters in both builds respond to the same
:ref:`PYTHON environment variables <using-on-envvars>` :ref:`PYTHON environment variables <using-on-envvars>`
@ -337,28 +338,28 @@ Known cautions and limitations:
thus it only needs to be run once. thus it only needs to be run once.
- If you cannot depend on the link in ``/usr/local/bin`` pointing to the - 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 ``python.org`` free-threaded |python_x_dot_y_t_literal| (for example, if you want
to install your own version there or some other distribution does), to install your own version there or some other distribution does),
you can explicitly set your shell ``PATH`` environment variable to you can explicitly set your shell ``PATH`` environment variable to
include the ``PythonT`` framework ``bin`` directory: include the ``PythonT`` framework ``bin`` directory:
.. code-block:: sh .. parsed-literal::
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH" export PATH="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin":"$PATH"
The traditional framework installation by default does something similar, The traditional framework installation by default does something similar,
except for :file:`Python.framework`. Be aware that having both framework ``bin`` except for :file:`Python.framework`. Be aware that having both framework ``bin``
directories in ``PATH`` can lead to confusion if there are duplicate names 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 like |python_x_dot_y_literal| in both; which one is actually used depends on the order
they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt`` they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt``
commands can show which path is being used. Using virtual environments commands can show which path is being used. Using virtual environments
can help avoid such ambiguities. Another option might be to create can help avoid such ambiguities. Another option might be to create
a shell :command:`alias` to the desired interpreter, like: a shell :command:`alias` to the desired interpreter, like:
.. code-block:: sh .. parsed-literal::
alias py3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13" alias py\ |version|\ ="/Library/Frameworks/Python.framework/Versions/\ |version|\ /bin/python\ |version|\ "
alias py3.13t="/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t" alias py\ |version|\ t="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin/python\ |version|\ t"
Installing using the command line Installing using the command line
--------------------------------- ---------------------------------
@ -369,22 +370,22 @@ 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 options, too. If you are not familiar with :command:`installer`, it can be
somewhat cryptic (see :command:`man installer` for more information). somewhat cryptic (see :command:`man installer` for more information).
As an example, the following shell snippet shows one way to do it, 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 using the |x_dot_y_b2_literal| release and selecting the free-threaded interpreter
option: option:
.. code-block:: sh .. parsed-literal::
RELEASE="python-3.13.0b2-macos11.pkg" RELEASE="python-\ |version|\ 0b2-macos11.pkg"
# download installer pkg # download installer pkg
curl -O https://www.python.org/ftp/python/3.13.0/${RELEASE} curl -O \https://www.python.org/ftp/python/\ |version|\ .0/${RELEASE}
# create installer choicechanges to customize the install: # create installer choicechanges to customize the install:
# enable the PythonTFramework-3.13 package # enable the PythonTFramework-\ |version|\ package
# while accepting the other defaults (install all other packages) # while accepting the other defaults (install all other packages)
cat > ./choicechanges.plist <<EOF cat > ./choicechanges.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?> <?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"> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "\http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"> <plist version="1.0">
<array> <array>
<dict> <dict>
@ -393,7 +394,7 @@ option:
<key>choiceAttribute</key> <key>choiceAttribute</key>
<string>selected</string> <string>selected</string>
<key>choiceIdentifier</key> <key>choiceIdentifier</key>
<string>org.python.Python.PythonTFramework-3.13</string> <string>org.python.Python.PythonTFramework-\ |version|\ </string>
</dict> </dict>
</array> </array>
</plist> </plist>
@ -404,19 +405,19 @@ option:
You can then test that both installer builds are now available with something like: You can then test that both installer builds are now available with something like:
.. code-block:: console .. parsed-literal::
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled $ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
$ /usr/local/bin/python3.13t -VV $ /usr/local/bin/python\ |version|\ t -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)] Python \ |version|\ .0b2 experimental free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ # and the traditional interpreter $ # and the traditional interpreter
$ /usr/local/bin/python3.13 -VV $ /usr/local/bin/python\ |version|\ -VV
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)] Python \ |version|\ .0b2 (v\ |version|\ .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 $ # test that they are also available without the prefix if /usr/local/bin is on $PATH
$ python3.13t -VV $ python\ |version|\ t -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)] Python \ |version|\ .0b2 experimental free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.13 -VV $ python\ |version|\ -VV
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)] Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
.. note:: .. note::