Skip to content

Commit 0782e92

Browse files
[3.14] gh-160425: Use parsed literals to keep version current in Windows docs (GH-160430) (#160435)
(cherry picked from commit ae5c457) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
1 parent 9695071 commit 0782e92

2 files changed

Lines changed: 65 additions & 55 deletions

File tree

‎Doc/conf.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,13 @@
8585
.. |python_x_dot_y_literal| replace:: ``python{version}``
8686
.. |python_x_dot_y_t_literal| replace:: ``python{version}t``
8787
.. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config``
88+
.. |python_x_dot_y_exe_literal| replace:: ``python{version}.exe``
89+
.. |python_x_dot_y_t_exe_literal| replace:: ``python{version}t.exe``
90+
.. |python_xy_dll_literal| replace:: ``python{v.major}{v.minor}.dll``
91+
.. |py_v_x_dot_y_literal| replace:: ``py -V:{version}``
92+
.. |py_v_x_dot_y_t_literal| replace:: ``py -V:{version}t``
93+
.. |x_dot_y_literal| replace:: ``{version}``
94+
.. |x_dot_y_64_literal| replace:: ``{version}-64``
8895
.. |x_dot_y_b2_literal| replace:: ``{version}.0b2``
8996
.. |applications_python_version_literal| replace:: ``/Applications/Python {version}/``
9097
.. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``

‎Doc/using/windows.rst‎

Lines changed: 58 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@ other tools you are using is generally a worthwhile benefit. Before committing
2525
to the process described here, we recommend investigating your existing tools to
2626
see if they can provide Python directly.
2727

28-
To obtain Python from the CPython team, use the Python Install Manager. This
28+
To obtain Python from the CPython team, use the Python install manager. This
2929
is a standalone tool that makes Python available as global commands on your
3030
Windows machine, integrates with the system, and supports updates over time. You
31-
can download the Python Install Manager from `python.org/downloads`_ or through
31+
can download the Python install manager from `python.org/downloads`_ or through
3232
the `Microsoft Store app`_.
3333

34-
Once you have installed the Python Install Manager, the global ``python``
34+
Once you have installed the Python install manager, the global ``python``
3535
command can be used from any terminal to launch your current latest version of
3636
Python. This version may change over time as you add or remove different
3737
versions, and the ``py list`` command will show which is current.
@@ -42,7 +42,7 @@ This provides isolation between projects, consistency over time, and ensures
4242
that additional commands added by packages are also available in your session.
4343
Create a virtual environment using ``python -m venv <env path>``.
4444

45-
If the ``python`` or ``py`` commands do not seem to be working, please see the
45+
If the ``python`` or ``py`` commands do not seem to be working, see the
4646
:ref:`Troubleshooting <pymanager-troubleshoot>` section below. There are
4747
sometimes additional manual steps required to configure your PC.
4848

@@ -76,7 +76,7 @@ To install through the Store, simply click "Install". After it has completed,
7676
open a terminal and type ``python`` to get started.
7777

7878
To install the file downloaded from python.org, either double-click and select
79-
"Install", or run ``Add-AppxPackage <path to MSIX>`` in Windows Powershell.
79+
"Install", or run ``Add-AppxPackage <path to MSIX>`` in Windows PowerShell.
8080

8181
After installation, the ``python``, ``py``, and ``pymanager`` commands should be
8282
available. If you have existing installations of Python, or you have modified
@@ -87,7 +87,7 @@ non-working commands.
8787
When you first install a runtime, you will likely be prompted to add a directory
8888
to your :envvar:`PATH`. This is optional, if you prefer to use the ``py``
8989
command, but is offered for those who prefer the full range of aliases (such
90-
as ``python3.14.exe``) to be available. The directory will be
90+
as |python_x_dot_y_exe_literal|) to be available. The directory will be
9191
:file:`%LocalAppData%\\Python\\bin` by default, but may be customized by an
9292
administrator. Click Start and search for "Edit environment variables for your
9393
account" for the system settings page to add the path.
@@ -101,7 +101,7 @@ manager does not uninstall any Python runtimes.
101101

