gh-95065: Add Argument Clinic support for deprecating positional use of parameters

Doc/howto/clinic.rst

@@ -1824,3 +1824,82 @@ blocks embedded in Python files look slightly different.  They look like this:
     #[python start generated code]*/
     def foo(): pass
     #/*[python checksum:...]*/
+
+
+How to deprecate positional use of optional parameters
+------------------------------------------------------
+
+Argument Clinic provides syntax that makes it possible to generate code that
+deprecates positional use of optional parameters.
+For example, say we've got a module level function :py:func:`!foo.myfunc` that
+takes three :class:`int` parameters:
+optional parameters *a* and *b*, and keyword-only parameter *c*::
+
+   /*[clinic input]
+   module foo
+   myfunc
+       a: int
+       b: int
+       *
+       c: int
+   [clinic start generated output]*/
+
+We now want to make the *b* parameter keyword-only from Python 3.14 and onward,
+and since :py:func:`!myfunc` is a public API,
+we must follow :pep:`387` and issue a deprecation warning.
+We can do that using the ``* [from ...]``` syntax,
+by adding the line ``* [from 3.14]`` right above the *b* parameter::
+
+   /*[clinic input]
+   module foo
+   myfunc
+       a: int
+       * [from 3.14]
+       b: int
+       *
+       c: int
+   [clinic start generated output]*/
+
+Next, regenerate Argument Clinic code (``make clinic``),
+and add unit tests for the new behaviour.
+
+The generated code will now emit a :exc:`DeprecationWarning`
+when an the optional parameter *b* is used as a positional paremeter.
+C preprocessor directives are also generated for emitting
+compiler warnings if the ``* [from ...]`` line has not been removed
+from the Argument Clinic input when the deprecation period is over,
+which means when the beta phase of the specified Python version kicks in.
+
+Let's return to our example and assume Python 3.14 development has entered the
+beta phase, and we forgot all about updating the Argument Clinic code for
+:py:func:`!myfunc`.
+Luckily for us, compiler warnings are now generated:
+
+.. code-block:: none
+
+   In file included from Modules/foomodule.c:139:
+   Modules/clinic/foomodule.c.h:83:8: warning: Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only. [-W#warnings]
+    #    warning "Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only."
+         ^
+
+We now close the deprecation phase by making *b* keyword-only;
+replace the ``* [from ...]``` line above *b*
+with the ``*`` from the line above *c*::
+
+   /*[clinic input]
+   module foo
+   myfunc
+       a: int
+       *
+       b: int
+       c: int
+   [clinic start generated output]*/
+
+Finally, run ``make clinic`` to regenerate the Argument Clinic code,
+and update your unit tests to reflect the new behaviour.
+
+.. note::
+
+   If you forget to update your clinic code during the target beta phase, the
+   copmiler warning will turn into a compiler error when the release candidate
+   phase kicks in.

Lib/test/clinic.test.c

@@ -4948,3 +4948,119 @@ Test_meth_coexist(TestObj *self, PyObject *Py_UNUSED(ignored))
 static PyObject *
 Test_meth_coexist_impl(TestObj *self)
 /*[clinic end generated code: output=808a293d0cd27439 input=2a1d75b5e6fec6dd]*/
