From 84b8e92e463bd6a5174bd3e5a6543580f6319c57 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 30 Mar 2017 10:01:03 +0300 Subject: [PATCH] bpo-29918: Add missed "const" modifiers in C API documentation. (#846) --- Doc/c-api/arg.rst | 28 +++++++-------- Doc/c-api/bytes.rst | 4 +-- Doc/c-api/dict.rst | 4 +-- Doc/c-api/import.rst | 11 ++---- Doc/c-api/module.rst | 8 ++--- Doc/c-api/structures.rst | 68 ++++++++++++++++++------------------- Doc/c-api/sys.rst | 4 +-- Doc/c-api/tuple.rst | 24 ++++++------- Doc/c-api/unicode.rst | 8 ++--- Doc/extending/extending.rst | 6 ++-- Doc/extending/newtypes.rst | 6 ++-- Doc/howto/clinic.rst | 2 +- 12 files changed, 84 insertions(+), 89 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index e8e7e0d5593..e4b48e66bc2 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 ee42f854ed8..f89cfa2f7a9 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 cfa5e13b9fe..b7225faf408 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 5273633667e..7c16ece0586 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 7724350d3c5..bae03728ffd 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 c080f317bee..67e4f9d4b9d 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 035cdc16824..bc00aa17b08 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 3922d50f80a..a66832cfa43 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 c37734c85b3..c743e57121c 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 4ac820a432b..2dc20fed131 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 118f336ae11..449c1e27544 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 eaab20ad975..b5c14d3af07 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