From d9d30193ee9e14cddff2d136b215b30727fee28e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 21 Feb 2025 14:36:28 +0200 Subject: [PATCH 1/6] Move usemac replacements from mac.rst to conf.py --- Doc/conf.py | 7 +++++++ Doc/using/mac.rst | 7 ------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 56594f32c6d02d..ce37dabc2bd86e 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -87,6 +87,13 @@ .. _FORCE_COLOR: https://force-color.org/ .. |NO_COLOR| replace:: ``NO_COLOR`` .. _NO_COLOR: https://no-color.org/ + +.. |usemac_x_dot_y| replace:: {version} +.. |usemac_python_x_dot_y_literal| replace:: ``python{version}`` +.. |usemac_python_x_dot_y_t_literal| replace:: ``python{version}t`` +.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python{version}t-config`` +.. |usemac_applications_folder_name| replace:: ``Python {version}`` +.. |usemac_applications_folder_version| replace:: ``/Applications/Python {version}/`` """ # There are two options for replacing |today|. Either, you set today to some diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 4b6c884f3d4f25..ee5a4aa2347348 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -20,13 +20,6 @@ the Pythons provided by the CPython release team for download from the `python.org website `_. 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: From 929dc1c856b5b4af35f9f09ae50bee4651dc729a Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 21 Feb 2025 14:54:50 +0200 Subject: [PATCH 2/6] Replace usemac replacements with existing ones --- Doc/conf.py | 3 --- Doc/using/mac.rst | 12 ++++++------ 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index ce37dabc2bd86e..c224ce75e44cd7 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -88,11 +88,8 @@ .. |NO_COLOR| replace:: ``NO_COLOR`` .. _NO_COLOR: https://no-color.org/ -.. |usemac_x_dot_y| replace:: {version} -.. |usemac_python_x_dot_y_literal| replace:: ``python{version}`` .. |usemac_python_x_dot_y_t_literal| replace:: ``python{version}t`` .. |usemac_python_x_dot_y_t_literal_config| replace:: ``python{version}t-config`` -.. |usemac_applications_folder_name| replace:: ``Python {version}`` .. |usemac_applications_folder_version| replace:: ``/Applications/Python {version}/`` """ diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index ee5a4aa2347348..e031b5a8a328be 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -107,7 +107,7 @@ 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 +* 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 Python distributions; and :program:`Python Launcher`, which handles double-clicking Python scripts from the macOS `Finder `_. @@ -134,7 +134,7 @@ How to run a Python script 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 +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`). The Python tutorial also has a useful section on :ref:`using Python interactively from a shell `. @@ -153,7 +153,7 @@ for more information. 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`` + |python_x_dot_y_literal| ``myscript.py`` To run your script from the Finder, you can either: @@ -261,7 +261,7 @@ Installing Free-threaded Binaries The ``python.org`` :ref:`Python for macOS ` 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). Check the release page on ``python.org`` for possible updated information. @@ -275,8 +275,8 @@ step of the installer as described above. 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 +This configuration allows a free-threaded Python |version| build to co-exist +on your system with a traditional (GIL only) Python |version| build with minimal risk while installing or testing. This installation layout is itself experimental and is subject to change in future releases. From efc3f133bd3db67df8bb076ebebe2a0e9d4e26fd Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 21 Feb 2025 15:01:38 +0200 Subject: [PATCH 3/6] Generalise the other usemac replacements --- Doc/conf.py | 7 +++---- Doc/using/mac.rst | 22 +++++++++++----------- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index c224ce75e44cd7..55edef9b97e3f0 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -79,6 +79,9 @@ rst_epilog = f""" .. |python_version_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`` +.. |applications_python_version_literal| replace:: ``/Applications/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: @@ -87,10 +90,6 @@ .. _FORCE_COLOR: https://force-color.org/ .. |NO_COLOR| replace:: ``NO_COLOR`` .. _NO_COLOR: https://no-color.org/ - -.. |usemac_python_x_dot_y_t_literal| replace:: ``python{version}t`` -.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python{version}t-config`` -.. |usemac_applications_folder_version| replace:: ``/Applications/Python {version}/`` """ # There are two options for replacing |today|. Either, you set today to some diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index e031b5a8a328be..642b6a828b3bd6 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -57,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 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. +installed in |applications_python_version_literal| and available to read anytime. .. image:: mac_installer_02_readme.png @@ -90,7 +90,7 @@ 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 +icon or file in the |applications_python_version_literal| window to complete the installation. .. image:: mac_installer_07_applications.png @@ -283,38 +283,38 @@ 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|, + will install links in :file:`/usr/local/bin` for |python_x_dot_y_t_literal|, + the free-threaded interpreter, and |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|. + be needed to use |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| + :file:`Update Shell Profile.command` in |applications_python_version_literal| 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|. + with |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 `` + |python_x_dot_y_t_literal| ``-m pip install `` - When working with multiple Python environments, it is usually safest and easiest to :ref:`create and use virtual environments `. This can avoid possible command name conflicts and confusion about which Python is in use: - |usemac_python_x_dot_y_t_literal| ``-m venv `` + |python_x_dot_y_t_literal| ``-m venv `` then :command:`activate`. - To run a free-threaded version of IDLE: - |usemac_python_x_dot_y_t_literal| ``-m idlelib`` + |python_x_dot_y_t_literal| ``-m idlelib`` - The interpreters in both builds respond to the same :ref:`PYTHON environment variables ` @@ -330,7 +330,7 @@ Known cautions and limitations: 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 + ``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), you can explicitly set your shell ``PATH`` environment variable to include the ``PythonT`` framework ``bin`` directory: From f5ac18e6a4deee479a26d8cc68633ac467d31ade Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sat, 22 Feb 2025 17:19:07 +0200 Subject: [PATCH 4/6] Replace more hardcoded version numbers --- Doc/conf.py | 3 +++ Doc/using/mac.rst | 11 ++++------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 55edef9b97e3f0..909e11faa32b7f 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -83,6 +83,9 @@ .. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config`` .. |applications_python_version_literal| replace:: ``/Applications/Python {version}/`` .. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}`` +.. |usemac_export_path| replace:: ``export PATH="/Library/Frameworks/PythonT.framework/Versions/{version}/bin":"$PATH"`` +.. |usemac_alias_py_x_dot_y| replace:: ``alias py{version}="/Library/Frameworks/Python.framework/Versions/{version}/bin/python{version}"`` +.. |usemac_alias_py_x_dot_y_t| replace:: ``alias py{version}t="/Library/Frameworks/PythonT.framework/Versions/{version}/bin/python{version}t"`` .. Apparently this how you hack together a formatted link: (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text) diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 642b6a828b3bd6..56df45bf123d0f 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -335,23 +335,20 @@ Known cautions and limitations: 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" + |usemac_export_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 + 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`` 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 + |usemac_alias_py_x_dot_y| - 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" + |usemac_alias_py_x_dot_y_t| Installing using the command line --------------------------------- From d33b1ab2764eb8e750d9a49f565176a40d9c3dcd Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 24 Feb 2025 14:19:32 +0200 Subject: [PATCH 5/6] Replace replacements with parsed literal blocks --- Doc/conf.py | 3 --- Doc/using/mac.rst | 23 +++++++++++++++++------ 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 909e11faa32b7f..55edef9b97e3f0 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -83,9 +83,6 @@ .. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config`` .. |applications_python_version_literal| replace:: ``/Applications/Python {version}/`` .. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}`` -.. |usemac_export_path| replace:: ``export PATH="/Library/Frameworks/PythonT.framework/Versions/{version}/bin":"$PATH"`` -.. |usemac_alias_py_x_dot_y| replace:: ``alias py{version}="/Library/Frameworks/Python.framework/Versions/{version}/bin/python{version}"`` -.. |usemac_alias_py_x_dot_y_t| replace:: ``alias py{version}t="/Library/Frameworks/PythonT.framework/Versions/{version}/bin/python{version}t"`` .. Apparently this how you hack together a formatted link: (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text) diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 56df45bf123d0f..869b691274beb2 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -302,19 +302,27 @@ Known cautions and limitations: - To install a package using :command:`pip` without a :command:`venv`: - |python_x_dot_y_t_literal| ``-m pip install `` + .. parsed-literal:: + + python\ |version|\ t -m pip install - When working with multiple Python environments, it is usually safest and easiest to :ref:`create and use virtual environments `. This can avoid possible command name conflicts and confusion about which Python is in use: - |python_x_dot_y_t_literal| ``-m venv `` + .. parsed-literal:: + + python\ |version|\ t -m venv + then :command:`activate`. - To run a free-threaded version of IDLE: - |python_x_dot_y_t_literal| ``-m idlelib`` + .. parsed-literal:: + + python\ |version|\ t -m idlelib + - The interpreters in both builds respond to the same :ref:`PYTHON environment variables ` @@ -335,7 +343,9 @@ Known cautions and limitations: you can explicitly set your shell ``PATH`` environment variable to include the ``PythonT`` framework ``bin`` directory: - |usemac_export_path| + .. parsed-literal:: + + export PATH="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin":"$PATH" The traditional framework installation by default does something similar, except for :file:`Python.framework`. Be aware that having both framework ``bin`` @@ -346,9 +356,10 @@ Known cautions and limitations: can help avoid such ambiguities. Another option might be to create a shell :command:`alias` to the desired interpreter, like: - |usemac_alias_py_x_dot_y| + .. parsed-literal:: - |usemac_alias_py_x_dot_y_t| + alias py\ |version|\ ="/Library/Frameworks/Python.framework/Versions/\ |version|\ /bin/python\ |version|\ " + alias py\ |version|\ t="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin/python\ |version|\ t" Installing using the command line --------------------------------- From 0016c134b7b001ca6ef10ec73145d278d4e81747 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 24 Feb 2025 14:34:32 +0200 Subject: [PATCH 6/6] Use parsed literal blocks for 'Installing using the command line' --- Doc/conf.py | 1 + Doc/using/mac.rst | 32 ++++++++++++++++---------------- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 55edef9b97e3f0..5e4d34060972a3 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -81,6 +81,7 @@ .. |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}`` diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 869b691274beb2..d44f55b5cc9581 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -370,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 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 +using the |x_dot_y_b2_literal| release and selecting the free-threaded interpreter option: -.. code-block:: sh +.. parsed-literal:: - RELEASE="python-3.13.0b2-macos11.pkg" + RELEASE="python-\ |version|\ 0b2-macos11.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: - # enable the PythonTFramework-3.13 package + # enable the PythonTFramework-\ |version|\ package # while accepting the other defaults (install all other packages) cat > ./choicechanges.plist < - + @@ -394,7 +394,7 @@ option: choiceAttribute selected choiceIdentifier - org.python.Python.PythonTFramework-3.13 + org.python.Python.PythonTFramework-\ |version|\ @@ -405,19 +405,19 @@ option: 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 - $ /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)] + $ /usr/local/bin/python\ |version|\ t -VV + 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 - $ /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)] + $ /usr/local/bin/python\ |version|\ -VV + 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 - $ 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)] + $ python\ |version|\ t -VV + 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)] + $ python\ |version|\ -VV + Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)] .. note::