Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b0f6d18

Browse files
gvanrossumgvanrossum
committed
Merge remote-tracking branch 'origin/main' into optim-exec
2 parents 9df20bb + 8c24a83 commit b0f6d18

38 files changed

+1036
-349
lines changed

‎.pre-commit-config.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ repos:
33
rev: v4.4.0
44
hooks:
55
- id: check-yaml
6+
- id: end-of-file-fixer
7+
types: [python]
8+
exclude: Lib/test/coding20731.py
69
- id: trailing-whitespace
710
types_or: [c, python, rst]
811

‎Doc/c-api/dict.rst

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -98,9 +98,11 @@ Dictionary Objects
9898
Return the object from dictionary *p* which has a key *key*. Return ``NULL``
9999
if the key *key* is not present, but *without* setting an exception.
100100
101-
Note that exceptions which occur while calling :meth:`__hash__` and
102-
:meth:`__eq__` methods will get suppressed.
103-
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
101+
.. note::
102+
103+
Exceptions that occur while this calls :meth:`~object.__hash__` and
104+
:meth:`~object.__eq__` methods are silently ignored.
105+
Prefer the :c:func:`PyDict_GetItemWithError` function instead.
104106
105107
.. versionchanged:: 3.10
106108
Calling this API without :term:`GIL` held had been allowed for historical
@@ -120,10 +122,13 @@ Dictionary Objects
120122
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
121123
:c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
122124
123-
Note that exceptions which occur while calling :meth:`__hash__` and
124-
:meth:`__eq__` methods and creating a temporary string object
125-
will get suppressed.
126-
To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
125+
.. note::
126+
127+
Exceptions that occur while this calls :meth:`~object.__hash__` and
128+
:meth:`~object.__eq__` methods or while creating the temporary :class:`str`
129+
object are silently ignored.
130+
Prefer using the :c:func:`PyDict_GetItemWithError` function with your own
131+
:c:func:`PyUnicode_FromString` *key* instead.
127132
128133
129134
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

‎Doc/c-api/object.rst

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,11 @@ Object Protocol
3333
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
3434
always succeeds.
3535
36-
Note that exceptions which occur while calling :meth:`__getattr__` and
37-
:meth:`__getattribute__` methods will get suppressed.
38-
To get error reporting use :c:func:`PyObject_GetAttr()` instead.
36+
.. note::
37+
38+
Exceptions that occur when this calls :meth:`~object.__getattr__` and
39+
:meth:`~object.__getattribute__` methods are silently ignored.
40+
For proper error handling, use :c:func:`PyObject_GetAttr` instead.
3941
4042
4143
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
@@ -44,10 +46,12 @@ Object Protocol
4446
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
4547
always succeeds.
4648
47-
Note that exceptions which occur while calling :meth:`__getattr__` and
48-
:meth:`__getattribute__` methods and creating a temporary string object
49-
will get suppressed.
50-
To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
49+
.. note::
50+
51+
Exceptions that occur when this calls :meth:`~object.__getattr__` and
52+
:meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
53+
object are silently ignored.
54+
For proper error handling, use :c:func:`PyObject_GetAttrString` instead.
5155
5256
5357
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)

‎Doc/library/exceptions.rst

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -912,10 +912,11 @@ their subgroups based on the types of the contained exceptions.
912912
Returns an exception group that contains only the exceptions from the
913913
current group that match *condition*, or ``None`` if the result is empty.
914914

915-
The condition can be either a function that accepts an exception and returns
916-
true for those that should be in the subgroup, or it can be an exception type
917-
or a tuple of exception types, which is used to check for a match using the
918-
same check that is used in an ``except`` clause.
915+
The condition can be an exception type or tuple of exception types, in which
916+
case each exception is checked for a match using the same check that is used
917+
in an ``except`` clause. The condition can also be a callable (other than
918+
a type object) that accepts an exception as its single argument and returns
919+
true for the exceptions that should be in the subgroup.
919920

920921
The nesting structure of the current exception is preserved in the result,
921922
as are the values of its :attr:`message`, :attr:`__traceback__`,
@@ -926,6 +927,9 @@ their subgroups based on the types of the contained exceptions.
926927
including the top-level and any nested exception groups. If the condition is
927928
true for such an exception group, it is included in the result in full.
928929

