gh-65210: Add const qualifiers in PyArg_VaParseTupleAndKeywords() by serhiy-storchaka · Pull Request #105958 · python/cpython · GitHub

Change the declaration of the keywords parameter in functions PyArg_ParseTupleAndKeywords() and PyArg_VaParseTupleAndKeywords() from char ** to char * const * in C and const char * const * in C++.

It makes these functions compatible with argument of type const char * const *, const char ** or char * const * in C++ and char * const * in C without explicit type cast.

Issue: PyArg_ParseTupleAndKeywords doesn't take const char *keywords[] #65210

📚 Documentation preview 📚: https://cpython-previews--105958.org.readthedocs.build/

Change the declaration of the keywords parameter in functions PyArg_ParseTupleAndKeywords() and PyArg_VaParseTupleAndKeywords() from `char **` to `char * const *` in C and `const char * const *` in C++. It makes these functions compatible with argument of type `const char * const *`, `const char **` or `char * const *` in C++ and `char * const *` in C without explicit type cast.

Please document this new macro somewhere with .. c:macro:: PY_CXX_CONST.

That will fix this warning and the one in 3.13.rst and the CI.

I do not know how to document it better than I did. I will appreciate your suggestions. For now I just removed the role.

@CAM-Gerlach Any suggestions?

@serhiy-storchaka To properly document a public entity (macro, function, class, method, etc), you can use the the appropriate directive—in this case, .. c:macro:: as @hugovk mentioned. This could be something like (placed, perhaps, at the top or bottom of the API Functions subsection):

.. macro:: PY_CXX_CONST

   The value to be inserted, if any, before :c:expr:`char * const *`
   in the *keywords* parameter declaration of
   :c:func:`PyArg_ParseTupleAndKeywords`
   and :c:func:`PyArg_VaParseTupleAndKeywords`.
   Default empty for C and ``const`` for C++ (:c:expr:`const char * const *`).
   To override, define it to the desired value before including :file:`Python.h`.

   .. versionadded:: 3.13

You can then simplify this note accordingly, per my other suggestion (in a separate comment).

Can we use this?

Suggested change

      
              This can be overridden by defining the macro ``PY_CXX_CONST``
          
              This can be overridden by defining the macro :c:macro:`!PY_CXX_CONST`

Yes, both :c:macro:`!PY_CXX_CONST` and ``PY_CXX_CONST`` would work.

To note, while they both silence the warning, they have different semantics in the source and rendering in the output.

However, with the changes suggested above, it is a moot point as you can link this and also simplify this What's New entry by referring readers to the macro description, which explains this (instead of duplicating the explanation here).

@serhiy-storchaka To properly document a public entity (macro, function, class, method, etc), you can use the the appropriate directive—in this case, .. c:macro:: as @hugovk mentioned. This could be something like (placed, perhaps, at the top or bottom of the API Functions subsection):

.. macro:: PY_CXX_CONST

   The value to be inserted, if any, before :c:expr:`char * const *`
   in the *keywords* parameter declaration of
   :c:func:`PyArg_ParseTupleAndKeywords`
   and :c:func:`PyArg_VaParseTupleAndKeywords`.
   Default empty for C and ``const`` for C++ (:c:expr:`const char * const *`).
   To override, define it to the desired value before including :file:`Python.h`.

   .. versionadded:: 3.13

You can then simplify this note accordingly, per my other suggestion (in a separate comment).

Suggested change

      
                  This can be overridden by defining the macro :c:macro:`PY_CXX_CONST`
          
                  before including :file:`Python.h` as ``const`` for the latter and as
          
                  empty value for the former.
          
                  This can be overridden with the :c:macro:`PY_CXX_CONST` macro.

Refer to the newly-added macro's documentation instead of needing to repeat these details here.

To note, while they both silence the warning, they have different semantics in the source and rendering in the output.

However, with the changes suggested above, it is a moot point as you can link this and also simplify this What's New entry by referring readers to the macro description, which explains this (instead of duplicating the explanation here).

Suggested change

      
              This can be overridden by defining the macro ``PY_CXX_CONST``
          
              before including :file:`Python.h` as ``const`` for the latter and as
          
              empty value for the former.
          
              This can be overridden with the :c:macro:`PY_CXX_CONST` macro.