+
+
+/*[clinic input]
+test_deprecate_positional_use
+    pos: object
+    * [from 3.14]
+    optarg: int = 5
+[clinic start generated code]*/
+
+PyDoc_STRVAR(test_deprecate_positional_use__doc__,
+"test_deprecate_positional_use($module, /, pos, optarg=5)\n"
+"--\n"
+"\n");
+
+#define TEST_DEPRECATE_POSITIONAL_USE_METHODDEF    \
+    {"test_deprecate_positional_use", _PyCFunction_CAST(test_deprecate_positional_use), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_use__doc__},
+
+static PyObject *
+test_deprecate_positional_use_impl(PyObject *module, PyObject *pos,
+                                   int optarg);
+
+static PyObject *
+test_deprecate_positional_use(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 2
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(pos), &_Py_ID(optarg), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"pos", "optarg", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "test_deprecate_positional_use",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[2];
+    Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 1;
+    PyObject *pos;
+    int optarg = 5;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 2, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    pos = args[0];
+    if (!noptargs) {
+        goto skip_optional_pos;
+    }
+    #if PY_MAJOR_VERSION == 3 && \
+        PY_MINOR_VERSION == 14 && \
+        PY_RELEASE_LEVEL == PY_RELEASE_LEVEL_BETA
+    #  ifdef _MSC_VER
+    #    pragma message ("Update 'optarg' in 'test_deprecate_positional_use' in 'clinic.test.c' to be keyword-only.")
+    #  else
+    #    warning "Update 'optarg' in 'test_deprecate_positional_use' in 'clinic.test.c' to be keyword-only."
+    #  endif
+    #elif PY_MAJOR_VERSION > 3 || \
+         (PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION > 14) || \
+         (PY_MAJOR_VERSION == 3 && \
+          PY_MINOR_VERSION == 14 && \
+          PY_RELEASE_LEVEL == PY_RELEASE_LEVEL_GAMMA)
+    #  error "Update 'optarg' in 'test_deprecate_positional_use' in 'clinic.test.c' to be keyword-only."
+    #endif
+    if (nargs == 2) {
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+            "Using 'optarg' as a positional argument is deprecated. "
+            "It will become a keyword-only argument in Python 3.14.", 2))
+        {
+            goto exit;
+        }
+    }
+    optarg = _PyLong_AsInt(args[1]);
+    if (optarg == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+skip_optional_pos:
+    return_value = test_deprecate_positional_use_impl(module, pos, optarg);
+
+exit:
+    return return_value;
+}
+
+static PyObject *
+test_deprecate_positional_use_impl(PyObject *module, PyObject *pos,
+                                   int optarg)
+/*[clinic end generated code: output=7a11cf25f54b6385 input=f77517a893443884]*/
+
+PyDoc_STRVAR(test_deprecate_positional_use__doc__,
+"test_deprecate_positional_use($module, /, pos, optarg=5)\n"
+"--\n"
+"\n");
+
+#define TEST_DEPRECATE_POSITIONAL_USE_METHODDEF    \
+    {"test_deprecate_positional_use", _PyCFunction_CAST(test_deprecate_positional_use), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_use__doc__},
+
+static PyObject *
+test_deprecate_positional_use_impl(PyObject *module, PyObject *pos,
+                                   int optarg);
+
+static PyObject *
+test_deprecate_positional_use(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)

Lib/test/test_clinic.py

@@ -948,6 +948,72 @@ def test_parameters_required_after_star(self):
                 out = self.parse_function_should_fail(block)
                 self.assertIn(msg, out)
 
+    def test_depr_star_invalid_format_1(self):
+        out = self.parse_function_should_fail("""
+            module foo
+            foo.bar
+                this: int
+                * [from 3]
+            Docstring.
+        """)
+        expected = (
+            "Error on line 0:\n"
+            "Function 'bar': '* [from ...]' format expected to be "
+            "'<major.minor>', where 'major' and 'minor' are digits.\n"
+        )
+        self.assertEqual(out, expected)
+
+    def test_depr_star_invalid_format_2(self):
+        out = self.parse_function_should_fail("""
+            module foo
+            foo.bar
+                this: int
+                * [from a.b]
+            Docstring.
+        """)
+        expected = (
+            "Error on line 0:\n"
+            "Function 'bar', '* [from <major.minor>]': "
+            "'major' and 'minor' must be digits, not 'a' and 'b'\n"
+        )
+        self.assertEqual(out, expected)
+
+    def test_parameters_required_after_depr_star(self):
+        out = self.parse_function_should_fail("""
+            module foo
+            foo.bar
+                this: int
+                * [from 3.14]
+            Docstring.
+        """)
+        msg = "Function bar specifies '* [from ...]' without any parameters afterwards."
+        self.assertIn(msg, out)
+
+    def test_depr_star_must_come_before_star(self):
+        out = self.parse_function_should_fail("""
+            module foo
+            foo.bar
+                this: int
+                *
+                * [from 3.14]
+            Docstring.
+        """)
+        msg = "Function 'bar': '* [from ...]' must come before '*'"
+        self.assertIn(msg, out)
+
+    def test_duplicate_depr_star(self):
+        out = self.parse_function_should_fail("""
+            module foo
+            foo.bar
+                a: int
+                * [from 3.14]
+                * [from 3.14]
+                b: int
+            Docstring.
+        """)
+        msg = "Function 'bar' uses '[from ...]' more than once."
+        self.assertIn(msg, out)
+
     def test_single_slash(self):
         out = self.parse_function_should_fail("""
             module foo

Misc/NEWS.d/next/Tools-Demos/2022-07-23-00-33-28.gh-issue-95065.NfCCpp.rst

@@ -0,0 +1,2 @@
+Add Argument Clinic support for deprecating positional use of optional
+parameters. Patch by Erlend E. Aasland.