930+
.. versionadded:: 3.13
931+
``condition`` can be any callable which is not a type object.
932+
929933
.. method:: split(condition)
930934

931935
Like :meth:`subgroup`, but returns the pair ``(match, rest)`` where ``match``

‎Doc/library/pathlib.rst

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -596,8 +596,8 @@ Pure paths provide the following methods and properties:
596596

597597
Set *case_sensitive* to ``True`` or ``False`` to override this behaviour.
598598

599-
.. versionadded:: 3.12
600-
The *case_sensitive* argument.
599+
.. versionchanged:: 3.12
600+
The *case_sensitive* parameter was added.
601601

602602
.. versionchanged:: 3.13
603603
Support for the recursive wildcard "``**``" was added. In previous
@@ -642,8 +642,8 @@ Pure paths provide the following methods and properties:
642642
are present in the path; call :meth:`~Path.resolve` first if
643643
necessary to resolve symlinks.
644644

645-
.. versionadded:: 3.12
646-
The *walk_up* argument (old behavior is the same as ``walk_up=False``).
645+
.. versionchanged:: 3.12
646+
The *walk_up* parameter was added (old behavior is the same as ``walk_up=False``).
647647

648648
.. deprecated-removed:: 3.12 3.14
649649

@@ -962,11 +962,11 @@ call fails (for example because the path doesn't exist).
962962
Return only directories if *pattern* ends with a pathname components
963963
separator (:data:`~os.sep` or :data:`~os.altsep`).
964964

965-
.. versionadded:: 3.12
966-
The *case_sensitive* argument.
965+
.. versionchanged:: 3.12
966+
The *case_sensitive* parameter was added.
967967

968-
.. versionadded:: 3.13
969-
The *follow_symlinks* argument.
968+
.. versionchanged:: 3.13
969+
The *follow_symlinks* parameter was added.
970970

971971
.. method:: Path.group()
972972

@@ -1362,8 +1362,8 @@ call fails (for example because the path doesn't exist).
13621362
infinite loop is encountered along the resolution path, :exc:`RuntimeError`
13631363
is raised.
13641364

1365-
.. versionadded:: 3.6
1366-
The *strict* argument (pre-3.6 behavior is strict).
1365+
.. versionchanged:: 3.6
1366+
The *strict* parameter was added (pre-3.6 behavior is strict).
13671367

13681368
.. method:: Path.rglob(pattern, *, case_sensitive=None, follow_symlinks=None)
13691369

@@ -1394,11 +1394,11 @@ call fails (for example because the path doesn't exist).
13941394
Return only directories if *pattern* ends with a pathname components
13951395
separator (:data:`~os.sep` or :data:`~os.altsep`).
13961396

1397-
.. versionadded:: 3.12
1398-
The *case_sensitive* argument.
1397+
.. versionchanged:: 3.12
1398+
The *case_sensitive* parameter was added.
13991399

1400-
.. versionadded:: 3.13
1401-
The *follow_symlinks* argument.
1400+
.. versionchanged:: 3.13
1401+
The *follow_symlinks* parameter was added.
14021402

14031403
.. method:: Path.rmdir()
14041404

‎Doc/library/sqlite3.rst

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -413,15 +413,15 @@ Module functions
413413

414414
.. function:: register_adapter(type, adapter, /)
415415

416-
Register an *adapter* callable to adapt the Python type *type* into an
417-
SQLite type.
416+
Register an *adapter* :term:`callable` to adapt the Python type *type*
417+
into an SQLite type.
418418
The adapter is called with a Python object of type *type* as its sole
419419
argument, and must return a value of a
420420
:ref:`type that SQLite natively understands <sqlite3-types>`.
421421

422422
.. function:: register_converter(typename, converter, /)
423423

424-
Register the *converter* callable to convert SQLite objects of type
424+
Register the *converter* :term:`callable` to convert SQLite objects of type
425425
*typename* into a Python object of a specific type.
426426
The converter is invoked for all SQLite values of type *typename*;
427427
it is passed a :class:`bytes` object and should return an object of the
@@ -484,7 +484,7 @@ Module constants
484484
SQLITE_DENY
485485
SQLITE_IGNORE
486486

487-
Flags that should be returned by the *authorizer_callback* callable
487+
Flags that should be returned by the *authorizer_callback* :term:`callable`
488488
passed to :meth:`Connection.set_authorizer`, to indicate whether:
489489

490490
* Access is allowed (:const:`!SQLITE_OK`),
@@ -629,8 +629,8 @@ Connection objects
629629

630630
Create and return a :class:`Cursor` object.
631631
The cursor method accepts a single optional parameter *factory*. If
632-
supplied, this must be a callable returning an instance of :class:`Cursor`
633-
or its subclasses.
632+
supplied, this must be a :term:`callable` returning
633+
an instance of :class:`Cursor` or its subclasses.
634634

635635
.. method:: blobopen(table, column, row, /, *, readonly=False, name="main")
636636

@@ -723,7 +723,7 @@ Connection objects
723723
If ``-1``, it may take any number of arguments.
724724

725725
:param func:
726-
A callable that is called when the SQL function is invoked.
726+
A :term:`callable` that is called when the SQL function is invoked.
727727
The callable must return :ref:`a type natively supported by SQLite
728728
<sqlite3-types>`.
729729
Set to ``None`` to remove an existing SQL function.
@@ -945,9 +945,10 @@ Connection objects
945945

946946
.. method:: set_authorizer(authorizer_callback)
947947

948-
Register callable *authorizer_callback* to be invoked for each attempt to
949-
access a column of a table in the database. The callback should return
950-
one of :const:`SQLITE_OK`, :const:`SQLITE_DENY`, or :const:`SQLITE_IGNORE`
948+
Register :term:`callable` *authorizer_callback* to be invoked
949+
for each attempt to access a column of a table in the database.
950+
The callback should return one of :const:`SQLITE_OK`,
951+
:const:`SQLITE_DENY`, or :const:`SQLITE_IGNORE`
951952
to signal how access to the column should be handled
952953
by the underlying SQLite library.
953954

@@ -970,7 +971,7 @@ Connection objects
970971

971972
.. method:: set_progress_handler(progress_handler, n)
972973

973-
Register callable *progress_handler* to be invoked for every *n*
974+
Register :term:`callable` *progress_handler* to be invoked for every *n*
974975
instructions of the SQLite virtual machine. This is useful if you want to
975976
get called from SQLite during long-running operations, for example to update
976977
a GUI.
@@ -985,8 +986,8 @@ Connection objects
985986

986987
.. method:: set_trace_callback(trace_callback)
987988

988-
Register callable *trace_callback* to be invoked for each SQL statement
989-
that is actually executed by the SQLite backend.
989+
Register :term:`callable` *trace_callback* to be invoked
990+
for each SQL statement that is actually executed by the SQLite backend.
990991

991992
The only argument passed to the callback is the statement (as
992993
:class:`str`) that is being executed. The return value of the callback is
@@ -1136,8 +1137,8 @@ Connection objects
11361137
Defaults to ``-1``.
11371138

11381139
:param progress:
1139-
If set to a callable, it is invoked with three integer arguments for
1140-
every backup iteration:
1140+
If set to a :term:`callable`,
1141+
it is invoked with three integer arguments for every backup iteration:
11411142
the *status* of the last iteration,
11421143
the *remaining* number of pages still to be copied,
11431144
and the *total* number of pages.
@@ -1401,8 +1402,8 @@ Connection objects
14011402

14021403
.. attribute:: text_factory
14031404

1404-
A callable that accepts a :class:`bytes` parameter and returns a text
1405-
representation of it.
1405+
A :term:`callable` that accepts a :class:`bytes` parameter
1406+
and returns a text representation of it.
14061407
The callable is invoked for SQLite values with the ``TEXT`` data type.
14071408
By default, this attribute is set to :class:`str`.
14081409
If you want to return ``bytes`` instead, set *text_factory* to ``bytes``.

‎Doc/library/typing.rst

Lines changed: 72 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -346,6 +346,68 @@ Or by using the :class:`TypeVar` factory directly::
346346
.. versionchanged:: 3.12
347347
Syntactic support for generics is new in Python 3.12.
348348

349+
.. _annotating-tuples:
350+
351+
Annotating tuples
352+
=================
353+
354+
For most containers in Python, the typing system assumes that all elements in
355+
the container will be of the same type. For example::
356+
357+
from collections.abc import Mapping
358+
359+
# Type checker will infer that all elements in ``x`` are meant to be ints
360+
x: list[int] = []
361+
362+
# Type checker error: ``list`` only accepts a single type argument:
363+
y: list[int, str] = [1, 'foo']
364+
365+
# Type checker will infer that all keys in ``z`` are meant to be strings,
366+
# and that all values in ``z`` are meant to be either strings or ints
367+
z: Mapping[str, str | int] = {}
368+
369+
:class:`list` only accepts one type argument, so a type checker would emit an
370+
error on the ``y`` assignment above. Similarly,
371+
:class:`~collections.abc.Mapping` only accepts two type arguments: the first
372+
indicates the type of the keys, and the second indicates the type of the
373+
values.
374+
375+
Unlike most other Python containers, however, it is common in idiomatic Python
376+
code for tuples to have elements which are not all of the same type. For this
377+
reason, tuples are special-cased in Python's typing system. :class:`tuple`
378+
accepts *any number* of type arguments::
379+
380+
# OK: ``x`` is assigned to a tuple of length 1 where the sole element is an int
381+
x: tuple[int] = (5,)
382+
383+
# OK: ``y`` is assigned to a tuple of length 2;
384+
# element 1 is an int, element 2 is a str
385+
y: tuple[int, str] = (5, "foo")
386+
387+
# Error: the type annotation indicates a tuple of length 1,
388+
# but ``z`` has been assigned to a tuple of length 3
389+
z: tuple[int] = (1, 2, 3)
390+
391+
To denote a tuple which could be of *any* length, and in which all elements are
392+
of the same type ``T``, use ``tuple[T, ...]``. To denote an empty tuple, use
393+
``tuple[()]``. Using plain ``tuple`` as an annotation is equivalent to using
394+
``tuple[Any, ...]``::
395+
396+
x: tuple[int, ...] = (1, 2)
397+
# These reassignments are OK: ``tuple[int, ...]`` indicates x can be of any length
398+
x = (1, 2, 3)
399+
x = ()
400+
# This reassignment is an error: all elements in ``x`` must be ints
401+
x = ("foo", "bar")
402+
403+
# ``y`` can only ever be assigned to an empty tuple
404+
y: tuple[()] = ()
405+
406+
z: tuple = ("foo", "bar")
407+
# These reassignments are OK: plain ``tuple`` is equivalent to ``tuple[Any, ...]``
408+
z = (1, 2, 3)
409+
z = ()
410+
349411
.. _user-defined-generics:
350412

351413
User-defined generic types
@@ -877,26 +939,6 @@ Special forms
877939
These can be used as types in annotations. They all support subscription using
878940
``[]``, but each has a unique syntax.
879941

880-
.. data:: Tuple
881-
882-
Deprecated alias for :class:`tuple`.
883-
884-
``Tuple[X, Y]`` is the type of a tuple of two items
885-
with the first item of type X and the second of type Y. The type of
886-
the empty tuple can be written as ``Tuple[()]``.
887-
888-
Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding
889-
to type variables T1 and T2. ``Tuple[int, float, str]`` is a tuple
890-
of an int, a float and a string.
891-
892-
To specify a variable-length tuple of homogeneous type,
893-
use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain ``Tuple`` annotation
894-
is equivalent to ``tuple``, ``Tuple[Any, ...]``, or ``tuple[Any, ...]``.
895-
896-
.. deprecated:: 3.9
897-
:class:`builtins.tuple <tuple>` now supports subscripting (``[]``).
898-
See :pep:`585` and :ref:`types-genericalias`.
899-
900942
.. data:: Union
901943

902944
Union type; ``Union[X, Y]`` is equivalent to ``X | Y`` and means either X or Y.
@@ -3136,7 +3178,16 @@ Aliases to built-in types
31363178
now supports subscripting (``[]``).
31373179
See :pep:`585` and :ref:`types-genericalias`.
31383180

3139-
.. note:: :data:`Tuple` is a special form.
3181+
.. data:: Tuple
3182+
3183+
Deprecated alias for :class:`tuple`.
3184+
3185+
:class:`tuple` and ``Tuple`` are special-cased in the type system; see
3186+
:ref:`annotating-tuples` for more details.
3187+
3188+
.. deprecated:: 3.9
3189+
:class:`builtins.tuple <tuple>` now supports subscripting (``[]``).
3190+
See :pep:`585` and :ref:`types-genericalias`.
31403191

31413192
.. _corresponding-to-types-in-collections:
31423193

0 commit comments

Comments
 (0)