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

serhiy-storchaka · 2023-06-21T09:03:27Z

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.

hugovk · 2023-06-22T06:47:56Z

Doc/c-api/arg.rst

+
+      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`


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).

arhadthedev · 2023-06-22T08:12:37Z

Doc/whatsnew/3.13.rst

@@ -433,7 +433,7 @@ New Features
  :c:expr:`const char * const *`, :c:expr:`const char **` or
  :c:expr:`char * const *` in C++ and :c:expr:`char * const *` in C
  without explicit type cast.
-  This can be overridden by defining the macro :c:macro:`PY_CXX_CONST`
+  This can be overridden by defining the macro ``PY_CXX_CONST``


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).

CAM-Gerlach · 2023-06-24T23:35:58Z

Doc/c-api/arg.rst

+
+      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`


@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).

CAM-Gerlach · 2023-06-24T23:43:21Z

Doc/c-api/arg.rst

+      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.


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.

CAM-Gerlach · 2023-06-24T23:48:17Z

Doc/whatsnew/3.13.rst

@@ -433,7 +433,7 @@ New Features
  :c:expr:`const char * const *`, :c:expr:`const char **` or
  :c:expr:`char * const *` in C++ and :c:expr:`char * const *` in C
  without explicit type cast.
-  This can be overridden by defining the macro :c:macro:`PY_CXX_CONST`
+  This can be overridden by defining the macro ``PY_CXX_CONST``


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).

CAM-Gerlach · 2023-06-24T23:49:18Z

Doc/whatsnew/3.13.rst

+  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.


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.

CAM-Gerlach · 2023-06-24T23:51:16Z

Doc/whatsnew/3.13.rst

+* 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


Suggested change

It makes these functions compatible with argument of type

It makes these functions compatible with arguments of type

Fix grammar error

CAM-Gerlach · 2023-06-24T23:51:42Z

Doc/whatsnew/3.13.rst

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


Suggested change

without explicit type cast.

without an explicit type cast.

Fix grammar error

CAM-Gerlach · 2023-06-24T23:54:30Z

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 <[email protected]>

serhiy-storchaka · 2023-12-01T10:07:23Z

@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 <[email protected]>

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 <[email protected]>

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
27 checks passed

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

serhiy-storchaka commented Jun 21, 2023 •

edited by github-actions bot

Loading

hugovk Jun 22, 2023

serhiy-storchaka Jun 22, 2023

hugovk Jun 24, 2023

CAM-Gerlach Jun 24, 2023

arhadthedev Jun 22, 2023

serhiy-storchaka Jun 22, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach Jun 24, 2023

CAM-Gerlach commented Jun 24, 2023

serhiy-storchaka commented Dec 1, 2023

	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() #105958

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

Conversation

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CAM-Gerlach commented Jun 24, 2023

serhiy-storchaka commented Dec 1, 2023

serhiy-storchaka commented Jun 21, 2023 •

edited by github-actions bot

Loading