Skip to content

Commit 6c1f809

Browse files
authored
Merge branch 'main' into tempdir-cleanup-bytes
2 parents 97e7c85 + 117ff5a commit 6c1f809

41 files changed

Lines changed: 3171 additions & 1191 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/c-api/dict.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,8 @@ Dictionary objects
526526
as an argument, prefer :c:func:`PyFrozenDict_New` to leave the source
527527
intact.
528528
529+
Does not work for dicts with embedded values.
530+
529531
.. impl-detail::
530532
531533
Works with O(1) complexity.

‎Doc/data/refcounts.dat‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2417,6 +2417,9 @@ PyType_GenericNew:PyObject*:type:0:
24172417
PyType_GenericNew:PyObject*:args:0:
24182418
PyType_GenericNew:PyObject*:kwds:0:
24192419

2420+
PyType_GetDict:PyObject*::+1:
2421+
PyType_GetDict:PyTypeObject*:type:0:
2422+
24202423
PyType_GetFlags:unsigned long:::
24212424
PyType_GetFlags:PyTypeObject*:type:0:
24222425

‎Doc/library/os.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6466,9 +6466,12 @@ Random numbers
64666466
random bytes in non-blocking mode (using the :data:`GRND_NONBLOCK` flag) or
64676467
to poll until the system urandom entropy pool is initialized.
64686468

6469-
On a Unix-like system, random bytes are read from the ``/dev/urandom``
6470-
device. If the ``/dev/urandom`` device is not available or not readable, the
6471-
:exc:`NotImplementedError` exception is raised.
6469+
On other Unix-like systems, the C ``getrandom()`` function is used if it is
6470+
available, otherwise the C ``getentropy()`` function.
6471+
6472+
If none of these functions can be used, random bytes are read from the
6473+
``/dev/urandom`` device. If the ``/dev/urandom`` device is not available or
6474+
not readable, the :exc:`NotImplementedError` exception is raised.
64726475

64736476
On Windows, it will use ``BCryptGenRandom()``.
64746477

‎Doc/library/ssl.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1965,7 +1965,7 @@ to speed up repeated connections from the same clients.
19651965
Set the allowed ciphers for sockets created with this context when
19661966
connecting using TLS 1.2 and earlier. The *ciphers* argument should
19671967
be a string in the `OpenSSL cipher list format
1968-
<https://docs.openssl.org/master/man1/ciphers/>`_.
1968+
<https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-list-format>`_.
19691969
To set allowed TLS 1.3 ciphers, use :meth:`SSLContext.set_ciphersuites`.
19701970

19711971
If no cipher can be selected (because compile-time options or other

‎Doc/library/this.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
:orphan:
2+
3+
:mod:`!this` --- The Zen of Python
4+
==================================
5+
6+
.. module:: this
7+
:synopsis: The Zen of Python
8+
9+
..
10+
This easter egg module is deliberately missing from the table of contents.
11+
12+
:pep:`20` -- The Zen of Python, by Tim Peters (RIP).
13+
14+
| Beautiful is better than ugly.
15+
| Explicit is better than implicit.
16+
| Simple is better than complex.
17+
| Complex is better than complicated.
18+
| Flat is better than nested.
19+
| Sparse is better than dense.
20+
| Readability counts.
21+
| Special cases aren't special enough to break the rules.
22+
| Although practicality beats purity.
23+
| Errors should never pass silently.
24+
| Unless explicitly silenced.
25+
| In the face of ambiguity, refuse the temptation to guess.
26+
| There should be one-\- and preferably only one -\-obvious way to do it.
27+
| Although that way may not be obvious at first unless you're Dutch.
28+
| Now is better than never.
29+
| Although never is often better than *right* now.
30+
| If the implementation is hard to explain, it's a bad idea.
31+
| If the implementation is easy to explain, it may be a good idea.
32+
| Namespaces are one honking great idea -\- let's do more of those!
33+
34+
`In Memoriam: Tim Peters 1952-2026 <https://discuss.python.org/t/in-memoriam-tim-peters-1952-2026/110028>`__.
35+
36+
37+
Usage
38+
-----
39+
40+
.. code-block:: shell-session
41+
42+
$ python3 -m this

‎Doc/library/types.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -515,14 +515,14 @@ Additional Utility Classes and Functions
515515
.. versionchanged:: 3.13
516516
Added support for an optional positional argument.
517517

518-
.. function:: DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)
518+
.. class:: DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)
519519

520-
Route attribute access on a class to __getattr__.
520+
Route attribute access on a class to :meth:`~object.__getattr__`.
521521

522522
This is a descriptor, used to define attributes that act differently when
523523
accessed through an instance and through a class. Instance access remains
524524
normal, but access to an attribute through a class will be routed to the
525-
class's __getattr__ method; this is done by raising AttributeError.
525+
class's ``__getattr__`` method; this is done by raising :exc:`AttributeError`.
526526

527527
This allows one to have properties active on an instance, and have virtual
528528
attributes on the class with the same name (see :class:`enum.Enum` for an example).

‎Doc/library/unittest.mock-examples.rst‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -642,7 +642,7 @@ Mocking a generator method
642642
~~~~~~~~~~~~~~~~~~~~~~~~~~
643643

644644
A Python generator is a function or method that uses the :keyword:`yield` statement
645-
to return a series of values when iterated over [#]_.
645+
to return a series of values when iterated over.
646646

647647
A generator method / function is called to return the generator object. It is
648648
the generator object that is then iterated over. The protocol method for
@@ -671,12 +671,6 @@ To configure the values returned from the iteration (implicit in the call to
671671
>>> list(mock_foo.iter())
672672
[1, 2, 3]
673673

674-
.. [#] There are also generator expressions and more `advanced uses
675-
<http://www.dabeaz.com/coroutines/index.html>`_ of generators, but we aren't
676-
concerned about them here. A very good introduction to generators and how
677-
powerful they are is: `Generator Tricks for Systems Programmers
678-
<http://www.dabeaz.com/generators/>`_.
679-
680674

681675
Applying the same patch to every test method
682676
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎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)