102102
If you are not able to install an MSIX in your context, for example, you are
103103
using automated deployment software that does not support it, or are targeting
104-
Windows Server 2019, please see :ref:`pymanager-advancedinstall` below for more
104+
Windows Server 2019, see :ref:`pymanager-advancedinstall` below for more
105105
information.
106106

107107

@@ -158,9 +158,9 @@ version, potentially with the platform. For compatibility, the ``V:`` may be
158158
omitted in cases where the tag refers to an official release and starts with
159159
``3``.
160160

161-
.. code::
161+
.. parsed-literal::
162162
163-
$> py -V:3.14 ...
163+
$> py -V:|version| ...
164164
$> py -V:3-arm64 ...
165165
166166
Runtimes from other distributors may require the *company* to be included as
@@ -232,7 +232,7 @@ added in the form of one or more tags (with or without company specifier), and
232232
each may include a ``<``, ``<=``, ``>=`` or ``>`` prefix to restrict to a range.
233233

234234
A range of formats are supported, and can be passed as the ``--format=<FMT>`` or
235-
``-f <FMT>`` option. Formats include ``table`` (a user friendly table view),
235+
``-f <FMT>`` option. Formats include ``table`` (a user-friendly table view),
236236
``csv`` (comma-separated table), ``json`` (a single JSON blob), ``jsonl`` (one
237237
JSON blob per result), ``exe`` (just the executable path), ``prefix`` (just the
238238
prefix path).
@@ -252,13 +252,13 @@ source. Passing either of these options will search the online index for
252252
runtimes that can be installed. The result shown by ``py list --online --one
253253
<TAG>`` will match the runtime that would be installed by ``py install <TAG>``.
254254

255-
.. code::
255+
.. parsed-literal::
256256
257-
$> py list --online 3.14
257+
$> py list --online |version|
258258
259259
For compatibility with the old launcher, the ``--list``, ``--list-paths``,
260-
``-0`` and ``-0p`` commands (e.g. ``py -0p``) are retained. They do not allow
261-
additional options, and will produce legacy formatted output.
260+
``-0`` and ``-0p`` commands (for example, ``py -0p``) are retained. They do not allow
261+
additional options, and will produce legacy-formatted output.
262262

263263

264264
Installing runtimes
@@ -289,9 +289,11 @@ To see the available runtime variants, run::
289289
py list --online
290290

291291
To install a specific variant, include it in the tag passed to
292-
``py install``::
292+
``py install``:
293+
294+
.. parsed-literal::
293295
294-
py install PythonTest\3.14
296+
py install PythonTest\\\ |version|
295297
296298
The ``--source=<URL>`` option allows overriding the online index that is used to
297299
obtain runtimes. This may be used with an offline index, as shown in
@@ -312,7 +314,7 @@ installs.
312314

313315
Passing ``--refresh`` will update all registrations for installed runtimes. This
314316
will recreate Start menu shortcuts, registry keys, and global aliases (such as
315-
``python3.14.exe`` or for any installed scripts). These are automatically
317+
|python_x_dot_y_exe_literal| or for any installed scripts). These are automatically
316318
refreshed on installation of any runtime, but may need to be manually refreshed
317319
after installing packages.
318320

@@ -451,10 +453,10 @@ customization.
451453
* - ``default_platform``
452454
- ``PYTHON_MANAGER_DEFAULT_PLATFORM``
453455
- The preferred default platform to launch or install.
454-
This is treated as a suffix to the specified tag, such that ``py -V:3.14``
455-
would prefer an install for ``3.14-64`` if it exists
456+
This is treated as a suffix to the specified tag, such that |py_v_x_dot_y_literal|
457+
would prefer an install for |x_dot_y_64_literal| if it exists
456458
(and ``default_platform`` is ``-64``),
457-
but will use ``3.14`` if no tagged install exists.
459+
but will use |x_dot_y_literal| if no tagged install exists.
458460

