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