Merge branch 'main' into fix_contains_error

Author: zware

.github/workflows/build.yml

@@ -199,8 +199,8 @@ jobs:
  uses: ./.github/workflows/reusable-macos.yml
  with:
  config_hash: ${{ needs.check_source.outputs.config_hash }}
- # macos-14 is M1, macos-13 is Intel
- os-matrix: '["macos-14", "macos-13"]'
+ # Cirrus is M1, macos-13 is default GHA Intel
+ os-matrix: '["ghcr.io/cirruslabs/macos-runner:sonoma", "macos-13"]'
 
  build_macos_free_threading:
  name: 'macOS (free-threading)'
@@ -210,8 +210,8 @@ jobs:
  with:
  config_hash: ${{ needs.check_source.outputs.config_hash }}
  free-threading: true
- # macos-14-large is Intel with 12 cores (most parallelism)
- os-matrix: '["macos-14"]'
+ # Cirrus is M1
+ os-matrix: '["ghcr.io/cirruslabs/macos-runner:sonoma"]'
 
  build_ubuntu:
  name: 'Ubuntu'

Doc/c-api/long.rst

@@ -494,6 +494,19 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
  .. versionadded:: 3.13
 
 
+.. c:function:: int PyLong_GetSign(PyObject *obj, int *sign)
+
+ Get the sign of the integer object *obj*.
+
+ On success, set *\*sign* to the integer sign (0, -1 or +1 for zero, negative or
+ positive integer, respectively) and return 0.
+
+ On failure, return -1 with an exception set. This function always succeeds
+ if *obj* is a :c:type:`PyLongObject` or its subtype.
+
+ .. versionadded:: 3.14
+
+
 .. c:function:: int PyUnstable_Long_IsCompact(const PyLongObject* op)
 
  Return 1 if *op* is compact, 0 otherwise.

Doc/c-api/monitoring.rst

@@ -2,7 +2,7 @@
 
 .. _monitoring:
 
-Monitorong C API
+Monitoring C API
 ================
 
 Added in version 3.13.

Doc/c-api/reflection.rst

@@ -19,23 +19,28 @@ Reflection
 
  .. deprecated:: 3.13
 
- To avoid creating a reference cycle in :term:`optimized scopes <optimized scope>`,
- use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
+ Use either :c:func:`PyEval_GetFrameLocals` to obtain the same behaviour as calling
  :func:`locals` in Python code, or else call :c:func:`PyFrame_GetLocals` on the result
- of :c:func:`PyEval_GetFrame` to get the same result as this function without having to
- cache the proxy instance on the underlying frame.
+ of :c:func:`PyEval_GetFrame` to access the :attr:`~frame.f_locals` attribute of the
+ currently executing frame.
 
- Return the :attr:`~frame.f_locals` attribute of the currently executing frame,
+ Return a mapping providing access to the local variables in the current execution frame,
  or ``NULL`` if no frame is currently executing.
 
- If the frame refers to an :term:`optimized scope`, this returns a
- write-through proxy object that allows modifying the locals.
- In all other cases (classes, modules, :func:`exec`, :func:`eval`) it returns
- the mapping representing the frame locals directly (as described for
- :func:`locals`).
+ Refer to :func:`locals` for details of the mapping returned at different scopes.
+
+ As this function returns a :term:`borrowed reference`, the dictionary returned for
+ :term:`optimized scopes <optimized scope>` is cached on the frame object and will remain
+ alive as long as the frame object does. Unlike :c:func:`PyEval_GetFrameLocals` and
+ :func:`locals`, subsequent calls to this function in the same frame will update the
+ contents of the cached dictionary to reflect changes in the state of the local variables
+ rather than returning a new snapshot.
 
  .. versionchanged:: 3.13
- As part of :pep:`667`, return a proxy object for optimized scopes.
+ As part of :pep:`667`, :c:func:`PyFrame_GetLocals`, :func:`locals`, and
+ :attr:`FrameType.f_locals <frame.f_locals>` no longer make use of the shared cache
+ dictionary. Refer to the :ref:`What's New entry <whatsnew313-locals-semantics>` for
+ additional details.
 
 
 .. c:function:: PyObject* PyEval_GetGlobals(void)

Doc/howto/logging-cookbook.rst

@@ -2950,7 +2950,7 @@ When run, this produces a file with exactly two lines:
 .. code-block:: none
 
  28/01/2015 07:21:23|INFO|Sample message|
- 28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n File "logtest7.py", line 30, in main\n x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|
+ 28/01/2015 07:21:23|ERROR|ZeroDivisionError: division by zero|'Traceback (most recent call last):\n File "logtest7.py", line 30, in main\n x = 1 / 0\nZeroDivisionError: division by zero'|
 
 While the above treatment is simplistic, it points the way to how exception
 information can be formatted to your liking. The :mod:`traceback` module may be

