@@ -167,7 +167,8 @@ It should be separated from the tag by a slash (either ``/`` or ``\``),
167167and may be shortened to any prefix of its full value.
168168Specifying the company is optional when it is ``PythonCore ``, and specifying the
169169tag 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
990991credentials embedded they will be used in preference to other credentials. Only
991992one 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
9951135Troubleshooting
0 commit comments