bpo-29918: Add missed "const" modifiers in C API documentation. (#846)

12 files changed, 84 insertions, 89 deletions

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index e8e7e0d..e4b48e6 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -138,7 +138,7 @@ which disallows mutable objects such as :class:`bytearray`.
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
    a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
 
-``u`` (:class:`str`) [Py_UNICODE \*]
+``u`` (:class:`str`) [const Py_UNICODE \*]
    Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
    Unicode characters.  You must pass the address of a :c:type:`Py_UNICODE`
    pointer variable, which will be filled with the pointer to an existing
@@ -151,16 +151,16 @@ which disallows mutable objects such as :class:`bytearray`.
       Previously, :exc:`TypeError` was raised when embedded null code points
       were encountered in the Python string.
 
-``u#`` (:class:`str`) [Py_UNICODE \*, int]
+``u#`` (:class:`str`) [const Py_UNICODE \*, int]
    This variant on ``u`` stores into two C variables, the first one a pointer to a
    Unicode data buffer, the second one its length.  This variant allows
    null code points.
 
-``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
+``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
    Like ``u``, but the Python object may also be ``None``, in which case the
    :c:type:`Py_UNICODE` pointer is set to *NULL*.
 
-``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
+``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
    Like ``u#``, but the Python object may also be ``None``, in which case the
    :c:type:`Py_UNICODE` pointer is set to *NULL*.
 
@@ -529,42 +529,42 @@ Building values
    not within format units such as ``s#``).  This can be used to make long format
    strings a tad more readable.
 
-   ``s`` (:class:`str` or ``None``) [char \*]
+   ``s`` (:class:`str` or ``None``) [const char \*]
       Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
       encoding. If the C string pointer is *NULL*, ``None`` is used.
 
-   ``s#`` (:class:`str` or ``None``) [char \*, int]
+   ``s#`` (:class:`str` or ``None``) [const char \*, int]
       Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
       encoding. If the C string pointer is *NULL*, the length is ignored and
       ``None`` is returned.
 
-   ``y`` (:class:`bytes`) [char \*]
+   ``y`` (:class:`bytes`) [const char \*]
       This converts a C string to a Python :class:`bytes` object.  If the C
       string pointer is *NULL*, ``None`` is returned.
 
-   ``y#`` (:class:`bytes`) [char \*, int]
+   ``y#`` (:class:`bytes`) [const char \*, int]
       This converts a C string and its lengths to a Python object.  If the C
       string pointer is *NULL*, ``None`` is returned.
 
-   ``z`` (:class:`str` or ``None``) [char \*]
+   ``z`` (:class:`str` or ``None``) [const char \*]
       Same as ``s``.
 
-   ``z#`` (:class:`str` or ``None``) [char \*, int]
+   ``z#`` (:class:`str` or ``None``) [const char \*, int]
       Same as ``s#``.
 
-   ``u`` (:class:`str`) [Py_UNICODE \*]
+   ``u`` (:class:`str`) [const Py_UNICODE \*]
       Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
       Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
 
-   ``u#`` (:class:`str`) [Py_UNICODE \*, int]
+   ``u#`` (:class:`str`) [const Py_UNICODE \*, int]
       Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
       Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
       and ``None`` is returned.
 
-   ``U`` (:class:`str` or ``None``) [char \*]
+   ``U`` (:class:`str` or ``None``) [const char \*]
       Same as ``s``.
 
-   ``U#`` (:class:`str` or ``None``) [char \*, int]
+   ``U#`` (:class:`str` or ``None``) [const char \*, int]
       Same as ``s#``.
 
    ``i`` (:class:`int`) [int]
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index ee42f85..f89cfa2 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -96,10 +96,10 @@ called with a non-bytes parameter.
    | :attr:`%x`        | int           | Exactly equivalent to          |
    |                   |               | ``printf("%x")``.              |
    +-------------------+---------------+--------------------------------+
-   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   | :attr:`%s`        | const char\*  | A null-terminated C character  |
    |                   |               | array.                         |
    +-------------------+---------------+--------------------------------+
-   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   | :attr:`%p`        | const void\*  | The hex representation of a C  |
    |                   |               | pointer. Mostly equivalent to  |
    |                   |               | ``printf("%p")`` except that   |
    |                   |               | it is guaranteed to start with |
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index cfa5e13..b7225fa 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -72,7 +72,7 @@ Dictionary Objects
    .. index:: single: PyUnicode_FromString()
 
    Insert *value* into the dictionary *p* using *key* as a key. *key* should
-   be a :c:type:`char\*`.  The key object is created using
+   be a :c:type:`const char\*`.  The key object is created using
    ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
    failure.
 
@@ -107,7 +107,7 @@ Dictionary Objects
 .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
 
    This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
-   :c:type:`char\*`, rather than a :c:type:`PyObject\*`.
+   :c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
 
 
 .. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 5273633..7c16ece 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -231,11 +231,6 @@ Importing Modules
    Finalize the import mechanism.  For internal use only.
 
 
-.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
-
-   For internal use only.
-
-
 .. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
 
    Load a frozen module named *name*.  Return ``1`` for success, ``0`` if the
@@ -266,8 +261,8 @@ Importing Modules
    is::
 
       struct _frozen {
-          char *name;
-          unsigned char *code;
+          const char *name;
+          const unsigned char *code;
           int size;
       };
 
@@ -300,7 +295,7 @@ Importing Modules
    The structure is defined in :file:`Include/import.h` as::
 
       struct _inittab {
-          char *name;                 /* ASCII encoded string */
+          const char *name;           /* ASCII encoded string */
           PyObject* (*initfunc)(void);
       };
 
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index 7724350..bae0372 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -80,7 +80,7 @@ Module Objects
    .. versionadded:: 3.3
 
 
-.. c:function:: char* PyModule_GetName(PyObject *module)
+.. c:function:: const char* PyModule_GetName(PyObject *module)
 
    Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
    ``'utf-8'``.
@@ -112,7 +112,7 @@ Module Objects
    .. versionadded:: 3.2
 
 
-.. c:function:: char* PyModule_GetFilename(PyObject *module)
+.. c:function:: const char* PyModule_GetFilename(PyObject *module)
 
    Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
    encoded to 'utf-8'.
@@ -146,11 +146,11 @@ or request "multi-phase initialization" by returning the definition struct itsel
 
       Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
 
-   .. c:member:: char* m_name
+   .. c:member:: const char *m_name
 
       Name for the new module.
 
-   .. c:member:: char* m_doc
+   .. c:member:: const char *m_doc
 
       Docstring for the module; usually a docstring variable created with
       :c:func:`PyDoc_STRVAR` is used.
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index c080f31..67e4f9d 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -125,20 +125,20 @@ the definition of all other Python objects.
    Structure used to describe a method of an extension type.  This structure has
    four fields:
 
-   +------------------+-------------+-------------------------------+
-   | Field            | C Type      | Meaning                       |
-   +==================+=============+===============================+
-   | :attr:`ml_name`  | char \*     | name of the method            |
-   +------------------+-------------+-------------------------------+
-   | :attr:`ml_meth`  | PyCFunction | pointer to the C              |
-   |                  |             | implementation                |
-   +------------------+-------------+-------------------------------+
-   | :attr:`ml_flags` | int         | flag bits indicating how the  |
-   |                  |             | call should be constructed    |
-   +------------------+-------------+-------------------------------+
-   | :attr:`ml_doc`   | char \*     | points to the contents of the |
-   |                  |             | docstring                     |
-   +------------------+-------------+-------------------------------+
+   +------------------+---------------+-------------------------------+
+   | Field            | C Type        | Meaning                       |
+   +==================+===============+===============================+
+   | :attr:`ml_name`  | const char \* | name of the method            |
+   +------------------+---------------+-------------------------------+
+   | :attr:`ml_meth`  | PyCFunction   | pointer to the C              |
+   |                  |               | implementation                |
+   +------------------+---------------+-------------------------------+
+   | :attr:`ml_flags` | int           | flag bits indicating how the  |
+   |                  |               | call should be constructed    |
+   +------------------+---------------+-------------------------------+
+   | :attr:`ml_doc`   | const char \* | points to the contents of the |
+   |                  |               | docstring                     |
+   +------------------+---------------+-------------------------------+
 
 The :attr:`ml_meth` is a C function pointer.  The functions may be of different
 types, but they always return :c:type:`PyObject\*`.  If the function is not of
@@ -236,25 +236,25 @@ definition with the same method name.
    Structure which describes an attribute of a type which corresponds to a C
    struct member.  Its fields are:
 
-   +------------------+-------------+-------------------------------+
-   | Field            | C Type      | Meaning                       |
-   +==================+=============+===============================+
-   | :attr:`name`     | char \*     | name of the member            |
-   +------------------+-------------+-------------------------------+
-   | :attr:`!type`    | int         | the type of the member in the |
-   |                  |             | C struct                      |
-   +------------------+-------------+-------------------------------+
-   | :attr:`offset`   | Py_ssize_t  | the offset in bytes that the  |
-   |                  |             | member is located on the      |
-   |                  |             | type's object struct          |
-   +------------------+-------------+-------------------------------+
-   | :attr:`flags`    | int         | flag bits indicating if the   |
-   |                  |             | field should be read-only or  |
-   |                  |             | writable                      |
-   +------------------+-------------+-------------------------------+
-   | :attr:`doc`      | char \*     | points to the contents of the |
-   |                  |             | docstring                     |
-   +------------------+-------------+-------------------------------+
+   +------------------+---------------+-------------------------------+
+   | Field            | C Type        | Meaning                       |
+   +==================+===============+===============================+
+   | :attr:`name`     | const char \* | name of the member            |
+   +------------------+---------------+-------------------------------+
+   | :attr:`!type`    | int           | the type of the member in the |
+   |                  |               | C struct                      |
+   +------------------+---------------+-------------------------------+
+   | :attr:`offset`   | Py_ssize_t    | the offset in bytes that the  |
+   |                  |               | member is located on the      |
+   |                  |               | type's object struct          |
+   +------------------+---------------+-------------------------------+
+   | :attr:`flags`    | int           | flag bits indicating if the   |
+   |                  |               | field should be read-only or  |
+   |                  |               | writable                      |
+   +------------------+---------------+-------------------------------+
+   | :attr:`doc`      | const char \* | points to the contents of the |
+   |                  |               | docstring                     |
+   +------------------+---------------+-------------------------------+
 
    :attr:`!type` can be one of many ``T_`` macros corresponding to various C
    types.  When the member is accessed in Python, it will be converted to the
@@ -268,7 +268,7 @@ definition with the same method name.
    T_LONG          long
    T_FLOAT         float
    T_DOUBLE        double
-   T_STRING        char \*
+   T_STRING        const char \*
    T_OBJECT        PyObject \*
    T_OBJECT_EX     PyObject \*
    T_CHAR          char
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 035cdc1..bc00aa1 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -136,7 +136,7 @@ accessible to C code.  They all work with the current interpreter thread's
 
    Reset :data:`sys.warnoptions` to an empty list.
 
-.. c:function:: void PySys_AddWarnOption(wchar_t *s)
+.. c:function:: void PySys_AddWarnOption(const wchar_t *s)
 
    Append *s* to :data:`sys.warnoptions`.
 
@@ -144,7 +144,7 @@ accessible to C code.  They all work with the current interpreter thread's
 
    Append *unicode* to :data:`sys.warnoptions`.
 
-.. c:function:: void PySys_SetPath(wchar_t *path)
+.. c:function:: void PySys_SetPath(const wchar_t *path)
 
    Set :data:`sys.path` to a list object of paths found in *path* which should
    be a list of paths separated with the platform's search path delimiter
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 3922d50..a66832c 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -144,9 +144,9 @@ type.
    +-------------------+------------------------------+------------------------------------+
    | Field             | C Type                       | Meaning                            |
    +===================+==============================+====================================+
-   | ``name``          | ``char *``                   | name of the struct sequence type   |
+   | ``name``          | ``const char *``             | name of the struct sequence type   |
    +-------------------+------------------------------+------------------------------------+
-   | ``doc``           | ``char *``                   | pointer to docstring for the type  |
+   | ``doc``           | ``const char *``             | pointer to docstring for the type  |
    |                   |                              | or NULL to omit                    |
    +-------------------+------------------------------+------------------------------------+
    | ``fields``        | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
@@ -164,16 +164,16 @@ type.
    :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
    field of the struct sequence is described.
 
-   +-----------+---------------+--------------------------------------+
-   | Field     | C Type        | Meaning                              |
-   +===========+===============+======================================+
-   | ``name``  | ``char *``    | name for the field or *NULL* to end  |
-   |           |               | the list of named fields, set to     |
-   |           |               | PyStructSequence_UnnamedField to     |
-   |           |               | leave unnamed                        |
-   +-----------+---------------+--------------------------------------+
-   | ``doc``   | ``char *``    | field docstring or *NULL* to omit    |
-   +-----------+---------------+--------------------------------------+
+   +-----------+------------------+--------------------------------------+
+   | Field     | C Type           | Meaning                              |
+   +===========+==================+======================================+
+   | ``name``  | ``const char *`` | name for the field or *NULL* to end  |
+   |           |                  | the list of named fields, set to     |
+   |           |                  | PyStructSequence_UnnamedField to     |
+   |           |                  | leave unnamed                        |
+   +-----------+------------------+--------------------------------------+
+   | ``doc``   | ``const char *`` | field docstring or *NULL* to omit    |
+   +-----------+------------------+--------------------------------------+
 
 
 .. c:var:: char* PyStructSequence_UnnamedField
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index c37734c..c743e57 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -490,10 +490,10 @@ APIs:
    | :attr:`%x`        | int                 | Exactly equivalent to          |
    |                   |                     | ``printf("%x")``.              |
    +-------------------+---------------------+--------------------------------+
-   | :attr:`%s`        | char\*              | A null-terminated C character  |
+   | :attr:`%s`        | const char\*        | A null-terminated C character  |
    |                   |                     | array.                         |
    +-------------------+---------------------+--------------------------------+
-   | :attr:`%p`        | void\*              | The hex representation of a C  |
+   | :attr:`%p`        | const void\*        | The hex representation of a C  |
    |                   |                     | pointer. Mostly equivalent to  |
    |                   |                     | ``printf("%p")`` except that   |
    |                   |                     | it is guaranteed to start with |
@@ -506,8 +506,8 @@ APIs:
    +-------------------+---------------------+--------------------------------+
    | :attr:`%U`        | PyObject\*          | A unicode object.              |
    +-------------------+---------------------+--------------------------------+
-   | :attr:`%V`        | PyObject\*, char \* | A unicode object (which may be |
-   |                   |                     | *NULL*) and a null-terminated  |
+   | :attr:`%V`        | PyObject\*,         | A unicode object (which may be |
+   |                   | const char\*        | *NULL*) and a null-terminated  |
    |                   |                     | C character array as a second  |
    |                   |                     | parameter (which will be used, |
    |                   |                     | if the first parameter is      |
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 4ac820a..2dc20fe 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -727,9 +727,9 @@ Philbrick (philbrick@hks.com)::
    keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
    {
        int voltage;
-       char *state = "a stiff";
-       char *action = "voom";
-       char *type = "Norwegian Blue";
+       const char *state = "a stiff";
+       const char *action = "voom";
+       const char *type = "Norwegian Blue";
 
        static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
 
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index 118f336..449c1e2 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -1361,9 +1361,9 @@ Here is a desultory example of the implementation of the call function. ::
    newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
    {
        PyObject *result;
-       char *arg1;
-       char *arg2;
-       char *arg3;
+       const char *arg1;
+       const char *arg2;
+       const char *arg3;
 
        if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
            return NULL;
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index eaab20a..b5c14d3 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1050,7 +1050,7 @@ Currently Argument Clinic supports only a few return converters:
     DecodeFSDefault
 
 None of these take parameters.  For the first three, return -1 to indicate
-error.  For ``DecodeFSDefault``, the return type is ``char *``; return a NULL
+error.  For ``DecodeFSDefault``, the return type is ``const char *``; return a NULL
 pointer to indicate an error.
 
 (There's also an experimental ``NoneType`` converter, which lets you