Merge pull request #3 from python/main

pull

Author: 1proprogrammerchant

Doc/c-api/init.rst

@@ -87,7 +87,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-b` option.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_DebugFlag
 
@@ -101,7 +101,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_DontWriteBytecodeFlag
 
@@ -115,7 +115,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
    environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_FrozenFlag
 
@@ -128,7 +128,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_HashRandomizationFlag
 
@@ -143,7 +143,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
    variable to initialize the secret hash seed.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_IgnoreEnvironmentFlag
 
@@ -156,7 +156,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-E` and :option:`-I` options.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_InspectFlag
 
@@ -171,7 +171,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_InteractiveFlag
 
@@ -196,7 +196,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. versionadded:: 3.4
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_LegacyWindowsFSEncodingFlag
 
@@ -215,7 +215,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. availability:: Windows.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_LegacyWindowsStdioFlag
 
@@ -233,7 +233,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. availability:: Windows.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_NoSiteFlag
 
@@ -248,7 +248,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    Set by the :option:`-S` option.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_NoUserSiteDirectory
 
@@ -262,7 +262,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-s` and :option:`-I` options, and the
    :envvar:`PYTHONNOUSERSITE` environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_OptimizeFlag
 
@@ -273,7 +273,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_QuietFlag
 
@@ -287,7 +287,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    .. versionadded:: 3.2
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_UnbufferedStdioFlag
 
@@ -300,7 +300,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
    environment variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 .. c:var:: int Py_VerboseFlag
 
@@ -316,7 +316,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
    Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
    variable.
 
-   .. deprecated:: 3.12
+   .. deprecated-removed:: 3.12 3.14
 
 
 Initializing and finalizing the interpreter

Doc/c-api/weakref.rst

@@ -55,9 +55,11 @@ as much as it can.
 
    Get a :term:`strong reference` to the referenced object from a weak
    reference, *ref*, into *\*pobj*.
-   Return 0 on success. Raise an exception and return -1 on error.
 
-   If the referent is no longer live, set *\*pobj* to ``NULL`` and return 0.
+   * On success, set *\*pobj* to a new :term:`strong reference` to the
+     referenced object and return 1.
+   * If the reference is dead, set *\*pobj* to ``NULL`` and return 0.
+   * On error, raise an exception and return -1.
 
    .. versionadded:: 3.13
 

Doc/glossary.rst

@@ -1107,6 +1107,21 @@ Glossary
       when several are given, such as in ``variable_name[1:3:5]``.  The bracket
       (subscript) notation uses :class:`slice` objects internally.
 
+   soft deprecated
+      A soft deprecation can be used when using an API which should no longer
+      be used to write new code, but it remains safe to continue using it in
+      existing code. The API remains documented and tested, but will not be
+      developed further (no enhancement).
+
+      The main difference between a "soft" and a (regular) "hard" deprecation
+      is that the soft deprecation does not imply scheduling the removal of the
+      deprecated API.
+
+      Another difference is that a soft deprecation does not issue a warning.
+
+      See `PEP 387: Soft Deprecation
+      <https://peps.python.org/pep-0387/#soft-deprecation>`_.
+
    special method
       .. index:: pair: special; method
 

Doc/library/functions.rst

@@ -794,7 +794,7 @@ are always available.  They are listed here in alphabetical order.
 
       For objects with custom :meth:`__hash__` methods, note that :func:`hash`
       truncates the return value based on the bit width of the host machine.
-      See :meth:`__hash__` for details.
+      See :meth:`__hash__ <object.__hash__>` for details.
 
 .. function:: help()
               help(request)

Doc/library/getopt.rst

@@ -7,18 +7,23 @@
 
 **Source code:** :source:`Lib/getopt.py`
 
+.. deprecated:: 3.13
+   The :mod:`getopt` module is :term:`soft deprecated` and will not be
+   developed further; development will continue with the :mod:`argparse`
+   module.
+
 .. note::
 
    The :mod:`getopt` module is a parser for command line options whose API is
-   designed to be familiar to users of the C :c:func:`getopt` function. Users who
-   are unfamiliar with the C :c:func:`getopt` function or who would like to write
+   designed to be familiar to users of the C :c:func:`!getopt` function. Users who
+   are unfamiliar with the C :c:func:`!getopt` function or who would like to write
    less code and get better help and error messages should consider using the
    :mod:`argparse` module instead.
 
 --------------
 
 This module helps scripts to parse the command line arguments in ``sys.argv``.
-It supports the same conventions as the Unix :c:func:`getopt` function (including
+It supports the same conventions as the Unix :c:func:`!getopt` function (including
 the special meanings of arguments of the form '``-``' and '``--``').  Long
 options similar to those supported by GNU software may be used as well via an
 optional third argument.
@@ -33,11 +38,11 @@ exception:
    be parsed, without the leading reference to the running program. Typically, this
    means ``sys.argv[1:]``. *shortopts* is the string of option letters that the
    script wants to recognize, with options that require an argument followed by a
-   colon (``':'``; i.e., the same format that Unix :c:func:`getopt` uses).
+   colon (``':'``; i.e., the same format that Unix :c:func:`!getopt` uses).
 
    .. note::
 
-      Unlike GNU :c:func:`getopt`, after a non-option argument, all further
+      Unlike GNU :c:func:`!getopt`, after a non-option argument, all further
       arguments are considered also non-options. This is similar to the way
       non-GNU Unix systems work.
 
@@ -71,7 +76,7 @@ exception:
    non-option argument is encountered.
 
    If the first character of the option string is ``'+'``, or if the environment
-   variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
+   variable :envvar:`!POSIXLY_CORRECT` is set, then option processing stops as
    soon as a non-option argument is encountered.
 
 
@@ -81,9 +86,9 @@ exception:
    an option requiring an argument is given none. The argument to the exception is
    a string indicating the cause of the error.  For long options, an argument given
    to an option which does not require one will also cause this exception to be
-   raised.  The attributes :attr:`msg` and :attr:`opt` give the error message and
+   raised.  The attributes :attr:`!msg` and :attr:`!opt` give the error message and
    related option; if there is no specific option to which the exception relates,
-   :attr:`opt` is an empty string.
+   :attr:`!opt` is an empty string.
 
 .. XXX deprecated?
 .. exception:: error

Doc/library/logging.rst

@@ -1015,6 +1015,10 @@ interchangeably.
    Attribute :attr:`manager` and method :meth:`_log` were added, which
    delegate to the underlying logger and allow adapters to be nested.
 
+.. versionchanged:: 3.13
+   Remove the undocumented ``warn()`` method which was an alias to the
+   ``warning()`` method.
+
 
 Thread Safety
 -------------
@@ -1162,6 +1166,10 @@ functions.
       identical to ``warning``. As ``warn`` is deprecated, please do not use
       it - use ``warning`` instead.
 
+   .. versionchanged:: 3.13
+      Remove the undocumented ``warn()`` function which was an alias to the
+      :func:`warning` function.
+
 
 .. function:: error(msg, *args, **kwargs)
 

Doc/library/optparse.rst

@@ -11,8 +11,9 @@
 **Source code:** :source:`Lib/optparse.py`
 
 .. deprecated:: 3.2
-   The :mod:`optparse` module is deprecated and will not be developed further;
-   development will continue with the :mod:`argparse` module.
+   The :mod:`optparse` module is :term:`soft deprecated` and will not be
+   developed further; development will continue with the :mod:`argparse`
+   module.
 
 --------------