Skip to content

Commit 47ab4ec

Browse files
[3.15] Improve PyManager documentation around tag matching (GH-161940)
Improve PyManager documentation around tag matching (GH-161940) (cherry picked from commit 9427640) Co-authored-by: Steve Dower <steve.dower@python.org>
1 parent 094f7fe commit 47ab4ec

1 file changed

Lines changed: 141 additions & 1 deletion

File tree

‎Doc/using/windows.rst‎

Lines changed: 141 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,8 @@ It should be separated from the tag by a slash (either ``/`` or ``\``),
167167
and may be shortened to any prefix of its full value.
168168
Specifying the company is optional when it is ``PythonCore``, and specifying the
169169
tag is optional (but not the slash) when you want the latest release from a
170-
specific company.
170+
specific company. For more details about how tags are matched, see
171+
:ref:`pymanager-tag-matching`.
171172

172173
.. code::
173174
@@ -990,6 +991,145 @@ Credentials may be embedded in either setting, however, when ``HTTPS_PROXY`` has
990991
credentials embedded they will be used in preference to other credentials. Only
991992
one set of credentials will be used for both types of proxy.
992993

994+
.. _pymanager-tag-matching:
995+
996+
Tags and tag matching
997+
---------------------
998+
999+
.. versionchanged:: 26.5
1000+
Previously the behavior was very similar to what is described here, but had
1001+
many more inconsistencies. We have streamlined it and ensured the behavior is
1002+
well-defined, which may result in some small differences from previous
1003+
versions.
1004+
1005+
Tags identify Python runtimes that may be installed, modified, or launched by
1006+
the Python install manager. They are based on :pep:`514`, with matching and
1007+
ordering rules specific to the install manager. These rules do not change
1008+
PEP 514's specification.
1009+
1010+
A tag has three components: Company, Tag, and Platform. Each part is
1011+
case-insensitive, but the exact comparison semantics vary.
1012+
1013+
.. code-block:: text
1014+
1015+
[<Company>/]<Tag>[-<Platform>]
1016+
1017+
The Company is optional and defaults to ``PythonCore``. It may contain slashes,
1018+
while the rest may not, and so the last forward slash or backslash separates it
1019+
from the Tag. When omitting Company, also omit any slash. In general, Company is
1020+
matched as a prefix.
1021+
1022+
The optional Platform suffix is one of the known platform suffixes, currently
1023+
``-32``, ``-64``, or ``-arm64``. Broadly speaking, the Platform suffix behaves
1024+
as part of the Tag, but it may be implied from the current configuration or
1025+
system in a way that is different from the rest of the tag. It also does not
1026+
parse or compare as a number.
1027+
1028+
Runtimes are defined as having a primary tag, and offer several more tags for
1029+
installation (``install-for``) and launching (``run-for``). Whether the install
1030+
tags or the launch tags are considered depends on context, but both sets are
1031+
used to filter to matching runtimes, from which the best option is selected
1032+
using more complex logic. If a runtime doesn't have specific tags, its primary
1033+
tag may be used for installation and uninstallation (but not launch - it will be
1034+
unlaunchable without any ``run-for`` tags).
1035+
1036+
You can observe this behaviour using ``py list`` with and without the ``--one``
1037+
option (to show the "best" or all candidates) and with and without the
1038+
``--online``/``--source`` options (to show install matches or launch matches).
1039+
1040+
Tags are not version numbers, though numeric sequences are treated as version
1041+
numbers. Hyphens divide the Tag into segments, where each segment is either text
1042+
or a version number with a text suffix. The version number part includes those
1043+
ending in ``a``, ``b``, or ``rc`` followed by a serial number, but any other
1044+
text is considered a separate suffix. Without a serial number, an ``a``, ``b``
1045+
or ``rc`` suffix is also treated as text.
1046+
1047+
Broadly, numbers are compared as numerical versions, so ``3.10`` is greater than
1048+
``3.1``, ``3.14`` is greater than ``3.14a1``, and ``3`` is equal to both ``3.0``
1049+
and ``3.0.0``. Text is compared case-insensitively, and must match, so ``2024b``
1050+
is not equivalent to ``2024.0`` because ``'b' != ''``.
1051+
1052+
.. note::
1053+
1054+
Do not interpret the depth of detail of the following few paragraphs about
1055+
constraints as representing their importance. Constraints are a necessary
1056+
evil, and we would prefer nobody rely on them instead of specific tags, which
1057+
are much simpler to reason about for publishers and end users. Unfortunately,
1058+
we are obliged to explain how our implementation handles constraints, and
1059+
this is the place for that explanation.
1060+
1061+
Constraints can select multiple tags. A matching tag will start with the same
1062+
segments as the constraining tag, where text segments are equal and numeric
1063+
segments are above, below, or equal, according to the constraint. The first
1064+
non-equal segment determines the result: non-equal text results in failure,
1065+
while a non-equal version either succeeds or fails based on the constraint.
1066+
Remaining segments in the matching tag are ignored.
1067+
1068+
When applying a constraint check to a version segment that was shorter than the
1069+
constraint (e.g. ``3`` has one field and so is shorter than ``==3.14``), it is
1070+
interpreted as representing any possible version. This will result in many
1071+
failed constraint checks that will usually be overridden by a more specific one.
1072+
For example ``3`` could represent ``3.99`` and so it is not equal to ``3.14``,
1073+
but if the install is offering tags ``['3', '3.14']`` then the later tag will
1074+
result in the constraint matching.
1075+
1076+
Here are some example cases showing the different applications of constraints:
1077+
1078+
* ``>=3.13`` matches ``3.13.4`` and ``3.14``
1079+
* ``>3.13`` matches ``3.14``, but not ``3.13.4``
1080+
* ``>=3.13t`` matches ``3.14t``, while ``>=3.13`` does not
1081+
* ``>=3.13`` matches ``3.14-abc`` but not ``3.14abc``
1082+
* ``>3.13-abc-123`` matches ``3.14`` (number is higher) and ``3.13-abc-124``
1083+
(number ``124`` is higher) but not ``3.13-def-123`` (text mismatch),
1084+
``3.14def`` (text ``def`` is not in the constraint),
1085+
``3.13-abc-123`` (number is not higher) or
1086+
``3.13-abc`` (not enough segments)
1087+
* ``>=3.0`` matches ``3``, but ``>3.0`` does not
1088+
* ``<4`` matches ``3``, but ``<3.12`` and ``<=3.12`` do not
1089+
* ``==3.0`` does not match ``3``, while ``==3.10`` still matches ``3.10.1``
1090+
* ``!=3.13`` rejects ``3`` (because it could be ``3.13``), but ``!=3.13t``
1091+
accepts ``3`` (different suffix)
1092+
1093+
The difference between hyphen-separated segments and adjacent text and numbers
1094+
is subtle, but should not be relevant to most users. Publishers will choose and
1095+
advertise the tags for their packages, and so should take care to choose between
1096+
adjacent text or separated text. For example, the core python\.org releases use
1097+
``3.14t`` for free-threaded builds, which should not be confused with original
1098+
builds and so ``3.14t`` should not match ``3.14``. However, ``3.14`` should be
1099+
allowed to match with ``3.14-64`` (recalling that known platform tags are
1100+
treated at text), and so the hyphenated convention is chosen instead. End users
1101+
get intuitive behavior because the publisher considered the impact of their
1102+
choices.
1103+
1104+
Note that constraints are not complementary, that is, the ``>=`` constraint does
1105+
not necessarily include every tag rejected by the ``<`` constraint.
1106+
For example, ``3.14t`` satisfies neither ``>=3.14`` nor ``<3.14``.
1107+
1108+
Publishers should provide tags for each way they want users to select a
1109+
runtime, commonly from most specific to least specific. For example, a
1110+
free-threaded runtime might offer ``3.14.4t``, ``3.14t``, and ``3t``. Include
1111+
a generic tag such as ``3.14`` only if that runtime should be eligible for
1112+
generic requests. Exact matches of user requested tags are preferred over
1113+
partial matches, so include the tags you expect your users to use.
1114+
1115+
The primary tag should be orderable against other runtimes from the same
1116+
publisher, but should not change with in-place updates. Also be aware that
1117+
operations reading an online feed assume that the feed is already ordered, and
1118+
will select the first runtime that matches requested tags.
1119+
1120+
After filtering, runtimes are ordered by their primary tag and then the best is
1121+
selected. "Best" is very context sensitive, and may be influenced by user
1122+
configuration (such as the default tag), active virtual environments, prerelease
1123+
marks on a runtime's sortable version, and whether a windowless interpreter is
1124+
desired (such as launching through ``pyw.exe`` instead of ``py.exe``).
1125+
1126+
Most notably, a request containing the text field ``dev``, such as ``3-dev``,
1127+
causes prereleases to be considered on equal footing with stable releases.
1128+
Typically stable releases are preferred unless filtering excludes all viable
1129+
options. However, this behavior only takes place after filtering, and so a
1130+
runtime that does not offer a tag containing ``dev`` will not be selected as a
1131+
candidate.
1132+
9931133
.. _pymanager-troubleshoot:
9941134

9951135
Troubleshooting

0 commit comments

Comments
 (0)