Skip to content

Commit 9427640

Browse files
authored
Improve PyManager documentation around tag matching (GH-161940)
1 parent 3ad9316 commit 9427640

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
@@ -169,7 +169,8 @@ It should be separated from the tag by a slash (either ``/`` or ``\``),
169169
and may be shortened to any prefix of its full value.
170170
Specifying the company is optional when it is ``PythonCore``, and specifying the
171171
tag is optional (but not the slash) when you want the latest release from a
172-
specific company.
172+
specific company. For more details about how tags are matched, see
173+
:ref:`pymanager-tag-matching`.
173174

174175
.. code::
175176
@@ -998,6 +999,145 @@ Credentials may be embedded in either setting, however, when ``HTTPS_PROXY`` has
998999
credentials embedded they will be used in preference to other credentials. Only
9991000
one set of credentials will be used for both types of proxy.
10001001

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

10031143
Troubleshooting

0 commit comments

Comments
 (0)