Doc/library/functions.rst

@@ -1004,9 +1004,8 @@ are always available. They are listed here in alphabetical order.
  115
 
  If the argument defines :meth:`~object.__int__`,
- ``int(x)`` returns ``x.__int__()``. If the argument defines :meth:`~object.__index__`,
- it returns ``x.__index__()``. If the argument defines :meth:`~object.__trunc__`,
- it returns ``x.__trunc__()``.
+ ``int(x)`` returns ``x.__int__()``. If the argument defines
+ :meth:`~object.__index__`, it returns ``x.__index__()``.
  For floating point numbers, this truncates towards zero.
 
  If the argument is not a number or if *base* is given, then it must be a string,
@@ -1044,9 +1043,6 @@ are always available. They are listed here in alphabetical order.
  .. versionchanged:: 3.8
  Falls back to :meth:`~object.__index__` if :meth:`~object.__int__` is not defined.
 
- .. versionchanged:: 3.11
- The delegation to :meth:`~object.__trunc__` is deprecated.
-
  .. versionchanged:: 3.11
  :class:`int` string inputs and string representations can be limited to
  help avoid denial of service attacks. A :exc:`ValueError` is raised when
@@ -1055,6 +1051,9 @@ are always available. They are listed here in alphabetical order.
  See the :ref:`integer string conversion length limitation
  <int_max_str_digits>` documentation.
 
+ .. versionchanged:: 3.14
+ :func:`int` no longer delegates to the :meth:`~object.__trunc__` method.
+
 .. function:: isinstance(object, classinfo)
 
  Return ``True`` if the *object* argument is an instance of the *classinfo*

Doc/library/pathlib.rst

@@ -1067,6 +1067,90 @@ Querying file type and status
  .. versionadded:: 3.5
 
 
+Reading and writing files
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
+
+ Open the file pointed to by the path, like the built-in :func:`open`
+ function does::
+
+ >>> p = Path('setup.py')
+ >>> with p.open() as f:
+ ... f.readline()
+ ...
+ '#!/usr/bin/env python3\n'
+
+
+.. method:: Path.read_text(encoding=None, errors=None, newline=None)
+
+ Return the decoded contents of the pointed-to file as a string::
+
+ >>> p = Path('my_text_file')
+ >>> p.write_text('Text file contents')
+ 18
+ >>> p.read_text()
+ 'Text file contents'
+
+ The file is opened and then closed. The optional parameters have the same
+ meaning as in :func:`open`.
+
+ .. versionadded:: 3.5
+
+ .. versionchanged:: 3.13
+ The *newline* parameter was added.
+
+
+.. method:: Path.read_bytes()
+
+ Return the binary contents of the pointed-to file as a bytes object::
+
+ >>> p = Path('my_binary_file')
+ >>> p.write_bytes(b'Binary file contents')
+ 20
+ >>> p.read_bytes()
+ b'Binary file contents'
+
+ .. versionadded:: 3.5
+
+
+.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
+
+ Open the file pointed to in text mode, write *data* to it, and close the
+ file::
+
+ >>> p = Path('my_text_file')
+ >>> p.write_text('Text file contents')
+ 18
+ >>> p.read_text()
+ 'Text file contents'
+
+ An existing file of the same name is overwritten. The optional parameters
+ have the same meaning as in :func:`open`.
+
+ .. versionadded:: 3.5
+
+ .. versionchanged:: 3.10
+ The *newline* parameter was added.
+
+
+.. method:: Path.write_bytes(data)
+
+ Open the file pointed to in bytes mode, write *data* to it, and close the
+ file::
+
+ >>> p = Path('my_binary_file')
+ >>> p.write_bytes(b'Binary file contents')
+ 20
+ >>> p.read_bytes()
+ b'Binary file contents'
+
+ An existing file of the same name is overwritten.
+
+ .. versionadded:: 3.5
+
+
 Other methods
 ^^^^^^^^^^^^^
 
@@ -1360,18 +1444,6 @@ example because the path doesn't exist).
  The *exist_ok* parameter was added.
 
 
-.. method:: Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)
-
- Open the file pointed to by the path, like the built-in :func:`open`
- function does::
-
- >>> p = Path('setup.py')
- >>> with p.open() as f:
- ... f.readline()
- ...
- '#!/usr/bin/env python3\n'
-
-
 .. method:: Path.owner(*, follow_symlinks=True)
 
  Return the name of the user owning the file. :exc:`KeyError` is raised
@@ -1388,37 +1460,6 @@ example because the path doesn't exist).
  The *follow_symlinks* parameter was added.
 
 
