8000 Use replacements to update versions in "Using Python on macOS" (#130400) · python/cpython@21bac3a · GitHub
[go: up one dir, main page]
Skip to content

Commit 21bac3a

Browse files
hugovkhugovk
authored
Use replacements to update versions in "Using Python on macOS" (#130400)
1 parent d8994b0 commit 21bac3a

File tree

2 files changed

+51
-46
lines changed

2 files changed

+51
-46
lines changed

‎Doc/conf.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@
7979
rst_epilog = f"""
8080
.. |python_version_literal| replace:: ``Python {version}``
8181
.. |python_x_dot_y_literal| replace:: ``python{version}``
82+
.. |python_x_dot_y_t_literal| replace:: ``python{version}t``
83+
.. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config``
84+
.. |x_dot_y_b2_literal| replace:: ``{version}.0b2``
85+
.. |applications_python_version_literal| replace:: ``/Applications/Python {version}/``
8286
.. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``
8387
8488
.. Apparently this how you hack together a formatted link:

‎Doc/using/mac.rst

Lines changed: 47 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,6 @@ the Pythons provided by the CPython release team for download from
2020
the `python.org website <https://www.python.org/downloads/>`_. See
2121
:ref:`alternative_bundles` for some other options.
2222

23-
.. |usemac_x_dot_y| replace:: 3.13
24-
.. |usemac_python_x_dot_y_literal| replace:: ``python3.13``
25-
.. |usemac_python_x_dot_y_t_literal| replace:: ``python3.13t``
26-
.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python3.13t-config``
27-
.. |usemac_applications_folder_name| replace:: ``Python 3.13``
28-
.. |usemac_applications_folder_version| replace:: ``/Applications/Python 3.13/``
29-
3023
.. _getting-osx:
3124
.. _getting-and-installing-macpython:
3225

@@ -64,7 +57,7 @@ Clicking on the **Continue** button brings up the **Read Me** for this installer
6457
Besides other important information, the **Read Me** documents which Python version is
6558
going to be installed and on what versions of macOS it is supported. You may need
6659
to scroll through to read the whole file. By default, this **Read Me** will also be
67-
installed in |usemac_applications_folder_version| and available to read anytime.
60+
installed in |applications_python_version_literal| and available to read anytime.
6861

6962
.. image:: mac_installer_02_readme.png
7063

@@ -97,7 +90,7 @@ When the installation is complete, the **Summary** window will appear.
9790
.. image:: mac_installer_06_summary.png
9891

9992
Double-click on the :command:`Install Certificates.command`
100-
icon or file in the |usemac_applications_folder_version| window to complete the
93+
icon or file in the |applications_python_version_literal| window to complete the
10194
installation.
10295

10396
.. image:: mac_installer_07_applications.png
@@ -114,7 +107,7 @@ Close this terminal window and the installer window.
114107

115108
A default install will include:
116109

117-
* A |usemac_applications_folder_name| folder in your :file:`Applications` folder. In here
110+
* A |python_version_literal| folder in your :file:`Applications` folder. In here
118111
you find :program:`IDLE`, the development environment that is a standard part of official
119112
Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
120113
scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
@@ -141,7 +134,7 @@ How to run a Python script
141134

142135
There are two ways to invoke the Python interpreter.
143136
If you are familiar with using a Unix shell in a terminal
144-
window, you can invoke |usemac_python_x_dot_y_literal| or ``python3`` optionally
137+
window, you can invoke |python_x_dot_y_literal| or ``python3`` optionally
145138
followed by one or more command line options (described in :ref:`using-on-general`).
146139
The Python tutorial also has a useful section on
147140
:ref:`using Python interactively from a shell <tut-interac>`.
@@ -160,7 +153,7 @@ for more information.
160153
To run a Python script file from the terminal window, you can
161154
invoke the interpreter with the name of the script file:
162155

163-
|usemac_python_x_dot_y_literal| ``myscript.py``
156+
|python_x_dot_y_literal| ``myscript.py``
164157

165158
To run your script from the Finder, you can either:
166159

@@ -268,7 +261,7 @@ Installing Free-threaded Binaries
268261

269262
The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
270263
installer package can optionally install an additional build of
271-
Python |usemac_x_dot_y| that supports :pep:`703`, the experimental free-threading feature
264+
Python |version| that supports :pep:`703`, the experimental free-threading feature
272265
(running with the :term:`global interpreter lock` disabled).
273266
Check the release page on ``python.org`` for possible updated information.
274267

@@ -282,46 +275,54 @@ step of the installer as described above.
282275
If the box next to the **Free-threaded Python** package name is checked,
283276
a separate :file:`PythonT.framework` will also be installed
284277
alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`.
285-
This configuration allows a free-threaded Python |usemac_x_dot_y| build to co-exist
286-
on your system with a traditional (GIL only) Python |usemac_x_dot_y| build with
278+
This configuration allows a free-threaded Python |version| build to co-exist
279+
on your system with a traditional (GIL only) Python |version| build with
287280
minimal risk while installing or testing. This installation layout is itself
288281
experimental and is subject to change in future releases.
289282

290283
Known cautions and limitations:
291284

292285
- The **UNIX command-line tools** package, which is selected by default,
293-
will install links in :file:`/usr/local/bin` for |usemac_python_x_dot_y_t_literal|,
294-
the free-threaded interpreter, and |usemac_python_x_dot_y_t_literal_config|,
286+
will install links in :file:`/usr/local/bin` for |python_x_dot_y_t_literal|,
287+
the free-threaded interpreter, and |python_x_dot_y_t_literal_config|,
295288
a configuration utility which may be useful for package builders.
296289
Since :file:`/usr/local/bin` is typically included in your shell ``PATH``,
297290
in most cases no changes to your ``PATH`` environment variables should
298-
be needed to use |usemac_python_x_dot_y_t_literal|.
291+
be needed to use |python_x_dot_y_t_literal|.
299292

300293
- For this release, the **Shell profile updater** package and the
301-
:file:`Update Shell Profile.command` in |usemac_applications_folder_version|
294+
:file:`Update Shell Profile.command` in |applications_python_version_literal|
302295
do not support the free-threaded package.
303296

304297
- The free-threaded build and the traditional build have separate search
305298
paths and separate :file:`site-packages` directories so, by default,
306299
if you need a package available in both builds, it may need to be installed in both.
307300
The free-threaded package will install a separate instance of :program:`pip` for use
308-
with |usemac_python_x_dot_y_t_literal|.
301+
with |python_x_dot_y_t_literal|.
309302

310303
- To install a package using :command:`pip` without a :command:`venv`:
311304

312-
|usemac_python_x_dot_y_t_literal| ``-m pip install <package_name>``
305+
.. parsed-literal::
306+
307+
python\ |version|\ t -m pip install <package_name>
313308
314309
- When working with multiple Python environments, it is usually safest and easiest
315310
to :ref:`create and use virtual environments <tut-venv>`.
316311
This can avoid possible command name conflicts and confusion about which Python is in use:
317312

318-
|usemac_python_x_dot_y_t_literal| ``-m venv <venv_name>``
313+
.. parsed-literal::
314+
315+
python\ |version|\ t -m venv <venv_name>
316+
319317
320318
then :command:`activate`.
321319

322320
- To run a free-threaded version of IDLE:
323321

324-
|usemac_python_x_dot_y_t_literal| ``-m idlelib``
322+
.. parsed-literal::
323+
324+
python\ |version|\ t -m idlelib
325+
325326
326327
- The interpreters in both builds respond to the same
327328
:ref:`PYTHON environment variables <using-on-envvars>`
@@ -337,28 +338,28 @@ Known cautions and limitations:
337338
thus it only needs to be run once.
338339

339340
- If you cannot depend on the link in ``/usr/local/bin`` pointing to the
340-
``python.org`` free-threaded |usemac_python_x_dot_y_t_literal| (for example, if you want
341+
``python.org`` free-threaded |python_x_dot_y_t_literal| (for example, if you want
341342
to install your own version there or some other distribution does),
342343
you can explicitly set your shell ``PATH`` environment variable to
343344
include the ``PythonT`` framework ``bin`` directory:
344345

345-
.. code-block:: sh
346+
.. parsed-literal::
346347
347-
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
348+
export PATH="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin":"$PATH"
348349
349350
The traditional framework installation by default does something similar,
350351
except for :file:`Python.framework`. Be aware that having both framework ``bin``
351352
directories in ``PATH`` can lead to confusion if there are duplicate names
352-
like ``python3.13`` in both; which one is actually used depends on the order
353+
like |python_x_dot_y_literal| in both; which one is actually used depends on the order
353354
they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt``
354355
commands can show which path is being used. Using virtual environments
355356
can help avoid such ambiguities. Another option might be to create
356357
a shell :command:`alias` to the desired interpreter, like:
357358

358-
.. code-block:: sh
359+
.. parsed-literal::
359360
360-
alias py3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13"
361-
alias py3.13t="/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t"
361+
alias py\ |version|\ ="/Library/Frameworks/Python.framework/Versions/\ |version|\ /bin/python\ |version|\ "
362+
alias py\ |version|\ t="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin/python\ |version|\ t"
362363
363364
Installing using the command line
364365
---------------------------------
@@ -369,22 +370,22 @@ the macOS command line :command:`installer` utility lets you select non-default
369370
options, too. If you are not familiar with :command:`installer`, it can be
370371
somewhat cryptic (see :command:`man installer` for more information).
371372
As an example, the following shell snippet shows one way to do it,
372-
using the ``3.13.0b2`` release and selecting the free-threaded interpreter
373+
using the |x_dot_y_b2_literal| release and selecting the free-threaded interpreter
373374
option:
374375

375-
.. code-block:: sh
376+
.. parsed-literal::
376377
377-
RELEASE="python-3.13.0b2-macos11.pkg"
378+
RELEASE="python-\ |version|\ 0b2-macos11.pkg"
378379
379380
# download installer pkg
380-
curl -O https://www.python.org/ftp/python/3.13.0/${RELEASE}
381+
curl -O \https://www.python.org/ftp/python/\ |version|\ .0/${RELEASE}
381382
382383
# create installer choicechanges to customize the install:
383-
# enable the PythonTFramework-3.13 package
384+
# enable the PythonTFramework-\ |version|\ package
384385
# while accepting the other defaults (install all other packages)
385386
cat > ./choicechanges.plist <<EOF
386387
<?xml version="1.0" encoding="UTF-8"?>
387-
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
388+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "\http://www.apple.com/DTDs/PropertyList-1.0.dtd">
388389
<plist version="1.0">
389390
<array>
390391
<dict>
@@ -393,7 +394,7 @@ option:
393394
<key>choiceAttribute</key>
394395
<string>selected</string>
395396
<key>choiceIdentifier</key>
396-
<string>org.python.Python.PythonTFramework-3.13</string>
397+
<string>org.python.Python.PythonTFramework-\ |version|\ </string>
397398
</dict>
398399
</array>
399400
</plist>
@@ -404,19 +405,19 @@ option:
404405
405406
You can then test that both installer builds are now available with something like:
406407

407-
.. code-block:: console
408+
.. parsed-literal::
408409
409410
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
410-
$ /usr/local/bin/python3.13t -VV
411-
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)]
411+
$ /usr/local/bin/python\ |version|\ t -VV
412+
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)]
412413
$ # and the traditional interpreter
413-
$ /usr/local/bin/python3.13 -VV
414-
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
414+
$ /usr/local/bin/python\ |version|\ -VV
415+
Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
415416
$ # test that they are also available without the prefix if /usr/local/bin is on $PATH
416-
$ python3.13t -VV
417-
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)]
418-
$ python3.13 -VV
419-
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
417+
$ python\ |version|\ t -VV
418+
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)]
419+
$ python\ |version|\ -VV
420+
Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
420421
421422
.. note::
422423

0 commit comments

Comments
 (0)
0