Merge branch 'main' into pickle_copy

Doc/c-api/init.rst

@@ -870,6 +870,19 @@ code, or when embedding the Python interpreter:
    When the current thread state is ``NULL``, this issues a fatal error (so that
    the caller needn't check for ``NULL``).
 
+   See also :c:func:`PyThreadState_GetUnchecked`.
+
+
+.. c:function:: PyThreadState* PyThreadState_GetUnchecked()
+
+   Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a
+   fatal error if it is NULL. The caller is responsible to check if the result
+   is NULL.
+
+   .. versionadded:: 3.13
+      In Python 3.5 to 3.12, the function was private and known as
+      ``_PyThreadState_UncheckedGet()``.
+
 
 .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
 

Doc/library/ast.rst

@@ -2483,26 +2483,26 @@ The following options are accepted:
 
 .. program:: ast
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message and exit.
 
-.. cmdoption:: -m <mode>
-               --mode <mode>
+.. option:: -m <mode>
+            --mode <mode>
 
    Specify what kind of code must be compiled, like the *mode* argument
    in :func:`parse`.
 
-.. cmdoption:: --no-type-comments
+.. option:: --no-type-comments
 
    Don't parse type comments.
 
-.. cmdoption:: -a, --include-attributes
+.. option:: -a, --include-attributes
 
    Include attributes such as line numbers and column offsets.
 
-.. cmdoption:: -i <indent>
-               --indent <indent>
+.. option:: -i <indent>
+            --indent <indent>
 
    Indentation of nodes in AST (number of spaces).
 

Doc/library/compileall.rst

@@ -26,74 +26,74 @@ compile Python sources.
 
 .. program:: compileall
 
-.. cmdoption:: directory ...
-               file ...
+.. option:: directory ...
+            file ...
 
    Positional arguments are files to compile or directories that contain
    source files, traversed recursively.  If no argument is given, behave as if
    the command line was :samp:`-l {<directories from sys.path>}`.
 
-.. cmdoption:: -l
+.. option:: -l
 
    Do not recurse into subdirectories, only compile source code files directly
    contained in the named or implied directories.
 
-.. cmdoption:: -f
+.. option:: -f
 
    Force rebuild even if timestamps are up-to-date.
 
-.. cmdoption:: -q
+.. option:: -q
 
    Do not print the list of files compiled. If passed once, error messages will
    still be printed. If passed twice (``-qq``), all output is suppressed.
 
-.. cmdoption:: -d destdir
+.. option:: -d destdir
 
    Directory prepended to the path to each file being compiled.  This will
    appear in compilation time tracebacks, and is also compiled in to the
    byte-code file, where it will be used in tracebacks and other messages in
    cases where the source file does not exist at the time the byte-code file is
    executed.
 
-.. cmdoption:: -s strip_prefix
-.. cmdoption:: -p prepend_prefix
+.. option:: -s strip_prefix
+.. option:: -p prepend_prefix
 
    Remove (``-s``) or append (``-p``) the given prefix of paths
    recorded in the ``.pyc`` files.
    Cannot be combined with ``-d``.
 
-.. cmdoption:: -x regex
+.. option:: -x regex
 
    regex is used to search the full path to each file considered for
    compilation, and if the regex produces a match, the file is skipped.
 
-.. cmdoption:: -i list
+.. option:: -i list
 
    Read the file ``list`` and add each line that it contains to the list of
    files and directories to compile.  If ``list`` is ``-``, read lines from
    ``stdin``.
 
-.. cmdoption:: -b
+.. option:: -b
 
    Write the byte-code files to their legacy locations and names, which may
    overwrite byte-code files created by another version of Python.  The default
    is to write files to their :pep:`3147` locations and names, which allows
    byte-code files from multiple versions of Python to coexist.
 
-.. cmdoption:: -r
+.. option:: -r
 
    Control the maximum recursion level for subdirectories.
    If this is given, then ``-l`` option will not be taken into account.
    :program:`python -m compileall <directory> -r 0` is equivalent to
    :program:`python -m compileall <directory> -l`.
 
-.. cmdoption:: -j N
+.. option:: -j N
 
    Use *N* workers to compile the files within the given directory.
    If ``0`` is used, then the result of :func:`os.process_cpu_count()`
    will be used.
 
-.. cmdoption:: --invalidation-mode [timestamp|checked-hash|unchecked-hash]
+.. option:: --invalidation-mode [timestamp|checked-hash|unchecked-hash]
 
    Control how the generated byte-code files are invalidated at runtime.
    The ``timestamp`` value, means that ``.pyc`` files with the source timestamp
@@ -106,17 +106,17 @@ compile Python sources.
    variable is not set, and ``checked-hash`` if the ``SOURCE_DATE_EPOCH``
    environment variable is set.
 
-.. cmdoption:: -o level
+.. option:: -o level
 
    Compile with the given optimization level. May be used multiple times
    to compile for multiple levels at a time (for example,
    ``compileall -o 1 -o 2``).
 
-.. cmdoption:: -e dir
+.. option:: -e dir
 
    Ignore symlinks pointing outside the given directory.
 
-.. cmdoption:: --hardlink-dupes
+.. option:: --hardlink-dupes
 
    If two ``.pyc`` files with different optimization level have
    the same content, use hard links to consolidate duplicate files.

Doc/library/gzip.rst

@@ -268,23 +268,23 @@ Once executed the :mod:`gzip` module keeps the input file(s).
 Command line options
 ^^^^^^^^^^^^^^^^^^^^
 
-.. cmdoption:: file
+.. option:: file
 
    If *file* is not specified, read from :data:`sys.stdin`.
 
-.. cmdoption:: --fast
+.. option:: --fast
 
    Indicates the fastest compression method (less compression).
 
-.. cmdoption:: --best
+.. option:: --best
 
    Indicates the slowest compression method (best compression).
 
-.. cmdoption:: -d, --decompress
+.. option:: -d, --decompress
 
    Decompress the given file.
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message.
 

Doc/library/inspect.rst

@@ -1655,6 +1655,6 @@ By default, accepts the name of a module and prints the source of that
 module. A class or function within the module can be printed instead by
 appended a colon and the qualified name of the target object.
 
-.. cmdoption:: --details
+.. option:: --details
 
    Print information about the specified object rather than the source code

Doc/library/json.rst

@@ -714,7 +714,7 @@ specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
 Command line options
 ^^^^^^^^^^^^^^^^^^^^
 
-.. cmdoption:: infile
+.. option:: infile
 
    The JSON file to be validated or pretty-printed:
 
@@ -734,36 +734,36 @@ Command line options
 
    If *infile* is not specified, read from :data:`sys.stdin`.
 
-.. cmdoption:: outfile
+.. option:: outfile
 
    Write the output of the *infile* to the given *outfile*. Otherwise, write it
    to :data:`sys.stdout`.
 
-.. cmdoption:: --sort-keys
+.. option:: --sort-keys
 
    Sort the output of dictionaries alphabetically by key.
 
    .. versionadded:: 3.5
 
-.. cmdoption:: --no-ensure-ascii
+.. option:: --no-ensure-ascii
 
    Disable escaping of non-ascii characters, see :func:`json.dumps` for more information.
 
    .. versionadded:: 3.9
 
-.. cmdoption:: --json-lines
+.. option:: --json-lines
 
    Parse every input line as separate JSON object.
 
    .. versionadded:: 3.8
 
-.. cmdoption:: --indent, --tab, --no-indent, --compact
+.. option:: --indent, --tab, --no-indent, --compact
 
    Mutually exclusive options for whitespace control.
 
    .. versionadded:: 3.9
 
-.. cmdoption:: -h, --help
+.. option:: -h, --help
 
    Show the help message.
 

Doc/library/pickletools.rst

@@ -53,24 +53,24 @@ Command line options
 
 .. program:: pickletools
 
-.. cmdoption:: -a, --annotate
+.. option:: -a, --annotate
 
    Annotate each line with a short opcode description.
 
-.. cmdoption:: -o, --output=<file>
+.. option:: -o, --output=<file>
 
    Name of a file where the output should be written.
 
-.. cmdoption:: -l, --indentlevel=<num>
+.. option:: -l, --indentlevel=<num>
 
    The number of blanks by which to indent a new MARK level.
 
-.. cmdoption:: -m, --memo
+.. option:: -m, --memo
 
    When multiple objects are disassembled, preserve memo between
    disassemblies.
 
-.. cmdoption:: -p, --preamble=<preamble>
+.. option:: -p, --preamble=<preamble>
 
    When more than one pickle file are specified, print given preamble
    before each disassembly.

Doc/library/py_compile.rst

@@ -139,13 +139,13 @@ not be compiled.
 
 .. program:: python -m py_compile
 
-.. cmdoption:: <file> ... <fileN>
-               -
+.. option:: <file> ... <fileN>
+            -
 
    Positional arguments are files to compile.  If ``-`` is the only
    parameter, the list of files is taken from standard input.
 
-.. cmdoption:: -q, --quiet
+.. option:: -q, --quiet
 
    Suppress errors output.
 

Doc/library/site.rst

@@ -266,11 +266,11 @@ If it is called without arguments, it will print the contents of
 :data:`USER_BASE` and whether the directory exists, then the same thing for
 :data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
 
-.. cmdoption:: --user-base
+.. option:: --user-base
 
    Print the path to the user base directory.
 
-.. cmdoption:: --user-site
+.. option:: --user-site
 
    Print the path to the user site-packages directory.
 

Doc/library/sqlite3.rst

@@ -2437,9 +2437,9 @@ or if :attr:`~Connection.autocommit` is ``True``,
 the context manager does nothing.
 
 .. note::
-
    The context manager neither implicitly opens a new transaction
-   nor closes the connection.
+   nor closes the connection. If you need a closing context manager, consider
+   using :meth:`contextlib.closing`.
 
 .. testcode::
 

Doc/library/tarfile.rst

@@ -1156,31 +1156,31 @@ For a list of the files in a tar archive, use the :option:`-l` option:
 Command-line options
 ~~~~~~~~~~~~~~~~~~~~
 
-.. cmdoption:: -l <tarfile>
-               --list <tarfile>
+.. option:: -l <tarfile>
+            --list <tarfile>
 
    List files in a tarfile.
 
-.. cmdoption:: -c <tarfile> <source1> ... <sourceN>
-               --create <tarfile> <source1> ... <sourceN>
+.. option:: -c <tarfile> <source1> ... <sourceN>
+            --create <tarfile> <source1> ... <sourceN>
 
    Create tarfile from source files.
 
-.. cmdoption:: -e <tarfile> [<output_dir>]
-               --extract <tarfile> [<output_dir>]
+.. option:: -e <tarfile> [<output_dir>]
+            --extract <tarfile> [<output_dir>]
 
    Extract tarfile into the current directory if *output_dir* is not specified.
 
-.. cmdoption:: -t <tarfile>
-               --test <tarfile>
+.. option:: -t <tarfile>
+            --test <tarfile>
 
    Test whether the tarfile is valid or not.
 
-.. cmdoption:: -v, --verbose
+.. option:: -v, --verbose
 
    Verbose output.
 
-.. cmdoption:: --filter <filtername>
+.. option:: --filter <filtername>
 
    Specifies the *filter* for ``--extract``.
    See :ref:`tarfile-extraction-filter` for details.