bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
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 @@
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 @@
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 @@
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 @@
| :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 @@
.. 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 @@
.. 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 @@
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 @@
is::
struct _frozen {
- char *name;
- unsigned char *code;
+ const char *name;
+ const unsigned char *code;
int size;
};
@@ -300,7 +295,7 @@
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 @@
.. 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 @@
.. 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
+-------------------+------------------------------+------------------------------------+
| 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 @@
: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 @@
| :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 @@
+-------------------+---------------------+--------------------------------+
| :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 |