Merge branch 'main' into feature/filecmp-coverage

Author: Bolotnyj

Doc/c-api/interp-lifecycle.rst

@@ -265,6 +265,48 @@ Initializing and finalizing the interpreter
    first initialized).
 
 
+.. c:function:: int Py_FrozenMain(int argc, char **argv)
+
+   .. index:: single: freeze utility
+
+   The main program for a "frozen" Python program (an executable that embeds
+   the interpreter together with the bytecode of the program's modules, as
+   produced by the :program:`freeze` utility; see :source:`Tools/freeze`).
+
+   This function initializes the interpreter, imports the frozen module named
+   ``__main__``, and finalizes the interpreter.
+   The frozen modules must have been registered in
+   :c:var:`PyImport_FrozenModules` before calling this function;
+   it is a fatal error if ``__main__`` is not among them.
+
+   *argc* and *argv* are byte strings like the arguments of a C program's
+   ``main`` function, and are passed to the interpreter with
+   :c:func:`PyConfig_SetBytesArgv`.
+   Unlike :c:func:`Py_Main`, the arguments are not parsed as Python command
+   line options (:c:member:`PyConfig.parse_argv` is ``0``), so all of them
+   are made available to the program in :data:`sys.argv`.
+   Apart from that, the interpreter uses the
+   :ref:`Python Configuration <init-python-config>`, so environment variables
+   such as :envvar:`PYTHONPATH` are honored.
+   Warnings about the path configuration
+   (:c:member:`PyConfig.pathconfig_warnings`) are suppressed.
+   If :envvar:`PYTHONINSPECT` is set and standard input is a terminal, an
+   interactive prompt is run after ``__main__`` has finished, as with the
+   :option:`-i` option.
+
+   Return ``0`` if ``__main__`` ran without an unhandled exception, ``1``
+   otherwise, and ``120`` if finalizing the interpreter failed (see
+   :c:func:`Py_FinalizeEx`).
+   An unhandled :exc:`SystemExit` terminates the process.
+   If the interpreter cannot be initialized, the process exits via
+   :c:func:`Py_ExitStatusException`.
+
+   On Windows, this function is not exported by the Python DLL.
+   The :program:`freeze` utility compiles :file:`Python/frozenmain.c` into the
+   frozen program instead, together with the Windows-specific hooks that the
+   function requires.
+
+
 .. c:function:: int Py_RunMain(void)
 
    Executes the main module in a fully configured CPython runtime.

Doc/library/ast.rst

@@ -48,10 +48,10 @@ Node classes
    module and re-exported in :mod:`!ast`.
 
    There is one class defined for each left-hand side symbol in the abstract
-   grammar (for example, :class:`ast.stmt` or :class:`ast.expr`).  In addition,
+   grammar (for example, :class:`!ast.stmt` or :class:`!ast.expr`).  In addition,
    there is one class defined for each constructor on the right-hand side; these
    classes inherit from the classes for the left-hand side trees.  For example,
-   :class:`ast.BinOp` inherits from :class:`ast.expr`.  For production rules
+   :class:`ast.BinOp` inherits from :class:`!ast.expr`.  For production rules
    with alternatives (aka "sums"), the left-hand side class is abstract: only
    instances of specific constructor nodes are ever created.
 
@@ -65,7 +65,7 @@ Node classes
 
       Each instance of a concrete class has one attribute for each child node,
       of the type as defined in the grammar.  For example, :class:`ast.BinOp`
-      instances have an attribute :attr:`left` of type :class:`ast.expr`.
+      instances have an attribute :attr:`!left` of type :class:`!ast.expr`.
 
       If these attributes are marked as optional in the grammar (using a
       question mark), the value might be ``None``.  If the attributes can have
@@ -104,10 +104,11 @@ Node classes
       one can get the source segment of a one-line expression node using
       ``source_line[node.col_offset : node.end_col_offset]``.
 
-   The constructor of a class :class:`ast.T` parses its arguments as follows:
+   The constructors of AST node classes parse their arguments as follows:
 
    * If there are positional arguments, there must be as many as there are items
-     in :attr:`T._fields`; they will be assigned as attributes of these names.
+     in :attr:`!_fields`; they will be assigned to attributes with
+     the corresponding names.
    * If there are keyword arguments, they will set the attributes of the same
      names to the given values.
 