459461
* - ``logs_dir``
460462
- ``PYTHON_MANAGER_LOGS``
@@ -526,7 +528,7 @@ customization.
526528

527529
* - ``global_dir``
528530
- (none)
529-
- Specify the directory where global commands (such as ``python3.14.exe``
531+
- Specify the directory where global commands (such as |python_x_dot_y_exe_literal|
530532
and ``pip.exe``) are stored.
531533
This directory should be added to your :envvar:`PATH` to make the
532534
commands available from your terminal.
@@ -547,7 +549,7 @@ Shebang lines
547549
-------------
548550

549551
If the first line of a script file starts with ``#!``, it is known as a
550-
"shebang" line. Linux and other Unix like operating systems have native
552+
"shebang" line. Linux and other Unix-like operating systems have native
551553
support for such lines and they are commonly used on such systems to indicate
552554
how a script should be executed. The ``python`` and ``py`` commands allow the
553555
same facilities to be used with Python scripts on Windows.
@@ -591,7 +593,7 @@ prefers launching known Python commands. A warning may be displayed when
591593
searching for arbitrary executables, and this search may be disabled by the
592594
``shebang_can_run_anything`` configuration option.
593595

594-
Shebang lines that do not match any of patterns are treated as *Windows*
596+
Shebang lines that do not match any of the patterns are treated as *Windows*
595597
executable paths that are absolute or relative to the directory containing the
596598
script file. This is a convenience for Windows-only scripts, such as those
597599
generated by an installer, since the behavior is not compatible with Unix-style
@@ -724,7 +726,7 @@ deployment tool.
724726

725727
Regardless of the install method, users will still need to install their own
726728
copies of Python itself, as there is no way to trigger those installs without
727-
being a logged in user. When using the MSIX, the latest version of Python will
729+
being a logged-in user. When using the MSIX, the latest version of Python will
728730
be available for all users to install without network access.
729731

730732
Note that the MSIX downloadable from the Store and from the Python website are
@@ -800,12 +802,13 @@ directory containing the configuration file that specified them.
800802
- Path or URL to an index to consult when the main index cannot be accessed.
801803

802804
* - ``install.enable_shortcut_kinds``
803-
- Comma-separated list of shortcut kinds to allow (e.g. ``"pep514,start"``).
805+
- Comma-separated list of shortcut kinds to allow
806+
(for example, ``"pep514,start"``).
804807
Enabled shortcuts may still be disabled by ``disable_shortcut_kinds``.
805808

806809
* - ``install.disable_shortcut_kinds``
807810
- Comma-separated list of shortcut kinds to exclude
808-
(e.g. ``"pep514,start"``).
811+
(for example, ``"pep514,start"``).
809812
Disabled shortcuts are not reactivated by ``enable_shortcut_kinds``.
810813

811814
* - ``install.hard_link_entrypoints``
@@ -852,16 +855,16 @@ Installing free-threaded binaries
852855
Pre-built distributions of the free-threaded build are available
853856
by installing tags with the ``t`` suffix.
854857

855-
.. code::
858+
.. parsed-literal::
856859
857-
$> py install 3.14t
858-
$> py install 3.14t-arm64
859-
$> py install 3.14t-32
860+
$> py install |version|\ t
861+
$> py install |version|\ t-arm64
862+
$> py install |version|\ t-32
860863
861864
This will install and register as normal. If you have no other runtimes
862865
installed, then ``python`` will launch this one. Otherwise, you will need to use
863-
``py -V:3.14t ...`` or, if you have added the global aliases directory to your
864-
:envvar:`PATH` environment variable, the ``python3.14t.exe`` commands.
866+
|py_v_x_dot_y_t_literal| or, if you have added the global aliases directory to your
867+
:envvar:`PATH` environment variable, the |python_x_dot_y_t_exe_literal| commands.
865868

866869

867870
.. _pymanager-index-signatures:
@@ -889,7 +892,7 @@ As well as requiring a valid signature, the ``required_root_subject`` and
889892
signatures based on the certificate Subject fields. Any attribute specified in
890893
the configuration must match the attribute in the certificate (additional
891894
attributes in the certificate are ignored). Typical attributes are ``CN=`` for
892-
the common name, ``O=`` for the organizational unit, and ``C=`` for the
895+
the common name, ``O=`` for the organization, and ``C=`` for the
893896
publisher's country.
894897

895898
Finally, the ``required_publisher_eku`` setting allows requiring that a specific
@@ -994,8 +997,8 @@ one set of credentials will be used for both types of proxy.
994997
Troubleshooting
995998
---------------
996999

997-
If your Python install manager does not seem to be working correctly, please
998-
work through these tests and fixes to see if it helps. If not, please report an
1000+
If your Python install manager does not seem to be working correctly,
1001+
work through these tests and fixes to see if it helps. If not, report an
9991002
issue at `our bug tracker <https://github.com/python/pymanager/issues>`_,
10001003
including any relevant log files (written to your :file:`%TEMP%` directory by
10011004
default).
@@ -1146,16 +1149,16 @@ directly accessed by end-users.
11461149
To install an embedded distribution, we recommend using ``py install`` with the
11471150
``--target`` option:
11481151

1149-
.. code::
1152+
.. parsed-literal::
11501153
1151-
$> py install 3.14-embed --target=<directory>
1154+
$> py install |version|-embed --target=<directory>
11521155
11531156
When extracted, the embedded distribution is (almost) fully isolated from the
11541157
user's system, including environment variables, system registry settings, and
11551158
installed packages. The standard library is included as pre-compiled and
1156-
optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python313.dll``,
1157-
``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
1158-
dependents, such as Idle), pip and the Python documentation are not included.
1159+
optimized ``.pyc`` files in a ZIP, and ``python3.dll``, |python_xy_dll_literal|,
1160+
``python.exe`` and ``pythonw.exe`` are all provided. Tcl/Tk (including all
1161+
dependents, such as IDLE), pip and the Python documentation are not included.
11591162