Now that this is documented, simply refer interested readers here directly instead of duplicating the whole explanation.

Suggested change

      
              It makes these functions compatible with argument of type
          
              It makes these functions compatible with arguments of type

Fix grammar error

Suggested change

      
              without explicit type cast.
          
              without an explicit type cast.

Fix grammar error

Standard reminder: You can directly apply all the suggestions you want in one go by going to Files changed -> Clicking Add to batch on each suggestion -> When done, clicking Commit.

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

@CAM-Gerlach Thank you, I applied all your suggestions.

…() (pythonGH-105958) Change the declaration of the keywords parameter in functions PyArg_ParseTupleAndKeywords() and PyArg_VaParseTupleAndKeywords() from `char **` to `char * const *` in C and `const char * const *` in C++. It makes these functions compatible with argument of type `const char * const *`, `const char **` or `char * const *` in C++ and `char * const *` in C without explicit type cast. Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

bedevere-bot added the awaiting core review label Jun 21, 2023

bedevere-bot mentioned this pull request Jun 21, 2023

PyArg_ParseTupleAndKeywords doesn't take const char *keywords[] #65210

Closed

serhiy-storchaka added the topic-C-API label Jun 21, 2023

Fix doc build.

1340934

hugovk reviewed Jun 22, 2023

View reviewed changes

Silence Sphinx warning.

040817e

arhadthedev reviewed Jun 22, 2023

View reviewed changes

serhiy-storchaka mentioned this pull request Jun 22, 2023

PyArg_ParseTupleAndKeywords and fields take (non-const) char *keywords[] capi-workgroup/problems#28

Open

CAM-Gerlach reviewed Jun 24, 2023

View reviewed changes

serhiy-storchaka and others added 2 commits December 1, 2023 11:51

Merge branch 'main' into PyArg_ParseTupleAndKeywords-const

910c5d2

Apply suggestions.

0e4dc59

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

serhiy-storchaka force-pushed the PyArg_ParseTupleAndKeywords-const branch from 4ff9e8f to 0e4dc59 Compare December 1, 2023 10:06

serhiy-storchaka merged commit da6760b into python:main Dec 4, 2023

bedevere-app Bot removed the awaiting core review label Dec 4, 2023

serhiy-storchaka deleted the PyArg_ParseTupleAndKeywords-const branch December 4, 2023 11:15

davidhewitt mentioned this pull request Aug 6, 2024

ffi: update modsupport.rs for Python 3.13 PyO3/pyo3#4420

Merged

+              * The *keywords* parameter of :c:func:`PyArg_ParseTupleAndKeywords` and
+                :c:func:`PyArg_VaParseTupleAndKeywords` has now type :c:expr:`char * const *`
+                in C and :c:expr:`const char * const *` in C++, instead of :c:expr:`char **`.
+                It makes these functions compatible with argument of type

+                    The *keywords* parameter declaration is :c:expr:`char * const *` in C and
+                    :c:expr:`const char * const *` in C++.
+                    This can be overridden by defining the macro :c:macro:`PY_CXX_CONST`

	This can be overridden by defining the macro ``PY_CXX_CONST``
	This can be overridden by defining the macro :c:macro:`!PY_CXX_CONST`

gh-65210: Add const qualifiers in PyArg_VaParseTupleAndKeywords() by serhiy-storchaka · Pull Request #105958 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-65210: Add const qualifiers in PyArg_VaParseTupleAndKeywords() - #105958

gh-65210: Add const qualifiers in PyArg_VaParseTupleAndKeywords()#105958serhiy-storchaka merged 5 commits intopython:mainpython/cpython:mainfrom serhiy-storchaka:PyArg_ParseTupleAndKeywords-constserhiy-storchaka/cpython:PyArg_ParseTupleAndKeywords-constCopy head branch name to clipboard

Conversation

serhiy-storchaka commented Jun 21, 2023 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CAM-Gerlach commented Jun 24, 2023

Uh oh!

serhiy-storchaka commented Dec 1, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gh-65210: Add const qualifiers in PyArg_VaParseTupleAndKeywords()#105958
serhiy-storchaka merged 5 commits into
python:mainfrom
serhiy-storchaka:PyArg_ParseTupleAndKeywords-const

serhiy-storchaka commented Jun 21, 2023 •
edited by github-actions Bot
Loading