-.. method:: Path.read_bytes()
-
- Return the binary contents of the pointed-to file as a bytes object::
-
- >>> p = Path('my_binary_file')
- >>> p.write_bytes(b'Binary file contents')
- 20
- >>> p.read_bytes()
- b'Binary file contents'
-
- .. versionadded:: 3.5
-
-
-.. method:: Path.read_text(encoding=None, errors=None, newline=None)
-
- Return the decoded contents of the pointed-to file as a string::
-
- >>> p = Path('my_text_file')
- >>> p.write_text('Text file contents')
- 18
- >>> p.read_text()
- 'Text file contents'
-
- The file is opened and then closed. The optional parameters have the same
- meaning as in :func:`open`.
-
- .. versionadded:: 3.5
-
- .. versionchanged:: 3.13
- The *newline* parameter was added.
-
 .. method:: Path.readlink()
 
  Return the path to which the symbolic link points (as returned by
@@ -1593,42 +1634,6 @@ example because the path doesn't exist).
  The *missing_ok* parameter was added.
 
 
-.. method:: Path.write_bytes(data)
-
- Open the file pointed to in bytes mode, write *data* to it, and close the
- file::
-
- >>> p = Path('my_binary_file')
- >>> p.write_bytes(b'Binary file contents')
- 20
- >>> p.read_bytes()
- b'Binary file contents'
-
- An existing file of the same name is overwritten.
-
- .. versionadded:: 3.5
-
-
-.. method:: Path.write_text(data, encoding=None, errors=None, newline=None)
-
- Open the file pointed to in text mode, write *data* to it, and close the
- file::
-
- >>> p = Path('my_text_file')
- >>> p.write_text('Text file contents')
- 18
- >>> p.read_text()
- 'Text file contents'
-
- An existing file of the same name is overwritten. The optional parameters
- have the same meaning as in :func:`open`.
-
- .. versionadded:: 3.5
-
- .. versionchanged:: 3.10
- The *newline* parameter was added.
-
-
 .. _pathlib-pattern-language:
 
 Pattern language

Doc/library/typing.rst

@@ -3080,35 +3080,37 @@ Introspection helpers
  Return a dictionary containing type hints for a function, method, module
  or class object.
 
- This is often the same as ``obj.__annotations__``. In addition,
- forward references encoded as string literals are handled by evaluating
- them in ``globals``, ``locals`` and (where applicable)
- :ref:`type parameter <type-params>` namespaces.
- For a class ``C``, return
- a dictionary constructed by merging all the ``__annotations__`` along
- ``C.__mro__`` in reverse order.
-
- The function recursively replaces all ``Annotated[T, ...]`` with ``T``,
- unless ``include_extras`` is set to ``True`` (see :class:`Annotated` for
- more information). For example:
-
- .. testcode::
-
- class Student(NamedTuple):
- name: Annotated[str, 'some marker']
-
- assert get_type_hints(Student) == {'name': str}
- assert get_type_hints(Student, include_extras=False) == {'name': str}
- assert get_type_hints(Student, include_extras=True) == {
- 'name': Annotated[str, 'some marker']
- }
+ This is often the same as ``obj.__annotations__``, but this function makes
+ the following changes to the annotations dictionary:
+
+ * Forward references encoded as string literals or :class:`ForwardRef`
+ objects are handled by evaluating them in *globalns*, *localns*, and
+ (where applicable) *obj*'s :ref:`type parameter <type-params>` namespace.
+ If *globalns* or *localns* is not given, appropriate namespace
+ dictionaries are inferred from *obj*.
+ * ``None`` is replaced with :class:`types.NoneType`.
+ * If :func:`@no_type_check <no_type_check>` has been applied to *obj*, an
+ empty dictionary is returned.
+ * If *obj* is a class ``C``, the function returns a dictionary that merges
+ annotations from ``C``'s base classes with those on ``C`` directly. This
+ is done by traversing ``C.__mro__`` and iteratively combining
+ ``__annotations__`` dictionaries. Annotations on classes appearing
+ earlier in the :term:`method resolution order` always take precedence over
+ annotations on classes appearing later in the method resolution order.
+ * The function recursively replaces all occurrences of ``Annotated[T, ...]``
+ with ``T``, unless *include_extras* is set to ``True`` (see
+ :class:`Annotated` for more information).
+
+ See also :func:`inspect.get_annotations`, a lower-level function that
+ returns annotations more directly.
 
  .. note::
 
- :func:`get_type_hints` does not work with imported
- :ref:`type aliases <type-aliases>` that include forward references.
- Enabling postponed evaluation of annotations (:pep:`563`) may remove
- the need for most forward references.
+ If any forward references in the annotations of *obj* are not resolvable
+ or are not valid Python code, this function will raise an exception
+ such as :exc:`NameError`. For example, this can happen with imported
+ :ref:`type aliases <type-aliases>` that include forward references,
+ or with names imported under :data:`if TYPE_CHECKING <TYPE_CHECKING>`.
 
  .. versionchanged:: 3.9
  Added ``include_extras`` parameter as part of :pep:`593`.