11601163
A default ``._pth`` file is included, which further restricts the default search
11611164
paths (as described below in :ref:`windows_finding_modules`). This file is
@@ -1210,7 +1213,7 @@ installation is sufficient to provide a loadable Python interpreter.
12101213

12111214
As with the application use, packages can be installed to any location as there
12121215
is an opportunity to specify search paths before initializing the interpreter.
1213-
Otherwise, there is no fundamental differences between using the embedded
1216+
Otherwise, there are no fundamental differences between using the embedded
12141217
distribution and a regular installation.
12151218

12161219

@@ -1261,7 +1264,7 @@ delete the package directory manually and install it again. Many CI systems
12611264
will do this automatically if they do not preserve files between builds.
12621265

12631266
Alongside the ``tools`` directory is a ``build\native`` directory. This
1264-
contains a MSBuild properties file ``python.props`` that can be used in a
1267+
contains an MSBuild properties file ``python.props`` that can be used in a
12651268
C++ project to reference the Python install. Including the settings will
12661269
automatically use the headers and import libraries in your build.
12671270

@@ -1270,7 +1273,7 @@ The package information pages on nuget.org are
12701273
for the 64-bit version, `www.nuget.org/packages/pythonx86
12711274
<https://www.nuget.org/packages/pythonx86>`_ for the 32-bit version, and
12721275
`www.nuget.org/packages/pythonarm64
1273-
<https://www.nuget.org/packages/pythonarm64>`_ for the ARM64 version
1276+
<https://www.nuget.org/packages/pythonarm64>`_ for the ARM64 version.
12741277

12751278
Free-threaded packages
12761279
----------------------
@@ -1283,8 +1286,8 @@ for the 64-bit version, `pythonx86-freethreaded
12831286
<https://www.nuget.org/packages/pythonx86-freethreaded>`_ for the 32-bit
12841287
version, and `pythonarm64-freethreaded
12851288
<https://www.nuget.org/packages/pythonarm64-freethreaded>`_ for the ARM64
1286-
version. These packages contain both the ``python3.13t.exe`` and
1287-
``python.exe`` entry points, both of which run free threaded.
1289+
version. These packages contain both the |python_x_dot_y_t_exe_literal| and
1290+
``python.exe`` entry points, both of which run free-threaded.
12881291