@@ -2223,8 +2224,8 @@ Async and await
 
 .. note::
    When a string is parsed by :func:`ast.parse`, operator nodes (subclasses
-   of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`,
-   :class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree
+   of :class:`!ast.operator`, :class:`!ast.unaryop`, :class:`!ast.cmpop`,
+   :class:`!ast.boolop` and :class:`!ast.expr_context`) on the returned tree
    will be singletons. Changes to one will be reflected in all other
    occurrences of the same value (for example, :class:`ast.Add`).
 

Doc/library/ctypes.rst

@@ -1107,6 +1107,17 @@ In addition, if a function argument is explicitly declared to be a pointer type
 type (``c_int`` in this case) can be passed to the function.  ctypes will apply
 the required :func:`byref` conversion in this case automatically.
 
+These conversions are also applied to the :attr:`!_as_parameter_` attribute of
+an object passed for a pointer argument (see
+:ref:`ctypes-calling-functions-with-own-custom-data-types`). So, for a
+``POINTER(c_int)`` argument, an object whose :attr:`!_as_parameter_` is a
+``c_int`` instance is passed by reference, and one whose :attr:`!_as_parameter_`
+is a ``c_int`` array is accepted as well.
+
+.. versionchanged:: next
+   Objects with an :attr:`!_as_parameter_` attribute now receive the same
+   implicit conversions for pointer arguments as the object they wrap.
+
 To set a POINTER type field to ``NULL``, you can assign ``None``::
 
    >>> bar.values = None

Doc/library/datetime.rst

@@ -2699,6 +2699,10 @@ convenience.
 |           | number, zero-padded to 6       | 999999                 |       |
 |           | digits.                        |                        |       |
 +-----------+--------------------------------+------------------------+-------+
+|  ``%Nf``  | Fraction of a second truncated | 000, 001, ..., 999     | \(5)  |
+|           | to *N* digits, where *N* is    | (``%3f``)              |       |
+|           | from 1 to 6.                   |                        |       |
++-----------+--------------------------------+------------------------+-------+
 | ``%:z``   | UTC offset in the form         | (empty), +00:00,       | \(6)  |
 |           | ``±HH:MM[:SS[.ffffff]]``       | -04:00, +10:30,        |       |
 |           | (empty string if the object is | +06:34:15,             |       |
@@ -2721,6 +2725,9 @@ differences between platforms in handling of unsupported format specifiers.
    ``%D``, ``%F``, ``%n``, ``%t``, and ``%:z`` were added for
    :meth:`~.datetime.strptime`.
 
+.. versionadded:: next
+   ``%Nf`` was added.
+
 
 Technical detail
 ^^^^^^^^^^^^^^^^
@@ -2745,6 +2752,13 @@ in the format string will be pulled from the default value.
    the default year of 1900 is *not* a leap year.  Always add a default leap
    year to partial date strings before parsing.
 
+.. note::
+   If a :meth:`~.datetime.strptime` format string contains more than
+   one directive for the same field, for example both ``%Y`` and ``%y``,
+   every directive must still match the input, but only the value of the
+   last one is used. For example, parsing ``200099`` with ``%Y%y`` gives
+   the year 1999. Repeating the same directive, like ``%Y%Y``, raises an error.
+
 .. testsetup::
 
     # doctest seems to turn the warning into an error which makes it
@@ -2826,7 +2840,8 @@ Notes:
 
 (5)
    When used with the :meth:`~.datetime.strptime` method, the ``%f`` directive
-   accepts from one to six digits and zero pads on the right. ``%f`` is
+   accepts from one to six digits and zero pads on the right, while ``%Nf``
+   accepts exactly *N* digits. ``%f`` is
    an extension to the set of format characters in the C standard (but
    implemented separately in datetime objects, and therefore always
    available).

Doc/library/pathlib.rst

@@ -586,10 +586,23 @@ Pure paths provide the following methods and properties:
       True
       >>> PurePath('a/b.py').full_match('*.py')
       False
-      >>> PurePath('/a/b/c.py').full_match('/a/**')
-      True
       >>> PurePath('/a/b/c.py').full_match('**/*.py')
       True
+      >>> PurePath('/a/b/c.py').full_match('/a/**')
+      True
+
+   Patterns ending in "``/**``", as in the example above, may surprise when
+   passed to ``full_match``. Even though "``**``" can match 0 segments,
+   "``.../**``" requires a separator to match. Hence "``/a/**``" does not
+   match path "``/a``". Since :class:`PurePath` drops trailing slashes, this
+   pattern also does not match "``/a/``".
+
+   ::
+
+      >>> PurePath('/a').full_match('/a/**')
+      False
+      >>> PurePath('/a/').full_match('/a/**')
+      False
 
    .. seealso::
       :ref:`pathlib-pattern-language` documentation.
@@ -1814,6 +1827,8 @@ The following wildcards are supported in patterns for
 
 ``**`` (entire segment)
   Matches any number of file or directory segments, including zero.
+  Note that in :meth:`~PurePath.full_match`, "``a/**``" does not match
+  "``a``", whereas :meth:`~Path.glob` yields "``a``" for that pattern.
 ``*`` (entire segment)
   Matches one file or directory segment.
 ``*`` (part of a segment)

Doc/library/pickle.rst

@@ -517,7 +517,11 @@ The following types can be pickled:
 * classes accessible from the top level of a module;
 
 * instances of such classes for which the result of calling :meth:`~object.__getstate__`
-  is picklable  (see section :ref:`pickle-inst` for details).
+  is picklable  (see section :ref:`pickle-inst` for details);
+
+* weak references and the weak containers from the :mod:`weakref` module,
+  provided that the weakly referenced objects are strongly referenced
+  elsewhere in the same pickle (see :class:`weakref.ref`).
 
 Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
 exception; when this happens, an unspecified number of bytes may have already

Doc/library/sys.rst

@@ -2432,6 +2432,26 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    .. versionadded:: 3.2
 
 
+.. data:: EXIT_SUCCESS
+
+    An int you can use to indicate your program ended gracefully.
+
+    .. code-block:: python
+
+        sys.exit(sys.EXIT_SUCCESS)
+
+    .. versionadded:: 3.16
+
+.. data:: EXIT_FAILURE
+
+    An int you can use to indicate your program encountered an error.
+
+    .. code-block:: python
+
+        sys.exit(sys.EXIT_FAILURE)
+
+    .. versionadded:: 3.16
+
 .. rubric:: Citations
 
 .. [C99] ISO/IEC 9899:1999.  "Programming languages -- C."  A public draft of this standard is available at https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ .