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