12891292

12901293
Alternative bundles
@@ -1321,8 +1324,8 @@ Supported Windows versions
13211324
As specified in :pep:`11`, a Python release only supports a Windows platform
13221325
while Microsoft considers the platform under extended support. This means that
13231326
Python |version| supports Windows 10 and newer. If you require Windows 7
1324-
support, please install Python 3.8. If you require Windows 8.1 support,
1325-
please install Python 3.12.
1327+
support, install Python 3.8. If you require Windows 8.1 support,
1328+
install Python 3.12.
13261329

13271330

13281331
.. _max-path:
@@ -1400,7 +1403,7 @@ Windows:
14001403
* If the environment variable :envvar:`PYTHONPATH` exists, as described in
14011404
:ref:`using-on-envvars`, its entries are added next. Note that on Windows,
14021405
paths in this variable must be separated by semicolons, to distinguish them
1403-
from the colon used in drive identifiers (``C:\`` etc.).
1406+
from the colon used in drive identifiers (such as ``C:\``).
14041407

14051408
* Additional "application paths" can be added in the registry as subkeys of
14061409
:samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
@@ -1413,13 +1416,13 @@ Windows:
14131416
"Python Home". Otherwise, the path of the main Python executable is used to
14141417
locate a "landmark file" (either ``Lib\os.py`` or ``pythonXY.zip``) to deduce
14151418
the "Python Home". If a Python home is found, the relevant sub-directories
1416-
added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that
1419+
added to :data:`sys.path` (such as ``Lib`` and ``plat-win``) are based on that
14171420
folder. Otherwise, the core Python path is constructed from the PythonPath
14181421
stored in the registry.
14191422

14201423
* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
14211424
the environment, and no registry entries can be found, a default path with
1422-
relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
1425+
relative entries is used (for example, ``.\Lib;.\plat-win``).
14231426

14241427
If a ``pyvenv.cfg`` file is found alongside the main executable or in the
14251428
directory one level above the executable, the following variations apply:
@@ -1435,11 +1438,11 @@ The end result of all this is:
14351438
directory), the core path is deduced, and the core paths in the registry are
14361439
ignored. Other "application paths" in the registry are always read.
14371440

1438-
* When Python is hosted in another .exe (different directory, embedded via COM,
1439-
etc), the "Python Home" will not be deduced, so the core path from the
1441+
* When Python is hosted in another .exe (for example, in a different directory or
1442+
embedded via COM), the "Python Home" will not be deduced, so the core path from the
14401443
registry is used. Other "application paths" in the registry are always read.
14411444

1442-
* If Python can't find its home and there are no registry value (frozen .exe,
1445+
* If Python can't find its home and there are no registry values (frozen .exe,
14431446
some very strange installation setup) you get a path with some default, but
14441447
relative, paths.
14451448

@@ -1451,7 +1454,7 @@ following advice will prevent conflicts with other installations:
14511454
environment variables, and also ignore :mod:`site` unless ``import site`` is
14521455
listed.
14531456

1454-
* If you are loading :file:`python3.dll` or :file:`python37.dll` in your own
1457+
* If you are loading :file:`python3.dll` or |python_xy_dll_literal| in your own
14551458
executable, explicitly set :c:member:`PyConfig.module_search_paths` before
14561459
:c:func:`Py_InitializeFromConfig`.
14571460

@@ -1472,7 +1475,7 @@ non-standard paths in the registry and user site-packages.
14721475

14731476
.. versionchanged:: 3.6
14741477

1475-
Add ``._pth`` file support and removes ``applocal`` option from
1478+
Add ``._pth`` file support and remove ``applocal`` option from
14761479
``pyvenv.cfg``.
14771480

14781481
.. versionchanged:: 3.6

0 commit comments

Comments
 (0)