From: Serhiy Storchaka <storchaka@gmail.com>
Date: Fri, 7 Aug 2026 04:09:28 +0000 (+0300)
Subject: gh-74366: Fix the documentation of "$" in PyArg_ParseTupleAndKeywords() (GH-155301)
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=af930c13787a15c22187d5d526f74f35c95f8056;p=thirdparty%2FPython%2Fcpython.git

gh-74366: Fix the documentation of "$" in PyArg_ParseTupleAndKeywords() (GH-155301)

The keyword-only arguments are not always optional: they are required if
"|" was not specified before "$".  Document also that "|" cannot be
specified after "$", and add examples for "|" and "$".
---

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 58456a36b96c..a878b20c928e 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -399,13 +399,18 @@ inside nested parentheses.  They are:
    their default value --- when an optional argument is not specified,
    :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C
    variable(s).
+   For example, the format string ``"OO|OO"`` corresponds to the Python
+   signature ``f(a, b, c=None, d=None)``.
 
 ``$``
    :c:func:`PyArg_ParseTupleAndKeywords` only:
    Indicates that the remaining arguments in the Python argument list are
-   keyword-only.  Currently, all keyword-only arguments must also be optional
-   arguments, so ``|`` must always be specified before ``$`` in the format
-   string.
+   keyword-only.
+   They are optional if ``|`` was specified before ``$``, and required otherwise.
+   ``|`` cannot be specified after ``$``.
+   For example, the format string ``"O|O$O"`` corresponds to the Python
+   signature ``f(a, b=None, *, c=None)``,
+   and the format string ``"OO$OO"`` corresponds to ``f(a, b, *, c, d)``.
 
    .. versionadded:: 3.3